### Install Unison Codebase UI

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Fetches and installs the latest release of the Unison codebase UI. This step is optional if you do not intend to run the UI locally.

```Shell
./dev-ui-install.hs
```

--------------------------------

### Install Stack

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Installs the Stack build tool, which is a prerequisite for building and running the Unison project. Follow the official documentation for detailed installation instructions.

```Shell
https://docs.haskellstack.org/en/stable/README/#how-to-install
```

--------------------------------

### Initial Project Setup and Merge

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

Demonstrates merging built-in libraries into a Unison project and defining initial code.

```ucm
proj/main> builtins.merge lib.builtin
```

```unison
lib.old.foo = 17
lib.new.foo = +18
thingy = lib.old.foo + 10
```

--------------------------------

### Unison UCM Commands Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Shows example commands executed within the Unison Compute Machine (UCM) environment. These commands are used for loading files and merging libraries.

```ucm
scratch/main> builtins.mergeio lib.builtins
scratch/main> load unison-src/transcripts-using-base/doc.md.files/syntax.u
```

--------------------------------

### Initialize and Run Unison

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Starts the Unison executable, initializing a codebase in the user's home directory (~/.unison) if it doesn't exist. It also watches for .u file changes in the current directory.

```Shell
stack exec unison
```

--------------------------------

### Unison Codebase Configuration File

Source: https://github.com/unisonweb/unison/blob/trunk/docs/configuration.md

Example syntax for the `.unisonConfig` file, used for setting default metadata and remote mappings.

```unisonconfig
# Attach myself as author and use BSD license for all of my contributions
DefaultMetadata = [ ".metadata.authors.chrispenner"
                  , ".metadata.licenses.chrispenner" ]

# RemoteMapping allows mapping a path in the codebase to a specific location on share.

```

--------------------------------

### Build Unison with Cabal

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Commands to build all projects, run tests, and install the Unison executable using Cabal. Requires specifying the project file location.

```Shell
cabal v2-build --project-file=contrib/cabal.project all
```

```Shell
cabal v2-test --project-file=contrib/cabal.project all
```

```Shell
cabal v2-install --project-file=contrib/cabal.project unison
```

--------------------------------

### Install Unison Plugin with vim-plug

Source: https://github.com/unisonweb/unison/blob/trunk/editor-support/vim/doc/unison.txt

Example of how to install the Unison filetype plugin using the vim-plug package manager. It specifies the repository, branch, and the relative path to the plugin's Vimscript files.

```vim
Plug 'unisonweb/unison', { 'branch': 'trunk', 'rtp': 'editor-support/vim' }
```

--------------------------------

### UCM Project Setup and Branching

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/deep-names.md

Initializes a new Unison project ('scratch/main') and creates two branches ('/app1', '/app2') to isolate dependency management scenarios.

```ucm
scratch/main> add

scratch/main> branch /app1

scratch/main> branch /app2
```

--------------------------------

### Unison Code Definitions

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

Example of defining variables and their values in Unison. Demonstrates basic arithmetic and referencing existing definitions.

```unison
lib.old.foo = 17
lib.new.foo = 18
thingy = lib.old.foo + 10
```

--------------------------------

### Unison Code Snippet Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

A simple Unison code snippet showing variable assignments and arithmetic operations, including references to other definitions.

```unison
lib.old.foo = 25
lib.new.foo = +30
a.x.x.x.x = 100
b.x.x.x.x = 100
c.y.y.y.y = lib.old.foo + 10
d.y.y.y.y = lib.old.foo + 10
bar = a.x.x.x.x + c.y.y.y.y
```

--------------------------------

### Upgrade and Reference Rewriting

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

Shows how Unison upgrades dependencies and rewrites references. This example demonstrates upgrading 'old' to 'new', removing 'old', and how a definition like 'mything' is updated to reflect the new dependency structure.

```ucm
foo/main> builtins.merge lib.builtin
lib.old.foo = 18
lib.new.other = 18
lib.new.foo = 19
mything = lib.old.foo + lib.old.foo

foo/main> add

  Okay, I'm searching the branch for code that needs to be
  updated...

  Done.

foo/main> upgrade old new

  I upgraded old to new, and removed old.

foo/main> view mything

  mything : Nat
  mything =
    use Nat +
    other + other
```

