Organizing your codebase with projects

One Unison codebase can house all your Unison code. In the projects quickstart we learned that your various libraries, applications, or other shareable, packageable work are described in separate projects within the codebase.

You can switch between one project to the next with the switch command, and get back to the root of your codebase with cd ..

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/1.0.0
        ReleaseNotes
      /releases/draft/1.1.0
      /featureInProgress
      /@contributor/coolContribution
        ...
        ...

- The /main branch 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 main branch you'll find the README term, 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 on Unison Share.
  - ReleaseNotes is a special term that describes the changes the library or application since the last release. If included, they'll be linked with release version.
  - - lib is a required namespace that contains the dependencies for the project. New dependencies are installed with the pull command.
    - - base is our standard library. It's downloaded automatically when you create a new project.
The /releases/draft/X.Y.Z branches are special branches created via the UCM release process, you shouldn't need to work within them directly.
Most of your Unison coding will be in branches like the /featureInProgress branch, which will later be merged into main once finished.
The /@contributor/coolContribution branch is a contributor branch, which is a branch that someone else created from a clone of the project. As part of the pull 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.delete command, to prune away branches that are no longer needed.

Summary

A codebase is subdivided into many projects
Projects have a main branch for the mainline of development
Inside a project, "README" and "ReleaseNotes" can be associated with your project in the Unison Share UI, and lib houses your dependencies
Feature branches are created from main and merged back into main when finished
Contributor branches are created from a clone of the project and merged back into a branch of your choice

pull

Downloading a project dependency:

myProject/main> pull @unison/base/releases/X.Y.Z lib.base

Pulling a public namespace:

scratch/main> pull unison.public.base.latest lib.base

Using git urls:

scratch/main> pull git(git@github.com:unisonweb/base).latest .base
scratch/main> pull git(https://github.com/org/repo:some-branch).some.path

For Unison version 0.5.21 and later, use libInstall to install libraries.

The pull command 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 share or from a git repo using the git url format.

The first argument to pull is 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.

Where to next?

Unison project

Git urls

pull

Contributor branch