diff --git a/README.md b/README.md index 28142db9..1abb755b 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,6 @@ The tool is designed to work with [the OpenUPM registry](https://openupm.com), b - [Authenticate for the Windows system user](#authenticate-for-the-windows-system-user) - [Troubleshooting](#troubleshooting) - [Command options](#command-options) - - [Work with different registries](#work-with-different-registries) - [Work with proxy](#work-with-proxy) - [Contributors](#contributors) @@ -77,42 +76,14 @@ Please install [Node.js 18 or above](https://nodejs.org/en/download/). ### Add packages -``` -openupm add [otherPkgs..] -openupm add @ -openupm add @git@github.com:... -openupm add @https://github.com/... -openupm add @file:... -``` - -The add command adds the package to the `manifest.json` and configures the scope registry by adding scopes for the package and its dependencies that available on the registry. - -The add command doesn't verify package or resolve dependencies for Git, HTTPS, and file protocol. See https://docs.unity3d.com/Manual/upm-git.html for more examples of the version string. - -The add command fails if the package is not qualified: - -- the package has a missing dependency -- the package requires a non-existed dependency version -- the package requires a higher editor version - -You shall either resolve these issues manually or add the option `-f` to continue. +Use `openupm add` to add one or more packages to your project. -You may specify the version to add in a few different ways: - -- A specific version like `com.my.package@1.2.0` -- The latest tag like `com.my.package@latest` which will install the latest -published version, including pre-releases. -- No version at all like `com.my.package` which is identical to using the -"latest" tag. -- The stable tag like `com.my.package@stable` which will install the latest -stable version, ie. excluding pre-releases. - -You can also add [testables](https://docs.unity3d.com/Manual/cus-tests.html) when importing: - -``` -openupm --test +```sh +openupm add com.my.package@1.2.3 ``` +Checkout [the commands doc page](./docs/cmd-add.md) for more information. + ### Remove packages ``` openupm remove [otherPkgs...] @@ -250,41 +221,6 @@ Show verbose logging openupm --verbose ... ``` -## Work with different registries - -By default the openupm will query any package from the following registries: - -1. Openupm (https://package.openupm.com) -2. Unity (https://packages.unity.com) - -Any package will be searched on these registries in the order that they are listed above. If you want to install packages from your own third party registries you can do this via the `--registry` option. - -```openupm --registry https://package.my-registry.com add com.my.package``` - -This will query the following registries: - -1. The private registry (https://package.my-registry.com) -2. Unity (https://packages.unity.com) - -Let's say `com.my.package` depends on a Openupm package. With the above configuration the install would fail because Openupm is not part of the queried registries. To fix, add Openupm to the --registry option. - -```openupm --registry https://package.my-registry.com https://package.openupm.com add com.my.package``` - -The query will now look like this: - -1. The private registry (https://package.my-registry.com) -2. Openupm (https://package.openupm.com) -3. Unity (https://packages.unity.com) - -Finally, it may not always be desirable to search the Unity registry. If you want to remove it from the registry list, run with the `--no-upstream` option. - -```openupm --registry https://package.my-registry.com https://package.openupm.com --no-upstream add com.my.package``` - -The resulting query is: - -1. The private registry (https://package.my-registry.com) -2. Openupm (https://package.openupm.com) - ## Work with proxy OpenUPM-CLI supports HTTP, HTTPS, or SOCKS proxy specified by the http_proxy environment variable. diff --git a/docs/cmd-add.md b/docs/cmd-add.md new file mode 100644 index 00000000..822e9e61 --- /dev/null +++ b/docs/cmd-add.md @@ -0,0 +1,121 @@ +# `openupm add` + +The `add` command adds one or more dependencies to a Unity project. This +means that it adds the given packages to the projects direct dependencies as well as configuring scoped registries so that Unity can +resolve the dependencies. + +_Currently openupm does not install the dependencies into the project itself. This is left for Unity to do._ + +You should run this command inside the projects root directory. + +## Arguments + +### Packages + +Specify one or more packages for openupm to add. The general format for a package reference is `name@version`. + +```sh +openupm add com.my.package@1.0.0 +``` + +The version may be one of the following options: + +#### No version + +This is identical to using the `latest` tag. + +Example: `com.my.package` + +#### A specific version + +Installs the specific given version. + +Example: `com.my.package@1.2.0` + +#### The latest tag + +This resolves the latest published version, including pre-releases. + +Example: `com.my.package@latest` + +#### The stable tag + +This resolves the latest published stable version, excluding pre-releases + +Example: `com.my.package@latest` + + +#### A git url + +A `http` or `git` based url to a git repository. Checkout the [Unity documentation on the topic](https://docs.unity3d.com/Manual/upm-git.html#syntax) [^1]. + +Examples (taken from the Unity documentation): + +- `com.my.package@https://github.example.com/myuser/myrepository1.git` +- `com.my.package@git@github.example.com/myuser/myrepository2.git` + +#### A local file url + +A `file` based url to a local package. Check out the [Unity documentation on the topic](https://docs.unity3d.com/Manual/upm-localpath.html) [^1]. + +Example (Taken from Unity documentation): `com.my.package@file:../github/my_package_folder` + +## Options + +### Testables + +If you also want to add packages to the [projects testables](https://docs.unity3d.com/Manual/upm-manifestPrj.html#testables) run the command with the `--test` option. + +```sh +openupm add com.my.package --test +``` + +### Force + +By default openupm validates added packages to check whether they can be added to the project [^1]. Specifically openupm will check whether all indirect dependencies can be resolved and whether the package is compatible with the projects editor version. If validation fails then the package can not be added. + +If you know what you doing and want to add the package even though there are validation problems you can run with the `--force`/`-f` option to bypass validation. + +```sh +openupm add com.my.package --force +``` + +### Registry + +By default openupm resolves packages from the openupm and Unity registries in that order. This behavior is configurable, specifically if you want to work with 3rd party registries. + +You can override the primary registry from which to resolve packages using the `--registry` option. + +```sh +openupm add com.my.package --registry https://packages.my.registry +``` + +You can also use the `--no-upstream` option if you don't want to resolve from the Unity registry. + +```sh +openupm add com.my.package --no-upstream +``` + +For more information read [the help article about working with 3rd party registries](./help-registry.md). + +### Project directory + +By default openupm expects that you run the add command inside your Unity projects root directory. Based on this it determines relative paths to your package manifest etc. + +If you need to run openupm from somewhere else you can change the working directory using the `--chdir`/`-c` option. This option accepts an **absolute** path to a Unity projects root directory. + +```sh +openupm add com.my.package -c /home/user/dev/MyProject +``` + +### Windows system user + +By default openupm collects registry authentication credentials from the users local `.upmconfig.toml`. + +If you want to authenticate with registries using the `.upmconfig.toml` file for the Windows system user then pass the `--system-user` option. + +```sh +openupm add com.my.package --system-user +``` + +[^1]: openupm does not validate or resolve indirect dependencies for url-based dependencies. \ No newline at end of file diff --git a/docs/help-registry.md b/docs/help-registry.md new file mode 100644 index 00000000..990c151a --- /dev/null +++ b/docs/help-registry.md @@ -0,0 +1,40 @@ +# Work with different registries + +By default the openupm will query any package from the following registries: + +1. Openupm (https://package.openupm.com) +2. Unity (https://packages.unity.com) + +Any package will be searched on these registries in the order that they are listed above. If you want to install packages from your own third party registries you can do this via the `--registry` option. + +```sh +openupm --registry https://package.my-registry.com add com.my.package +``` + +This will query the following registries: + +1. The private registry (https://package.my-registry.com) +2. Unity (https://packages.unity.com) + +Let's say `com.my.package` depends on a Openupm package. With the above configuration the install would fail because Openupm is not part of the queried registries. To fix, add Openupm to the --registry option. + +```sh +openupm --registry https://package.my-registry.com https://package.openupm.com add com.my.package +``` + +The query will now look like this: + +1. The private registry (https://package.my-registry.com) +2. Openupm (https://package.openupm.com) +3. Unity (https://packages.unity.com) + +Finally, it may not always be desirable to search the Unity registry. If you want to remove it from the registry list, run with the `--no-upstream` option. + +```sh +openupm --registry https://package.my-registry.com https://package.openupm.com --no-upstream add com.my.package +``` + +The resulting query is: + +1. The private registry (https://package.my-registry.com) +2. Openupm (https://package.openupm.com)