🗄 Unison projects introduction

A Unison project represents a library, application, or other code package that can be shared, collaborated on, and versioned. You'll create and manipulate projects with a few simple UCM commands and can view your projects on Unison Share. One Unison codebase typically houses multiple projects, each with its own dependencies, branches, and code structure.

✨

Some things that you'll end up doing with projects include:

  • Specifying if a package is public or private
  • Working on a branch of a project without affecting the mainline
  • Creating a pull request that can be reviewed and merged by others
  • Adding a dependency on a library
  • Releasing a new version of a library

🏁 Projects quickstart

Let's walk through a quick example of how to navigate a Unison codebase with projects. We'll create a new project, add a project library dependency, create and merge a branch in our project, and push it to Unison Share.

Let's create a new project called helloProjects now:

scratch/main> project.create helloProjects

  🎉 I've created the project helloProjects.

  I'll now fetch the latest version of the base Unison library...

helloProjects/main>

In the UCM, your console prompt will be updated to indicate that you're in the helloProjects project; the segment prefixed by a slash, /main, is a branch of the project. Branches allow for concurrent work streams, long-lived feature work, PR's, etc.

Let's create a new branch instead of working on main directly.

helloProjects/main> branch myNewBranch

  Done. I've created the myNewBranch branch based off of main

  Tip: Use `merge /myNewBranch /main` to merge your work back
       into the main branch.

branch creates a new branch of the project from the current branch. In this case myNewBranch is a copy of main and contains all the same code and history. Take a look around at the branches of the current project with the branches command and we should see both main and myNewBranch.

helloProjects/myNewBranch> branches

       Branch        Remote branch
  1.   main
  2.   myNewBranch

Upon creating a new project, the UCM installs the base standard library as a dependency in the lib namespace for you. The UCM looks for project dependencies in a lib namespace located at the root of the project. Let's add another dependency on the cloud project with the lib.install command.

If you ever forget the command for downloading a library, the Unison Share UI shows you the latest download command when you navigate to the project's home page.

helloProjects/myNewBranch> lib.install @unison/cloud

This will install the latest version of the cloud project into the lib namespace.

When we're within a project, the existing UCM commands for navigating and viewing namespaces work as before. Let's take a look at the cloud project we just pulled in.

helloProjects/myNewBranch> ls lib.unison_cloud_20_16_0

  1.  AccessToken        (type)
  2.  AccessToken/       (2 terms)
  3.  CHANGELOG          (base.Doc)
  4.  CHANGELOG/         (1 term)

Open up a scratch.u file in a text editor window and add the following Unison code to it. Save the file when you're ready to add it to the codebase.

README = {{
  # Hello Projects

  This is a simple Unison project.
}}

helloWorld : '{IO, Exception} ()
helloWorld = do
  printLine ("Hello " ++ "yourName")

Use the update command in the UCM so the helloWorld function will be present in myNewBranch. In Unison, we don't have specific named "commits", just additions to the codebase state.

We'll merge this branch back into the main branch next.

helloProjects/myNewBranch> update

  ⍟ I've added these definitions:

    README     : Doc
    helloWorld : '{IO, Exception} ()

merge takes two arguments, the source and the destination, respectively. We can indicate that we are merging a branch into another branch by prefixing the branch name with a slash.

helloProjects/myNewBranch> merge /myNewBranch /main

  Here's what's changed in helloProjects/main after the merge:

  Added definitions:

    1. README     : Doc
    2. helloWorld : '{IO, Exception} ()
✨

The UCM commands for managing projects allow you to drop the project name from the command if you are referencing the same project that or branch your UCM prompt is currently located in.

helloProjects/main> merge helloProjects/myNewBranch helloProjects/main

The above command is equivalent to:

helloProjects/main> merge /myNewBranch

Switch back to the main branch with the switch command, and optionally delete your old feature branch. Now that we've merged our changes into the main branch, we can push our project to Unison Share.

helloProjects/myNewBranch> switch main
helloProjects/main> delete.branch myNewBranch

First log into Unison Share with the auth.login command. Once logged in, we'll use the push command to do this. Pushing a project to Unison Share will automatically create a remote mapping between the local branch and the remote branch.

helloProjects/main> push

Head to the Unison Share url displayed by the UCM to view your project. You'll see that the main branch is hosted there and the project's welcome page includes your README.

Finally, view a list of your projects with the projects command. You can always get back to your project with the switch command. switch helloProjects will take you back to the last branch you were working on.

helloProjects/main> projects

  1. anotherHypotheticalProject

helloProjects/main> switch anotherHypotheticalProject

Hooray! You have just created what we hope will be the first of many new Unison projects! Happy coding! 😎

More about projects in Unison

🌟 Full list of common workflows for projects

📚 Projects FAQ's

📚 Codebase organization