One Unison codebase can house all your Unison code.In the projects quickstartwe learned that your various libraries, applications, or other shareable, packageable work are described in separate
projectswithin the codebase.
You can switch between one project to the next with the
switchcommand, and get back to the root of your codebase with
A project can contain many branches to manage Unison work streams. Here's a sample project with some example branches and terms. We'll talk through what each of them mean next:
myProject /main README ReleaseNotes lib base /releases/draft/1.0.0 ReleaseNotes /releases/draft/1.1.0 /featureInProgress /@contributor/coolContribution ... ...
/mainbranch is the mainline branch for the project containing the codebase history of changes. It's the default branch that you clone when you want to contribute to a project.
- Within the
mainbranch you'll find the
READMEterm, which is a term that describes the project. If included at the top-level of the project, it will be displayed on the project's home page onUnison Share.
ReleaseNotesis a special term that describes the changes the library or application since the last release. If included, they'll be linked with release version.
libis a required namespace that contains the dependencies for the project. New dependencies are installed with the
baseis our standard library. It's downloaded automatically when you create a new project.
- Within the
/releases/draft/X.Y.Zbranches are special branches created via theUCM release process,you shouldn't need to work within them directly.
- Most of your Unison coding will be in branches like the
/featureInProgressbranch, which will later be merged into
/@contributor/coolContributionbranch is acontributor branch,which is a branch that someone else created from a clone of the project. As part of thepull request process,you'll review the code in the contributor branch and merge it back into another branch.
You can keep your local branch structure clean with the
branch.deletecommand, to prune away branches that are no longer needed.
- A codebase is subdivided into many projects
- Projects have a
mainbranch for the mainline of development
- Inside a project, "README" and "ReleaseNotes" can be associated with your project in the Unison Share UI, and
libhouses your dependencies
- Feature branches are created from
mainand merged back into
- Contributor branches are created from a
cloneof the project and merged back into a branch of your choice
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(firstname.lastname@example.org:user/repo)refers to the root of a git repository
git(email@example.com:user/repo).some.remote.pathrefers to the
.some.remote.pathnamespace of the git repository
git(firstname.lastname@example.org: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(email@example.com:" (which you can complete with org/reponame.git)
glsto "git(firstname.lastname@example.org:" (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(email@example.com: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.
A contributor branch is a special type of branch that represents when a user is working on another person's project. When you
cloneanother user's project, you're creating a new branch of the project that is associated with your Unison Share username. Contributor branches take the form