Configuration reference¶

This is the exact reference for every setting git-city reads. Project settings live in TOML files you can read, edit, and commit; per-branch state lives in your local Git config. If you want the rationale for that split rather than the bare keys, read the configuration concept first — this page is the lookup table.

TOML settings¶

git-city resolves its project settings from two TOML files, merged key by key, with local overriding global:

File	Path	Scope
Global	`$XDG_CONFIG_HOME/git-city/config.toml` or `…/git-city.toml` (default base `~/.config/git-city/`)	Your personal defaults, across every repository
Local	`<repo>/git-city.toml` or `<repo>/.git-city.toml`	One project; committable, shared with your team

Each location accepts either filename, but only one may exist at a time — git-city errors rather than guess precedence if it finds both.

The merge is per key, not whole file. A key set in the local file overrides the same key in the global file; keys present only in the global file still apply.

Local wins, key by key

If your global config sets perennials and a repo's local git-city.toml sets only trunk, the effective configuration is the local trunk plus the global perennials. A repository can override exactly the one key it cares about.

Keys¶

Key	Type	Default	Meaning
`trunk`	string	auto-detected (`main`/`master`)	The long-lived mainline. Never rebased; fast-forwarded from its remote.
`perennials`	array of strings	`[]` (none)	Additional long-lived branches that behave like trunks — never rebased, always fast-forwarded from their remote.
`remote`	string	`origin` if present, else the first remote	The remote that `sync`, `land`, and friends push to and fetch from. Set this when you have more than one remote (e.g. a deploy remote like `piku` alongside your real upstream) so git-city doesn't guess wrong.

Everything that is not the trunk or a perennial is a feature. For the full picture of what each branch type means, see branch types & flags.

Pin the remote when you have several

With multiple remotes and no origin, git-city falls back to the first remote — which may be a deploy target, not your upstream. Setting remote (or running git city init --remote <name>) removes the guesswork. A configured remote that doesn't actually exist is ignored, and git-city falls back to the default pick.

Sample `git-city.toml`¶

trunk = "main"
remote = "origin"
perennials = ["release", "staging"]

A minimal file may set only trunk:

trunk = "main"

Malformed TOML

A broken or unparseable TOML file produces a clean git-city: <message> error on stderr (exit code 1), not a crash. Fix the syntax and rerun.

init writes only the local file

git city init records the trunk in the local git-city.toml. It never bakes your global values into the committed file, so your personal preferences stay personal.

→ git city init

Per-branch state (Git config)¶

A feature's parent and its modifier flags are stored under the git-city.branch.<name>.* namespace in your repository's Git config. This data is local to your clone — it never appears in a tracked file, so it produces no diff and never conflicts with a teammate's stack.

Key	Type	Meaning
`git-city.branch.<name>.parent`	string	The branch this feature is stacked onto.
`git-city.branch.<name>.parked`	bool	Skip this branch during `sync`.
`git-city.branch.<name>.private`	bool	Sync with its parent like any feature, but never push.
`git-city.branch.<name>.landed`	bool	Set by `land`; marks the branch for `prune`.
`git-city.branch.<name>.sync-strategy`	`rebase` \| `merge`	How `sync` integrates the parent (default `rebase`).

The parent key is set for you by the commands that move commits — new, insert, reparent, and the rest. The landed flag is set for you by land and cleared when prune removes the branch. You do not normally edit either by hand.

The parked and private flags do not yet have dedicated CLI commands. Set them with git config for now:

git config git-city.branch.add-login.parked true
git config git-city.branch.add-login.private true

To clear a flag, unset the key:

git config --unset git-city.branch.add-login.parked

→ Branch types & flags

Inspecting the effective configuration¶

git city config prints the resolved settings and the path to each config file, noting whether it exists:

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

This is the fastest way to confirm which trunk and remote git-city is actually using and where it read its settings from.

→ git city config