Configuration & files

The gs CLI keeps two kinds of state on disk: your logins, which live in your home directory and are shared across every repo, and per-repo bookkeeping, which lives in a .gitstack/ directory inside each clone. One repo file is tracked and travels with the repository: .gitstack/policy.toml, which sets what a review needs before it lands. Who can read, write, and own a repo is not a file; it is set on the repo's settings page (see Repository access). This page documents each file, its schema, and which commands write it.

~/.config/gs/config.toml#

Your default login. gs login writes it after a successful browser handshake, and every command that talks to the server reads it (unless a named profile is selected; see below). Absence means "logged out": commands that need auth print not logged in; run gs login first.

server = "https://gitstack.sh"
token  = "gsd_9f3c...redacted"
handle = "alice"

The file is written with 0600 permissions inside ~/.config/gs/ (created 0700). gs whoami prints a summary of the active login without exposing the token.

gs logout revokes every device token you own on the server, then removes the selected profile's config.toml and token file. Other profiles keep their sessions. It is idempotent: running it while already logged out does nothing.

Auth profiles#

One machine can hold several signed-in identities, say a personal account and a work account on the same server, or accounts on two different servers. Each extra identity is a named profile:

gs login --profile work

That writes ~/.config/gs/profiles/work/ with its own config.toml (server, token, handle) and token sidecar, in the same shapes described on this page. The plain gs login identity is the default profile and stays where it always was, directly in ~/.config/gs/.

Every command picks exactly one profile to act as, checking in order:

1. The --profile <name> flag on the command itself.
2. The GS_PROFILE environment variable.
3. The repository pin, if the current repo has one.
4. The global default: default_profile in config.toml, else the default login itself.

A selector that names a profile that does not exist is a hard error. gs never falls through to a different identity than the one you asked for.

Two commands manage the roster:

gs auth list              # every profile: server, handle, default marker,
                          # and which one answers in this directory
gs auth use work          # set the global default
gs auth use work --repo   # pin the current repository instead

The repo pin is a one-line file at .git/gs-profile (in the git common directory, so every linked worktree of the checkout shares it). It is machine-local and never committed: your clone acts as work without imposing anything on anyone else who clones the repo.

The git credential helper#

gs login also sets up plain git push to authenticate against the same server, so pushes from inside a stack do not prompt for a password. Alongside config.toml it writes two more files into ~/.config/gs/:

It then adds a global git config entry so git runs that helper for your server's URL only:

credential.https://gitstack.sh.helper = !/Users/you/.config/gs/credential-helper.sh

The entry is reset before it is added, which clears any inherited helper (such as the macOS keychain helper Xcode ships) for that one URL. Everything else in your git config is left alone.

The .gitstack/ directory#

Every clone has a .gitstack/ directory at its root holding gs's per-repo bookkeeping. gs creates it on first use and adds two lines to the repo's machine-local ignore file, .git/info/exclude: /.gitstack/* and !/.gitstack/*.toml. The bookkeeping never shows up in git status, never lands in a commit, and is never imposed on anyone else who clones the repo. The exclude lines are written once and shared across every worktree of the clone.

The same directory holds the repo's committed config: policy.toml and checks.toml. The *.toml exception keeps those visible, so you change them like any other file: edit, gs add .gitstack/policy.toml, commit, and land the review. gs add stages config files even in clones that ignore the whole directory.

The directory holds the manifest, a couple of navigation and autostack sidecars, and a set of short-lived files that carry state from one command to the next:

.gitstack/branch-reviews.json#

The manifest. It maps the current branch to its tip commit and lists, bottom to top, the reviews carved out of the branch with each review's tip SHA. gs pushes this file to the server as a git blob, so the on-disk bytes and the pushed blob hash to the same SHA when they match.

{
  "branch": "add-billing",
  "branch_tip": "8f2a1c9e4b7d0a6f3c5e8b1d2f4a7c9e0b3d6f8a",
  "reviews": [
    { "review_id": "R412", "tip_sha": "1a2b3c4d5e6f7081920a1b2c3d4e5f6071829304" },
    { "review_id": "R413", "tip_sha": "8f2a1c9e4b7d0a6f3c5e8b1d2f4a7c9e0b3d6f8a" }
  ],
  "fixes": [188, 190]
}

A resolves field also exists on the wire to carry drained comment-thread ids to the server on push, but it is stripped from the persistent on-disk form.

For how reviews and stacks map onto this file, see Stacks & navigation and Reviews.

.gitstack/last-branch#

A one-line file naming the branch you were on. gs checkout r5 detaches HEAD at a review's tip so you can inspect it; before detaching, gs records your branch here. Switching back to a real branch clears the file. That is how gs knows which branch to return you to after you finish looking at a detached review.

.gitstack/autostack-fixes.json#

A sidecar written by gs autostack when its gate applies auto-fixes on top of your reorganized work. It records what the gate flagged and the exact diff the fixes introduced, kept separate from "your work, reorganized" so you can review the machine's changes on their own.

{
  "flags": [ /* findings the gate raised */ ],
  "gate_delta": "diff --git a/... (unified diff of the auto-fixes)"
}

