This doc walks through the process of updating a dependency which has been released as aUnison project.The following workflow uses Unison's standard library,
base,as an example.
pullthe new version of the library into the
libnamespace of your project. It shouldnotbe pulled into the same namespace as your existing library version. Instead, give the new version a distinct name, like
newBase.We can change the name later. The exact version number of library you want to install can be found by visiting the project's home page onUnison Share.Click the big green button called "Use Project" to get a copy of the command to run.
myProject/upgradeBase> pull @unison/base/releases/X.Y.Z lib.newBase
Then apply the the patch from the new library version to the project. Assuming your UCM console is located at the top of your project, you can use the patch command like so:
myProject/upgradeBase> patch lib.newBase.patch
Patches map old term references to new references in a namespace; they're part of what helps Unison automatically propagate changes when functions get updated. Patch entries are created automatically when the library author runs
Next you should check if there are
todoitems in your project as a result of applying the patch. At the root of your project, run
Todo items can happen if a function in your project depends on a function in the library whose type signature has changed in the new version. If there are
todoitems after applying the patch, the UCM should supply a suggested order to tackle them in. You'll want to edit the terms into a scratch file, resolve the conflicts and then
Once there are no
todoitems it's safe to delete the old library version from the
libnamespace of the project. You may want to rename your new library version to
baseagain so that it's easier to refer to in the future.
myProject/upgradeBase> delete.namespace lib.base myProject/upgradeBase> rename.namespace lib.newBase lib.base
Finally, merge the
mainand delete your upgrade branch.
myProject/upgradeBase> merge /upgradeBase /main myProject/upgradeBase> delete.branch /upgradeBase
It's done! Your project is now using the latest version of the dependency!
A Unison project is a Unison codebase concept that represents a library, application, or other code package that can be shared, collaborated on, and versioned. You can create and manipulate projects with UCM commands and view your projects on Unison Share.
UCM commands like
pullcan reference git urls for Unison code which is not hosted on Unison's own code-hosting platform, Unison Share.
This can have which have one of the following forms:
git(email@example.com:user/repo)refers to the root of a git repository
git(firstname.lastname@example.org:user/repo).some.remote.pathrefers to the
.some.remote.pathnamespace of the git repository
git(email@example.com:user/repo:some-branch)pulls a git branch called
some-branchfrom the git repository
some.remote.pathnamespace from a branch of the repository
The UCM tab completion provides some handy shortcuts:
ghto "git(https://github.com:" (which you can complete with org/reponame.git)
ghsto "git(firstname.lastname@example.org:" (which you can complete with org/reponame.git)
glsto "git(email@example.com:" (which you can finish with org/reponame.git)
Downloading a project dependency:
myProject/main> pull @unison/base/releases/X.Y.Z lib.base
Pulling a public namespace:
.> pull unison.public.base.latest lib.base
Using git urls:
.> pull git(firstname.lastname@example.org:unisonweb/base).latest .base .> pull git(https://github.com/org/repo:some-branch).some.path
pullcommand is used to pull definitions from another codebase into the current codebase. Commonly used to download Unison dependencies.
You can pull Unison code from unison's own code-hosting platform,unison shareor from a git repo using thegit url format.
The first argument topullis any Git URL that identifies the namespace to pull from and the second argument (if given) identifies a namespace that the remote codebase will be merged into. If a second argument is not supplied, then the remote codebase will be merged into the current namespace.
To optionally pull from a Git branch, the repository name is followed by
:and the name of the branch.