🗺 A tour of Unison

This document walks through the basics of using the Unison codebase manager and writing Unison code. We will introduce bits and pieces of the core Unison language and its syntax as we go. The Unison language documentation is a more in-depth resource if you have questions or want to learn more.

If you want to follow along with this document (highly recommended), this guide assumes you've already gone through the steps inthe quickstart guideand skimmed throughthe big idea.

👋 to the Unison codebase manager

The Unison Codebase Manager, or UCM for short, is the command line tool that runs the Unison programming language and allows you to interact with the Unison code you've written and saved. Put differently, the UCM is the interface to your Unison codebase.

💡 Remember: Unison code is not saved as text-based file content. Because of this, we need a tool that lets us change and run Unison programs.

Its many responsibilities include:

Typechecking and compiling new code
Organizing, navigating, and finding Unison definitions
Storing the state of your codebase
Running Unison programs and Unison binaries
Publishing and pulling Unison libraries

🎉 Running the UCM

By default, runningucmin a directory will interact with any.usuffixed file in the directory where the command was issued while opening the default codebase in your home directory. You'll get a message in the UCM like:

Now starting the Unison Codebase Manager (UCM)...

[…]

Get started:

  📖 Type help to list all commands, or help <cmd> to view help for one command
  🎨 Type ui to open the Codebase UI in your default browser
  📚 Read the official docs at https://www.unison-lang.org/learn/
  🌏 Visit Unison Share at https://share.unison-lang.org to discover libraries
  👀 I'm watching for changes to .u files under /Users/rebeccamark/Unison/website3/website

 .>

What's happening here? This is the Unison Codebase Manager starting up and initializing a fresh codebase. We're used to thinking about our codebase as a bag of text files that's mutated as we make changes to our code, but in Unison the codebase is represented as a collection of serialized syntax trees, identified by a hash of their content and stored in a collection of files inside of a.unisondirectory in the path you supplied to the ucm.

The Unison codebase format has a few key properties:

It isappend-only:once a file in the.unisondirectory is created, it is never modified or deleted, and files are always named uniquely and deterministically based on their content.
As a result, a Unison codebase can be versioned and synchronized with Git or any similar tool and will never generate a conflict in those tools.

The codebase location the UCM drops you in if you have never used it before is represented by the.in the prompt,.>.We call this "the root" of your codebase.

Rather than creating multiple codebases for each application you're working on, Unison subdivides the codebase into "projects". We'll introduce the concept of projects by creating one for thistourand establishing some conventions for organizing it.

Unisonprojectsare analogous to source code repositories. They help organize your codebase into applications, libraries, and other work that you may want to collaborate with others on or shrare. Projets are further divided intobranchesfor representing independent work streams.

Inside a project, your code is further organized into Unisonnamespaces.Namespaces are mappings from human-readable names to their definitions. Names in Unison are things like:math.sqrt,base.Optional.Some,base.Nat,base.Nat.*,++,orfoo.That is: an optional.,followed by one or more segments separated by a.,with the last segment allowed to be an operator name like*or++.

We often think of these name segments as forming a tree, much like a directory of files where names are like file paths in the tree. It's most common to work with your UCM prompt at the root of the project, but you can also navigate through the namespace tree with thenamespace(or equivalentlycd)command.

In the codebase manager console, create atourproject with theproject.createcommand. This is where you'll be adding code for the remainder of this guide.

.> project.create tour

   🎉 I've created the project tour.


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


   🎨 Type `ui` to explore this project's code in your browser.
   🌏 Discover libraries at https://share.unison-lang.org
   📖 Use `help-topic projects` to learn more about projects.

   Write your first Unison code with UCM:

     1. Open scratch.u.
     2. Write some Unison code and save the file.
     3. In UCM, type `add` to save it to your new project.

   🎉 🥳 Happy coding!

tour/main>

Notice the prompt changes totour/main>,indicating your current project is nowtourand your current branch is/main.When editing Unison code, and interacting with the UCM your UCM commands and code are "scoped" to this project and branch unless otherwise indicated with anabsolute path.

When you create a new project, the UCM automatically installs thebasestandard library for you. It's located in a special namespace calledlib.

