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

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.

create.author

.> create.author alicecoder "Alice McGee"

create.authorcreates anbase.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

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

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

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

findfoo bar bazsearches the current codebase for the given argument(s).

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.

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

find.verbose

.> 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@github.com:myUser/myUnisonRepo:.gists
Gist created. Pull via:

pull 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

.> pull git@github.com:unisonweb/base:.releases._latest .base

Thepullcommand is used to pull definitions from another Unison codebase into the current codebase.

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.

push

.> push git@github.com:myUser/myCodebase:.releases.v1 .update.v1

Thepushcommand is used to push definitions from a local codebase to a remote codebase

The first argument topushis any Git URL 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,(),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.

view

.> view .base.List.map

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