Repository access#

Who can read, write, and own a repo is set on the repo's settings page, under Access. It is not a file in the repository, so moving a branch never changes who has access.

The person who created the repo is always an owner and is not listed. In an organization, members reach every repo through their org role as well. Repo owners, org owners and admins can add someone by handle, change a role, or remove someone. A change takes effect right away and is recorded in the audit log.

Repos created with an older GitStack may still have a .gitstack/owners.toml. GitStack no longer reads it, and the settings page points it out so you can delete it.

.gitstack/policy.toml#

The repo's landing policy: which CI checks must pass and who must approve a review before it lands, and what happens when a land turns the default branch red. It also lists branches gs repo prune must keep. It is tracked, lives on the default branch, and changes only through a review that a repo owner approves. The policy that applies to a land is the one already on the default branch, never the one in the review being landed.

# .gitstack/policy.toml
[checks]
enabled = true
required = ["build-and-test", "lint"]

[approvals]
min_lgtms = 2
require_requested_reviewers = true
owners_bypass = false

[[approvals.rules]]
paths = ["docs/**", "CHANGELOG.md"]
min_lgtms = 0

[[approvals.rules]]
paths = ["src/billing/**"]
min_lgtms = 3
owner_lgtm = true

[prune]
keep = ["staging", "release/*"]

[mirror]
github_managed = ["production"]

[landing]
on_red = "revert"

Every table is optional. Without the file, a review needs no LGTM, owners may land anything, and no checks are required. A change to an owner-controlled file still needs an owner's LGTM.

[approvals]:

Site admins can always land, so a repo can't lock itself out. Automerge never gets the owner bypass.

[[approvals.rules]] set the approvals for the files they match, so review effort goes where the risk is:

Each file a review changes takes the last rule that matches it, as in CODEOWNERS; files no rule matches take the top-level min_lgtms. The review needs the most any of its files needs, counting only the review's own changes, not the rest of its stack. gs stack, gs submit and the review page name the rule that decided: needs 1 more LGTM (1 of 3, src/billing/**). If GitStack can't list a review's files, it applies the strictest rule.

[checks]:

[prune]:

[mirror]:

[landing]:

An invalid file counts as "notify".

The file is read strictly. A typo like min_lgtm, a wrong type, a min_lgtms outside 0 to 10, a path rule missing paths or min_lgtms, a malformed glob, an on_red other than "revert" or "notify", or a github_managed glob that matches the default branch makes it invalid, and an invalid policy refuses every land except a repo owner's, so an owner can land the fix. It also refuses every prune, since the branches it means to keep are unknown. The repo settings page shows the policy in force, and flags an invalid file.

Repo owners can also change the policy from the repo settings page. Like a collaborator change, saving does not touch the default branch: it opens (or updates) a review on the reserved settings/policy branch that edits policy.toml for you, and the new rules take effect when a repo owner lands it.

Migrating from checks.toml#

Repos that set required checks before policy.toml existed have a .gitstack/checks.toml with enabled and required at the top level. It keeps working, and migrating is optional and manual:

1. In a review, add a [checks] table to .gitstack/policy.toml with the same enabled and required keys, and have a repo owner approve and land it.
2. Once it lands, policy.toml wins and checks.toml is ignored. The repo settings page says so. Delete checks.toml in a later review.

A partial migration is safe. A policy.toml with only an [approvals] table, or with an empty [checks] table, leaves checks.toml in force.