--------------------------------

### Unison Upgrade Workflow

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

Demonstrates a typical upgrade workflow in Unison, starting with merging built-ins, showing code changes detected, performing an upgrade, and verifying the results.

```ucm
proj/main> builtins.merge lib.builtin
```

```ucm
proj/main> add

  Okay, I'm searching the branch for code that needs to be
  updated...

  Done.
```

```ucm
proj/main> upgrade old new

  I upgraded old to new, and removed old.
```

```ucm
proj/main> ls lib

  1. builtin/ (582 terms, 100 types)
  2. new/     (1 term)
```

```ucm
proj/main> view thingy

  thingy : Nat
  thingy =
    use Nat +
    foo + 10
```

--------------------------------

### Unison Dependency Installation

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/help.md

Installs a specified dependency into the 'lib' namespace. Supports installation from releases by version or tag, or from a specific branch.

```APIDOC
lib.install (or install.lib)
  The `lib.install` command installs a dependency into the `lib` namespace.

  Usage:
  `lib.install @unison/base/releases/latest`  installs the latest release of `@unison/base`
  `lib.install @unison/base/releases/3.0.0`   installs version 3.0.0 of `@unison/base`
  `lib.install @unison/base/topic`            installs the `topic` branch of `@unison/base`
```

--------------------------------

### Unison Console Rendering

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Example of rendering Unison documentation to the console. It shows how to get the pretty-printed representation of a guide.

```unison
rendered = Pretty.get (docFormatConsole doc.guide)
```

--------------------------------

### Manual Installation: Windows

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/release-steps.output.md

Instructions for manually installing Unison on Windows by downloading and extracting the release zip file.

```bash
Download [the release](https://github.com/unisonweb/unison/releases/latest/download/ucm-windows.zip) and extract it to a location of your choosing.
Run `ucm.exe`
```

--------------------------------

### Manual Installation: Linux

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/release-steps.output.md

Instructions for manually installing Unison on Linux by downloading and extracting the release archive.

```bash
mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-linux.tar.gz \
    | tar -xz
./ucm
```

--------------------------------

### Unison Simplest Possible Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-round-trip/main.output.md

A minimal example demonstrating basic arithmetic and the use of a type clause, likely for testing or as a starting point.

```Unison
simplestPossibleExample : Nat
simplestPossibleExample =
  use Nat +
  1 + 1
```

--------------------------------

### NeoVim: Lazy.nvim Plugin Installation

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/language-server.output.md

Installs the Unison Vim plugin using the Lazy.nvim package manager for NeoVim. This configuration includes setup for RTP and filetype detection.

```lua
{
  "unisonweb/unison",
  branch = "trunk",
  config = function(plugin)
      vim.opt.rtp:append(plugin.dir .. "/editor-support/vim")
      require("lazy.core.loader").packadd(plugin.dir .. "/editor-support/vim")
  end,
  init = function(plugin)
       require("lazy.core.loader").ftdetect(plugin.dir .. "/editor-support/vim")
  end,
}
```

--------------------------------

### Manual Installation: macOS

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/release-steps.output.md

Instructions for manually installing Unison on macOS by downloading and extracting the release archive.

```bash
mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos.tar.gz \
  | tar -xz
./ucm
```

--------------------------------

### NeoVim: vim-plug Plugin Installation

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/language-server.output.md

Installs the Unison Vim plugin using the vim-plug package manager. This setup ensures proper integration for filetype detection and syntax highlighting.

```vim
Plug 'unisonweb/unison', { 'branch': 'trunk', 'rtp': 'editor-support/vim' }
```

--------------------------------

### Unison Project Initialization

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/branch-command.md

Demonstrates creating empty projects and merging built-in libraries, which are common setup steps before branching.

```ucm
scratch/main> project.create-empty foo

scratch/main> project.create-empty bar
```

```ucm
scratch/main> builtins.merge lib.builtins

  Done.

  Okay, I'm searching the branch for code that needs to be
  updated...

  Done.
```

--------------------------------

### Initial Unison Setup and Definition

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/merge.md

