init¶

git city init is the one-time onboarding step for a repository. It records which branch is your trunk — the long-lived, never-rebased branch that every feature ultimately descends from — into the project's local configuration file so that all other commands know where the tree is rooted.

You run it once per clone (or once per project, since the file it writes is committable). After that, git city new, sync, tree, and the rest have a trunk to anchor on.

git city init [--trunk <name>] [--remote <name>] [--dry-run]

Note

init only touches configuration. It does not create branches, move commits, or talk to the remote. It is safe to run on a dirty working tree. Use --dry-run to see which trunk (and remote) it would record, and in which file, without writing anything.

Recording a preferred remote¶

If your repository has more than one remote — say a deploy target like piku alongside your real upstream — pass --remote <name> to record which one git-city should push to and fetch from:

git city init --trunk main --remote origin

This writes remote = "origin" into the local git-city.toml. Without it, git-city uses origin when present, otherwise the first remote — which may not be the one you want. The name must be an existing remote; an unknown name is refused. See the configuration reference for how the remote is resolved.

How the trunk is chosen¶

init resolves the trunk in one of three ways, in priority order:

Source	When it applies	Result
`--trunk <name>`	You pass the flag explicitly	The trunk is set to exactly `<name>`
Auto-detect	No flag, common names exist	Picks `main`, else `master`
Interactive dropdown	No flag, no obvious default, on a TTY	Lets you choose a branch from a list

If none of these can settle on a branch — for example, no flag, no main/master, and no interactive terminal — init reports a clean error rather than guessing.

Explicit: `--trunk`¶

When you know the name, pass it directly. This is the right choice in scripts, CI, or any non-interactive context.

git city init --trunk develop

Auto-detect¶

With no flag, init looks for the conventional trunk names and uses the first it finds:

git city init

It selects main if present, otherwise master. This covers the vast majority of repositories with no further input.

If there is no flag and no obvious default but you are on an interactive terminal, init shows a dropdown of the repository's branches so you can pick the trunk yourself. This relies on a TTY; in a non-interactive environment with nothing to auto-detect, it errors instead of prompting.

What it writes¶

init writes only the local file, <repo>/git-city.toml. It records a single key:

trunk = "main"

Because this file lives in the repository, you can commit it so the whole team shares the same trunk. init deliberately does not copy any values from your global configuration into it — the local file stays minimal and contains only what you actually set here.

Tip

Your global file at ~/.config/git-city/config.toml (or $XDG_CONFIG_HOME/git-city/config.toml) still applies and is merged underneath the local file, key by key. init simply does not bake those global values into the committable local file.

Settings such as perennials (additional long-lived branches treated like the trunk) are not written by init; add them to git-city.toml by hand when you need them.

Verifying the result¶

After running init, use config to confirm what git-city resolved and which files are in play:

git city config

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

The local: line points at the file init just wrote.

Examples¶

Onboard a standard repository where the trunk is main or master:

git city init

Onboard a repository whose trunk is named something else, non-interactively:

git city init --trunk trunk

Then create your first feature off the trunk:

git city new add-login

→ Configuration reference