mob-sakai/GitDependencyResolverForUnity

Git Dependency Resolver For Unity

This plugin resolves git-based dependencies in the package for Unity Package Manager.
You can use git repositories url as a package dependencies! :+1:

<< Description | Install | Usage | Development Note | Contributing | Change log >>

Description

In Unity 2018.3, the Unity Package Manager (UPM) supported Git. :)

This update allows us to quickly install packages on code hosting services such as GitHub.

However, UPM does not support git-based dependencies in the package. :(

[ package-a/package.json ]
{
  "name": "com.coffee.package-a",
  "version": "0.1.0",
  "dependencies": {
    "com.coffee.core-a" : "https://github.com/mob-sakai/GitPackageTest#core-a-0.1.0"
  }
}

When the above package is installed, the following error occur.

Git-based dependencies in packages feature is on the roadmap for 2020, but no specific ETA.

This plugin resolves git-based dependencies in the package.
You can use git repositories url as a package dependencies! :+1:

Features

• Easy to use: just install
• Resolve git-based dependencies in packages
• Automatically uninstall unused packages that is installed by this plugin
• Support GitHub, Bitbucket, GitLab, etc.
• Support private repository
• Support Unity 2018.3 or later
• Support .Net 3.5 and 4.x
• Update package with a specific tag/branch/hash
• Deterministic package installation
• Support CI environment
• Support path query parameter (sub-directory) even Unity 2019.2 or earlier
  • path must be a relative path to the root of the repository.
  • path query parameter must be placed before the revision anchor. The reverse order will fail.
  • A package manifest (package.json) is expected in the specified path.
  • e.g. With Path query parameter: https://github.com/user/repo.git?path=/example/folder
  • e.g. With revision anchor and path query parameter: https://github.com/user/repo.git?path=/example/folder#v1.2.3

Notes

From: https://forum.unity.com/threads/git-support-on-package-manager.573673/page-3#post-4552084

There is no conflict detection and/or resolution algorithm. The lastest package found with the same name is used. This is not how the package manager resolve dependency (See https://docs.unity3d.com/Manual/upm-conflicts-auto.html).

In Unity's algorithm, package conflicts are resolved by "dependency-level from root".
The all packages resolved by this plugin are "dependency-level=1".
Therefore, in some cases, the package of the intended version may not be installed.

For example, in the case of a project with a dependency graph like this:

project (root)
 ├ package A: 1.0.0
 │  └ package X: 2.0.0
 └ package B: 1.0.0
    └ package C: 2.0.0
       └ package X: 2.0.1

This plugin's algorithm

Install -> A: 1.0.0, B: 1.0.0, C: 2.0.0, X: 2.0.1

Unity's algorithm

Install -> A: 1.0.0, B: 1.0.0, C: 2.0.0, X: 2.0.0

Installation

Requirement

• Unity 2018.3 or later

Using OpenUPM

This package is available on OpenUPM. You can install it via openupm-cli.

openupm add com.coffee.git-dependency-resolver

Using Git

Find the manifest.json file in the Packages directory in your project and edit it as follows:

{
  "dependencies": {
    "com.coffee.git-dependency-resolver": "https://github.com/mob-sakai/GitDependencyResolverForUnity.git",
    ...
  },
}

To update the package, change suffix #{version} to the target version.

• e.g. "com.coffee.git-dependency-resolver": "https://github.com/mob-sakai/GitDependencyResolverForUnity.git#1.2.0",

Or, use UpmGitExtension to install and update the package.

Usage

For package user

• Install this plugin.
  • See installation section.
• If the dependencies are not resolved successfully, reopen the project. If that does not work, try the following:
  1. Close the project.
  2. Delete Library/ScriptAssemblies directory in the project.
  3. Open the project.
• When Unity Package Manager Error window is opens, click Continue.
  
• Add Packages/.* to .gitignore to hide auto-installed package.

For package developer

• Find the package.json file in your package and edit it as follows:

{
  ...
  "gitDependencies": {
    "your.package": "https://github.com/yourname/yourpackage.git#v1.2.3",
    ...
  }
}

• You can use path query parameter (sub-directory) even Unity 2019.2 or earlier.
  • e.g. "your.package": "https://github.com/yourname/yourpackage.git?path=/pkg/dir#v1.2.3"
  • path must be a relative path to the root of the repository.
  • path query parameter must be placed before the revision anchor. The reverse order will fail.
  • A package manifest (package.json) is expected in the specified path.
• You must use gitDependencies instead of dependencies to define git-based dependencies for the package.
  • This plugin also supports dependencies to resolve git-based dependencies, but if dependencies include packages that UPM can't resolve, it will fail to start Unity in CI environment.
• You must announce to your package users that they must install com.coffee.git-dependency-resolver.
  • See installation section.
• It is recommended to use SemVer as a tag or branch name.
  • e.g. 1.0.0, 0.5.0-preview10, 0.1.0-alpha+daily5

Contributing

Issues

Issues are very valuable to this project.

• Ideas are a valuable source of contributions others can make
• Problems show where this project is lacking
• With a question you show where contributors can improve the user experience

Pull Requests

Pull requests are, a great way to get your ideas into this repository.
See CONTRIBUTING.md.

Support

This is an open source project that I am developing in my spare time.
If you like it, please support me.
With your support, I can spend more time on development. :)

License

• MIT
• MiniJson by Calvin Rien
• SemVer by Max Hauser

Author

mob-sakai

See Also

• GitHub page : https://github.com/mob-sakai/GitDependencyResolverForUnity
• Releases : https://github.com/mob-sakai/GitDependencyResolverForUnity/releases
• Issue tracker : https://github.com/mob-sakai/GitDependencyResolverForUnity/issues
• Change log : https://github.com/mob-sakai/GitDependencyResolverForUnity/blob/upm/CHANGELOG.md