🧠

Unison looks for project dependencies directly under theproject root.Thelibdirectory in ourtourproject will contain all the dependencies necessary for running the code in the project.

Let's explore thebaselibrary that was just downloaded and get used to navigating a Unison codebase.

You can view the terms and types in a namespace with thelsucm command.

tour/main> ls lib.base.data.List

The output should be a numbered list of definitions and their associated signatures.

tour/main> ls lib.base.data.List

1.   ++                    ([a] -> [a] -> [a])
2.   +:                    (a -> [a] -> [a])
3.   :+                    ([a] -> a -> [a])
4.   Nonempty              (type)
[…]

Because of the append-only nature of the codebase format, we can cache all sorts of interesting information about definitions in the codebase andnever have to worry about cache invalidation.For instance, Unison is a statically-typed language and we know the type of all definitions in the codebase, so one thing that's useful and easy to maintain is an index that lets us search for definitions in the codebase by their type. Try out the following twofindcommands (new syntax is explained below):

tour/main> find reverse

1.  lib.base.data.List.Nonempty.reverse : List.Nonempty a -> List.Nonempty a
2.  lib.base.data.List.reverse : [a] -> [a]
3.  lib.base.Text.reverse : Text -> Text
4.  lib.base.data.List.Nonempty.reverse.doc : Doc

Thefindcommand here is searching for definitions whose names includereverse.It searches first within our own code in the project, and then in the dependencies inlib.

tour/main> find : [a] -> [a]

 1. lib.base.data.deprecated.Heap.sortDescending : [a] -> [a]
 2. lib.base.data.deprecated.Heap.sort : [a] -> [a]
 3. lib.base.data.List.distinct : [a] -> [a]
 4. lib.base.data.List.sort : [a] -> [a]
 5. lib.base.data.List.dropLast : [a] -> [a]
 6. lib.base.data.List.reverse : [a] -> [a]

tour/main> view 6

  lib.base.data.List.reverse : [a] -> [a]
  lib.base.data.List.reverse as = List.foldLeft (acc a -> a +: acc) [] as

Here, we did a type-based search, withfindfollowed by a colon,:,to search for functions of type[a] -> [a].We got a list of results, and then used theviewcommand to look at the nicely formatted source code of one of these results. Let's introduce some Unison syntax:

List.reverse : [a] -> [a]is the syntax for giving a type signature to a definition. We pronounce the:symbol as "has type", as in reverse has the type[a] -> [a].
[Nat]is the syntax for the type consisting of lists of natural numbers (terms like[0, 1, 2]and[]will have this type), and more generally[Foo]is the type of lists whose elements have some typeFoo.
Any lowercase variable in a type signature is assumed to beuniversally quantified,so[a] -> [a]really means and could be writtenforall a . [a] -> [a],which is the type of functions that take a list whose elements are some type, and return a list of elements of that same type.
List.reverse astakes one parameter, calledas.The stuff after the=is called thebodyof the function, and here it's ablock,which is demarcated by whitespace.
acc a -> ..is the syntax for an anonymous function.
Function arguments are separated by spaces and function application binds tighter than any operator, sof x y + g p qparses as(f x y) + (g p q).You can always use parentheses to control grouping more explicitly.

Names are stored separately from definitions so renaming is fast and 100% accurate

The Unison codebase, in its definition forList.reverse,doesn't store names for the definitions it depends on (like theList.foldLeftfunction); it references these definitions via their hash. As a result, changing the name(s) associated with a definition is easy.

Let's try this out.List.reverseis defined usingList.foldLeft.Let's rename that toList.foldlto make it more familiar to Haskell fans. Try out the following command (you can use tab completion here if you like):

tour/main> move.term lib.base.data.List.foldLeft lib.base.data.List.foldl

  Done.

tour/main> view lib.base.data.List.reverse

  lib.base.data.List.reverse : [a] -> [a]
  lib.base.data.List.reverse as =
     use base.data.List +:
     base.data.List.foldl (acc a -> a +: acc) [] as

Notice thatviewshows thefoldlname now, so the rename has taken effect. Nice!

