Configuration

XCommander works without any configuration. When you want to change a key, add your own, or pick another leader, you write a small text file in TOML format. Changes apply as soon as you save: no restart.

Where the files go

Neither file exists until you create it. The folder ~/.config is hidden in Finder; from Terminal:

mkdir -p ~/.config/xcommander
touch ~/.config/xcommander/config.toml
xed ~/.config/xcommander/config.toml

xed opens it in Xcode. Any code editor works; avoid TextEdit, whose smart quotes turn "m z" into “m z”, which isn't valid TOML.

The project folder is the nearest folder, going up from the file you're editing, that holds an .xcodeproj, an .xcworkspace, a Package.swift or a .git folder.

The project file is applied after the global one, so it only needs the lines that differ. You can commit it to the project's repository and share it with your team.

An example

version = 1

[general]
leader = "⌃SPC"         # see "Choosing a leader" below
panel-delay = 200       # milliseconds before the which-key panel appears (default 350)
sequence-timeout = 15   # seconds before an unfinished sequence gives up (default 10)

[groups]
m = "build"             # what the which-key panel calls the m group

[keys]
"m z" = "make.clean"    # bind a key sequence to a command id
"f s" = "file.saveAll"

[unbind]
keys = ["q X"]          # remove keys XCommander ships with

Every file must start with version = 1. If the format ever changes in a way that would make an old file mean something different, the version goes up, and XCommander refuses a file it doesn't understand rather than guessing.

When a setting is in both the file and the Settings window, the file wins.

Sections

Two more sections exist in the format but aren't built yet: [commands] (macros, a named list of commands) and [layouts] (saved pane arrangements). XCommander tells you it ignored them, and loads the rest of the file.

Writing keys

A sequence is keys separated by spaces, written the way the which-key panel shows them: m m, c d, f F. Don't include the leader.

• Uppercase means with Shift: "g F" is g then Shift-f.
• Modifiers are written as symbols before the key: ⌃ Control, ⌥ Option, ⇧ Shift, ⌘ Command.
• Keys without a character have names: ESC, SPC, TAB, RET, DEL, the arrows ← → ↑ ↓, and F1 to F12.
• A key is the character you type, whatever your keyboard layout. On a French keyboard, / is the key that types /.

ESC can't be bound, anywhere in a sequence: it's how you cancel one, including one your own configuration broke.

Finding command ids

Every command has an id, like make.build or pane.swap. The command reference lists them all, with their default keys. You can also print the list from the app itself, which is always exactly what your version supports:

/Applications/XCommander.app/Contents/MacOS/XCommander --print-reference

Choosing a leader

The leader is the key that starts every sequence. Pick one in Settings → General, or with leader in [general]:

The leader is swallowed while Xcode is in front, so it must be a chord you would never type as text. That's why there's no free choice of key.

When a file has a mistake

XCommander never applies half a file. It reads and checks the whole file first, and only switches to it if it's valid. If you save a file with a typo, you keep working with the last good keymap, and the problem is reported:

• in Settings → Diagnostics → Check config;
• from Terminal, with --check, which runs the exact code the app uses and suggests the closest match for a mistyped command id:

/Applications/XCommander.app/Contents/MacOS/XCommander --check ~/.config/xcommander/config.toml

It prints what it found and exits with an error code if the file can't be used, so you can also use it in a script or a Git hook for a shared project file.