Organizing your codebase with projects

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 separateprojectswithin the codebase.

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

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:

    • The/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 themainbranch you'll find theREADMEterm, 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 thepullcommand.
          • baseis our standard library. It's downloaded automatically when you create a new project.
  • 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 intomainonce finished.
  • The/@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 thebranch.deletecommand, to prune away branches that are no longer needed.


  • A codebase is subdivided into many projects
  • Projects have amainbranch for the mainline of development
  • Inside a project, "README" and "ReleaseNotes" can be associated with your project in the Unison Share UI, andlibhouses your dependencies
  • Feature branches are created frommainand merged back intomainwhen finished
  • Contributor branches are created from acloneof the project and merged back into a branch of your choice