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 view all your projects with the projects command and switch between them with the switch command.

A project can contain many branches for managing 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 lib.install 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.

Keep your local branch structure clean with the branch.delete command, to prune away branches that are no longer needed.