To make this happen, Unison just changed the name associated with the hash ofList.foldLeftin one place.Theviewcommand looks up the names for the hashes on the fly, right when it's printing out the code.

Unisonisn'tdoing a bunch of text mutation on your behalf, updating possibly thousands of files, generating a huge textual diff, and also breaking a bunch of downstream library users who are still expecting that definition to be called by the old name. The two names are, to Unison, the same thing.

So rename and move things around as much as you want! Don't worry about picking a perfect name the first time. Give the same definition multiple names if you so choose! Naming things is hard enough, renaming them shouldn't be a trial.

The fact that Unison codebases are immutable and append-only means that we can "rewind" our codebase to an earlier point in time. Use thereflogcommand to see a log of the codebase changes. You should see some help text and a numbered list of hashes.

1. #2cbugd57qa : move.term lib.base.data.List.foldLeft lib.base.data.List.foldl
2. #na6fel77ai : project.create tour
3. #sjg2v58vn2 : (initial reflogged namespace)

Reflog keeps track of the history of the codebase by recording the hash of the rootnamespaceof your entire codebase. Namespace hashes change along with updates to the term and type definitions that they enclose. When we renamedList.foldLeft,conceptually, the "state" of the codebase changed, but the log-based format of the codebase history means those changes are retrievable.

Let's try to undo the rename action. Use thereset-rootcommand to pick a prior codebase state to return to. We'll give it the hash of the codebase from just before themove.termcommand was issued.

tour/main> reset-root #na6fel77ai

  Done.

Great! OK, go drink some water, 🚰 and then let's start writing some Unison code!

Unison's interactive scratch files

The codebase manager lets you make changes to your codebase and explore the definitions it contains, but it also listens for changes to any file ending in.uin the current directory. When any such file is saved (which we call a "scratch file"), Unison parses and typechecks that file. Let's try this out.

Keep yourucmterminal running and open up a file,scratch.u(orfoo.u,or whatever you like) in your preferred text editor (if you want syntax highlighting for Unison files,follow this linkfor instructions on setting up your editor).

Now put the following in your scratch file:

use base
square : Nat -> Nat
square x =
  use Nat *
  x * x

This defines a function calledsquare.It takes an argument calledxand it returnsxmultiplied by itself.

The first line,use base,tells Unison that you want to use short names for the base libraries in this file (which allows you to sayNatinstead of having to saybase.Nat).The UCM will prefer thebaseinstance found inlib.

When you save the file, Unison replies:

✅

I found and typechecked these definitions in ~/unisoncode/scratch.u. If you do an
`add` or `update` , here's how your codebase would change:

  ⍟ These new definitions are ok to `add`:

    square : base.Nat -> base.Nat

Now evaluating any watch expressions (lines starting with `>`)… Ctrl+C cancels.

It typechecked thesquarefunction and inferred that it takes a natural number and returns a natural number, so it has the typeNat -> Nat.It also tells us thatsquareis "ok toadd."We'll do that shortly, but first, let's try calling our function right in thescratch.ufile, just by starting a line with>:

use base

square : Nat -> Nat
square x = x * x

> square 4

And Unison prints:

6 | > square 4
      ⧩
      16

That6 |is the line number from the file. The> square 4on line 6 of the file, starting with a>is called a "watch expression", and Unison uses these watch expressions instead of having a separate read-eval-print-loop (REPL). The code you are editing can be run interactively as you go, with a full text editor at your disposal, with the same definitions all in scope, without needing to switch to a separate tool.

Theuse baseis awildcard use clause.This lets us use anything from thebasenamespace under thelibnamespace unqualified. For example we refer tobase.Natas simplyNat.

Question:do we really want to reevaluate all watch expressions on every file save? What if they're expensive? Luckily, Unison keeps a cache of results for expressions it evaluates, keyed by the hash of the expression, and you can clear this cache at any time without ill effects. If a result for a hash is in the cache, Unison returns that instead of evaluating the expression again. So you can think of and use your.uscratch files a bit like spreadsheets, which only recompute the minimal amount when dependencies change.

🤓

