UCM Environment Variables

The following are optional environment variables. You can set them in your shell profile (e.g. .bashrc, .zshrc, etc.) to have them persistently available, or provide them as arguments when you enter the ucm command.

Merge/diff tool config

UCM_MERGETOOL

Allows selecting which merge tool to use when resolving merge conflicts.

UCM_MERGETOOL='/path/to/your/merge/tool \
  --merge "$REMOTE" "$LOCAL" "$BASE" "$MERGED"' ucm

See the UCM merge tool documentation for more details.

UCM_DIFFTOOL

Allows selecting which diff tool to use when viewing diffs.

UCM_DIFFTOOL='/path/to/your/diff/tool "$LOCAL" "$REMOTE"' ucm

If the UCM_DIFFTOOL environment variable is set, it will be executed with variables $LOCAL and $REMOTE as described in the Git-scm docs.

Console output config

UNISON_PAGER

Allows selecting which pager to use for long command outputs. Defaults to less on Linux & Mac, more on Windows

E.g.

# User more instead of less
$ UNISON_PAGER=more ucm

UNISON_FZF_PATH

Allows configuring which binary to use when triggering fuzzy searches using fzf. If unset, we default to searching for a binary named fzf in your $PATH.

E.g.

$ UNISON_FZF_PATH="/opt/homebrew/bin/fzf" ucm

If you wish to disable fzf entirely, you can set UNISON_FZF_PATH to "NONE".

$ UNISON_FZF_PATH="NONE" ucm

Unison Share config

UNISON_SHARE_HOST

Allows selecting the location for the default Share server.

E.g.

$ UNISON_SHARE_HOST="http://localhost:5424" ucm

UNISON_SHARE_ACCESS_TOKEN

Allows overriding the credentials used when authenticating with the Share server.

E.g.

$ UNISON_SHARE_ACCESS_TOKEN="my.token.string" ucm

UNISON_SYNC_VERSION

Allows regressing to sync version 1 when interacting with Share.

$ UNISON_SYNC_VERSION="1" ucm

UNISON_SYNC_HISTORY_COMMENTS

Toggles on/off syncing of history comments with Share.

Defaults to disabled.

$ UNISON_SYNC_VERSION="true" ucm

UNISON_LSP_PORT

Allows selecting the port to run the LSP server on. Defaults to 5757.

E.g.

$ UNISON_LSP_PORT=8080 ucm

Language server config

UNISON_LSP_ENABLED

Allows explicitly enabling or disabling the LSP server. Acceptable values are 'true' or 'false'

Note for Windows users: Due to an outstanding issue with GHC's IO manager on Windows, the LSP is disabled by default on Windows machines. Enabling the LSP on windows can cause UCM to hang on exit and may require the process to be killed by the operating system or via Ctrl-C. Note that this doesn't pose any risk of codebase corruption or cause any known issues, it's simply an annoyance.

If you accept this annoyance, you can enable the LSP server on Windows by exporting the UNISON_LSP_ENABLED=true environment variable.

You can set this persistently in powershell using:

[System.Environment]::SetEnvironmentVariable('UNISON_LSP_ENABLED','true')

See this issue for more details.

E.g.

$ UNISON_LSP_ENABLED=true ucm

General codebase config

UNISON_READONLY

Force unison to use readonly connections to codebases.

$ UNISON_READONLY="true" ucm

UNISON_DEBUG

Enable debugging output for various portions of the application. See lib/unison-prelude/src/Unison/Debug.hs for the full list of supported flags.

E.g.

# Enable ALL debugging flags (likely quite noisy)
$ UNISON_DEBUG= ucm
# Enable timing debugging, printing how long different actions take.
$ UNISON_DEBUG=timing ucm
# Enable LSP and TIMING debugging
$ UNISON_DEBUG=lsp,timing ucm

UNISON_ENTITY_VALIDATION

Allows disabling validation of entities pulled from a codebase server. It's generally a good idea to leave this enabled unless you know exactly what you're doing.

Defaults to enabled.

$ UNISON_ENTITY_VALIDATION="false" ucm

UNISON_MIGRATION

Setting:

$ UNISON_MIGRATION="auto" ucm

will cause ucm to automatically migrate the codebase to the latest version, without prompting for confirmation.

UNISON_PULL_WORKERS

Allows setting the number of workers to use when pulling from a codebase server. Defaults to 5.

$ UNISON_PULL_WORKERS=6 ucm

UNISON_PUSH_WORKERS

Allows setting the number of workers to use when pushing to a codebase server. Defaults to 1.

$ UNISON_PUSH_WORKERS=2 ucm

UNISON_SYNC_CHUNK_SIZE

Allows setting the chunk size used in requests when syncing a codebase. Defaults to 50.

$ UNISON_SYNC_CHUNK_SIZE=100 ucm

Local Codebase Server

The port, host and token to be used for the local codebase server can all be configured by providing environment variables when starting ucm, using UCM_PORT, UCM_HOST, and UCM_TOKEN.

E.g.

UCM_PORT=8080 UCM_HOST=localhost UCM_TOKEN=1234 ucm