Skip to content

config

git city config prints the effective configuration — the values git-city actually uses after merging your global and local TOML files — alongside the paths of those files and whether each one exists. It is read-only: nothing is written, fetched, or changed.

Reach for it whenever you want to confirm which branch git-city treats as the trunk, what counts as a perennial, and exactly which files are feeding those values.

git city config

trunk:      main  (auto-detected)
remote:     origin  (auto-detected)
perennials: (none)
global:     /home/you/.config/git-city/config.toml  (not present)
local:      /path/to/repo/git-city.toml

What it reports

Line Meaning
trunk The resolved trunk branch. The note in parentheses tells you where it came from — (auto-detected) when git-city inferred main/master, or recorded by init.
remote The resolved remote that git-city pushes to and fetches from. (auto-detected) means it fell back to origin (or the first remote); otherwise it was set via remote in the config or init --remote.
perennials The resolved list of additional long-lived branches, or (none) when the array is empty.
global Path to the global config file, with (not present) if it does not exist on disk.
local Path to the committable, per-repo config file, with (not present) if it does not exist.

The trunk and perennials shown are the merged result: the local file overrides the global one key by key. So the values on these lines may not come from a single file — config shows you the outcome, while the global and local lines show you the sources.

Note

A (not present) file is not an error. git-city works with no config at all: with neither file present it auto-detects the trunk and treats the perennials list as empty. The output above is exactly what a fresh repository looks like before you run init.

How the values are resolved

git-city reads two TOML files and merges them, with local winning per key:

$XDG_CONFIG_HOME/git-city/config.toml   (global, default ~/.config/git-city/config.toml)
        │  merged, local overrides global key by key
        ▼
<repo>/git-city.toml                    (local, committable)

Both files share the same keys:

Key Type Description
trunk string The long-lived branch every feature ultimately descends from.
remote string The remote git-city pushes to and fetches from (defaults to origin, else the first remote).
perennials array of strings Extra branches treated as trunks (never rebased, fast-forwarded from their remote).

After init records a trunk in the local file, the output reflects it:

trunk:      main
remote:     origin  (auto-detected)
perennials: (none)
global:     /home/you/.config/git-city/config.toml  (not present)
local:      /path/to/repo/git-city.toml

Tip

Per-branch metadata — each feature's parent, plus the parked and private flags — does not live in these TOML files. It is stored in Git config (git-city.branch.<name>.parent) and is local to your clone, so it never churns a tracked file. config reports only the repo-wide trunk and perennials.

Inspecting and editing the files

config tells you where the files are; edit them directly when you want to change the trunk or add perennials. A local file might look like this:

trunk = "main"
perennials = ["develop", "release"]

Warning

A malformed TOML file produces a clean git-city: <message> error rather than a crash. If config errors out, check the file paths it would have printed for a syntax mistake.

Note that init only ever writes the local file, and it does not bake resolved global values into it — so the local file stays minimal and the global file remains the place for your cross-repo defaults.

  • init — record the trunk in the local git-city.toml (interactively or with --trunk).
  • For the full key reference, file precedence rules, and per-branch Git-config state, see the configuration reference.

→ Configuration reference