There's one more ingredient that makes this work effectively, and that's functional programming. When an expression has no side effects, its result isdeterministic,and you can cache it as long as you have a good key to use for the cache, like the Unison content-based hash. Unison's type system won't let you do I/O inside one of these watch expressions or anything else that would make the result change from one evaluation to the next.

Let's try out a few more examples:

-- A comment, ignored by Unison

> List.reverse [1,2,3,4]
> 4 + 6
> 5.0 / 2.0
> not true

✅

~/unisoncode/scratch.u changed.

Now evaluating any watch expressions (lines starting with
`>`)… Ctrl+C cancels.

  6 | > List.reverse [1,2,3,4]
        ⧩
        [4, 3, 2, 1]

  7 | > 4 + 6
        ⧩
        10

  8 | > 5.0 / 2.0
        ⧩
        2.5

  9 | > not true
        ⧩
        false

Testing your code

Let's add a test for oursquarefunction:

square : Nat -> Nat
square x = x * x

test> square.tests.ex1 =
   use Nat ==
   check (square 4 == 16)

Save the file, and Unison comes back with:

8 | test> square.tests.ex1 = check (square 4 == 16)

✅ Passed : Proved.

Some syntax notes:

Thetest>prefix tells Unison that what follows is a test watch expression. Note that we're also giving a name to this expression,square.tests.ex1.
There's nothing special about the namesquare.tests.ex1;we could call those bindings anything we wanted. Here we use the convention that tests for a definitionfoogo infoo.tests.

Thetest.checkfunction has the signaturetest.check : Boolean -> [test.Result].It takes aBooleanexpression and gives back a list of test results, of type[base.test.Result](tryview test.Result).In this case there was only one result, and it was a passed test.

A property-based test

Let's test this a bit more thoroughly.squareshould have the property thatsquare a * square b == square (a * b)for all choices ofaandb.The testing library supports writing property-based tests like this. There's some new syntax here, explained afterwards:

use base

square : Nat -> Nat
square x = x * x

use test

test> square.tests.ex1 = check (square 4 == 16)

test> square.tests.prop1 =
  go _ = a = !gen.natInOrder
         b = !gen.natInOrder
         expect (square a * square b == square (a * b))
  runs 100 go

11 |   go _ = a = !natInOrder

✅ Passed : Passed 100 tests.

This will test our function with a bunch of different inputs.

Syntax notes

The Unison block, which begins after an=,can have any number ofbindings(likea = …)all at the same indentation level, terminated by a single expression (hereexpect (square ..)),which is the result of the block.
You can call a function parameter_if you just plan to ignore it. Here,goignores its argument; its purpose is just to makegolazily evaluatedso it can be run multiple times by therunsfunction.
natInOrderis adelayed computation.A delayed computation is one in which the result is not computed right away. The signature for a delayed computation can be thought of as a function with no arguments, returning the eventual result:() -> a.The!in!gen.natInOrderevaluates the delayed computation, summoning a value of typeNat.
natInOrdercomes fromtest-test.gen.natInOrder.It's a "generator" of natural numbers.!natInOrdergenerates one of these numbers starting at 0 and incrementing by one each time it is called.

Adding code to the codebase

Thesquarefunction and the tests we've written for it are not yet part of the codebase. So far they only exist in our scratch file. Let's add them now. Switch to the UCM and typeadd.You should get something like:

tour/main> add

  ⍟ I've added these definitions:

    square             : Nat -> Nat
    square.tests.ex1   : [Result]
    square.tests.prop1 : [Result]

You've just added a new function and some tests to your Unison codebase under thetournamespace. Try typingview squareorview square.tests.prop1.Notice that Unison inserts preciseusestatements when rendering your code.usestatements aren't part of your code once it's in the codebase. When rendering code, a minimal set ofusestatements is inserted automatically by the code printer, so you don't have to be precise with yourusestatements.

If you typetestat the Unison prompt, it will "run" your test suite:

tour/main> test

  Cached test results (`help testcache` to learn more)

  ◉ square.tests.ex1      : Proved.
  ◉ square.tests.prop1    : Passed 100 tests.

  ✅ 2 test(s) passing

  Tip: Use view square.tests.ex1 to view the source of a test.

