UCM Command Reference

add

myProject/main> add

myProject/main> add myNewTerm

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

x These definitions failed:

Reason
needs update   myFunction : Doc

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.

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.

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

copy.patch

Use copy.patch foo bar to copy a patch from foo to bar

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

scratch/main> debug.clear-cache

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

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

delete.patch

scratch/main> delete.patch foo.patch

Use delete.patch foo.patch to remove the patch in the foo namespace. The argument to this must be a patch.

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.

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

find.all

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

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

gist

.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 a pull command that others can use to retrieve your gist.

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.

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

merge.preview src dest is 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.

merge can 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

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

patch

scratch/main> patch

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

You'll know that the patch should be run if a term called patch is present in the namespace.

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

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

pull-request.load base head will load a pull request for merging the remote repo head into the remote repo base staging each in the current namespace (so you should make yourself a fresh namespace to work first).

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

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.

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.

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.

todo

.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 the todo command to identify refactoring work that a namespace may have after updates to its dependent functions or types were performed.

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

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.

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.