This snippet shows the initial setup command and a basic Unison code definition. It sets the stage for demonstrating name resolution differences.

```ucm
scratch/main> builtins.mergeio lib.builtins
```

```unison
hello = 17
```

--------------------------------

### Unison Code Evaluation Examples

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Illustrates how to evaluate Unison expressions and code blocks directly within documentation. Includes examples of inline evaluation and block evaluation using the '⧨' symbol.

```Unison
Expressions can be evaluated inline, for instance `2`.

Blocks of code can be evaluated as well, for instance:

    id x = x
    id (sqr 10)
    ⧨
    100

also:

    match 1 with
      1 -> "hi"
      _ -> "goodbye"
    ⧨
    "hi"
```

--------------------------------

### Unison Help Command Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/errors/obsolete-bug.md

Demonstrates how to use the `help` command in the Unison command-line interface (UCM) to get information about the 'edit' functionality. This is a common command for exploring Unison's features.

```ucm
scratch/main> help edit
```

--------------------------------

### Install Unison on Windows (Manual)

Source: https://github.com/unisonweb/unison/blob/trunk/docs/release-steps.md

Manual installation steps for Unison on Windows. This involves downloading the release zip file, extracting it, and running the executable.

```shell
Download [the release](https://github.com/unisonweb/unison/releases/latest/download/ucm-windows.zip) and extract it to a location of your choosing.
Run `ucm.exe`
```

--------------------------------

### Unison DSL Syntax Elements

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

This snippet details various syntax elements used in the Unison DSL, including literals, indentation, annotations, and example definitions. It covers how code structures and inline examples are represented.

```Unison DSL
Lit
    () (Right (Plain "include"))
, Lit
    () (Right (Plain "typechecked"))
, Lit
    () (Right (Plain "code"))
, Lit
    () (Right (Plain "snippets"))
, Lit
    () (Right (Plain "inline,"))
, Lit
    () (Right (Plain "for"))
, Lit
    () (Right (Plain "instance:"))
, Lit
    () (Right (Plain "\n"))
, Indent
    () (Lit
      () (Right (Plain "  ")))
, Annotated.Group
    () (Annotated.Group
      () (Annotated.Append
        () [
          Indent
            () (Lit
              () (Right (Plain "* ")))
          , Lit
            () (Right (Plain "  "))
          , Wrap
            () (Annotated.Append
              () [
                Lit
                  () (Left
                    (Example
                      2
                      (Term.Term
                        (Any
                          (do
                            f
                            x ->
                              f
                                x
                                Nat.+ sqr
                                  1))))))
                , Lit
                  () (Right
```

--------------------------------

### Install Unison Base Library

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/base_release_transcript.output.md

Demonstrates installing a specific version of the Unison base library using the `ucm` command. This is a prerequisite for using library functions.

```ucm
scratch/main> lib.install @unison/base/releases/3.35.0

  I installed @unison/base/releases/3.35.0 as
  unison_base_3_35_0.

```

--------------------------------

### Unison Unique Type Declarations

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/type-declarations.output.md

Shows the syntax for declaring unique types in Unison, which possess extrinsic semantics defined by a GUID. This allows for textual representation of identical types using a specified GUID, as demonstrated in the `Day` type examples.

```haskell
unique type Day = Mon | Tue | Wed | ...

unique[<guid>]
type Day = Mon | Tue | Wed | ...
```

--------------------------------

### UCM: Initial Setup and Branching

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/merge.md

Shows the initial UCM commands to set up the environment, load changes, and create a new branch ('bob') from an existing one ('alice'). This establishes the context for the merge operation.

```ucm
scratch/alice> builtins.mergeio lib.builtins

scratch/alice> add

scratch/alice> branch bob
```

--------------------------------

### Install Unison on Linux (Manual)

Source: https://github.com/unisonweb/unison/blob/trunk/docs/release-steps.md

Manual installation steps for Unison on Linux. This involves downloading the release archive, extracting it, and running the executable.

```shell
mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-linux.tar.gz \
    | tar -xz
./ucm
```

--------------------------------

### Unison Unique Type Declarations

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/type-declarations.output.md