But actually, it didn't need to run anything! All the tests had been run previously and cached according to their Unison hash. In a purely functional language like Unison, tests like these are deterministic and can be cached and never run again. No more running the same tests over and over again!

Moving and renaming terms

When we addedsquare,we were at thetournamespace, sosquareand its tests are attour.square.We can also move the terms and namespaces to different locations in our codebase with themovecommands.

tour/main> move.term square mySquare

  Done.

tour/main> find

  1.  mySquare : base.Nat -> base.Nat

tour/main> move.namespace square.tests mySquare.tests

  Done.

When you're done shuffling some things around, you can usefindwith no arguments to view all the definitions under the current namespace:

tour/main> find

  1. mySquare : Nat -> Nat
  2. mySquare.tests.ex1 : [Result]
  3. mySquare.tests.prop1 : [Result]

Also notice that we don't need to rerun our tests after this reshuffling. The tests are still cached:

tour/main> test

  Cached test results (`help testcache` to learn more)

  ◉ mySquare.tests.ex1       : Proved.
  ◉ mySquare.tests.prop1     : Passed 100 tests.

  ✅ 2 test(s) passing

  Tip:  Use view square.tests.ex1 to view the source of a test.

We get this for free despite the renaming because the test cache is keyed by the hash of the test, not by what the test is called.

When you're starting out writing some code, sometimes it's nice to put it in a temporary namespace, perhaps calledtemporscratch.Later, without breaking anything, you can move that namespace or bits and pieces of it elsewhere, using themove.term,move.term,andmove.namespacecommands.

Modifying existing definitions

Instead of starting a function from scratch, often you just want to slightly modify something that already exists. Here we'll make a change to the implementation of ourmySquarefunction.

Using the`edit`command

Try enteringedit mySquarein the UCM:

tour/main> edit mySquare
  ☝️

  I added these definitions to the top of ~/unisoncode/scratch.u

    mySquare : Nat -> Nat
    mySquare x =
      use Nat *
      x * x

  You can edit them there, then do `update` to replace the definitions currently in this branch.

This copies the pretty-printed definition ofmySquareinto your scratch file "above the fold." That is, it adds a line starting with---and puts whatever was already in the file below this line. Unison ignores any file contents below the fold.

Let's editmySquareand instead definemySquare x(just for fun) as the sum of the firstxodd numbers (here's anice geometric illustration of why this gives the same results):

use base

mySquare : Nat -> Nat
mySquare x =
  sum (map (x -> x * 2 + 1) (range 0 x))

sum : [Nat] -> Nat
sum = foldLeft (+) 0

✅

I found and typechecked these definitions in ~/unisoncode/scratch.u. If you do an
''add'' or ''update'' , here's how your codebase would change:

    ⍟ These new definitions are ok to `add`:

      sum : [Nat] -> Nat

    ⍟ These names already exist. You can `update` them to your new definition:

      mySquare : Nat -> Nat

Adding an updated definition to the codebase

Notice the message says thatmySquareis ok toupdate.Let's try that:

tour/main> update

  ⍟ I've added these definitions:

    sum : [Nat] -> Nat

  ⍟ I've updated these names to your new definition:

    mySquare : Nat -> Nat

Only affected tests are rerun on`update`

If we rerun the tests, the tests won't be cached this time, since one of their dependencies has actually changed:

tour/main> test

  ✅

    New test results:

  ◉ mySquare.tests.ex1      : Proved.
  ◉ mySquare.tests.prop1    : Passed 100 tests.

  ✅ 2 test(s) passing

  Tip: Use view mySquare.tests.ex1 to view the source of a test.

Notice the message indicates that the tests weren't cached. If we dotestagain, we'll get the newly cached results.

The dependency tracking for determining whether a test needs rerunning is 100% accurate and is tracked at the level of individual definitions. You'll only rerun a test if one of the individual definitions it depends on has changed.

Publishing code and installing Unison libraries

🎉

The last you'll need to do to get set up to write Unison code is to sign up for Unison-share! Head toUnison Shareand follow the instructions there to link your local codebase for code hosting!

