Configuration

Where the file lives

revision keeps its settings in a single JSON document:

$XDG_CONFIG_HOME/revision/config.json

When XDG_CONFIG_HOME is unset, that resolves to ~/.config/revision/config.json on both macOS and Linux. revision deliberately does not use the platform convention on macOS (~/Library/Application Support), so the same path works everywhere — including inside a container or over SSH.

The file is created with defaults on first run. Every setting falls back to its built-in default when the file, or an individual key, is absent, so a partial file is perfectly valid.

Editing in-app

Press S:

╭─ [1] Status ─────────────────╮╭─ [0] Diff ───────────────────────────────────╮
│Root      /home/alice/work/wc ││Loading diff…                                 │
│Source    /home/alice/work/wc ││                                              │
│CWD       /home/alice/work/wc ││                                              │
│Branch    trunk╭─ Settings ───────────────────────────────────╮               │
│Revision  r42  │> Log limit          100                      │               │
│               │  Editor             native                   │               │
╰───────────────│  Theme              auto                     │               │
╭─ [2] ─ Changes│  Directory diff     on                       │               │
│  ▾ /          │  Hide untracked     off                      │               │
│>     M modifie│  SSH key            ~/.ssh/id_rsa            │               │
│               │  Display from       cwd                      │               │
│               │  Diff output                                 │               │
│               │  Optimistic updates on                       │               │
╰───────────────│  Live refresh       on                       │               │
╭─ [3] Log ─────│  Allow mouse        off                      │               │
│  Rev Author Me│                                              │───────────────╯
│               │ctrl+s save · ↑↓ move · esc cancel            │───────────────╮
│               ╰──────────────────────────────────────────────╯               │
│                              ││                                              │
│                              ││                                              │
│                              ││                                              │
╰──────────────────────────────╯╰──────────────────────────────────────────────╯
space stage · n changelist · c commit · r revert · d delete · [ ] view · ? help

Key	Action
`↑↓`	Move between fields
`←→`	Cycle the theme and editor, and toggle switches
`ctrl+s`	Save
`esc`	Cancel

Cycling the theme applies it live so you can preview each scheme in place; esc reverts the preview and ctrl+s keeps it. Saving writes the same config.json, and the theme, directory-diff, hide-untracked, live-refresh, mouse and display-scope changes take effect immediately.

Settings

Key	Type	Default	Description
`theme`	string	`auto`	Colour scheme — see Themes.
`directoryDiff`	bool	`true`	Show the combined diff of every change beneath a directory when its row is highlighted.
`hideUntracked`	bool	`false`	Hide untracked (unversioned) files from the Changes and diff panels.
`displayFrom`	string	`cwd`	Where the working copy is displayed from: `cwd` or `root`.
`sshKeyPath`	string	`~/.ssh/id_rsa`	The SSH private key to load for `svn+ssh://` working copies.
`diffOutputDir`	string	`""`	Where diffs saved with `w` are written.
`logLimit`	int	`100`	How many revisions the Log panel loads per page.
`editor`	string	`native`	Which editor `e` opens the highlighted file in.
`optimisticUpdates`	bool	`true`	Show an action as done the moment it is asked for, with `svn` confirming afterwards.
`liveRefresh`	bool	`true`	Watch the working copy in the background and pick up changes made outside `revision`.
`allowMouse`	bool	`false`	Let the pointer click and scroll the panels.

theme

One of auto, everforest, dracula, nord, gruvbox, or cipher. See Themes.

directoryDiff

With directoryDiff set to false, highlighting a directory shows a short hint instead of its diff. Pressing D toggles the directory diff for the current session, so you can inspect one without changing the file.

Useful on large working copies, where a combined diff of a deep directory is expensive to generate.

hideUntracked

With hideUntracked set to true, untracked files are left out of the Changes tree, the Changelists view and the diff panel. Pressing U toggles them back into view for the current session, so you can inspect or add one without changing the file.

displayFrom

Value	Effect
`cwd` (default)	Every panel is scoped to the directory `revision` was started in.
`root`	Status, history and diffs are all rooted at the working copy’s root, no matter which directory inside it you started in.

The Status panel’s Source line names whichever one is in effect.

sshKeyPath

The private key loaded into ssh-agent for svn+ssh:// working copies. A leading ~ is expanded to your home directory. See Authentication.

diffOutputDir

Where w writes saved diffs, and where the Files panel’s Diffs view reads them from. The directory is created if it does not exist, and a leading ~ is expanded.

Empty — the default — means the working copy’s root, regardless of which directory inside it you started revision in and regardless of displayFrom.

logLimit

How many revisions the Log panel fetches at a time. It is a page size, not a ceiling on how far back you can look: n and p turn the panel through the rest of the history a page at a time. See the Log panel.

Raise it to page less often, lower it to make each fetch cheaper over a slow svn+ssh:// connection. Changing it returns the panel to the first page.

editor

One of native, vim (vi is accepted as a spelling of it), nvim, or nano. See Opening files in an editor.

optimisticUpdates

With optimisticUpdates on, staging, unstaging and changelist assignment restyle the row on the keypress and svn confirms behind it; if svn disagrees, the previous state comes back with an error toast. Revert, delete and commit are never shown as having succeeded before they have — their rows are marked as in flight instead.

Set it to false and every action waits for svn before anything on screen moves.

liveRefresh

With liveRefresh on, revision watches the working copy in the background, so a file saved in your editor, a build, or an svn command run in another terminal reaches the Files and diff panels within a couple of seconds — without R. The cursor stays on the same file and Main keeps its scroll position.

Pressing L toggles the watcher for the current session, so you can turn it off during an expensive build without changing the file. Nothing is re-read while a prompt, the commit editor or the settings form is open — the refresh waits for the screen. See Keeping up with the working copy.

Turn it off on a network filesystem or a very large working copy, where the periodic scan costs more than it is worth — see troubleshooting.

allowMouse

With allowMouse on the panels answer the pointer, and every gesture is a key as well:

Gesture	Same as
Click a panel	Its number key
Click a view name in the border	`[` / `]`
Click a row	Walking to it with `↑` / `↓`
Double-click a file	`e` — open it in your editor
Double-click a directory	`enter` — fold or unfold it
Double-click a changelist	`enter` — drill into it
Double-click a revision	`space` — update the working copy to it
Double-click a diff line	`e` — open the file at that line
Wheel	The scroll keys, on the panel under the pointer

The wheel scrolls sideways with shift held and never moves focus. The overlays — the side-by-side view, the resolution window, every prompt — stay on the keyboard.

It is off by default because reporting the pointer takes it from the terminal: while it is on, selecting text on screen needs shift held. Nothing is mouse-only, so leaving it off costs nothing but the pointer.

Example

{
  "theme": "cipher",
  "directoryDiff": false,
  "hideUntracked": true,
  "displayFrom": "root",
  "diffOutputDir": "~/patches",
  "liveRefresh": false
}

Upgrades and invalid values

After an upgrade the file is brought up to date automatically:

Settings added by a newer version are merged in silently.
A value the running build no longer supports — a retired theme, say — is reset to its default and reported in a startup toast.
A structurally invalid value, such as a non-positive logLimit, is normalised back to the default the same way.
Unknown keys are ignored, not deleted.

If the file cannot be read at all, revision starts on built-in defaults and prints a line to stderr rather than refusing to run.