Configuration

Margin needs zero configuration; everything below is optional. Config keys are a stability surface (ADR-0021): renames get a deprecation cycle.

Files and precedence

Later sources win:

1. Built-in defaults
2. User config: $XDG_CONFIG_HOME/margin/config.toml (~/.config/margin/config.toml fallback; %APPDATA%\margin\config.toml on Windows). Set $MARGIN_CONFIG to point at an explicit file.
3. Repo config: .margin.toml at the repository root (searched upward from the working directory, stopping at the .git boundary)
4. CLI flags: --theme, --layout, --no-untracked, --no-mouse. collapse and custom themes are file-only; --discard-without-backup is flag-only by design (ADR-0017) and never stored.

Inspect the merged result with margin --dump-config.

Unknown or misspelled keys are errors with did-you-mean suggestions, never silently ignored.

Keys

# User config: full surface.
theme = "auto"             # auto | ledger | foolscap | carbon | blueprint
                           # auto matches the terminal background (themes.md)
                           # or the name of a [themes.<name>] section
layout = "auto"            # auto | unified | split
include_untracked = true   # show untracked files in `margin` / `margin diff`
                           # (`--no-untracked` overrides per invocation)
mouse = true               # wheel scroll + click in the TUI; false keeps the
                           # terminal's own text selection (`--no-mouse` too)
discard_trash = true       # back up discarded hunks to .git/margin/trash/
                           # before applying (ADR-0014); `margin undo` restores
                           # DEPRECATED (ADR-0017): `false` still opts out
                           # until removal, but every invocation warns — use
                           # `--discard-without-backup` per invocation instead
collapse = []              # globs to auto-collapse (za expands), on top of
                           # built-in lockfile/generated heuristics; `*` stays
                           # within a path segment, `**` crosses, `?` is one
                           # char; slash-less patterns match the basename

[themes.mocha]             # custom themes (themes.md#custom-themes): a
base = "carbon"            # built-in base plus #rrggbb overrides; user
addition = "#3ddc84"       # config only — never the repo file

Repo config is display-only

.margin.toml accepts theme, layout, and collapse only. This is the ADR-0008 trust rule: checking out a repository must never change what Margin does, only how it looks. (collapse qualifies: folding hides no content permanently — za reopens anything.) Behavior keys in a repo config are an error — in particular, a checked-out repository can never disable discard backups.

The user-level discard_trash = false opt-out is deprecated (ADR-0017): it still applies until removal, but Margin warns on every invocation and the confirmation prompt states that recovery is unavailable. To discard without a recovery copy, pass --discard-without-backup for that invocation instead — the choice is never stored.

Environment

See themes.md for what each theme looks like and how the degraded modes behave.