Code is published to Unison's own code hosting solution,Unison Share,using thepushcommand and libraries are installed via thepullcommand. There's no separate tooling needed for managing dependencies or publishing code, and you'll never encounter dependency conflicts in Unison.

Absolute path

An absolute path is a path that starts at the root of the codebase. Absolute paths are prefixed with a dot,.,and are used to refer to namespaces.

aProject/main> merge .absoluteNamespace.path lib.base

add

.> add

.> add myNewTerm

Adds all the definitions from the most recently typechecked file to the codebase.

FAQ about theaddcommand

I got an error about "these definitions failed" on add

This message happens when some of the definitions couldn't be added to the codebase. UCM shows a table of definitions along with the reason why they didn't succeed, like this:

x These definitions failed:

Reason
needs update   myFunction : Doc

Here's what these reasons mean:

needs update:The scratch file has a definition with the same name as an existing definition. Doingupdateinstead of add will turn this failure into a successful update.
conflicted:The file has a definition whose name is currently conflicted. Resolving the conflict and then trying an update again will turn this into a successful update.
term/ctor collision:A definition with the same name as an existing constructor for some data type. Rename your definition or the data type before trying again toaddorupdate.
ctor/term collision:A type defined in the file has a constructor that's named the same as an existing term. Rename that term or your constructor before trying again toaddorupdate.
needs alias:A definition in the file already has another name. You can use thealias.termoralias.typecommands to create new names for existing definitions.
blocked:This definition couldn't be added because it dependended on another definition in the file that had a failed status.
extra dependency:This definition was added because it was a dependency of a definition explicitly selected.

I want to undo a partially completed add where some of the definitions failed

You can use theundocommand in the case of an undesired partially completed add.

`use`clause

The use clause allows code in the currentlexical scopeto use terms and types in the given namespace without referencing them by their fully qualified names.

use Nat drop +

(drop 5 4) + 8

usecan be called without referencing specific terms--''use List'' brings everything under theListnamespace into scope, or it can reference specific definitions, as in,use List map flatMap

update

adds all definitions in the .u file, noting replacements in the default patch for the current namespace.

.> update

.> update <patch>

adds all definitions in the .u file, noting replacements in the specified patch.

.>
update <patch> foo bar

addsfoo,bar,and their dependents from the .u file, noting any replacements into the specified patch.

updateworks likeadd,except that if a definition in the file has the same name as an existing definition, the name gets updated to point to the new definition. If the old definition has any dependents,updatewill add those dependents to a refactoring session, specified by an optional patch.

push

Pushing from within a project:

myProject/branch> push
@othersProject/feature> push /@myUser/feature

Pushing a namespace to a remote namespace:

.> push git(git@github.com:myUser/myCodebase).releases.v1 .update.v1
.> push myUser.public.myProject .myProject

Thepushcommand is used to push definitions from a local codebase to a remote codebase.

The first argument topushis any hosted project or remote namespace path that identifies the location to push to and the second argument (if given) identifies a namespace or project in the local codebase that should be applied to the remote repo. If a second argument is not supplied, then the current namespace or project will be pushed to the given remote namespace.

pull

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(git@github.com:unisonweb/base).latest .base
.> pull git(https://github.com/org/repo:some-branch).some.path

Thepullcommand 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.

👋 to the Unison codebase manager

🎉 Running the UCM

Names are stored separately from definitions so renaming is fast and 100% accurate

Unison's interactive scratch files

Testing your code

A property-based test

Syntax notes

Adding code to the codebase

Moving and renaming terms

Modifying existing definitions

Using theeditcommand

Adding an updated definition to the codebase

Only affected tests are rerun onupdate

Publishing code and installing Unison libraries

What next?

Unison project

Unison branch

Namespace

cd

Absolute path

ls

view

view

view

reflog

Namespace

reset-root

Deterministic

add

FAQ about theaddcommand

I got an error about "these definitions failed" on add

I want to undo a partially completed add where some of the definitions failed

useclause

move.term

move.type

move.namespace

update

push

Git urls

pull

Using the`edit`command

Only affected tests are rerun on`update`

`use`clause