Shows the syntax for declaring unique types in Unison, which possess extrinsic semantics defined by a GUID. This allows for textual representation of identical types using a specified GUID, as demonstrated in the `Day` type examples.

```haskell
unique type Day = Mon | Tue | Wed | ...

unique[<guid>]
type Day = Mon | Tue | Wed | ...
```

--------------------------------

### Unison TLS Client Connection Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/patternMatchTls.md

Demonstrates establishing a secure TLS connection using Unison's io2.Tls module. It covers client creation, connecting to a server, performing a handshake, sending data, and terminating the connection. This example relies on the builtin.io2.Tls module and includes a helper function for handling Either types.

```unison
use builtin.io2.Tls newClient send handshake terminate

frank: '{IO} ()
frank = do
  socket = assertRight (clientSocket.impl "example.com" "443")
  config = ClientConfig.default "example.com" 0xs
  tls = assertRight (newClient.impl config socket)
  () = assertRight (handshake.impl tls)
  () = assertRight (send.impl tls 0xs)
  () = assertRight (terminate.impl tls)
  ()

assertRight : Either a b -> b
assertRight = cases
  Right x -> x
  Left _ -> bug "expected a right but got a left"
```

--------------------------------

### Unison Merge Conflict: Type/Term Conflict Example 1

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/merge.md

Demonstrates a merge conflict where one branch redefines a type with a constructor that clashes with a term in another branch. The example shows the setup, branch operations, and the resulting merge error.

```ucm
scratch/main> builtins.mergeio lib.builtins
```

```unison
Foo.Bar : Nat
Foo.Bar = 17
```

```ucm
scratch/main> add

scratch/main> branch alice
```

```unison
unique type Foo = Alice Nat
```

```ucm
scratch/alice> add

scratch/main> branch bob
```

```ucm
scratch/bob> delete.term Foo.Bar

  Done.
```

```unison
unique type Foo = Bar Nat Nat
```

```ucm
scratch/bob> add
```

```ucm
scratch/alice> merge bob

  Loading branches...

  Loading definitions...

  Computing diffs...

  Loading dependents of changes...

  Loading and merging library dependencies...

  Rendering Unison file...

  I couldn't automatically merge scratch/bob into scratch/alice.
  However, I've added the definitions that need attention to the
  top of scratch.u.

  When you're done, you can run

    merge.commit

  to merge your changes back into alice and delete the temporary
  branch. Or, if you decide to cancel the merge instead, you can
  run

    delete.branch /merge-bob-into-alice

  to delete the temporary branch and switch back to alice.
```

```unison
-- scratch/alice
Foo.Bar : Nat
Foo.Bar = 17

-- scratch/alice
unique[q9d1rl3aatgsa0cndefhert8i6ps1ol7] type Foo = Alice Nat

-- scratch/bob
unique[kluar3l6itvegkkqpfs6kfkuvcafpi82] type Foo = Bar Nat Nat
```

```ucm
scratch/main> project.delete scratch
```

--------------------------------

### Unison CLI Command Examples

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/project-outputs/docs/branchless.output.md

Demonstrates common Unison command-line operations for managing code, including navigating directories, forking projects, merging changes, moving definitions, and creating aliases. It also shows how to view project todos and resolve conflicts.

```unison-cli
/> cd libs/Foo
/libs/Foo> cd ..
/libs> fork Foo Foo2
/libs> fork <someurl> thing
/libs> fork Foo /outside/Foo
/libs> fork /outside/Foo /outside/Foo2
/libs> help merge
	`> merge src dest`
/libs> merge /outside/Foo Foo
/libs> merge Foo2 Foo

/libs/Foo> <work work work>
/libs> move /libs/Foo /libs/Foo'
/libs>

A.B.c
A.B.d

arya renames, and has: ->
A.Z.c
A.Z.d

paul adds, and has ->
A.B.e
A.B.c
A.B.d

then merge -> 
"Merge introduces the following aliases:"
A.Z.c -> A.B.c
A.Z.d -> A.B.d

/libs> delete /libs/Foo
"warning: /libs/Foo includes the following definitions that aren't anywhere else:

	A.B.e#123

run it again to proceed with deletion"

/libs> alias /libs/Foo/sqrt /libs/Foo2/butt
-- we talked about combining alias & fork into a single "copy" command
/libs>
```

