Configuration

File location

Magritte’s global configuration file lives at:

$XDG_CONFIG_HOME/magritte/config.toml

Or when XDG_CONFIG_HOME is not set:

~/.config/magritte/config.toml

Magritte automatically reloads config values when the file changes. Omitted values automatically fall back to their default, so an empty file is still a valid configuration.

See config.example.toml for a full example that you can copy and edit as you see fit.

Settings screen

Press , or choose Magritte > Settings to access the settings screen. Here you can change common options such as themes, fonts, editors, and the keymap preset.

Per-repo configuration

All configuration values can be overridden by a repo-local configuration file located at .git/magritte/config.toml. E.g.:

# .git/magritte/config.toml
dark_theme = "Nord Dark"

[fetch]
auto = true
interval_minutes = 10

If you create the .git/magritte directory outside Magritte while the app is running, restart Magritte once so it can begin watching the directory.

Top level settings

All scalar settings are top-level TOML keys. Every setting is optional.

Theme names match the entries under Light theme and Dark theme in Settings. Magritte includes GitHub, Solarized, Selenized, Gruvbox, Catppuccin, Nord, Dracula, and tao variants.

External file editor

Set editor to a command such as code -w, zed, or subl -w. On macOS, you can also use an application name such as "Zed" or "Visual Studio Code". Leave it empty to use the system default application.

Magritte opens supported editors at the line under the cursor. Terminal editors are not supported for Open File because Magritte cannot attach them to your existing terminal session.

Status sections

Use [status] to choose which sections appear and their order:

[status]
sections = [
  "untracked", "unstaged", "staged", "stashes",
  "unpulled", "unpulled-pushremote", "unpushed", "unpushed-pushremote",
  "recent",
]
recent_count = 10

sections is an ordered list. The list order becomes the display order, and an omitted section is hidden. Omit [status] or use an empty list to restore the default order shown above. Unknown section ids produce a warning.

Push-target sections are hidden when the push target and upstream are the same. All empty sections are skipped. Commit rows show labels for branches, tags, and remotes.

Actions follow the item at the cursor. Return opens a commit or stash, while Cmd+C copies its hash or reference. On a stash, a applies it, A pops it, and x in the Evil preset or k in the Vanilla preset drops it after confirmation. On a section heading, s or u acts on the whole section. Discarded untracked files are moved to the system Trash.

Set show_tags_in_title_bar = true to show the nearest reachable tag. For example, v1.0 (5) means the current commit is five commits after v1.0.

Auto-fetch

Use [fetch] to keep incoming and outgoing commit counts current. Background fetching is off by default.

[fetch]
auto = true            # default false
interval_minutes = 30  # default 30; minimum 1

Magritte runs git fetch for the current branch’s configured remote, then refreshes the status view. It skips a fetch while another operation is running. If a fetch fails, for example while you are offline, Magritte waits until the next interval and tries again.

This setting can be configured per-repo like all others, as described in per-repo configuration.

As a git mergetool

You can set git to use Magritte as your mergetool, even when you’re working outside of Magritte. Just put the following in your .gitconfig:

# .gitconfig
[merge]
    tool = magritte
[mergetool "magritte"]
    cmd = magritte --mergetool "$MERGED"
    trustExitCode = true

Run git mergetool to open each conflicted file in Magritte. Resolve the conflicts and confirm the finish prompt. Magritte returns success only when the file has no unresolved conflict markers, which lets Git stage it. Closing the window before then reports failure for that file.

Key mappings

Every key resolves to a command, and three tables cover the three places keys live: [keymap] binds keys in the views, [transient.<id>] edits the keys and options inside one command menu, and [vim.keymap] adds sequences to the commit editor’s Vim mode. The same command IDs work in the first two, and "unbound" removes an entry wherever it appears.

Global keys

Magritte offers two base keybinding presets: evil and vanilla. The evil preset follows evil-collection’s magit bindings, while vanilla follows standard Emacs and Magit bindings.

Regardless of the preset chosen, key mappings can be added, changed, or removed via the [keymap] table. Each entry maps a key to a command ID.

keymap_preset = "evil"

[keymap]
"K" = "branch-delete"   # K now deletes a branch
"x" = "unbound"         # remove the default discard binding
"E" = "commit-extend"   # E now extends the current commit

Keys are case-sensitive. For example, s and S are different bindings. Sequences are written with spaces between their keys, such as g r or ctrl-x ctrl-c, and modifiers are written as ctrl-, alt-, or cmd-. Prefixes do not need separate bindings. If you bind ". c" = "commit", . automatically becomes a prefix.

Some keys are fixed and cannot be remapped:

• Esc and Ctrl-g cancel a job, selection, pending sequence, or popup.
• ? opens help.

Transient menus, pickers, and the commit editor handle their own keys while they are active.

Transients menu keys

Transient menus are the command menus opened by keys such as c, b, and p. Use [transient.<id>] to add an action or Git option, move an existing entry, or remove one. The customizable menu ids:

