User commands

Custom shell commands wired to a keybind, for project-specific actions (run a test suite, open the current commit in tig / lazygit, ping a deploy script, …). The command and the key are configured separately: the command lives under [core.user_command], the key under [keybind].

Define commands

Each command is an entry commands_N (where N is the command’s ID):

[core.user_command]
commands_1 = { name = "Run tests", commands = ["cargo", "test", "--workspace"] }
commands_2 = { name = "Open in tig", type = "suspend", commands = ["tig", "{{target_hash}}"] }
commands_3 = { name = "Notify deploy", type = "silent", commands = ["notify-send", "deploy started"] }
tab_width = 4

Field	Type	Description
name	string	Label shown in the user-command output view.
commands	array of strings	Program + arguments. First element is the binary, rest are args.
type	inline (default) / silent / suspend	How the command runs, see below.
refresh	bool (default false)	After execution, refresh the commit list. Incompatible with inline (validated at config-load).
tab_width	int (sibling of commands_N)	Display width for \t characters in command output. Applies to all commands.

Execution types

• inline, output renders inside a gitoui pane. gitoui stays alive, you can scroll the output. Best for git diff, git log, static-output inspection.
• silent, output discarded. Best for fire-and-forget commands (notify-send, background &, …).
• suspend, gitoui drops alt-screen + raw mode, the command takes over the terminal, gitoui resumes on exit. Best for interactive editors (vim, nano) and full-screen TUIs (tig, lazygit).

Bind a key

The command entry itself does not carry a key. To bind a shortcut, use [keybind] with the special user_command_N action name where N matches the command’s ID:

[keybind]
user_command_1 = ["f5"]
user_command_2 = ["f6"]
user_command_3 = ["ctrl-d"]

When you press the bound key, gitoui dispatches UserCommand(N) → opens the user-command view → runs commands_N.

Pick stable keys

F-keys (f1 … f12), ctrl+letter or alt+letter behave the same across terminals and keyboard layouts. Shift+digit (e.g. shift-1) is fragile, QWERTY US sends ! instead of shift+1, while AZERTY FR sends shift+1 literally. Stick to F-keys / ctrl-/ alt- for predictable bindings.

Overrides drop the default

Binding user_command_1 = ["t"] in [keybind] replaces the default add_tag = ["t"], t no longer adds a tag. Mirror it to keep both: add_tag = ["t", "ctrl-t"] (or pick a free key in the first place).

Placeholders

Inside the commands array, these tokens are substituted at runtime with values from the focused commit / view:

Token	Value
{{target_hash}}	Full SHA of the focused commit.
{{first_parent_hash}}	Full SHA of the focused commit’s first parent.
{{parent_hashes}}	All parent SHAs, space-separated (useful for merges).
{{refs}}	All refs pointing at the commit (branches + remote branches + tags).
{{branches}}	Local branch names at the commit.
{{remote_branches}}	Remote branch names at the commit.
{{tags}}	Tag names at the commit.
{{area_width}}	Width (cells) of the user-command output pane.
{{area_height}}	Height (cells) of the output pane.

{{area_width}} / {{area_height}} are handy for tools that take a --width / --columns flag, pass the pane size so output wraps correctly inside gitoui rather than against your terminal width.

Full worked example

[core.user_command]
commands_1 = { name = "git diff (colored)", type = "inline", commands = [
  "git", "--no-pager", "diff", "--color=always",
  "{{first_parent_hash}}", "{{target_hash}}",
] }
commands_2 = { name = "Open in tig", type = "suspend", commands = ["tig", "{{target_hash}}"] }
commands_3 = { name = "Run tests", commands = ["cargo", "test", "--workspace"], refresh = true }

[keybind]
user_command_1 = ["f5"]
user_command_2 = ["f6"]
user_command_3 = ["f7"]

Limits

• Commands run with the same env as the gitoui process, no isolation, no sandbox.
• Output renders verbatim; ANSI escape codes (colors, cursor moves) pass through.
• inline blocks the UI until the command exits. Prefer suspend for interactive tools, or background with & + silent.