```unison-cli
/foo> todo

These names are conflicted:
  foo#abc
  foo#xyz
Use `rename` to change a names, or `unname` to remove one.

These edits are conflicted:
  bar#fff -> bar#ggg : Nat        (12 usages)
  bar#fff -> bar#hhh : Nat -> Nat (7 usages)
  bar#fff (Deprecated)

Use `view bar#ggg bar#hhh` to view these choices.
Use `edit.resolve` to choose a canonical replacement.
Use `edit.unreplace` to cancel a replacement.
Use `edit.undeprecate` to cancel a deprecation.
Use `edit.replace bar#hhh bar#ggg` to start replacing the 7 usages of `bar#hhh` with `bar#ggg`.
```

```unison-cli
/foo> edit.resolve bar#fff bar#ggg

Cleared bar#fff -> bar#hhh
Added   bar#ggg -> bar#hhh
```

```unison-cli
/foo> edit.unreplace bar#fff bar#ggg

Cleared bar#fff -> bar#ggg
```

```unison-cli
/foo> alias bar baz

Not sure which bar you meant?
  bar#ggg
  bar#hhh
Try specifying the hash-qualified name, or sort out the conflicts before
making the alias.
```

```unison-cli
/libfoo/Foo <- type
/libfoo/Foo <- constructor
/libfoo/Foo.f <- term in child namespace

/libfoo> move Foo Foo2
/libfoo> alias Foo Foo2
```

--------------------------------

### Profile a Cabal Package

Source: https://github.com/unisonweb/unison/blob/trunk/nix/README.md

Demonstrates how to enter a development environment for a specific Cabal package and run it with profiling enabled. This involves using `nix develop` and then `cabal run` with specific RTS options.

```shell
nix develop '.#cabal-unison-parser-typechecker'
cd unison-cli
cabal run --enable-profiling unison-cli-main:exe:unison -- +RTS -p
```

--------------------------------

### Haskell Code Snippet

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Example of a fenced code block for Haskell code. These blocks are intended for display and are not processed by the Unison compiler.

```Haskell
-- A fenced code block which isn't parsed by Unison
reverse = foldl (flip (:)) []
```

--------------------------------

### Scala Code Snippet

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Example of a fenced code block for Scala code. These blocks are intended for display and are not processed by the Unison compiler.

```Scala
-- A fenced code block which isn't parsed by Unison
def reverse[A](xs: List[A]) = 
  xs.foldLeft(Nil : List[A])((acc,a) => a +: acc)
```

--------------------------------

### Unison Command Line Execution Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/serial-test-03.md

This snippet demonstrates how to interact with the Unison compiler and runtime environment (ucm). It shows commands to add a file to the project (`add`) and then execute a defined Unison function (`run mkTestCase`). This is a typical workflow for running Unison programs and tests.

```ucm
scratch/main> add
scratch/main> run mkTestCase
```

--------------------------------

### IO.process.start: Start a New Process

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/all-base-hashes.output.md

Starts a new external process with the specified executable and arguments. Returns handles for stdin, stdout, stderr, and the process itself.

```Unison
builtin.io2.IO.process.start : Text
        -> [Text]
        ->{IO} (Handle, Handle, Handle, ProcessHandle)
```

--------------------------------

### Raw Code Block Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Demonstrates how to include raw, unparsed code blocks within the documentation using triple single quotes.

```raw
   _____     _             
  |  |  |___|_|___ ___ ___ 
  |  |  |   | |_ -| . |   |
  |_____|_|_|_|___|___|_|_|
  
```

--------------------------------

### Install Unison on macOS (Manual)

Source: https://github.com/unisonweb/unison/blob/trunk/docs/release-steps.md

Manual installation steps for Unison on macOS. This involves downloading the release archive, extracting it, and running the executable.

```shell
mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos.tar.gz \
  | tar -xz
