UCM Command Reference

🏗️This list is in progress and will grow in the future.

For now, you can always typehelpinto theUCMto get a full list of supported commands, or typehelp <desiredCommand>to get more information about a particular command.


myProject/main> add
myProject/main> 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:

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.


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

alias.term foo barcreates the namebaras an alias for the termfoo.The term can then be referenced by both names. Metadata linked tofoois copied over to bar (useunlinkif this isn't what you want).fooandbarcan be any term names includingoperatorsand hash qualified names.


.> alias.type ExistingName NewName
.> alias.type Employee#2jdk10 v1.Employee
.base> alias.type List.map .utils.List.map

alias.type foo barcreates the namebaras an alias for the typefoo.Metadata linked tofoois copied over tobar(useunlinkif this isn't what you want).fooandbarcan be any type names.


.> auth.login

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

Will open with your default browser.


.> create.author alicecoder "Alice McGee"

create.authorcreates anmetadata.Authorvalue inmetadata.authorsandmetadata.copyrightHolders.


.> cd .base.Bag
.> cd base.List
.> cd ..
.> cd back

cdis used to move to a different namespace in the codebase. It accepts relative or absolute paths. Also known asnamespaceorj.


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


.> compile myMain myMainFile
$ ucm run.compiled myMainFile.uc

compile myMain myFilecreates a file calledmyFile.ucin the directory where the codebase lives from the Unison programmyMain.This file can be run by the UCM when given as an argument to therun.compiledcommand line option.

See also



Usecopy.patch foo barto copy a patch fromfootobar


.> create.author alicecoder "Alice McGee"

create.authorcreates anmetadata.Authorvalue inmetadata.authorsandmetadata.copyrightHolders.


.> debug.clear-cache

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


.> debug.clear-cache

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


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.namespace foo

delete.namespacedeletes 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 thereflogcommand.


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


.> delete.patch foo.patch

Usedelete.patch foo.patchto remove the patch in thefoonamespace. The argument to this must be a patch.


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


.> display myTerm
.> display

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


.> display.to myFile myTerm

display.to<filename> fooprints a rendered version of the termfooto the given file.


.> docs Exception.bracket

docsprints the docs for the given term in the UCM if a corresponding.docterm exists.

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


.> docs.to-html base.List website/base/listDocs
.> docs.to-html .base.Set setDocsFolder

docs.to-htmlnamespace output/filecreates a html representation from theDocterms 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 myTerm
.> ls base.List
.> edit 4
.> edit 1-5

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

Often used in conjunction withucmCommands.update.


.myProject> find
.myProject> find myTerm
.myProject> find Map List
.myProject> find : [a] -> [[a]]

findfoo bar bazsearches the current namespace tree for the given argument(s), excluding thelibdirectory.

If no arguments are supplied,findwill either list the definitions in the current namespace or, iffzfis installed on your machine,findwill delegate tofzffor fuzzy search.See thefzfgithubfor more details.

To search for terms including thelibdirectory, usefind.all

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


.myProject> List.reverse

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

Thefind.allcommand behaves identically to thefindcommand, except that it includes the*.libnamespace, by default, in its search.

While it is possible for the namespaces inside of thelibdirectory to contain their ownlibnamespaces, this command does not recursively search through alllibsub-namespaces.


.myProject> find.verbose emp

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

Thefind.verbosecommand behaves identically tofind,except that it includes hashes and aliases in its output


.myProject> find.verbose emp

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

Thefind.verbosecommand behaves identically tofind,except that it includes hashes and aliases in its output


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

.> fork src destination


.myNamespace> gist git(git@github.com:myUser/myUnisonRepo)
Gist created. Pull via:

pull git(git@github.com:myUser/myUnisonRepo)#hashReference

Pushes the contents of the namespace in which it is called to the given remote repository. Used for sharing quick snippets of code. The UCM will return apullcommand that others can use to retrieve your gist.


myTest : '{IO, Exception} [Result]
myTest _ =
printLine "hi"
check (1 == 1)
.> 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 theIOability and returns atest.Result.


lsdisplays the terms, types, and sub-namespaces in the given namespace.nameaccepts both absolute and relative namespace paths.

.> ls base.List
.> ls .base.Bag


.> load myScratch.u

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

.> load

Parses, typechecks and evaluates the given.usuffixed scratch file. Once typechecked and evaluated, you canaddthe terms to your codebase, soloadis often used in transcripts.


merges the source namespace into the destination

.> merge src dest

merges the source namespace into the current namespace

.currentDestination> merge src

Use themergecommand to merge two namspaces with the following behavior:

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


merge.preview src destis used to preview the changes that will be made to a branch or namespace when merging another branch or namespace into it. The first argument is the source and the second is the destination. The second argument is optional. When omitted, the destination is the current branch or namespace.

mergecan be used to merge a namespace into a branch, but not a branch into a namespace.

myProject/main> merge.preview /otherBranch
myProject/main> merge.preview /branch1 /branch2
myProject/main> merge.preview .otherNamespace


.> move.term oldName newName

move.termold newrenames an existing term


.> move.type oldName newName

move.typeold newrenames an existing type


.> patch

Rewrites any definitions that depend on definitions with type-preserving edits to use the updated versions of these dependencies.

You'll know that thepatchshould be run if a term calledpatchis present in the namespace.


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.


.> pull-request.load git(git@github.com:unisonweb/base).releases._latest git(git@github.com:unisonweb/base).releases._main
.> pull-request.load unison.public.base.latest unison.public.base.main .tmp._prs

pull-request.load base headwill load a pull request for merging the remote repoheadinto the remote repobasestaging each in the current namespace (so you should make yourself a fresh namespace to work first).

Optionally, thepull-request.loadcommand can take a third argument which is a namespace destination where the pull request should be loaded. The destination namespace must be empty.


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.


.> reflog

refloglists the changes that have affected the root namespace


.> reset-root #6psnlk5i02
.> reset-root .foo

Resets the root namespace (along with its history) to that of the specified namespace. The argument to reset-root can be a hash or a namespace


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

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

Theruncommand 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 withrun.

Run takes a delayed computation and performs!myProgram,wheremyProgramis searched for in the most recent typechecked file, or in the codebase. The function provided to theruncommand must have a final return type of unit,(),and may perform the IO andExceptionabilities.

Any arguments following theruncommand will be passed as program arguments.


$ ucm run.compiled myProgram.uc

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


.base.Bag.foldLeft> test

runs unit tests for the current namespace. Does not accept any arguments


.newFeature> update
.newFeature> todo


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

unique type .myWork.Box

I recommend working on them in the following order:

1. toText : myWork.Box -> Text

Use thetodocommand to identify refactoring work that a namespace may have after updates to its dependent functions or types were performed.

Thetodocommand is scoped to the namespace in which it is called. If I have changes to perform in a namespace.myWork.featureand I call thetodocommand at the root of my project, the todo items will not be shown.


.> ui

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


.> undo

Useundoto revert the most recent change to the codebase. Some commands result in multiple steps in the history. You can use thereflogandreset-rootcommands to move around history more reliably.


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 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 yourlibnamespace for the upgrade command to run. Once issued, it will initiate anupdateprocess 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.


.> version


Prints the version of Unison that you are running


.> view .base.List.map

viewdisplays the source code of the given Unison term or type.