Key mappings take the form of "key" = "command-id". An extended form with options is also available:

[transient.<id>]
# Basic form
"<key>" = "<command-id>"

# Extended form
"<key>" = {
    command = "<command-id>",   # Specify one of
    flag = "<--flag>",          # command or flag
    description = "<description>",
    before = "<other-key>",     # Specify at most
    after = "<other-key>",      # one of before,
    group = "<group name>"      # after, or group
}

Some concrete examples:

[transient.branch]
"X" = "branch-delete"        # b X deletes a branch

[transient.fetch]
"-d" = "--depth=1"           # add a Git option

[transient.commit]
"A" = "commit-amend"         # add an action to the Custom group
"-v" = { flag = "--verbose", description = "Show diff in message", after = "-s" }
"W" = { command = "user.wip", group = "Create" }
"f" = { after = "c" }        # move Fixup after Commit
"F" = { group = "Edit" }     # move Instant fixup into Edit

• A switch contains a Git option such as "--depth=1". Switch keys begin with a dash, so -d appears under the menu’s - prefix.
• Use before or after to place an entry beside another key. Use group to append it to a named group. Magritte creates a missing group at the end.
• Built-in entries can be moved by specifying only before, after, or group
• Set an entry to "unbound" to remove it. For example, "-n" = "unbound" removes commit’s --no-verify option.

Config-derived switches

Some switches start with the value from your Git configuration:

Turning one of these switches off passes its negated form, such as --no-gpg-sign. Magritte highlights the switch to show that it overrides your Git configuration.

Saved argument defaults

Press Ctrl-s in a transient menu to save its current options as the defaults for the next time you open it. Magritte asks where to save them.

Globally saved arguments are stored in transient-arguments.toml beside your global configuration file. Locally saved arguments are stored in .git/magritte/transient-arguments.toml.

The file stores Git arguments rather than menu keys, so key remapping does not affect saved defaults:

# transient-arguments.toml
commit = ["--all", "--signoff"]
log = ["-n50", "--grep=fix"]

A config-derived switch is saved only when you change it from the Git-config value. Leaving it untouched continues to follow Git configuration.

Vim mode keys

Set commit_vim_mode = true to enable Normal, Insert, and Visual modes in the in-app commit editor. It supports most standard vim movements and operations.

For full Vim behavior, you can use an external commit editor:

commit_in_editor = true
commit_editor = "nvim"

A [vim.keymap] table adds your own key sequences for the editor-level commands: commit, cancel, discard (cancel without the confirmation), reflow (the whole message), and help.

[vim.keymap]
"Q" = "cancel"
"; w" = "commit"
"cmd-g z" = "help"
"ctrl-x ctrl-c" = "commit"

Write sequences with a space between keystrokes, such as Q x, Q enter, or ctrl-x ctrl-c. A modifier chord is one keystroke: use cmd-, ctrl-, alt-, or shift-, as in cmd-enter. Mappings are case sensitive, e.g. Q means Shift-Q. Named keys include enter, tab, and escape.

For literal character-only sequences, the compact form is also accepted: Qx is equivalent to Q x. Spaces are recommended because they also work when a sequence contains named keys or modifier chords.

The first key of a custom sequence shadows its normal Vim action. For example, mapping "d x" makes d wait for x, so it no longer starts the delete operator. Choose prefixes you do not otherwise need.

Custom commands

Use [[command]] to make a git or shell command available in the : palette and the keymap.

[[command]]
id = "user.sync"
title = "Sync"
run = "git pull --rebase && git push"

[[command]]
id = "user.wip"
title = "WIP commit"
run = "git commit -m WIP"
refresh = false           # skip the status refresh afterward
confirm = false           # never ask (unset = ask when it looks destructive)

run executes through sh -c in the repository root. Shell operators, pipes, and redirection work, and the command can run any program. For example, run = "make test" is valid.

Placeholder templates

The following placeholders can be used in run and title values:

If a required value is unavailable, the command does not run. For example, a command containing {file} reports an error when no file is selected.

A title such as "Rebase onto {default-remote}/{default-branch}" displays as “Rebase onto origin/main”, for example. If a title placeholder cannot be resolved, it remains visible as written.

Bind a custom command by id, for example "X" = "user.wip", or run it by title from the command palette. Bound commands also appear in the ? menu’s Commands group.

Command output appears in a notification. Failures remain until dismissed, and long output points to the $ command log for the full text. Commands containing clean, --hard, --force, or --force-with-lease ask for confirmation. Set confirm = false on a command you trust to skip that prompt, or confirm = true to always ask — for a destructive command those words can’t reveal, such as a script.

Command ID reference

Bind any id below from [keymap], or reference it from a [transient.<id>] action. none in the default-key column means the command has no direct binding, but you can still find it in a transient menu or the : command palette.

Secondary views add scoped ids that can be remapped in the same way. These include refs-*, worktree-*, flat-*, rebase-todo-*, resolve-*, log-open, and git-log-toggle-queries. Open the : palette in a view to see every command available there.