./ucm
```

--------------------------------

### Find Unison Executable Path

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Locates the path to the Unison executable installed by Stack. This is useful for adding Unison to your system's PATH environment variable.

```Shell
stack exec which unison
```

--------------------------------

### Basic Upgrade and Merge

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

Demonstrates a standard upgrade operation where changes are merged into the main branch, followed by adding new definitions and performing an upgrade. It shows the initial state, the result of adding definitions, and the successful upgrade command.

```ucm
myproject/main> builtins.merge lib.builtin
lib.old.foo = 25
lib.new.foo = +30
a.x.x.x.x = 100
b.x.x.x.x = 100
c.y.y.y.y = lib.old.foo + 10
d.y.y.y.y = lib.old.foo + 10
bar = a.x.x.x.x + c.y.y.y.y

myproject/main> add

  Okay, I'm searching the branch for code that needs to be
  updated...

  Done.

myproject/main> upgrade old new
```

--------------------------------

### Unison: Expression Prefix Error

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/fix-4536.md

Demonstrates an error where an expression starts with an invalid prefix, such as '.foo>'. The parser expected a binding, watch expression, or declaration.

```unison
.foo> 17
```

--------------------------------

### Development Environment with Stack

Source: https://github.com/unisonweb/unison/blob/trunk/nix/README.md

Enters a Nix development environment pre-configured with tools necessary for building with Stack, including GHC, Stack, Ormolu, and Haskell Language Server.

```shell
nix develop
```

--------------------------------

### Unison Documentation: Lists

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

Demonstrates the creation and nesting of bulleted and numbered lists within Unison documentation. Shows how bullet types and starting numbers are handled.

```unison
# Bulleted lists
  
  Bulleted lists can use `+`, `-`, or `*` for the bullets
  (though the choice will be normalized away by the
  pretty-printer). They can be nested, to any depth:

  * A
  * B
  * C
    * C1
    * C2

# Numbered lists
  
  1. A
  2. B
  3. C

  The first number of the list determines the starting
  number in the rendered output. The other numbers are
  ignored:

  10. A
  11. B
  12. C

  Numbered lists can be nested as well, and combined with
  bulleted lists:

  1. Wake up.
     * What am I doing here?
     * In this nested list.
  2. Take shower.
  3. Get dressed.
```

--------------------------------

### UCM Shell Commands for Running Unison Code

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/serial-test-02.md

Demonstrates UCM shell commands to prepare and execute Unison code. It includes adding a target to the scratch directory and running the `mkTestCase` function defined in the Unison code.

```ucm
scratch/main> add
scratch/main> run mkTestCase

```

--------------------------------

### Unison Code Snippet with Type Annotations

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/upgrade.md

An example of Unison code showing type annotations for definitions, including how arithmetic operations are expressed with explicit type usage.

```unison
bar : Nat
bar =
  use Nat +
  x + c.y.y.y.y

c.y.y.y.y : Nat
c.y.y.y.y =
  use Nat +
  foo + 10

d.y.y.y.y : Nat
d.y.y.y.y =
  use Nat +
  foo + 10
```

--------------------------------

### Unison: Method Call Prefix Error

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/fix-4536.md

Illustrates an error in Unison where a method-like call starts with an invalid sequence, like 'foo.>'. This syntax is not recognized at the beginning of an expression.

```unison
foo.> 17
```

--------------------------------

### Define Unison Libraries

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/deep-names.md

Initializes two conceptual libraries, 'text' and 'http', with associated values. These serve as the base components for dependency management examples.

```unison
text.a = 1
text.b = 2
text.c = 3

