UCM Command Reference

add

.> add

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

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

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

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

.> create.author alicecoder "Alice McGee"

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

cd

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

compile

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

copy.patch

Usecopy.patch foo barto copy a patch fromfootobar

create.author

.> create.author alicecoder "Alice McGee"

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

debug.clear-cache

.> debug.clear-cache

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

debug.clear-cache

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

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

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

Usedelete.patch footo remove the patchfoo

dependencies

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

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

.> display.to myFile myTerm

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

docs

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

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

.> docs.to-html .base.Set setDocsFolder

docs.to-htmlnamespace output/filecreates a html representation from thebase.Docterms 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

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

find

.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

find.all

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

find.verbose

.myProject> find.verbose emp

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

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

find.verbose

.myProject> find.verbose emp

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

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

fork

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

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

io.test

myTest : '{IO, Exception} [Test.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.

ls

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

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

merge

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

move.term

.> move.term oldName newName

move.termold newrenames an existing term

move.type

.> move.type oldName newName

move.typeold newrenames an existing type

patch

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

pull

Using Unison Share:

.> 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 Unison codebase into the current codebase.

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

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

push

.> 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 anyGit URLor Unison Share namespace path that identifies the namespace to push to and the second argument (if given) identifies a namespace in the local codebase that should be applied to the repo. If a second argument is not supplied, then the current namespace will be pushed to the given remote namespace.

reflog

.> reflog

refloglists the changes that have affected the root namespace

reset-root

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

run

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,superProgram : Boolean -> Nat superProgram bool = if Boolean.not bool then base.bug (Generic.failure "Fatal Issue Encountered" bool) else 100,and may perform the IO andExceptionabilities.

Any arguments following theruncommand will be passed as program arguments.

run.compiled

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

test

.base.Bag.foldLeft> test

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

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

.> ui

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

undo

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

update

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

.> update

.> update <patch>

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

.>
update <patch> foo bar

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

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

version

.> version

`

Prints the version of Unison that you are running

view

.> view .base.List.map

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