UCM Command Reference

You can always type help into the UCM to get a full list of supported commands, or type help <desiredCommand> to get more information about a particular command.

add

myProject/main> add

myProject/main> add myNewTerm

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

FAQ about the add command

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. Most commonly this is because you are trying to add a term that already exists in the codebase with the same namespace and name.

x These definitions failed:

Reason
needs update   myFunction : Doc

Entering update instead of add will turn this failure into a successful update.

add.preview

scratch/main> add.preview

Previews additions to the codebase from the most recently typechecked file. This command only displays cached typechecking results. Use load to reparse & typecheck the file if the context has changed.

add.run

scratch/main> run main
scratch/main> add.run resultMain

Adds the result of calling the most recent run command back into the codebase as a Unison term with the given name.

alias.many

scratch/main> alias.many foo.foo bar.bar bazNamespace

alias.many <relative1> [relative2...] <namespace> creates aliases relative1, relative2, ... in the namespace namespace.

alias.term

scratch/main> alias.term existingName newName
scratch/main> alias.term frobnicate#2jdk10 zonk.betterName
scratch/main> alias.term Nat.drop .utils.Nat.-

alias.term foo bar creates the name bar as an alias for the term foo. The term can then be referenced by both names. Metadata linked to foo is copied over to bar (use unlink if this isn't what you want). foo and bar can be any term names including operators and hash qualified names.

alias.type

scratch/main> alias.type ExistingName NewName
scratch/main> alias.type Employee#2jdk10 v1.Employee
scratch/main> alias.type List.map .utils.List.map

alias.type foo bar creates the name bar as an alias for the type foo. Metadata linked to foo is copied over to bar (use unlink if this isn't what you want). foo and bar can be any type names.

api

scratch/main> api

Provides details about the Unison Codebase Manager API.

auth.login

scratch/main> auth.login

Obtains an authentication session with Unison Share. Also authenticates the user for running programs using the Unison Cloud library.

Will open with your default browser.

create.author

scratch/main> create.author alicecoder "Alice McGee"

create.author creates an metadata.Author value in metadata.authors and metadata.copyrightHolders.

back

scratch/main> switch /feature1
scratch/feature1> back
scratch/main>

Undoes the last switch command.

branch

scratch/main> branch feature1

scratch/main> branch /feature1 feature2

branch feature1 forks the current project branch to a new branch called "feature1"

branch /feature1 feature2 forks the branch feature1 to a new branch called feature2.

More info about creating branches can be found in the project workflows documentation

branch.empty

scratch/main> branch.empty newBranch

Creates a new empty branch. The newly created branch will not have a parent-child relationship with the branch it was created from.

branches

scratch/main> branches

scratch/main> branches base

Lists the branches in the current project or in the given project argument

clear

scratch/main> clear

Clears the UCM terminal screen

clone

scratch/main> clone @unison/json/topic json/my-topic
@unison/json/my-topic>

scratch/main> clone /feature /my-feature
scratch/my-feature>

Clones a remote project and branch from Unison Share into a local codebase. Use this command instead of pull or lib.install if you would like to bring code locally to work on.

`--codebase-create`

ucm --codebase-create my/new/codebase/path

Creates a new codebase at the given path. Opens an existing codebase when the path supplied already contains a .unison directory.

compile

scratch/main> compile myMain myMainFile

$ ucm run.compiled myMainFile.uc

compile myMain myFile creates a file called myFile.uc in the directory where the codebase lives from the Unison program myMain. This file can be run by the UCM when given as an argument to the run.compiled command line option.

create.author

scratch/main> create.author alicecoder "Alice McGee"

create.author creates an metadata.Author value in metadata.authors and metadata.copyrightHolders.

debug.clear-cache

scratch/main> debug.clear-cache

Used for clearing the UCM cache of previous test or watch expression runs.

debug.doc-to-markdown

scratch/main> debug.doc-to-markdown term.doc

Prints a Doc element into a markdown text snippet in the UCM.

delete

delete myTerm

delete Optional

Deletes the given term or type name from the codebase. If the term or type is still in use, the UCM will render an error indicating where it is referenced.

delete.branch

myProject/main> delete.branch /myBranch

Deletes the branch with the given name

delete.namespace

scratch/main> delete.namespace foo

delete.namespace deletes the namespace and the terms it contains from the codebase. If the definitions in the namespace are still in use, the UCM will not perform the deletion. Previously deleted namespaces are still in the codebase's history and can be retrieved with the reflog command.

delete.namespace.force

scratch/main> delete.namespace.force foo

Removes the namespace even if the terms within that namespace are used in the codebase. The code dependencies will contain hash references of the deleted terms and types.

dependencies

scratch/main> dependencies myTerm

Dependencies of #myTermHash:

Reference   Name
1.  #hash1 dependent1
2.  #hash2 dependent2

Lists the dependencies of the specified definition. Accepts a term name or hash.

dependents

foo : Nat
foo = 42

bar = foo + 1

scratch/main> dependents foo

  Dependents of: foo

  Terms:

  1. bar

The dependents command lists all the terms that make use of the given term or type in their implementation. This can be useful for understanding the impact of a change to a term or for finding out where a type is used in a project.

display

scratch/main> display myTerm

scratch/main> display

Displays a rendered version of the given term to the console. If called with no arguments, display invokes a search to select a definition to display, requiring that fzf be found within your PATH. display is often used for reading documentation in the command line. Currently this command works for terms in a codebase but does not display types or abilities. This may change in an upcoming release of the UCM.

display.to

scratch/main> display.to myFile myTerm

display.to <filename> foo prints a rendered version of the term foo to the given file.

docs

scratch/main> docs Exception.bracket

docs prints the docs for the given term in the UCM if a corresponding .doc term exists.

In the example above, the UCM is looking for a term called Exception.bracket.doc

docs.to-html

scratch/main> docs.to-html base.List website/base/listDocs

scratch/main> docs.to-html .base.Set setDocsFolder

docs.to-html namespace output/file creates a html representation from the Doc terms in the given namespace. The namespace argument can be either a relative or absolute namespace. The output file path is created relative to the root of the folder where the UCM command was issued from.

edit

scratch/main> edit myTerm

scratch/main> ls base.List
scratch/main> edit 4
scratch/main> edit 1-5

edit prepends the definition of the given argument(s) to the top of the most recently saved file.

Often used in conjunction with ucmCommands.update.

edit.namespace

scratch/main> edit.namespace foo.bar

scratch/main> edit.namespace foo bar.baz

Brings the contents of an entire namespace (and its sub-namespaces) inside a scratch file for editing. Accepts multiple namespace arguments.

edit.new

scratch/main> edit.new foo.bar

Commonly used with ls and numbered arguments.

scratch/main> ls
scratch/main> edit.new 1-n

Brings the arguments into a scratch file above a fold --- to provide a new workspace for working on Unison code. Everything below the fold is ignored by the UCM.

find

.myProject> find

.myProject> find myTerm

.myProject> find Map List

.myProject> find : [a] -> [[a]]

find foo bar baz searches the current namespace tree for the given argument(s), excluding the lib directory.

If no arguments are supplied, find will either list the definitions in the current namespace or, if fzf is installed on your machine, find will delegate to fzf for fuzzy search. See the fzf github for more details.

To search for terms including the lib directory, use find.all

Type driven search

If find is followed by a colon, the ucm will search the codebase for definitions which match the given type signature.

find.all

scratch/main> find.all List.reverse

1. lib.base.List.reverse : [a] -> [a]

The find.all command behaves identically to the find command, except that it includes the *.lib namespace, by default, in its search.

While it is possible for the namespaces inside of the lib directory to contain their own lib namespaces, this command does not recursively search through all lib sub-namespaces.

find-in

find-in can be used with a namespace argument to list all definitions in the specified sub-namespace

scratch/main> find-in foo.bar

scratch/main> find-in foo.bar term1 term2

Lists all definitions with a name similar to the given arguments inside the namespace argument.

find.verbose

.myProject> find.verbose emp

1. -- #bs08eqa1ukvve64fh71sqp406jf73c8s6c3v8ltg1ucqre10lcq32qk45sf8pgrfrctstbldlm4m7mscnk9vkra2ohcpmqqhtprb9jo
  isEmpty : [a] -> Boolean

The find.verbose command behaves identically to find, except that it includes hashes and aliases in its output

fork

Creates a copy of the given source namespace at the a new destination.

scratch/main> fork src destination

Fork a namespace across projects and branches with the following syntax:

project0/main> fork project0/branch0:a.path project1/branch1:foo

You can also create a namespace from the contents of an entire branch of a given project:

srcproject/main> fork srcproject/srcbranch dest

help

scratch/main> help add.run

Prints usage information and patterns about the given UCM command.

help-topics

Enter help-topics with no arguments to see a list of topics:

scratch/main> help-topics

scratch/main> help-topics projects

Displays information about the given UCM topic.

history

scratch/main> history

Note: The most recent namespace hash is immediately below this message.

⊙ 1. #6tfcojje2h

  - Deletes:

    deploy

⊙ 2. #f85r0fefal

  + Adds / updates:

    testNewFunction

The history command displays the history of changes (such as additions, updates, and deletes) to the current branch. The history is a more detailed view of the changes that have been made to the codebase than the reflog command, including the names of terms that have been changed.

io.test

myTest : '{IO, Exception} [Result]
myTest _ =
printLine "hi"
check (1 == 1)

scratch/main> io.test myTest

io.test can execute a single test which performs I/O. The argument to io.test should be a delayed computation which performs the IO ability and returns a test.Result.

io.test.all

myTest : '{IO, Exception} [Result]
myTest _ =
printLine "hi"
check (1 == 1)

scratch/main> io.test.all

Runs all the unit tests for the current branch that use IO. Each test should be a delayed computation which performs the IO ability and returns a test.Result.

lib.install

Downloads the latest release of the specified library:

myProject/main> lib.install @unison/base

To install a specific version of a library, use the name of the libray followed by "release/versionNumber":

myProject/main> lib.install @unison/base/releases/1.0.0

The lib.install command is used to install a library from Unison Share, as of Unison version 0.5.21. If you are using an older Unison version, use the pull command to install libraries.

ls

ls displays the terms, types, and sub-namespaces in the given namespace. name accepts both absolute and relative namespace paths.

scratch/main> ls base.List

scratch/main> ls .base.Bag

load

scratch/main> load myScratch.u

Without an argument, load parses, typechecks, and evaluates the most recent scratch file.

scratch/main> load

Parses, typechecks and evaluates the given .u suffixed scratch file. Once typechecked and evaluated, you can add the terms to your codebase, so load is often used in transcripts.

merge

merges the source namespace into the destination

scratch/main> merge src dest

merges the source namespace into the current namespace

scratch/main> merge src

Use the merge command to merge two namspaces with the following behavior:

If a function is added in the source namespace, it will be present in the resulting destination namespace
If a function is updated in the source namespace, the UCM will use the updated version in the resulting destination
If the destination namespace has additional functions that the source namespace does not contain, the destination namespace will retain the functions in the resulting namespace

merge.commit

scratch/main> merge topic

At this point, the merge may require you to fix issues in a scratch file. Then run:

scratch/merge-topic-into-main> update
scratch/merge-topic-into-main> merge.commit
scratch/main>

Merges a temporary branch created by the ucmCommands.merge command back into its parent branch, and removes the temporary branch.

move

scratch/main> move foo bar

Move is a general command for renaming terms, types, and namespaces. move foo bar renames the term, type, and namespace foo to bar.

move.namespace

scratch/main> move.namespace old.name new.name

Renames the path of the old namespace to the desired new namespace. All the terms and sub-namespaces can be found under the new name.

move.term

scratch/main> move.term oldName newName

move.term old new renames an existing term

move.type

scratch/main> move.type oldName newName

move.type old new renames an existing type

project.create

Create a project with a random, friendly name by giving the command no argument:

scratch/main> project.create
happy-starfish/main>

scratch/main> project.create myCloudService

Creates a new project and /main branch with the given name. By default, project.create creates a lib namespace and installs the standard lib, base for you.

project.rename

scratch/main> project.rename temp
temp/main>

Renames the currently active project to the given name.

projects

scratch/main> projects

Lists all the projects in the current codebase.

pull

Downloading a project dependency:

myProject/main> pull @unison/base/releases/X.Y.Z lib.base

Pulling a public namespace:

scratch/main> pull unison.public.base.latest lib.base

Using git urls:

scratch/main> pull git(git@github.com:unisonweb/base).latest .base
scratch/main> pull git(https://github.com/org/repo:some-branch).some.path

For Unison version 0.5.21 and later, use libInstall to install libraries.

The pull command 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 share or from a git repo using the git url format.

The first argument to pull is 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.

pull.without-history

scratch/main> pull.without-history @unison/base/main

Merges a remote namespace into a local branch without including the remote's history. This usually results in smaller codebase sizes but branches will no longer be able to find common ancestors for issuing pull requests. Use clone or pull if you are hoping to contribtue to a branch.

push

Pushing from within a project:

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

Pushing a namespace to a remote namespace:

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

The push command is used to push definitions from a local codebase to a remote codebase.

The first argument to push is 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.

quit

scratch/main> quit

Exits the current UCM session.

reflog

myProject/main> reflog

     Branch      When          Hash          Description
1.   tour/main   an hour ago   #a1vh3f0sa1   Include latest base library
2.   tour/main   an hour ago   #sg60bvjo91   Project Created

The reflog command takes an optional branch name argument.

myProject/main> reflog /anotherBranch

reflog, also known as branch.reflog or reflog.branch lists the changes that have affected the current project branch.

Often used in tandem with reset to rewind a branch to a previous state.

For viewing changes across multiple branches in a project, use the project.reflog command.

For viewing changes across the entire codebase, use the global.reflog command.

project.reflog

myProject/main> project.reflog

Branch                   When          Hash          Description
1.   myProject/aBranch   1 min ago     #44hhv8v9bk   move myProject/aBranch:loadApiKey jobs.loadA...
2.   myProject/aBranch   2 mins ago    #d4h0k49ng3   delete myProject/aBranch:.deploy
3.   myProject/aBranch   2 mins ago    #0d5om21ev5   Branch created from myProject/main
4.   myProject/main      7 mins ago    #0d5om21ev5   add

project.reflog is used for viewing changes to the codebase across multiple branches in a project.

For viewing changes that are scoped to the current branch in a project, see the reflog command.

global.reflog

myProject/main> global.reflog

Branch                              When                Hash          Description
1.    tour/main                     an hour ago         #a1vh3f0sa1   reset a1vh3f0sa1
2.    tour/main                     an hour ago         #ijqrr5987q   move tour/main:.a tour/main:.b
5.    anotherProject/aBranch        about 2 hours ago   #6tfcojje2h   reset 6tfcojje2h aBranch

global.reflog or reflog.global lists the changes to the codebase across all projects and branches.

For viewing changes that are scoped to the current project branch, use the reflog command.

For viewing changes across multiple branches in a project, use the project.reflog command.

reset

This reset command will undo the add that happened in the reflog:

myProject/main> reflog
  Branch                When         Hash          Description
  1.   myProject/main   1 secs ago   #0d5om21ev5   add
  2.   myProject/main   9 mins ago   #6tfcojje2h   delete myProject/main:.deploy
myProject/main> reset #6tfcojje2h

reset accepts an optional target branch to reset. If no branch is provided, the current branch is reset.

myProject/main> project.reflog

Branch                   When          Hash          Description
1.   myProject/aBranch   1 min ago     #44hhv8v9bk   move myProject/aBranch:loadApiKey jobs.loadA...
2.   myProject/aBranch   2 mins ago    #d4h0k49ng3   delete myProject/aBranch:.deploy
3.   myProject/aBranch   2 mins ago    #0d5om21ev5   Branch created from myProject/main
4.   myProject/main      7 mins ago    #0d5om21ev5   add
myProject/main> reset #d4h0k49ng3 /aBranch

Resets a branch of the project (along with its history) to that of the specified hash or numbered argument. This is useful for undoing changes to the project, often used in tandem with reflog.

Differs from the deprecated reset-root command in that it only affects the current project, not the entire codebase.

run

myProgram : '{IO, Exception} ()
myProgram = '(printLine "Hello World")

myProgramWithArgs : '{IO, Exception} ()
myProgramWithArgs = 'let
  printLine ("Hello " ++ Optional.getOrElse "World" (List.head !getArgs) ++ "!")

scratch/main> run myProgram
scratch/main> run myProgramWithArgs Rebecca

The run command is used to evaluate terms that require the IO ability within ucm. A program that performs IO cannot be evaluated in a watch expression but can be executed with run.

Run takes a delayed computation and performs !myProgram, where myProgram is searched for in the most recent typechecked file, or in the codebase. The function provided to the run command can return any type, and may perform the IO and Exception abilities.

Any arguments following the run command will be passed as program arguments.

run.compiled

$ ucm run.compiled myProgram.uc

run.compiled is a command line option to the UCM which runs a binary executable unison program. It is used in tandem with the compile command.

run.native

scratch/main> run.native main args

Executes the main function using native compilation via scheme. Currently in beta-testing.

switch

scratch/main> switch otherProject
otherProject/main>

scratch/main> switch /feature1
scratch/feature1>

Switches between projects or branches. Branches are indicated with a leading slash for disambiguation.

Switch with no arguments opens an interactive selector to pick a project and open a branch.

test

scratch/main> test foo.bar

1.  foo.bar.test1          ◉ Passed

scratch/main> test

1.  foo.bar.test1          ◉ Passed
2.  foo.baz.test1          ◉ Passed
2.  foo.baz.test2          ◉ Passed

Runs unit tests for the given namespace argument. If no argument is given, the command runs all the tests in the current project.

test.all

scratch/main> test.all

Runs all the unit tests inside the current branch (including the lib namespace)

text.find

scratch/main> text.find token123 "99" tokenABC

Finds terms with literals (text or numeric) or documentation containing the given token arguments. Partial string matches are supported.

Numeric literals must be quoted (ex: "42") but single words need not be quoted.

Does not search through lib namespace. Use text.find.all to search through dependencies.

text.find.all

scratch/main> text.find.all token123 "99" tokenABC

Like text.find but searches through the lib namespace dependencies of a project.

todo

scratch/newFeature> update
scratch/newFeature> todo

🚧

The namespace has 1 transitive dependent(s) left to upgrade.
Your edit frontier is the dependents of these definitions:

unique type Box

I recommend working on them in the following order:

1. toText : Box -> Text

Lists the current namespace's outstanding issues, including conflicted names, dependencies with missing names, and merge precondition violations.

ui

scratch/main> ui

Opens the local codebase UI for the UCM. Can be run from any namespace in the codebase.

undo

scratch/main> undo

Use undo to revert the most recent change to the codebase. You can use the reflog and reset commands to move farther back in your codebase state.

unsafe.force-push

scratch/main> unsafe.force-push

Like push, but forcibly overwrites the remote namespace. You should use this command with caution, since there is no way to recover the remote namespace's state once this command has been applied.

update

myProject/main> update

myProject/main> update aTerm

Adds everything in the most recently typechecked file to the namespace, replacing existing definitions having the same name, and attempts to update all the existing dependents accordingly. If the process can't be completed automatically, the dependents will be added back to the scratch file for your review.

upgrade

myproject/main> upgrade base_1_0_0 base_1_1_0

Upgrades the given dependency to a newer version. You need to have both the old and new version of the library in your lib namespace for the upgrade command to run. Once issued, it will initiate an update process for all the terms that depend on the upgraded library. If there are non-type-preserving changes, the impacted terms will be edited to a scratch file. Otherwise, the library upgrade will auto-propagate and the old version of the library will be removed.

upgrade.commit

scratch/upgrade_x_to_y> update
scratch/upgrade_x_to_y> upgrade.commit
scratch/main>

upgrade.commit merges a temporary branch created by the upgrade command back into its parent branch, and removes the temporary branch. Also known as commit.upgrade

version

myProject/main> version

Prints the version of Unison that you are running

view

myproject/main> view .base.List.map

view displays the source code of the given Unison term or type.

add

FAQ about the add command

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

add.preview

add.run

alias.many

alias.term

alias.type

api

auth.login

create.author

back

branch

branch.empty

branches

clear

clone

--codebase-create

compile

See also

create.author

debug.clear-cache

debug.doc-to-markdown

delete

delete.branch

delete.namespace

delete.namespace.force

dependencies

dependents

display

display.to

docs

docs.to-html

edit

edit.namespace

edit.new

find

Type driven search

find.all

find-in

find.verbose

fork

help

help-topics

history

io.test

io.test.all

lib.install

ls

load

merge

merge.commit

move

move.namespace

move.term

move.type

project.create

project.rename

projects

pull

pull.without-history

push

quit

reflog

project.reflog

global.reflog

reset

run

run.compiled

run.native

switch

test

test.all

text.find

text.find.all

todo

ui

undo

unsafe.force-push

`--codebase-create`