http.x = 6
http.y = 7
http.z = 8
```

--------------------------------

### Get Project Definition API

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/api-getDefinition.md

Retrieves the definition of a specific term within a Unison project. It returns details about the definition, including its signature and associated documentation.

```APIDOC
GET /api/projects/scratch/branches/main/getDefinition?names=thing.doc&relativeTo=doctest
  Description:
    Fetches the definition for a given term name relative to a specified path within a project branch.

  Parameters:
    - names (string, required): The name(s) of the definition to retrieve, e.g., "thing.doc".
    - relativeTo (string, required): The relative path context for resolving the definition name, e.g., "doctest".

  Response Structure:
    {
      "missingDefinitions": [],
      "termDefinitions": {
        "#<hash>": {
          "bestTermName": "string",
          "defnTermTag": "string",
          "signature": [
            {
              "annotation": { ... },
              "segment": "string"
            }
          ],
          "termDefinition": {
            "contents": [
              {
                "annotation": { ... },
                "segment": "string"
              }
            ],
            "tag": "string"
          }
        }
      }
    }

  Example Response Snippet:
    {
        "missingDefinitions": [],
        "termDefinitions": {
            "#t9qfdoiuskj4n9go8cftj1r83s43s3o7sppafm5vr0bq5feieb7ap0cie5ed2qsf9g3ig448vffhnajinq81pnnkila1jp2epa7f26o": {
                "bestTermName": "doctest.thing.doc",
                "defnTermTag": "Doc",
                "signature": [
                    {
                        "annotation": {
                            "contents": "#ej86si0ur1lsjade71dojr25phk9bbom9rdks6dltolos5tjivakujcriqe02npba53n9gd7tkh8bmv08ttjb9t35lq2ch5heshqcs0",
                            "tag": "TypeReference"
                        },
                        "segment": "Doc2"
                    }
                ],
                "termDefinition": {
                    "contents": [
                        {
                            "annotation": {
                                "contents": "doctest.thing.doc",
                                "tag": "HashQualifier"
                            },
                            "segment": "doctest.thing.doc"
                        },
                        {
                            "annotation": {
                                "tag": "TypeAscriptionColon"
                            },
                            "segment": " :"
                        },
                        {
                            "annotation": null,
                            "segment": " "
                        },
                        {
                            "annotation": {
                                "contents": "#ej86si0ur1lsjade71dojr25phk9bbom9rdks6dltolos5tjivakujcriqe02npba53n9gd7tkh8bmv08ttjb9t35lq2ch5heshqcs0",
                                "tag": "TypeReference"
                            },
                            "segment": "Doc2"
                        },
                        {
                            "annotation": null,
                            "segment": "\n"
                        },
                        {
                            "annotation": {
                                "contents": "doctest.thing.doc",
                                "tag": "HashQualifier"
                            },
                            "segment": "doctest.thing.doc"
                        },
                        {
                            "annotation": {
                                "tag": "BindingEquals"
                            },
                            "segment": " ="
                        },
                        {
                            "annotation": null,
                            "segment": " "
                        },
                        {
                            "annotation": {
                                "tag": "DocDelimiter"
                            },
                            "segment": "{{"
                        }
                    ],
                    "tag": "Doc"
                }
            }
        }
    }
```

--------------------------------

### Unison: Basic Thread Creation and Execution

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/thread.md

Demonstrates the fundamental process of creating and running a new thread in Unison using `forkComp`. The example includes a parent thread that initiates a child thread and logs messages from both.

```unison
otherThread : '{io2.IO}()
otherThread = 'let
  watch "I'm the other Thread" ()

testBasicFork : '{io2.IO} [Result]
testBasicFork = 'let
  test = 'let
    watch "I'm the parent thread" ()
    threadId = .builtin.io2.IO.forkComp otherThread
    emit (Ok "created thread")

  runTest test

```

```ucm
scratch/main> add
scratch/main> io.test testBasicFork
```

--------------------------------

### Scala Fenced Code Block

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/bug-strange-closure.md

This snippet showcases a fenced code block for Scala. Similar to the Haskell example, it is noted as not being parsed by Unison, suggesting it's for presentation purposes.

```Scala
// A fenced code block which isn't parsed by Unison
def reverse[A](xs: List[A]) = 
  xs.foldLeft(Nil : List[A])((acc,a) => a +: acc)
```

--------------------------------

### UCM: Ambiguity Error Message

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/name-resolution.md

UCM reports an error when a reference 'foo' is ambiguous. It lists potential matches ('file.foo', 'ns.foo') and their types, guiding the user to qualify the reference.

```ucm
I couldn't figure out what foo refers to here:

    5 | bar = foo + 10

The name foo is ambiguous. Its type should be: Nat

I found some terms in scope that have matching names and
types. Was any of these what you wanted?

  file.foo : Nat
  ns.foo : Nat
