Skip to content
gitouiv0.3.6

Config file

The config file lives at $XDG_CONFIG_HOME/gitoui/config.toml (default ~/.config/gitoui/config.toml). Override with GITOUI_CONFIG_FILE=....

Everything below is optional, gitoui ships with sensible defaults and only reads the keys you specify. Unknown keys are rejected with a styled diagnostic at boot.

Where it lives

Section titled “Where it lives”
  • Directory~/.config/gitoui/
    • config.toml the file documented on this page
    • Directorythemes/
    • github_token.toml OAuth (mode 0600, user-only)

Top-level sections

Section titled “Top-level sections”
Section Purpose
[core.option] UI defaults (theme, graph style, initial selection…).
[core.search] Persistent search toggles (fuzzy / case / regex).
[core.user_command] Custom user-defined shell commands.
[core.external] External hooks (clipboard, browser opener).
[ui.common] Per-view mode preferences.
[graph.color] Graph palette overrides (independent of the UI theme).
[color] Theme color tokens, usually populated via a named theme.
[keybind] Keybindings (global section + scoped sub-tables).

[core.option]

Section titled “[core.option]”
Key Type / default Effect
theme string / "Tokyo Night" Built-in theme name or custom theme stem (file at ~/.config/gitoui/themes/<name>.toml). Empty string disables theming.
syntax_theme string / "base16-ocean.dark" Syntect theme for diff syntax highlighting. Overridden when theme is a named theme.
graph_renderer auto / ascii / kitty / iterm / kitty-unicode / sixel (default auto) Image protocol for the commit graph. auto detects at startup. ascii renders with Unicode box-drawing characters (no image protocol).
graph_style rounded / angular / smooth (default smooth) Branch corner shape.
graph_width auto / single / double (default auto) Graph image cell width.
initial_selection latest / head / top (default latest) Cursor position when opening.
github_avatars bool / true Render GitHub avatars next to commits, comments, reviews.
date_time_format enum (default ddmmyyyy_hhmm) One of: ddmmyyyy_hhmm, ddmmyyyy, mmddyyyy_hhmm, yyyymmdd_hhmm, iso, yyyymmdd_hhmm_dash.
date_time_local bool / true Convert commit times to your local zone.
huge_repo_threshold usize / 50_000 Commit-count cap above which gitoui auto-disables the graph column at startup. On very large repos (kernel, rust-lang/rust, chromium, …) the inline-image pipeline can struggle to keep up: lag, freezes, render glitches. When the live git rev-list --count HEAD exceeds this value, [ui.list] graph_enabled is forced to false at launch and the Configuration view’s Graph Enabled row shows a red warning in its Details panel. The user can still toggle the graph back on from that view. Set to 0 to disable the auto-disable entirely.

[core.search]

Section titled “[core.search]”

Persistent toggles for the list-view search bar.

Key Type / default Effect
fuzzy bool / false Default to fuzzy matching.
ignore_case bool / false Default to case-insensitive matching.
regex bool / false Default to regex matching.

These mirror the in-app toggles (s, z, x in search mode). The view writes back to disk when the user flips them.

[ui.common]

Section titled “[ui.common]”
Key Type / default Effect
mouse_enabled bool / true Master mouse switch.
diff_mode enhanced / unified (default enhanced) Side-by-side vs unified diff view.
conflict_view two-pane / inline (default two-pane) Conflict editor layout.
rebase_view inline / compact / split (default inline) Interactive-rebase plan layout.

[ui.list]

Section titled “[ui.list]”
Key Type / default Effect
graph_enabled bool / true Render the inline commit-graph image column. Set to false to skip all graph image generation and terminal-image uploads, for near-instant scrolling on huge repos (rust-lang/rust, linux kernel).

When the native graph is wider than ~40% of the panel (heavy multi-branch repos), the column is capped to that 40% and the visible lane window slides with ← / → from the commit list (Kitty terminals only: it uses Kitty’s source-rect crop).

[ui.refs]

Section titled “[ui.refs]”
Key Type / default Effect
width u16 / 42 Width (in cells) of the refs side-panel that opens with Tab. Minimum 1. Bump if you have long branch names like origin/dependabot/github_actions/... and want them visible without scrolling.

[graph.color] and [color]

Section titled “[graph.color] and [color]”

Override the graph palette without changing the UI theme:

[graph.color]
background = "#1a1b26"      # graph cell background
edge = "#3b4261"            # connector lines + commit-circle outline
branches = [
  "#f7768e", "#7aa2f7", "#9ece6a", "#e0af68",
  "#bb9af7", "#7dcfff", "#ff9e64", "#73daca",
  "#ad8ee6", "#2ac3de", "#ff007c", "#41a6b5",
]

If a named theme defines its own graph_branches, that wins over a generic [graph.color.branches] setting, see Themes.

[keybind]

Section titled “[keybind]”

Two-layer keybinding system, see the dedicated Keybindings page for the full reference.

[keybind]
# Global UserEvents, same shape as upstream serie.
quit = ["q"]
navigate_up = ["k", "up"]


# Per-view scopes nest under `[keybind.scope.<path>]`.
[keybind.scope.pr]
approve = ["ctrl-a"]

Validation

Section titled “Validation”

gitoui validates the entire config at boot. Failures render a styled --help-shaped diagnostic block before the no-repo splash, catching:

  • TOML syntax errors → file + line + caret pointer to the bad token.
  • Schema mismatches (wrong type, unknown key) → which key and what was expected.
  • Theme problems, unknown name, missing file under themes/, file with invalid TOML, or an unknown base = "..." reference.
  • Keybind issues, duplicate keys within a scope, unknown event name, keys with more than one modifier prefix.

Config error diagnostic, gitoui refuses to start, styled error pane with caret pointer + line + expected schema