Git URLs

When the Package Manager fetches a package from a Git repository, it adds the package locally to your project. This allows you to easily test unpublished changes, but you cannot use it to contribute to that Git repository. To set up an existing local Git repository as a dependency in your project, use a local path instead.

To use Git packages in a project, make sure the Git client is installed on your machine and that you have added the Git executable path to the PATH system environment variable.

If the repository tracks files with Git LFS, make sure the Git LFS client is also installed on your machine. If it is not installed, the Package Manager can’t retrieve the files stored on the LFS server and instead checks out the LFS pointer files without any error or warning messages.

Note: You can also use the Package Manager window to install a package directly from a Git repository. For more information, see Installing from a Git URL.

To specify a Git URL as a dependency, add the name of the package to install with a Git URL instead of the version number or local file path. For example, this demonstrates how to specify a remote Git using the recommended HTTPS protocol:

{
  "dependencies": {
    "com.mycompany.mypackage": "https://mycompany.github.com/gitproject/com.mycompany.mypackage.git"
}

The Package Manager supports the https, http, ssh, git, and file protocols using this form:

  <protocol>://[<user>[:<password>]@]<host>[:<port>]/<path>.git[#<revision>]

You can also skip the .git path suffix if the URL starts with git in these forms:

  git://[<user>[:<password>]@]<host>[:<port>]/<path>[#<revision>]

or:

  git+<protocol>://[<user>[:<password>]@]<host>[:<port>]/<path>[#<revision>]

You might need to configure credentials in Git configuration files in order to provide your username and password securely. This is preferable to hard-coding them in the Git URL, which is a major security issue if the project is shared with others.

Git uses the keys at the default location when you use SSH to authenticate. However, if you are using PuTTY as the SSH client on Windows, you might need to configure the GIT_SSH environment variable to make it point to plink.exe.

You need to set up SSH keys outside of Unity. The Editor notifies you of authentication failure if you don’t have proper access.

For more information on setting up authentication for a specific host, see the help pages for GitLab and GitHub.

Targeting a specific revision

You can specify any revision to install. A revision is an expression that eventually resolves to a commit hash in Git. The most common types of revisions are commit hashes, tags, and branches.

To target a specific revision, append the following to the Git URL in the dependencies attribute: # followed by the revision (either the version or a specific Git hash). Specifying the hash ensures that you get exactly the version you want. For example:

{
  "dependencies": {
    "com.mycompany.mypackage": "https://mycompany.github.com/gitproject/com.mycompany.mypackage.git#523c4f291cea796141e7211f4951702984d2e9ca"
  }
}

If the revision omitted, the Package Manager uses the remote repository’s HEAD revision.

For more information about setting a proper revision, see the Git user manual section on Git revisions.

Using the SSH protocol

If you want to use the ssh protocol, you can use either the full URL syntax or the SCP shorthand:

# SCP shorthand
{
  "dependencies": {
    "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
}

# Full SSH protocol
{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
}

Note: If you set up your SSH key with a passphrase, the Package Manager can’t retrieve the package, because you need to enter the passphrase in a shell or command line. In this case, consider using the https protocol instead, or use the ssh-add utility shipped with Git. For more information, see Authentication issues with Git URLs.

Using the FILE protocol

The Package Manager does not recognize file paths with the file prefix as Git URLs, but it does recognize full URLs with the file protocol as Git URLs if they are properly formatted. For example:

{
  "dependencies": {
    "com.mycompany.mypackage1": "file://localhost/absolute/path/to/com.mycompany.mypackage1.git",
    "com.mycompany.mypackage2": "git+file:///absolute/path/to/other/com.mycompany.mypackage2"
  }
}