```

--------------------------------

### EasyTest Example Test Suite

Source: https://github.com/unisonweb/unison/blob/trunk/yaks/easytest/README.markdown

Demonstrates a complete EasyTest suite, combining `ok`, `scope`, and `crash` within a monadic `do` block. It also shows how to run the suite using `run`.

```Haskell
module Main where

import EasyTest (ok, scope, crash, expect, run)

suite :: Test ()
suite = do
  ok
  scope "test-crash" $ crash "oh noes!"
  expect (1 + 1 == 2)

main = run suite
```

--------------------------------

### Build Unison Project

Source: https://github.com/unisonweb/unison/blob/trunk/development.markdown

Builds the Unison project using Stack. This command compiles all necessary Haskell code and executables required for running Unison.

```Shell
stack build
```

--------------------------------

### Extensionality Test Setup

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/codeops.output.md

A function to set up and run an extensionality test for a given function. It uses `roundtrip` to get a potentially modified version of the function and then applies `extensionals` to compare it against the original.

```unison
extensionality : Text -> (Three Nat Nat Nat -> Nat -> b) ->{io2.IO} Result
extensionality t f = let
  sh t n = "(" ++ showThree t ++ ", " ++ toText n ++ ")"
  handle
    g = roundtrip f
    extensionals sh f g (prod threes fib10)
  with handleTest t
```

--------------------------------

### Unison Branch Creation Examples

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts/idempotent/branch-command.md

Illustrates various ways to use the `branch` command to create new branches, including from different projects and branches.

```ucm
foo/main> branch topic1

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic1`.

foo/main> branch /topic2

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic2`.

foo/main> branch foo/topic3

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic3`.

foo/main> branch main topic4

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic4`.

foo/main> branch main /topic5

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic5`.

foo/main> branch main foo/topic6

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic6`.

foo/main> branch /main topic7

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic7`.

foo/main> branch /main /topic8

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic8`.

foo/main> branch /main foo/topic9

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic9`.

foo/main> branch foo/main topic10

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic10`.

foo/main> branch foo/main /topic11

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic11`.

scratch/main> branch foo/main topic12

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

  Tip: To merge your work back into the main branch, first
       `switch /main` then `merge /topic12`.

foo/main> branch bar/topic

  Done. I've created the bar/topic branch based off foo/main.

bar/main> branch foo/main topic2

  Done. I've created the bar/topic2 branch based off foo/main.

bar/main> branch foo/main /topic3

  Done. I've created the bar/topic3 branch based off foo/main.

scratch/main> branch foo/main bar/topic4

  Done. I've created the bar/topic4 branch based off foo/main.
```

--------------------------------

### Extensionality Test Setup

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-using-base/codeops.md

A function to set up and run an extensionality test for a given function. It uses `roundtrip` to get a potentially modified version of the function and then applies `extensionals` to compare it against the original.

```unison
extensionality : Text -> (Three Nat Nat Nat -> Nat -> b) ->{io2.IO} Result
extensionality t f = let
  sh t n = "(" ++ showThree t ++ ", " ++ toText n ++ ")"
  handle
    g = roundtrip f
    extensionals sh f g (prod threes fib10)
  with handleTest t
```

--------------------------------

### Build Unison with Stack

Source: https://github.com/unisonweb/unison/blob/trunk/README.md

Provides instructions for cloning the Unison repository, setting up the build environment using Stack, and compiling/executing the project. It includes commands to check the Stack version and run tests.

```Shell
$ git clone https://github.com/unisonweb/unison.git
$ cd unison
$ stack --version # we'll want to know this version if you run into trouble
$ stack build --fast --test && stack exec unison
```

--------------------------------

### Unison Tab Completion Example

Source: https://github.com/unisonweb/unison/blob/trunk/unison-src/transcripts-manual/remote-tab-completion.md

Demonstrates using the `debug.tab-complete` command in Unison to get suggestions. Note that this feature is reported as non-functioning (`:bug`) and makes a network call to the share service for completions.

```ucm
scratch/main> debug.tab-complete pull @uniso
```

```ucm
scratch/main> debug.tab-complete pull @unison/ba
```