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

.> add
.> add myNewTerm

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

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:

Reason
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

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

Obtains an authentication session withAlso authenticates the user for running programs using the

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.

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

## 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. ### See also run.compiled ## 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 Iffindis followed by a colon, the ucm will search the codebase for definitions which match the given type signature. ## 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 toexcept that it includes hashes and aliases in its output ## find.verbose .myProject> find.verbose emp 1. -- #bs08eqa1ukvve64fh71sqp406jf73c8s6c3v8ltg1ucqre10lcq32qk45sf8pgrfrctstbldlm4m7mscnk9vkra2ohcpmqqhtprb9jo isEmpty : [a] -> Boolean Thefind.verbosecommand behaves identically toexcept 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

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