greengate

Catch the bad commit before it exists — and take the whole thing back out in one command.

One Rust binary, no runtime, no config file to write. Install it, run greengate install in a repository, and your next commit is checked by thirty-nine language-aware checks that already know when to stay out of the way.

greengate catching a commit and letting the fixed one through

Why this one

  • Useful in the first minute. Other hook managers install empty and wait for you to write YAML. greengate ships thirty-nine checks — commit-message conventions, merge-conflict markers, linters and formatters for the languages your repository actually uses, branch rules, your test suite — and each one fires only where the repository has opted into its tool. greengate list shows you what runs here, and why the rest will not.
  • Nothing on the commit path but std. The hook binary links no external crates, and CI fails any build that changes that. What runs on every commit, with your credentials, has the smallest supply chain this project could arrange: none.
  • A cloned repository cannot run code on your machine. Repositories declare their own checks in a committed greengate.conf — and those declarations are inert until you review them and say greengate trust. No other hook manager puts a review gate between git clone and running the repository's commands. The trust model.
  • Your uncommitted work is never collateral. Checks run against exactly what you staged; unstaged work is held aside without git stash and restored even if a check panics. The design that makes that true is the most carefully argued part of the codebase.
  • Leaving is one command. greengate uninstall removes exactly the six shims install wrote — a hook you or another tool put there is named and left alone. A gate you cannot exit cleanly is a gate you were right not to enter.

How that stacks up against pre-commit, lefthook and husky, feature by feature: how it compares.

Why you can let this near your commits

A prompt theme is cosmetic. This blocks commits and pushes, reads every staged file, and runs with your credentials while nobody is watching — so the claim it has to earn is not "delightful", it is "harmless".

  • The commit path links no external crates. greengate and greengate-runtime are std-only, and scripts/check-no-deps.sh fails a build that changes that — fails closed, so a cargo error or an unreachable registry is a failure rather than a reassuring green tick.
  • No telemetry, no update checks. With the commit path std-only there is not even an HTTP client linked to phone home with. The network a push does touch is git's own and the tools you opted into: pull-rebase runs git ls-remote/git fetch against your upstream (off with git config greengate.autoRebase false, see configuration), and the audit-* checks call cargo audit, npm audit, pip-audit and govulncheck.
  • Over a thousand tests, run on Linux, macOS and Windows, alongside cargo fmt --check, clippy -D warnings, an MSRV floor of 1.74 compiled for the commit path, and cargo-audit.
  • v1.0.0 followed a full security review, and each finding landed with a committed reproduction — a drive-by RCE via a relative path in the shim, a held-store format that let a repository plant a symlink outside the worktree, a trust prompt a repository could conceal declarations from.
  • Your uncommitted work is the thing that must never be lost. The release profile deliberately omits panic = "abort" so the Drop that restores unstaged work still runs when a check panics — with a test asserting on the manifest, because no behavioural test could catch that regression.

Threat model and private reporting: SECURITY.md.

The repositories around it

Three companions, each its own repository because it runs somewhere greengate deliberately does not:

  • greenbelay — a Claude Code PreToolUse hook for the mistake no git hook can reach, because it lives in the command string itself: git push … | tail -5 reports tail's exit status, so a rejected push reads as success. The guard judges the pipeline before it runs. Independent by design — no shared code, and neither needs the other; they meet in one optional place, where its session notice asks greengate agents-md --check whether the guidance block an agent is about to believe has gone stale.
  • greensummit — the CI half of greengate.attest: when every pre-push block gate passed locally, greengate leaves a signed note on the tree it tested, and this single-purpose verifier lets CI skip work provably already done. Fail-open by construction, and separate precisely so that greengate itself never runs in CI — the reasoning.
  • greengate-pack-java — the worked example of a pack: how checks greengate deliberately does not build in get shipped anyway.

Start here

  1. Installing and activating — get the binary, turn hooks on in one repository (or every repository you ever clone), and turn them off again.
  2. The checks — what the thirty-nine built-ins do, and what each one needs before it fires.
  3. Opting out — skip one check, downgrade a whole trigger, bypass a single commit, or remove the hooks entirely.

Then, as you need them: where the hooks fit in your flow · commit and branch conventions · configuration · custom checks · the trust model.

How the documentation is organised

The pages under Using greengate are for anybody who has installed it or is deciding whether to.

The pages under Design records are for maintainers: the arguments behind the current behaviour, kept because "why is it like this" is a question that comes back. Do not start there.

Installing and activating

Two separate acts, and keeping them separate is deliberate. Installing the binary puts a program on your machine. Activating turns hooks on in a repository. Nothing about the first does the second.

greengate was called amont until 3.0.0. Every installer below also places amont and amont-fleet beside greengate and greengate-fleet, as copies of them, so hooks a 2.x install baked to …/amont keep running the current build. Copies, not links: a 2.x amont install copies onto its target, and through a link it would overwrite greengate itself. The names greengate reads from disk, git config and the environment (greengate.conf, amont.* keys, GREENGATE_*) are unchanged in 3.0.0. The amont-* crates on crates.io stay at 2.3.1, and amont on npm at 2.3.0.

1. Get the binary

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/install/install.sh | sh

Windows, in PowerShell — the line above is POSIX sh, so on Windows it runs only under Git Bash:

irm https://raw.githubusercontent.com/greenharness/greengate/main/install/install.ps1 | iex

The installer resolves the latest release, downloads the archive for your platform, verifies it against the published SHA256SUMS, and writes the binary to $GREENGATE_BIN_DIR (default ~/.local/bin) by atomic rename, so a half-copied greengate never exists.

It refuses to guess. If the checksum does not match it exits rather than installing; if SHA256SUMS is missing or there is no sha256 tool on the machine it says loudly that the download was not verified rather than staying quiet about it. Verifying what this binary is before putting it in a position to read every staged file is the argument the project makes about its own dependencies, applied to itself.

The checksum is not the whole story, though. SHA256SUMS comes from the same release as the archives it describes, so it proves the download is intact — not that the release was built by this repository. Every release artifact, SHA256SUMS included, also carries a GitHub build attestation, and that is the check the installer does not run for you, because it needs the gh CLI or a Sigstore client:

gh attestation verify greengate-<version>-<target>.tar.gz --repo greenharness/greengate

See SECURITY.md for what each check does and does not prove.

~/.local/bin is not an arbitrary default: it is a candidate in the shim's own resolution order, so a binary there is found even by a shim whose baked path is wrong — and it is the same convention systemd, pipx and uv observe.

Where the binary ends up

greengate install copies the running binary somewhere stable and bakes that path into every shim it writes — unless the binary is already on your PATH, in which case it bakes it where it is and copies nothing.

That split matters for package managers. ./target/release/greengate install must copy, because cargo clean deletes that directory and the shims would stop resolving. A binary from brew install, cargo install or a distro package must not be copied: the copy is a second, unmanaged binary that the package manager will never update again, so brew upgrade greengate refreshes one file while every repository stays baked to a frozen one. That is the same staleness the copy exists to prevent, arrived at from the other side.

The path baked for a package-managed binary is the one PATH exposes, not the resolved one. Homebrew's /usr/local/bin/greengate is a symlink into /usr/local/Cellar/greengate/<version>/bin/, and that versioned directory is deleted on the next upgrade — baking it would pin every repository to a path about to stop existing. The same is true of nix, asdf and mise.

Installing somewhere else

$GREENGATE_BIN_DIR moves the binary, and install bakes wherever it landed into the shims it writes — so a custom location resolves through the baked path and needs nothing further.

The exception is the setup where shims are deliberately left unbaked: init.templateDir pointed at a checkout. Those shims resolve at run time from ~/.local/bin, which is a constant inside a POSIX sh file. Choose both and they stop composing — nothing baked a path, and the one path the shims know is not where the binary went. greengate install says so when it sees the combination, and offers the two ways out: link the binary where the shims look, or set $GIT_HOOKS_BIN.

$GREENGATE_BIN_DIR is an install-time setting only; the shim never reads it. The runtime override is $GIT_HOOKS_BIN — one variable able to redirect which binary executes on every commit is enough surface.

Pin a version, or install elsewhere:

GREENGATE_VERSION=v1.0.0 GREENGATE_BIN_DIR=~/bin \
  curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/install/install.sh | sh

Without the installer

Download an archive and its checksum from Releases. Prebuilt targets: x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc.

Or build it:

git clone https://github.com/greenharness/greengate.git
cd greengate && cargo build --release
./target/release/greengate install

Or from crates.io, which builds the same source (it places no amont alias; run greengate install once for it):

cargo install greengate

Or with Homebrew:

brew tap fredericrous/tap
brew trust fredericrous/tap
brew install fredericrous/tap/greengate

The brew trust line is Homebrew's policy for every tap outside its own core, not something specific to this one — a formula is code, and Homebrew now asks you to decide about running it explicitly. Which is the same argument this tool makes about a repository's declared checks.

As a project dependency (npm)

For a JavaScript project, the binary can travel with the repository instead of with the machine:

npm i -D @greenharness/greengate   # or: pnpm add -D @greenharness/greengate
npm pkg set scripts.prepare="greengate init"
npm install           # prepare runs; the hooks appear

Anyone who then clones the repository and runs npm install gets the hooks. That is §2 done for them, by the package manager, once — which is the whole point of the shape.

Six prebuilt platform packages are declared as optionalDependencies (@greenharness/greengate-darwin-arm64, @greenharness/greengate-linux-x64-gnu, …), each carrying os, cpu and libc, so npm and pnpm install exactly one and skip the other five. They live under a scope so that adding a target later cannot be refused by npm's spam heuristic, which rejects unscoped names on their shape alone — it turned down an unscoped amont-agent-win32-x64 while accepting amont-agent-linux-x64-musl beside it. There is no postinstall, deliberately: npm ci --ignore-scripts is a normal hardening choice, and a package that quietly installs nothing under it would fail much later, as greengate: not found from a git hook.

The bin npm links is a small JS shim, because a linked bin has to live inside the package it belongs to. It is not on the hook path: greengate init bakes the native binary's path into .git/hooks, so node runs once during prepare and never on a commit.

If your platform is not one of the six, npm install will succeed and the shim will say so the first time it runs. cargo install greengate builds the same source anywhere Rust does.

init and install are different verbs

greengate init wires up one repository and nothing else. It does not copy a binary into ~/.local/bin, does not touch ~/.config/git/git-templates, and never prompts — all three of which install does, and all three of which are wrong for something that runs on every teammate's npm install. The trust prompt is the sharp one: it reads /dev/tty, so in a terminal it would block, and npm install would hang on a question about a manifest nobody has read.

Outside a git repository init exits 0 in silence, because npm install legitimately runs from a tarball, inside a Docker build and in CI. It stays loud about everything else.

If anything ever installs without your dev dependencies

npm runs prepare on npm ci too — including npm ci --omit=dev, which is the usual second stage of a Dockerfile. greengate is a dev dependency, so it is not there, and prepare fails on a command that does not exist. The install fails with it, and a broken image build is a confusing way to learn this.

Guard it the same way husky's own documentation does:

"prepare": "greengate init || true"

Only where you need it. A repository with no production-install path should keep the bare greengate init, so a real failure — a hook it may not overwrite, a core.hooksPath another tool owns — is loud rather than swallowed. || true buys nothing there and hides something.

init already handles the other half of a Docker build on its own: the builder stage has a package.json and no .git, which is the silent exit 0 above.

On turning hooks on from a package manager

The installer says, and means, that it does not turn any hooks on. A prepare script plainly does. The two are not in tension, and the distinction is worth stating rather than leaving to be reconciled:

  • the machine still decides nothing implicitly. Installing this tool, by any route, activates nothing anywhere;
  • the repository opts in, once, by committing a line to its own package.json — a reviewable change, in the open, that a reader can see;
  • what arrives is still five legible files in .git/hooks. A colleague who has never heard of this tool can cat .git/hooks/pre-commit and see what runs, which is exactly the property that made us refuse core.hooksPath.

Requirements

Git 2.31+. git rev-parse --path-format=absolute landed in 2.31, and three places depend on it: install.rs resolving the hooks directory, hooks/common.rs finding the git common dir, and hooks/python_tools.rs locating a linked worktree's main .venv. On an older git those return nothing rather than failing loudly, which is the worst possible shape for a version floor — the tool appears to work and quietly resolves the wrong paths.

Nothing else. Each check brings its own tool requirement only where you have opted into that check: a repository with no ruff.toml never needs ruff.

2. Turn hooks on

Per repository — the default

cd <your-repo> && greengate install
greengate list                        # what would run here, and why not

That writes six shims into .git/hooks — pre-commit, pre-push, commit-msg, prepare-commit-msg, post-commit, post-rewrite — each of which resolves the binary at run time and dispatches into it. post-rewrite only starts a background rehearsal after a rebase, and only where greengate.rehearseOnCommit asks for one. post-commit is the bookkeeping half of moving a gate entry to commit time: it records that the moved check actually ran, so the push gate can trust the event rather than the declaration. Nothing runs in any repository you did not do this in.

Across many repositories at once:

greengate-fleet install --root ~/Developer
greengate-fleet                              # report the fleet
greengate-fleet tui                          # the dashboard
greengate-fleet fix --root ~/Developer       # what drifted (dry run)

the greengate-fleet dashboard scanning a fleet of repositories

It answers the questions a directory full of repositories accumulates: which repos are covered, which shims went stale after an upgrade, and which repository is quietly carrying a hook.skip somebody forgot. Design record: the fleet dashboard.

greengate-fleet is a separate binary on purpose: it pulls ratatui, crossterm and serde, and keeping the two apart is what stops "I wanted the dashboard" from becoming "every commit now depends on a TUI library". The one-line installers put both binaries in place; from crates.io it is its own cargo install greengate-fleet.

When another tool already owns the hooks

core.hooksPath redirects hook dispatch, and husky sets it. In a repository that runs husky, git reads .husky/_ and never looks at .git/hooks at all — so an install that wrote there would produce six files git never runs, and one that wrote to .husky/_ would hand them to a directory husky's own prepare regenerates on the next npm install.

Both are refused, by name:

✗ git dispatches hooks from /repo/.husky/_, not /repo/.git/hooks
    `core.hooksPath` is set, so husky owns the hooks here. Shims
    written to either directory would be overwritten or never run.
    Hand dispatch back first: git config --unset core.hooksPath

--force does not move it. That flag means "that file is mine to replace"; it has never meant "write where git does not look".

This is not a blanket objection to core.hooksPath. A repository that deliberately keeps its hooks in, say, tooling/hooks under version control has chosen a location, not handed dispatch to something that will overwrite it, and is installed into exactly as before. The refusal needs evidence: either the destination belongs to a hook manager that regenerates it, or our shims are already sitting in the repository's own hooks directory — which means greengate was installed here and something later took dispatch away.

greengate uninstall deliberately does not refuse. Versions before this check wrote shims into whatever core.hooksPath named, so it has to be able to reach files that are already there.

--force, and what it will not do

greengate install --force replaces a hook the installer would otherwise refuse:

  • one that is present but carries no marker of ours — somebody else's hook, or one you wrote;
  • one that is a symlink, where writing normally would rewrite whatever it points at.

Without the flag, install names every such file and writes none of them. --force is how you say the file is yours to replace, and the output then names what it took rather than only counting what it wrote.

Two refusals --force does not override:

  • A tracked file is never written. That is source belonging to a checkout, and it is the guard this project got wrong twice.
  • A path that is a directory or a device is refused whatever you pass. That is not "a hook that is there", it is a sign something else is going on, and refusing costs you one rm.

Neither ever deletes a hook it did not write. A pre-commit-* or pre-push-* file in .git/hooks without our marker is reported and left exactly where it is. greengate-fleet --remove-unrecognized opts into removing them, and is spelled that way rather than --remove-stale because "stale" means our own retired shims, which are a different thing entirely.

Everywhere, forever — a real opt-in

$ greengate enroll

One command: it puts the binary somewhere stable, populates the template directory, and points init.templateDir at it — refusing, loudly, if that key already points somewhere else. Add --conventions declared on a machine that also clones other people's projects, so those get only the safety net; the full story is Rolling out to a team. The manual spelling, for anyone who prefers to see every write:

mkdir -p ~/.config/git
git clone https://github.com/greenharness/greengate.git ~/.config/git/git-templates
git config --global init.templateDir ~/.config/git/git-templates/templates
git config --global commit.template ~/.config/git/git-templates/message

Git copies that directory into .git/hooks on every init and every clone, so from then on every repository you clone runs these hooks without being asked again. That is the convenience, and it is worth having: you never forget to install, and greengate-fleet never shows you an uncovered repo.

It is also a standing grant, and worth stating in full. A cloned repository can declare its own checks in greengate.conf. With this key set, those declarations are present in every repository you clone — including one you cloned only to read — and are one greengate trust away from running. They do not run before that; see the trust model. But if you set this key, trust deliberately, rather than letting installation be the moment you decided:

greengate trust          # show what this repo declares, and accept it
greengate trust --show   # what is trusted here

Full reasoning: index fidelity and run modes §0.

3. Turn them off again

greengate uninstall              # this repository
greengate uninstall --repo       # this repository only: the template dir stays
greengate uninstall --binary     # …and remove the binary from ~/.local/bin
greengate-fleet uninstall --root ~/Developer

--repo leaves the machine alone: the template dir every clone copies from, init.templateDir and the binary stay byte for byte as they were. It is what an installer that armed one repository runs to disarm it.

Uninstall removes our six shims and nothing else. A hook you wrote yourself is left alone and named in the output, whatever it is — a hook it cannot even read is named too, rather than passed over in silence. hook.skip and greengate.severity are never touched, because those are your statements about your repository, not ours.

It does forget its own bookkeeping, and says which parts it forgot: the gate stamps and attestation notes, the bypass ledger, the version-skew marker, the known-identity memo — each of which only ever said "greengate checked this", which stops being true once the hooks are gone — and the greengate.conf trust record. That last one is a deliberate choice: trust is consent for a committed file to run commands, and uninstalling is a request to stop running them, so a later reinstall asks again rather than silently re-honouring a review from a year ago. Re-granting is one greengate trust, which shows you the file. greengate-fleet uninstall now does the same sweep in every repository it disarms, instead of leaving that bookkeeping behind in all of them.

What no uninstall ever touches is work you have not committed: an interrupted run's parked changes stay in $GIT_DIR/greengate-held, and greengate restore keeps working after the hooks are gone.

It also takes the shims back out of the template directory, and — if init.templateDir is still set — says so loudly, with the command to unset it. Without that, an uninstall you believed had finished would leave every future git clone re-installing the hooks. A template directory that is itself a checkout of this repository is never deleted from; those files are tracked source and belong to the checkout.

This is also why the documentation never tells you to run rm $(git rev-parse --git-dir)/hooks/*. That glob deletes every hook in the directory — including ones other tools installed and ones you wrote — in order to remove six files that belong to us. greengate uninstall exists precisely so that removing our hooks never means removing yours.

For bypassing a single commit, or disabling one check without uninstalling anything, see opting out.

4. Keeping it up to date

Ordinary binary updates need nothing per repository: every shim points at the one binary, so replacing the binary reaches every repo at once.

curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/install/install.sh | sh

Re-installing is only needed when the shim set changes — a hook added, removed or renamed:

cd <your-repo> && greengate install        # re-bake the shims here
greengate-fleet fix --root ~/Developer     # or see what the whole fleet needs
greengate-fleet fix --apply --root ~/Developer

Upgrading from 3.x to 4.0

4.0 reads only greengate's names (see the CHANGELOG), so upgrade in this order. The host-slot names switch once, so greengate, relais and greenpiste (now greenbelay) are installed together while no slot is held; installing one alone leaves two slot queues on one machine.

  1. Wait for the slot directory to be empty (greengate slots lists who holds one) and for no amont process to be running.
  2. Install greengate 4.0, the matching relais and the matching greenpiste (now greenbelay).
  3. Run any greengate command in a repository. The first one moves what 3.x left there (state in .git, the local amont.* keys) and then does what you asked. A 3.x store of parked changes (.git/amont-held) stops it: greengate restore puts the changes back, then run the command again.
  4. Run greengate migrate --global once for the machine's keys.
  5. Rename each repository's committed names: greengate migrate --tracked (alone, it takes no other flag: with --reverse or --global it exits 2) stages amont.conf → greengate.conf, amont.pack → greengate.pack and the AGENTS.md / CLAUDE.md markers for you to commit. Across a root, greengate-fleet fix --migrate lists the repositories that need it, and greengate-fleet fix --apply --migrate commits it in each one that is already on a branch named chore/greengate-names; a repository on another branch, or with uncommitted changes to tracked files, is skipped and named. 4.0 reads the old committed names until a later release drops that fallback.
  6. Run greengate doctor: it exits 1 and names every AMONT_* variable, amont.* key or state left over, and a greengate.cluster.kubeconfig still under ~/.config/amont/, a signing key still named ~/.ssh/amont-attest (signing keeps working; rename it to ~/.ssh/greengate-attest) and local refs/notes/attest-local/amont-* signer refs, with the command that moves each. It does not check the committed names (step 5 does); when it exits 0, this machine is clean, and the upgrade is done once step 5 has moved every repository (any it skipped is named there).

To go back to 3.x, before installing it: greengate migrate --reverse in each repository and greengate migrate --reverse --global once, then revert each sweep commit and point amont.cluster.kubeconfig at the 3.x kubeconfig. 4.0 leaves a reversed repository alone until greengate migrate (and greengate migrate --global) is run again.

Windows

Everything works, with one setup difference: there is no symlink. (The greengate trust prompt reads the console directly — CONIN$, the platform's /dev/tty — and Ctrl-C mid-check restores your parked unstaged changes before dying, both same as unix.)

The one-liner for this platform is PowerShell:

irm https://raw.githubusercontent.com/greenharness/greengate/main/install/install.ps1 | iex

It writes greengate.exe and greengate-fleet.exe, each with its amont.exe / amont-fleet.exe copy, into %USERPROFILE%\.local\bin, which is where the shims look — they try greengate, greengate.exe, amont and amont.exe there, so a binary in that directory resolves even in a shim whose path was never baked. CI runs this script on a real Windows runner against a real published release, because a documented install path nobody executes is one you find out about from a bug report.

To build it yourself instead — Git for Windows ships bash and coreutils but not make:

cargo build --release
./target/release/greengate install

On macOS and Linux ~/.config/git/git-templates is usually a symlink to the checkout, so init.templateDir can point at a stable XDG path. Windows does not create symlinks without Developer Mode or elevation, so point git straight at the checkout:

git config --global init.templateDir 'C:/path/to/amont/templates'

Nothing else changes. The shims never need the symlink: they resolve the binary at run time, trying $GIT_HOOKS_BIN, the baked path, ~/.local/bin/amont and ~/.local/bin/amont.exe, then PATH. The installer detects the .exe suffix on its own.

Rolling out to a team

Hooks only protect the machines that installed them. One person with greengate has one protected machine; a team has sixty, plus new hires, plus the laptop that got reimaged on Tuesday. This page is the whole story of closing that gap, and it is honest about the one thing git will not do.

The constraint nobody gets to skip

Git deliberately runs nothing on git clone. A repository cannot install its own hooks into your machine, and any tool that made it look otherwise would be a supply-chain attack with good ergonomics. So "the repo declares it, the clone self-installs" needs a machine-side grant somewhere — the only question is what shape the grant takes and how often somebody has to type it.

Three shapes exist, and they compose:

shapetyped how oftencovers
"prepare": "greengate init" in package.jsonnever (npm types it)JS repositories, on npm install
greengate enrollonce per machineevery future git clone and git init
greengate initonce per repository per machinethat one clone

The machine grant: greengate enroll

$ brew install fredericrous/tap/amont   # or the curl installer, or cargo
$ greengate enroll --conventions declared

enroll does three things greengate install has always done one repository at a time — puts the binary somewhere stable, populates the template directory, and (the part install deliberately left to the user) points init.templateDir at it. From then on every git clone and every git init on that machine arrives with the shims already in .git/hooks, resolving whatever greengate binary the machine has. Upgrading the binary upgrades every repository at once; nothing is re-run per clone.

It refuses to overwrite an init.templateDir that already points somewhere else — something else installs hooks on that machine, and silently disabling it is the husky failure one level up. And it is idempotent: re-running it is a no-op that says so.

Two lines in the onboarding doc — install the binary, greengate enroll — replace a per-clone ritual forever. Repositories cloned before the grant are the one thing it does not reach: greengate init wires one, greengate-fleet install --root ~/work wires all of them.

The repository declaration: greengate.conf, and --conventions declared

The objection to a standing grant is real: the same machine clones the team's services and upstream open-source projects, and those did not agree to your commit-subject shape, your branch naming, or your auto-rebase. A grant that imposes house rules on somebody else's repository is a grant people revoke.

--conventions declared (or git config --global greengate.conventions declared by hand) splits the checks in two:

  • The safety net runs everywhere: merge-conflict markers, leaked secrets, oversized files, and debug leftovers (debugger, dbg!(…), breakpoint()) in the diff you are committing. These are mistakes in any codebase, with near-zero false positives, and catching them in an upstream clone is a favour to the upstream.
  • The conventions wait for a declaration: commit-message shape, branch patterns, lint and format gates, test suites, audits, auto-rebase. They run only in a repository that has committed an greengate.conf — even an empty one:
$ echo "# this repository subscribes to greengate" > greengate.conf
$ git add greengate.conf && git commit -m "chore: declare greengate"

Presence is the declaration; presence executes nothing, so it needs no trust decision. What the file says — declared checks, tool pins — stays trust-gated exactly as before. A held-back stage says so in one line (N convention check(s) held back … the safety net still runs) rather than silently doing less, and greengate list reports the state in text and in --json ("conventions_apply").

The default is everywhere: nothing changes for anyone until a machine opts into declared.

The team recipe

  1. Each machine, once (onboarding doc, two lines):
    $ brew install fredericrous/tap/amont     # pick your installer
    $ greengate enroll --conventions declared
    
  2. Each repository, once ever (committed, travels with the clone):
    • commit an greengate.conf — empty declares; custom checks, committed policy (severity/skip lines for the built-ins) and tool pins can come later;
    • JS repositories additionally get "prepare": "greengate init" so even an unenrolled machine is covered by npm install.
  3. Repositories cloned before enrollment: greengate init in one, greengate-fleet install --root <dir> for all of them.

New hire day one: install, enroll, clone — protected. No per-clone step, no per-repo step, nothing to forget.

Step 0, before any of it: trial it at warn

The recipe above imposes thirty-odd opinions your team did not pick, and the honest risk is not that a check is wrong — it is that two of them are wrong for you, people start reaching for --no-verify, and the habit generalises to the checks that mattered. A guard that teaches its own bypass is worse than no guard.

So measure first. On your own machine, in a repository you work in daily:

git config greengate.severity.pre-commit warn

Everything runs and reports; nothing blocks. A fortnight later, greengate list tells you what a rollout would have felt like:

problems that did not block
  pre-commit-usual-name    61   last 2h ago
  pre-commit-ban-terms      4   last 1d ago
  66 events over 41 commits, since 12d ago

Then decide per check, with evidence, before anyone else is affected — greengate.severity.<check> warn keeps the ones you want advisory. A check firing sixty times in a fortnight is a conversation to have with your team, not a default to inflict on them.

The ledger is local to the machine that recorded it, so this measures your habits, not the team's. That is a real limit of the no-telemetry promise, and the workable version is to ask two or three colleagues to run the same trial and compare — not to look for a fleet-wide number that deliberately does not exist.

What this does not solve

  • Hooks remain advisory. --no-verify still works, deliberately, and is counted rather than prevented. The guarantee lives in CI, not on laptops; put the same checks there and the hook becomes the fast feedback, not the enforcement — the CI backstop ships copyable workflow templates for exactly that.
  • Version skew. Enrolled machines resolve whatever binary they have; two teammates on different greengate versions run different check sets until a shim is newer than a binary (which warns). Commit the floor: set minVersion 1.11.0 in greengate.conf makes every older binary say so on each commit — warn-only, but no longer silent. Pin the exact version in your installer of choice if you need more than a floor.
  • Machines that never enrolled. The fleet dashboard sees one machine's checkouts. A teammate who skipped onboarding is invisible — which is one more reason the real backstop belongs in CI.

The CI backstop

Hooks are advisory by construction: --no-verify and hook.skip are each one command away, deliberately, and a teammate whose machine never enrolled runs nothing at all. So the question "what actually stops a bad commit reaching the default branch" has one honest answer, and it is not a hook — it is CI, where nothing can be skipped from a laptop.

greengate does not run in CI — on purpose

The obvious move would be an greengate run step, or a marketplace action. Deliberately not. greengate's job is local ergonomics: one binary orchestrating many tools with scoped selection, index fidelity, live progress, and escape hatches a human sitting at the keyboard is entitled to. CI wants none of that — it wants the real tools, called directly:

  • failures attribute to the tool that found them, in the tool's own words, with the platform's log folding and annotations;
  • each tool gets first-class caching, matrices, and versions pinned by the workflow, not by whatever binary a runner happens to have;
  • there is no second opinion to keep in sync: when cargo clippy disagrees between laptop and CI, that is a toolchain version question, not an greengate question.

The checks that exist only inside greengate — ban-terms, the secrets scan, large-files, merge-conflict, the commit-message and branch-name conventions, pull-rebase — are deliberately not reproduced in CI. They are local ergonomics (catch it before it exists) or they have a better server-side answer (GitHub's own push protection and 100 MB limit, platform merge tooling). Losing them in CI loses nothing the tools below don't already guard: a debugger; that slips past the local hook still has to survive the test suite and review.

One thing this repository points CI at does run there, and it is deliberately not greengate: attest, a single-purpose verifier that reads a signed note and reports which checks it covers. It runs no checks and has no opinions to keep in sync — it verifies a document about work that already happened, which is the opposite of the second-opinion problem above. It lives in its own repository precisely so this rule can stay written as it is; greengate is still not installed on any runner.

The templates

Copy the file for your stack into .github/workflows/ (GitHub) or .forgejo/workflows/ (Forgejo), then prune the steps your repository does not use. Each step is annotated with the greengate check it mirrors, so the local and CI stories stay legible against each other.

Or fetch one directly:

$ curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/templates/ci/github/rust.yaml \
    -o .github/workflows/checks.yaml

What maps where

greengate check (local)CI step
pre-commit-cargo-fmtcargo fmt --all -- --check
pre-commit-clippycargo clippy --workspace --all-targets --all-features -- -D warnings
pre-push-cargo-testcargo test --workspace --all-features
pre-push-audit-rustcargo audit
pre-commit-lint-jsnpx --no-install eslint --max-warnings 0 .
pre-push-run-tests-jsnpm run typecheck / test:unit / test --if-present
pre-push-audit-jsnpm audit / pnpm audit, per lockfile directory
pre-commit-ruff / pre-commit-pyrightruff check . / pyright --warnings
pre-push-pytestpytest
pre-push-audit-pythonpip-audit -r requirements.txt
pre-commit-gofmt / pre-commit-go-vettest -z "$(gofmt -l .)" / go vet ./...
pre-push-go-testgo test ./...
pre-push-audit-gogovulncheck ./...
ban-terms, secrets, large-files, merge-conflict, commit/branch conventions, pull-rebasedeliberately local-only — see above

One shape carries over exactly: the audits. Locally they warn on a branch push and block a v* tag push; the templates express the same split natively with continue-on-error: ${{ !startsWith(github.ref, 'refs/tags/v') }} — advisory red on branches, a hard failure when a release is leaving the building. That mirrors what this repository's own release workflow enforces for itself.

Keeping the two in step

The hook is the fast feedback; CI is the same verdict, slower and unskippable. When they disagree, it is almost always a tool version — pin the versions your workflow installs, and consider a tool pin in greengate.conf so the laptop warns when it drifts from what CI runs.

Skipping what pre-push already proved

"CI is the backstop" does not require CI to repeat work it can verify happened. When pre-push has just run the suite against the pushed tree and every block gate passed, re-running the identical suite on the identical tree buys a second copy of the same answer — real money on a resource-constrained runner fleet. So greengate can leave a receipt:

ssh-keygen -t ed25519 -N "" -f ~/.ssh/greengate-attest   # once, per machine
git config greengate.attest true                          # per repository

With the toggle on, a push whose pre-push block gates all passed writes a note on each pushed tip in refs/notes/greensummit and pushes that ref alongside the branch. The note is a four-line payload plus an SSH signature over exactly those bytes:

greensummit-v2
tree <the tree the gates ran against>
gates pre-push-cargo-test pre-push-audit-rust
platform aarch64-macos
amont 1.9.0

-----BEGIN SSH SIGNATURE-----
…
-----END SSH SIGNATURE-----

This does not repeal "greengate does not run in CI". CI still never executes greengate — the templates' attest step is greenharness/greensummit, which needs nothing but git and ssh-keygen, and skips a test step only when all four hold:

  1. the signature verifies against .forgejo/allowed_signers (or your platform's path), a file committed in the repository, whose entry is pinned to the greensummit namespace:

    you@example.com namespaces="greensummit" ssh-ed25519 AAAA…
    
  2. the attested tree is byte-for-byte the tree CI checked out — not the commit hash: a reword keeps its attestation, a single changed byte loses it, and a PR merge commit whose tree drifted from the tested tip never skips;

  3. the step's own gate is named in gates. The list holds only checks that PASSED — Warned and Unavailable never appear, because "could not run" is not "passed" — so a CI step with no local mirror (an e2e suite, an image build) is never skippable by construction;

  4. the attestation's platform is the platform asking. A pass is a pass on something.

A matrix asks the fourth question for you

cargo test green on an arm64 Mac is no evidence at all about the Windows leg of a matrix — and a mechanism that let one laptop retire three platforms' CI would be the unsound version of this whole idea. So the note records where the suite ran, and greengate attest covered defaults to requiring that platform to equal the verifier's own:

legattestation saysoutcome
macos-latestplatform aarch64-macosskips — that suite really ran here
ubuntu-latestplatform aarch64-macosruns
windows-latestplatform aarch64-macosruns

No per-leg configuration: every leg runs the same one-liner and only the matching one finds anything covering it. greengate's own CI is the worked example — a laptop push retires the macOS leg's cargo test and leaves the other two exactly as they were.

For a suite whose result genuinely does not depend on where it ran — a pure-JS unit run, most pytest suites — the workflow says so, once, in a line that is committed and reviewed like any other:

- id: attest
  uses: greenharness/greensummit@v2
  with:
    platform: any

That is a claim about the suite, so make it where the suite is defined rather than on the signing side: the machine holding the key should not get to decide that its results travel.

Reading the result

The action publishes two outputs. Use gates:

- run: cargo test --workspace
  if: ${{ !contains(fromJSON(steps.attest.outputs.gates), 'pre-push-cargo-test') }}

gates is a JSON array, and contains over an array matches elements. The other output, covered, is the same names as a string, where contains matches substrings — so a gate named pre-push-cargo-test-slow satisfies a check for pre-push-cargo-test and skips the real suite. covered is kept only for workflows written against the older inline templates; new ones should not use it.

Everything is fail-open, and the action says why it found nothing rather than leaving you guessing:

greensummit: attested on aarch64-macos, this leg is x86_64-linux
greensummit: no attestation found for tree 9f2a1c…

If you would rather not depend on an action, greensummit covered (cargo install greensummit) is the same verifier as a binary, and greengate attest covered runs it too, through the greensummit library greengate links (decisions ADR-0037), for CI that is neither GitHub nor Forgejo. All of them answer to the format in SPEC.md.

Origin is the source of truth. greengate attest covered treats the local refs/notes/greensummit as a mirror of origin's: deleting that ref on origin revokes every attestation it held — the next covered in any clone deletes its copy and prints how to undo that — and an origin that cannot be reached covers nothing, with the reason on stderr. The spec in .github/greensummit-inputs may mark a path with a leading ? (?build.rs): it may be absent, and the gate re-runs the day it appears.

What signs is the machine that ran the tests, so the trust statement is exactly "whoever holds greengate.attestKey vouches for this tree" — the same trust you extend by pushing at all when you are the only committer. On a team, that key is a shared authority: hand one to each developer (one allowed_signers line each) or accept that any holder can mint "tests passed". And the failure doctrine is the gate stamps' own, one direction only: no note, an unknown format version, a foreign or tampered note, a mismatched tree, a signer CI never heard of — every one of them reads as "no attestation", and no attestation means CI runs the tests. The mechanism can only ever save a redundant run; it cannot skip a check that did not happen. --no-verify skips pre-push entirely, mints nothing, and CI quietly does the full job — which is the backstop doing exactly what it is for.

A gate the busy host deferred

Under set onBusy defer (ADR-0013), a heavy gate whose host slot did not free in time is deferred: it does not run locally and is never attested, so the attest step leaves it out of gates and the CI step runs it, exactly as for a gate that was never run. Nothing in CI changes. What a repository owes is the promise behind the line: every heavy gate it may defer has a CI step.

Reusing a result when only plans changed: declared inputs

Every cache above is keyed by the whole tree, so a commit that changes only docs/plans/*.md — the plan that opens a branch and the closing commit that records its verification — misses all of them. .github/greensummit-inputs lets a repository say what each gate reads; a result is then reused on any tree whose declared paths are byte-identical to the ones it passed on (attest's input fingerprints). Both halves use the same fingerprint, from one module (crates/greengate-runtime/src/attest_inputs.rs):

  • CI verifies the signature as before, but on the fingerprint.
  • The local hooks file each gate's stamp under its fingerprint too, in refs/notes/greengate-gate-inputs, and honour it at pre-commit (judged on the staged tree, so partial staging is judged on what is committed) and pre-push. Never run git notes prune on that ref: its keys are not objects. A gate the spec does not declare keeps the whole-tree behaviour, and so does every gate when the spec is missing, invalid or ambiguous. The token's identity (command, tool, greengate version) still has to match.

The grammar cannot exclude paths, so a declaration is only as good as its completeness: a gate that omits something it reads is skipped wrongly the day that something changes. greengate attest check-inputs --require <gate>… (run by make check, gates listed in the Makefile's ATTEST_GATES) fails unless each named gate declares every tracked file, by real ancestry: crates/foo never stands for crates, and one gate is never rescued by another. Only docs/plans/ is exempt, and the spec itself, .gitattributes and .gitmodules are always part of a fingerprint. Exit 0 covered, 1 something is not covered, 2 no usable spec; it is the opposite of covered, which fails open. A new top-level path or docs/ child therefore fails the check until it is declared for every gate — a deliberate cost of a skip nobody has to trust.

With no declaration: the canonical tree

A repository that declares nothing needs nothing: since amont 1.56.0 the same reuse works with no greensummit-inputs file, on attest 1.5.0's canonical tree. The canonical fingerprint is that of the tree with the content of the top-level docs/plans/ left out and its existence kept, so a closing plan commit reuses every gate while a plan added, deleted or renamed, or any other path changed, does not. Nothing is declared, so nothing can be under-declared and no completeness check is needed.

  • The push adds canon <fp> to the signed block and files the block under the canonical key in refs/notes/greensummit-inputs (a repository with a valid spec keeps its input lines and gains the canon line).
  • The local hooks file each gate's stamp under the canonical fingerprint too, in refs/notes/greengate-gate-inputs, and honour it at pre-commit and pre-push. A repository with a spec that is valid keeps its declared route; one whose spec is invalid, ambiguous or unlistable gets neither route, and the gate runs.
  • The cost of the exemption: a gate that reads the contents of a plan (a formatter or linter over the whole tree, a link checker) would be skipped on a plans-only change. Ignore docs/plans in that tool's configuration, or opt the repository out with set planExempt off in greengate.conf (see configuration).

In CI: verify, run what is uncovered, sign what passed

ci.yaml splits the work in three so that no job that runs the test suite holds the key:

  1. verify always runs make attest-inputs (an undeclared new file changes no fingerprint, so only this catches it), then asks attest's verifier once per platform which gates a signature covers, and prints one plain line per gate: <gate>: skipped, a signature covers this tree's declared inputs (ADR-0024) or <gate>: running, no valid signature. It names no commit: a signed payload identifies a tree. A schedule run covers nothing.
  2. The heavy jobs (rust, msrv, deps, the test legs, the Windows cargo test step) run only when uncovered. test takes its matrix from verify, because a job-level if cannot see the matrix. The Windows installer and end-to-end steps always run: they install the latest published release, an external input no fingerprint captures. A job that passed writes a result file (gate, platform, tree) and uploads it. The load scenarios (make test-load) are the load job, gates ci-load-ubuntu and ci-load-macos.
  3. sign is the only job with the key. It signs a result only when it succeeded, names the tree sign itself is standing on, and names the platform the workflow declares for that gate (scripts/ci-attest-sign-plan.sh), one block per platform. It runs on push and on same-repository pull requests, never for a fork (no secret) and never on schedule. A branch push runs through pull_request, so that is where a branch's signatures are made; the merge to main finds them again because the declared inputs are unchanged.

Which event proves what

A tree is tested once per platform, at the cheapest point that still stops a bad release (decisions plan 2026-10-17-amont-ci-proves-platforms-once):

eventruns
pull requestLinux: rust, msrv, deps, hooks (ubuntu)
push to mainwhat the pull request deferred: hooks (macos), the Windows cargo test, both load legs, each skipped where a signature covers the tree
tagnothing new: the release waits until every gate is attested for the tagged tree

A pull request runs macOS, Windows and load too when it changes something platform-specific (scripts/ci-platform-touched.sh). That means the workflows, the CI scripts, the toolchain or dependency tree, the installers, npm/, templates/, or a product source file with a platform cfg. Adding the full-ci label also runs everything. A deferred gate says so in the attestations summary: <gate>: deferred to the push to main. A platform can therefore go red on main after a green pull request; that is fixed forward, and no release ships until it is green.

The trust is the trust of write access: the workflow and the scripts sign runs come from the ref under test, so whoever can push a branch can edit them, and allowed_signers, and any job running that code could upload an artifact under any name. The split is separation of duties (a test job holds no key and signs nothing); against a hostile pull request the guarantee is write access. .github/CODEOWNERS states that intent. A signature made with a key added in a pull request covers nothing on main, whose own allowed_signers decides.

A tracked file that configures a gate (greengate.conf) must be a declared input of that gate, or a change to its scope would be invisible to the fingerprint: a gate whose declaration omits a tracked greengate.conf is not offered the fingerprint route at all, and keeps the whole-tree behaviour. Settings outside tracked files are not in any fingerprint; they were not in the whole-tree key either.

Skipping lint: tree gates

Test gates are signed from pre-push. Lint and format are different: the pre-commit linters see staged files only, so their pass says nothing about the whole tree. A tree gate (a tree line in greengate.conf) runs the whole-tree command at commit, beside the other checks, and its pass is attested as tree-<name>:

- id: attest
  uses: greenharness/greensummit@v2
  with:
    anywhere: tree-eslint     # formatting and lint do not depend on the platform

- name: Lint
  if: ${{ !contains(fromJSON(steps.attest.outputs.gates || '[]'), 'tree-eslint') }}
  run: npm run lint

Command parity

An attestation names a gate, and a gate is worth only the command behind it. So the CI step must run exactly the gate's normalized declaration:

  • the declared command;
  • with {cache} removed;
  • then a dangling trailing -- removed;
  • then whitespace collapsed.

tree eslint eslint * attest npm run lint -- {cache} requires run: npm run lint. Tool resolution is part of the command (uvx ruff@0.16.0, uv run, npm run), so CI and the laptop resolve the same tool. One gate proves one command: two CI steps (ruff check and ruff format --check) are two gates.

greengate tree-parity (and the pre-commit-tree-parity check) enforce this. It fails closed on a gated step it cannot read with certainty:

  • a block scalar, an anchor or alias, a quoted form with escapes, or ${{ }} in run:;
  • a step-level env: or shell:, or a working-directory: the gate does not declare as cwd=;
  • any env: or defaults: the job or workflow hands down.

The one inherited setting it accepts is defaults: run: shell: bash, and only for a simple command: no pipe, list, redirection or substitution. There, bash's -e and pipefail cannot change the verdict. Run greengate tree-parity as an ungated CI step, so a drift committed with --no-verify still fails.

A step skipped on a built-in test gate (!contains(…, 'pre-push-cargo-test'), and likewise pre-push-go-test, pre-push-pytest, pre-push-run-tests-js) is compared with that gate's local command, and a difference is a warning, never a failure: CI is skipping a step on a signature of a different command. The equivalences it accepts:

  • cargo test, with --workspace and --all-features optional;
  • go test ./...;
  • pytest, python -m pytest, or uv run [--no-sync|--frozen] pytest;
  • one of typecheck, test:unit or test, through npm, pnpm or yarn.

-q and -v are ignored. Anything else differs: a coverage floor, -race, --locked, a package subset, a make target, a pipe. A check only CI makes belongs in a step that is never skipped.

The provenance record (not a skip)

Next to its attestation, a push can publish a second signed note, refs/notes/greengate-provenance: what the push carried besides its tests, the plan it implements and the verdicts given on it (decisions ADR-0036). amont-agent writes the unsigned payload when its implementation-review hook passes a push with a plan; greengate's pre-push signs it with the attestation key under the namespace greengate-provenance and publishes it by tree and by commit, with the same append-and-push loop as attestations. The format is the attest SPEC's greengate-provenance-v1 section.

CI never reads it, and no step is skipped on it. amont-agent shipped <plan> does: it lists each pull request a plan shipped in, its merge commit, its release, and the record that went out. A repository's allowed_signers must list the namespace (namespaces="greensummit,greengate-provenance,amont-provenance") for a record to verify.

The checks

Six git hooks are installed — pre-commit, commit-msg, prepare-commit-msg, post-commit, post-rewrite, pre-push — and behind them thirty-nine named checks, plus any your repository declares in greengate.conf.

This page is the catalogue. It is not the answer to "what will run in my repository" — for that, ask:

greengate list                       # here, and why not
greengate list --stage pre-push      # one trigger
greengate list --all                 # the inert ones too, one row each
greengate list --json                # the same, machine-readable

Most checks are inert in most repositories, by design. A check fires only when the commit touches files it understands and the repository carries the configuration that opts into that tool. A JavaScript repository never invokes cargo; a repository with no ruff.toml never needs ruff.

That is why greengate list leads with what actually runs and gives the rest a line:

  15 active here.  23 inert (Go, JavaScript, Kubernetes, Python, Rust) — greengate list --all

Even in a repository greengate serves well, about half the checks are inert; in one built on a stack it does not cover yet, two thirds. Printing all of them interleaved meant a Terraform shop read thirty rows naming Rust, Go, Python and JavaScript — which says "this tool is for other people" when the truth is the opposite: the checks that were running are secrets, large-files and merge-conflict, the ones that prevent incidents in any repository at all.

--all prints the condition each inert check is waiting on, which is still the answer to "why is clippy not running here". Skipped (⊘) and unusable (✗) checks are never collapsed — somebody silenced the first and broke the second, and a count is the wrong shape for either.

Reading the table

  • id — <trigger>-<name>. Any of the three spellings (full id, short name, trigger) can address it in hook.skip and greengate.severity; see configuration.
  • fires when — the scope. always means it has no file condition.
  • fixes — the check can rewrite the file rather than only complain. Those rewrites are staged; see run modes.
  • Linters with a warning class run at zero warnings: eslint gets --max-warnings 0, yamllint --strict, pyright --warnings, and clippy has always run with -D warnings. A warning that exits 0 is a list nobody is forced to read — a human scrolls past it, an agent reads "passed" and moves on — so a finding either blocks or it does not exist. A repository that wants the old behaviour downgrades the check: git config greengate.severity.lint-js warn.
  • Checks marked soft warn and skip when their tool is missing, rather than blocking a commit, because CI is the hard gate and not every developer has every toolchain installed.

--json, the machine contract

greengate list --json is what an agent or a script reads instead of parsing the human table, so its field names are a contract rather than an implementation detail. Every document it prints declares which contract it is:

{"format": "greengate-list-v1", "stage_filter": null, "pushed": false, "checks": [...]}

Assert that format before reading anything else, the same way this tool refuses a gate stamp or an attestation whose version it does not know. The version changes when a field's MEANING changes or a field is removed; adding a field does not change it, which is why the top level is an object rather than a bare array.

Envelope: format, stage_filter, pushed, checks, commit_style, branch_style, bypasses, downgrades, conventions_apply, installed, template_dir.

installed and template_dir: whether greengate's six shims are in this repository's hooks directory (where git dispatches from) and in the machine's template dir, read from the shim files themselves. Each is {"state", "hooks_dir", "shims": [{"name", "binary"}]}, where state is present (all six), absent, partial, or unknown (outside a repository, git would not answer, or a hook could not be read), and binary is the absolute path a shim bakes, null when it bakes none. An installer reads these to decide what it may remove; unknown must never be read as absent.

Each entry of checks:

fieldwhat it says
id<trigger>-<name>, the full spelling
short_namethe name without its trigger
stagewhich trigger runs it
sourcebuiltin, or declared for an greengate.conf check
declared_severitywhat the check ships as (warn for a declared check that cannot run)
manifest_severityfor a declared check, what its greengate.conf line says, trusted or not; null for a builtin or a line that did not parse
effective_severitywhat it is here, after overrides
severity_overriddenwhether those two differ
severity_sourceconfig or policy when overridden, else null
fixwhether it can rewrite the file
statusready, inert, skipped, unavailable
reasonwhy, in the words the text view uses
scope_filesextensions it fires on ([] means always)
scope_opt_infiles whose presence opts the repository in
commandthe command a declared check runs, else null
scope_from_twinfiles a pre-commit declaration also fires on because its push twin reads them ([] when it is not widened)
scope_twinthe push gate or gates whose files those are, comma-separated (pre-push-cargo-test), else null

A field named here and absent there — or the reverse — is a bug this page's own test fails on, because a reader who guesses a field name gets null rather than an error, and null reads as a perfectly plausible answer.

commit-msg

Validates the summary line and reformats the message. --no-verify skips it (git's rule); no hook.skip or severity override names it.

Validates: a subject is present and at most 72 characters; it carries a conventional type prefix; a description follows the prefix; the description is at most 50 characters. Messages git itself writes (Merge …, Revert "…", fixup!/squash!/amend!) pass through unjudged.

Formats: hard-wraps the body at 72 columns, groups the trailing footers with one blank line before them, and places the type's gitmoji wherever you asked for it — nowhere, by default.

Every number above and the gitmoji placement are greengate.commit.* settings; greengate setup walks them. See if the defaults do not fit.

prepare-commit-msg

Appends the issue id found in the branch name to the footer: JIRA first (ABC-1234), else a bare Kanbanize id (1234).

Only for a commit you are authoring. -m, -t, a merge, a squash and --amend all pass a source in $2 and are left alone.

The safety net vs the conventions

With git config --global greengate.conventions declared — the mode greengate enroll offers for machines that also clone other people's projects — the checks split in two. Five are the safety net and run in every repository, declared or not: merge-conflict, large-files, both secrets checks, and ban-terms — findings that are mistakes in any codebase, with near-zero false positives. Everything else, the commit-msg/prepare-commit-msg hooks included, is a convention and runs only where the repository commits an greengate.conf. The default mode, everywhere, keeps the distinction inert.

pre-commit

All twenty-two run concurrently, and a panic in one is isolated so the other twenty-one still report — in two waves (ADR-0020). The Light checks run first. The Heavy ones (clippy, go vet, pyright, and any declared heavy or moved gate) start only once none of the Light checks has blocked. When one has, a commit that is already refused does not wait for its test suite:

  ↷ 1 check(s) skipped because pre-commit-cargo-fmt failed: pre-commit-clippy
  fix the failures above and commit again; to run one now:
    greengate run pre-commit-clippy

A skipped check earns no stamp, so the corrected commit runs it. A Light failure at warn does not skip anything. git config greengate.failFast false (or GREENGATE_FAIL_FAST=false for one commit) runs every check at once, as before 2.1.

idfires whenwhat it does
pre-commit-agents-mdAGENTS.md/CLAUDE.md carry the greengate markersThe generated guidance block is behind the greengate that would generate it now — an agent reading it follows last release's instructions. Warns with the greengate agents-md fix; with greengate.fix true regenerates and re-stages. Silent without the markers (opt-in), and during merge/rebase/cherry-pick. Never blocks. fixes
pre-commit-argo-lint.yaml .yml + kustomization.yaml/.ymlArgo CD app lint. soft
pre-commit-ban-terms.js .jsx .ts .tsx .vue .rs .pyRefuses focused/debug leftovers in staged sources — describe.only, fit(, debugger in JS/TS, dbg!( in Rust, breakpoint() and pdb.set_trace() in Python. Scoped to what this commit touches, and re-checked against staged content with each language's comments and string literals blanked (a term named in prose is discussion, not code — and an f-string interpolation or template substitution is code, not prose).
pre-commit-branch-patternalwaysSays at the first commit what pre-push-branch-pattern will refuse at push time, with the git branch -m fix — while renaming costs nothing. Quiet on a detached head, in a remoteless repository, and on any branch a remote already has. Never blocks.
pre-commit-branch-protectalwaysSays at commit time that a commit landing on main/master will be refused by pre-push-branch-protect, with the git switch -c fix — while moving it costs one command and nothing is stacked on it. Quiet on a detached head and in a remoteless repository. Never blocks.
pre-commit-cargo-fmt.rs + Cargo.tomlcargo fmt. fixes
pre-commit-clippy.rs + Cargo.tomlcargo clippy
pre-commit-go-vet.go + go.modgo vet ./..., per touched module.
pre-commit-gofmt.go + go.modgofmt, handed exactly the staged files. fixes
pre-commit-kube-linter.yaml .yml + .kube-linter*.yaml/.ymlkube-linter. soft
pre-commit-kubeconform.yaml .yml + kustomization.yaml/.ymlSchema-validates rendered manifests. soft
pre-commit-lint-js.js .jsx .ts .tsx .vue + package.jsonESLint at zero warnings (--max-warnings 0), only in repos that carry an eslint config.
pre-commit-lint-json-yaml.json .yaml .ymlParses staged JSON/YAML so a syntax error never reaches the repo. soft
pre-commit-manifest-trustgreengate.confBlocks a commit that changes greengate.conf while the checks it declares are untrusted — otherwise they stand down as "could not run" for exactly the commit that introduces them. Names the fix (greengate trust); never trusts anything itself. Not during a merge, rebase, cherry-pick or revert: a manifest arriving from another branch stays a gap.
pre-commit-merge-conflictalwaysRefuses staged files still carrying conflict markers.
pre-commit-package-lockpackage.jsonKeeps package.json and its lockfile in step, scoped per directory — one project's lockfile does not satisfy another's in a monorepo, and a package.json with no lockfile beside it never demands one.
pre-commit-prettiera prettier config is presentFormat check. fixes
pre-commit-pyright.py .pyi + pyrightconfig.json/.jsonc/pyproject.tomlType check.
pre-commit-ruff.py .pyi + ruff.toml/.ruff.toml/pyproject.tomlLint and format. fixes
pre-commit-tree-paritygreengate.conf, *.yml, *.yaml (repositories with greengate.conf)Every tree gate must be matched by the workflow step skipped on it: the step's run: equals the gate's normalized command. Fails closed on what it cannot read with certainty. A step skipped on a built-in test gate (pre-push-cargo-test …) is compared with its local command and only warns. See the CI backstop.
pre-commit-usual-namealwaysWarns the first time you commit under a given name/email, so a misconfigured user.name is noticed at commit one rather than commit twenty. Never blocks.
pre-commit-hadolintDockerfileDockerfile lint. Matches that basename exactly — Dockerfile.dev and Dockerfile.prod do not, because scope name tokens are exact basenames.
pre-commit-helm-lint.yaml .yml .tpl + Chart.yamlhelm lint, once per chart directory the commit touched — resolved by walking up to the nearest Chart.yaml, not once per file.
pre-commit-shellcheck.sh .bashShell lint. No opt-in file: shellcheck's defaults are the reason to run it, unlike yamllint's. A script with a shebang and no extension is not matched.
pre-commit-yamllint.yaml .yml + .yamllint/.yamllint.yaml/.ymlStrict YAML lint, where a repo has opted in.

Both Python checks prefer the repository's pinned tool over an ambient latest, in this order: uv run --no-sync (the lockfile-pinned one CI runs) → the worktree's .venv → the main worktree's .venv (a linked worktree has none of its own) → PATH → uvx, which is unpinned latest and therefore warns, because it flags issues the CI-pinned version does not.

Checks that are paused mid-operation

Most content checks do not run during a merge, rebase, cherry-pick or revert: half the tree is somebody else's work and you cannot fix it from inside the operation anyway.

merge-conflict and ban-terms are deliberately not paused. Those are exactly the checks you want during a resolution commit — leaving a conflict marker in the commit that resolves a merge is the bug, and importing a banned term from the other branch is the other one.

pre-push

These run in sequence, cheapest and most decisive first: refuse a forbidden push before validating a name, and validate everything structural before paying for a test suite.

idfires whenwhat it does
pre-push-branch-protectalwaysRefuses a direct push to main or master.
pre-push-branch-patternalwaysRequires prefix/branch-name (e.g. feat/3002-image-crop), unless the branch already exists on the remote.
pre-push-pull-rebasealwaysRebases the branch onto its own upstream before pushing (then asks for a second push — the first one's refs predate the rebase), and warns — never acts — when the default branch has moved ahead. Acts only when the push carries the checked-out branch: a push of tags or of another branch leaves the checkout alone. Never touches a dirty tree, aborts cleanly on conflict, and greengate.autoRebase false makes it a pure, networkless advisor.
pre-push-run-tests-js.js .jsx .ts .tsx .vue + package.jsonRuns each touched JS package's gate: typecheck, test:unit, test, whichever it defines, cheapest first. Skips any of those a pre-commit declaration already covers — see below.
pre-push-cargo-test.rs Cargo.toml Cargo.lock rustfmt.toml clippy.toml rust-toolchain(.toml) + Cargo.tomlcargo test. A version bump alone runs it, so it is rehearsed and stamped like a code change.
pre-push-go-test.go go.mod go.sum + go.modgo test ./..., per touched module, against the pushed tree.

pull-rebase's constraints are load-bearing: rebasing onto the default branch instead of the branch's own upstream, or autostashing a dirty tree to do it, are exactly the ways a pre-push hook loses somebody's work — so it does neither, ever.

The large-file guard — large-files

Git history never forgets a megabyte: an accidentally committed dataset or bundle is paid for by every clone forever, even after deletion — deleting adds a commit, it does not remove the bytes. At pre-commit, a staged file over greengate.largeFileWarn MB (default 10) gets a named warning — a large asset can be deliberate, and this is the moment to decide — and one over greengate.largeFileBlock MB (default 100, GitHub's own refusal line) blocks with the remedy named: git-lfs, or keep it out of history.

The Python test gate — pytest

cargo-test's contract for the third ecosystem: a repository declaring a pytest setup (a pytest.ini or a conftest.py — a bare pyproject.toml is not a promise to test) runs its suite at pre-push against the PUSHED tree, per ref, for pushes that change Python. Missing pytest or an unanswering git is Unavailable — loud, never green.

The secrets check — secrets, at both stages

A staged credential is a ten-second fix: unstage it. A PUSHED credential is not a history problem, it is an incident — the secret is compromised the moment it leaves the machine, and the remedy stops being git commit --amend and becomes rotation. So this check exists twice:

  • pre-commit-secrets scans the staged content and blocks — private key headers, cloud access key ids, the well-known API token prefixes (GitHub, Slack, Google, Stripe live keys, npm, OpenAI/Anthropic, Vault).
  • pre-push-secrets scans every line every pushed commit ADDS — including commits made with --no-verify, from other tools, or three commits ago, and including a secret added and removed within the pushed range, because the history being published still carries it. The push is the last moment a secret is recoverable at all.

Detection is curated token shapes, not entropy — entropy heuristics are where secret scanners get noisy, and a noisy blocker is a blocker people learn to delete. A legitimate fixture opts out per line with the pragma greengate:allow-secret on the same line: visible in review, greppable, and narrower than skipping the whole check. Binary files and files over 2 MB are skipped.

Findings are redacted: the report names the kind and the place (a private key at config/deploy.pem:1), never the matched text — a hook that echoes a secret into scrollback and CI logs has widened the leak it exists to prevent.

The dependency audits — audit-rust, audit-js, audit-python, audit-go

At pre-push, one vulnerability audit per ecosystem the repository uses: cargo audit (opted in by a Cargo.lock), npm audit (package-lock.json) and pnpm audit (pnpm-lock.yaml), each in every directory that tracks one, pip-audit (requirements.txt, or a pyproject.toml project's virtualenv), and govulncheck ./... (go.sum). No lockfile, no check — an audit without a resolved tree audits a guess — and no check means nothing said: an audit the repository never opted into is inert, exactly as greengate list reports it, not a check that "could not run".

The severity is the push's, not the finding's:

  • a branch push with known vulnerabilities gets a named warning — the advisory is information, tomorrow's retry is free, and it tells you now that it will block a release;

  • a push carrying a v* tag (a v followed by a digit — v1.2.3, v2; a tag merely starting with the letter v does not count) is a release leaving the building, and known vulnerabilities in what it SHIPS refuse it, with the tool's full report reprinted. A finding only the development tree carries — a build script's toolchain, a test runner — is named and does not refuse the tag, because nobody who installs the release installs it:

    • JS: the finding is audited again with npm audit --omit=dev or pnpm audit --prod;
    • Rust: each affected crate must be reached by one of the workspace's own crates through cargo tree -i <crate>@<version> -e normal,build --target all --all-features (dev-only only on cargo's own "nothing to print") — build dependencies count, since a dependency's build script runs wherever it compiles;
    • Python: a requirements.txt is the production list by convention; a virtualenv's findings are matched against uv export --frozen --no-dev --all-extras (an optional extra ships: a consumer who asks for it installs it);
    • Go: govulncheck ./... runs without -test and reports only what the module's code reaches, so it already audits what ships.

    Whatever cannot be attributed — a crate the report does not name, a tree or export that fails, a virtualenv without uv.lock — still refuses the tag: an unknown is not a pass. An advisory that ships but that nobody can fix yet (no patched version, a path the project cannot replace) passes only under a waiver: a committed .greengate-audit-waivers file (.amont-audit-waivers is still read until greengate migrate --tracked renames it), one line per advisory,

    # id                 expires     reason
    GHSA-vfj7-8cjw-p6xm  2026-12-31  braces via react-strict-dom; no patched version
    

    reviewed like code, named on every release push it lets through, and void once past its date or when dated more than 90 days ahead — a waiver is a decision to revisit, never an exemption. It matches advisory ids (GHSA, RUSTSEC, GO, PYSEC, CVE, OSV), so a finding the tool reports without an id cannot be waived. Branch pushes never consult it: they never block;

  • warning-class advisories (unmaintained, unsound) are named and never block, anywhere — a gate nothing can pass is a gate people learn to delete;

  • a tool that is missing or cannot reach its advisory database says so loudly and never blocks: a hook may be offline, and a push gate that fails on a captive portal teaches --no-verify. If your releases must not ship unchecked, enforce that in CI, where the network is never in question — this repository's own release workflow does exactly that.

The tools' output decides, never the exit code alone: every one of these tools conflates "found vulnerabilities" with "could not fetch the database" in its exit status, and those mean opposite things.

audit-rust names the crate, and what reaches it. An advisory id says nothing about whether it matters to you, so the warning reads RUSTSEC-2026-0002 (lru → greengate-fleet): the crate the advisory is against, and which of this workspace's crates depend on it. A finding in an opt-in tool is a different Monday from one on the commit path, and reading the id alone meant running cargo tree --invert by hand to tell them apart.

Two details that are answers rather than omissions:

  • (<crate>, not in the build graph) means exactly that. cargo audit reads Cargo.lock, which records the resolved dependency set with no edge kinds — no dev, no optional, no per-feature — so it flags crates nothing ever compiles. An optional dependency of a feature nobody enabled gets reported, and this says so instead of implying you ship it.
  • Attribution is a better message, never a gate. A clean audit runs no extra process at all; the cargo tree calls happen once per affected crate, only when there is already something to say, and if one cannot run the advisory is still reported without it.

Moving a gate entry earlier

typecheck sits in the push gate because nothing checks it sooner. For some repositories that is too late — a type error is cheapest to hear about at the commit that caused it, not an hour later when you go to push.

Move it by declaring it in greengate.conf under the name of the script:

# stage       name       scope       severity  command
pre-commit    typecheck  *.ts,*.tsx  block     npm run typecheck

pre-push-run-tests-js then drops typecheck from its gate and says so:

✓ typecheck gated at commit instead — not repeating it here

This is the argument that already keeps lint out of the gate — pre-commit lints staged files, so repeating it on push costs time and catches nothing — applied to whatever a repository decides to move. It is not typecheck-specific: test:unit and test work the same way.

And it is not npm-specific. A gate is a NAME declared at both stages — the vocabulary is yours, not package.json's. Declare the same name at pre-commit (severity block) and at pre-push, and the commit-time side earns per-commit stamps the push-time side defers to:

# stage       name   scope   severity  command
pre-commit    test   *.rs    block     cargo test
pre-push      test   *.rs    block     cargo test

A BUILT-IN gate needs only the commit-time half. greengate already owns the push side of cargo-test, pytest, go-test and run-tests-js, so declare the commit-time twin under the built-in's own short name and stop:

# stage       name        scope   severity  command
pre-commit    cargo-test  *.rs    block     cargo test

pre-push-cargo-test then defers to its stamps — no second declaration, no hook.skip, and no repeating a command greengate already knows how to run. The name must be the SHORT one (cargo-test, not pre-push-cargo-test): it is matched against what you wrote here, and a full id matches nothing.

The commit-time line also fires on its twin's files. A built-in push gate acts on more files than the pattern you wrote: pre-push-cargo-test runs for Cargo.toml, Cargo.lock, rustfmt.toml and the toolchain pin as well as .rs. A commit that changes only one of those fired neither side, earned no stamp, and the push ran the whole suite again without saying why. A blocking declaration now fires at commit on its own files and its twin's, and says so when only the twin's are staged:

cargo-test: Cargo.lock is read by pre-push-cargo-test — running it at commit

The twin is the built-in of that short name, a pre-push line of the same name in this file (wherever it sits), or, for typecheck, test:unit and test, the npm push gate (.js, .jsx, .ts, .tsx, .vue); when a declared pre-push line and the built-in gate both exist, the commit-time line covers what either acts on. greengate list --json reports the files a row gained in its trailing scope_from_twin field, and the gate that reads them in scope_twin; the text view prints them on a continuation line under the row, so a script reads --json. Three declarations are left as written: a files one (its command is handed the matched paths, and handing a linter Cargo.lock is wrong), a warn one (it vouches for nothing, so widening it would only add a run), and one whose twin has no patterns at all (widening to every change would run the suite on every docs commit).

When a pair does not vouch, the push says why before it runs the gate, instead of running it in silence:

⚠ cargo-test at commit covers *.rs, not rustfmt.toml — running it here
    a files declaration is not widened: add rustfmt.toml to greengate.conf line 3
⚠ cargo-test at commit is warn-only, so it vouches for nothing — running it here
⚠ cargo-test at commit is skipped here (hook.skip) — running it here
⚠ cargo-test at commit is not opted in (needs marker) — running it here
⚠ cargo-test at commit: its program was not found — running it here

The same lines come before the refusal when a bare push is refused (the default, ahead of any connection), so that case is explained too. On a terminal a long path is cut to fit 80 columns and the ending — running it here is kept; piped, nothing is cut. With no same-named commit-time declaration there is nothing to explain and the push says nothing, as before. Exit codes are unchanged: it is a line, not a verdict.

This is worth reaching for when a suite is fast enough to run on every commit. When it is not — a four-minute suite is not a per-commit cost anyone accepts — leave it at push time and rehearse the push instead; see the next section. The window that matters is the same either way: git opens its connection to the remote before calling pre-push and holds it idle until the gate finishes, and a remote may close it first (ssh keepalive does not prevent that).

A commit-time gate is not repeated for the same tree either. pre-commit records the gates that ran clean, bound to the tree the commit is about to seal; post-commit turns that record into the stamp. When the commit never reaches post-commit — commit-msg refused the subject, the editor was closed on an empty message — the record is still there, and the next attempt on the same staged tree reads it instead of running the suite again:

✓ run-tests-js passed on this exact tree earlier — not repeating it here

The stamp on the tree answers the same way for a commit undone with reset --soft and made again. Anything that changes the content — one staged byte, the declaration's own line in greengate.conf — is a different tree and runs the gate; a gate that failed records nothing, so a rejection is never reused. git config greengate.commitStamps false turns the reuse off.

A monorepo's root script that already runs its members

pre-push-run-tests-js runs each gate script (typecheck, test:unit, test) in the root package and in every changed workspace member. When the root's own script is recursive ("test": "pnpm -r test"), each changed member runs twice: once inside the root's run, once on its own. greengate cannot tell that a script is recursive without a list of runners and flags to maintain, so the repository says so, in greengate.conf:

set rootRunsMembers test,typecheck

The value is a comma-separated list of the gate's script names, or none (the root runs no members). It is policy like onBusy: it counts only from a trusted greengate.conf, it is strict, and it is set once.

For a declared script, a changed member is not run again when the root package runs that script in this push and the member is inside the workspace: a pnpm-workspace.yaml packages list for a pnpm root (and only that file), else the root package.json workspaces (an array or {"packages": [...]}), with *, **, ? and ! negations. A package outside the globs still runs, and so does a member when the file cannot be read in a form greengate understands. The push says what it skipped, naming the root's command so a stale declaration reads against what it claims:

3 packages skipped, covered by the root's test (per greengate.conf): `pnpm -r test`

When a script ran at the root and in a changed member and nothing is declared, the push cannot know whether that was a repeat, so it runs both and says how to declare it, once per script:

⚠ test ran at the root and in 2 packages — a repeat if the root runs them
    declare it in greengate.conf: set rootRunsMembers test   (or: none)

set rootRunsMembers none silences it for a repository whose root does not run its members. If an untrusted greengate.conf carries the line, the hint says it does not count until greengate trust. A declared script whose workspace cannot be read runs its members and says so once, so a line that seems to do nothing is explained. On a terminal the root's command is the part cut from the summary line, never the count or the cause.

Things to know:

  • A wrong declaration skips tests that ran nowhere. Read the summary line, and declare only a root script that runs every member with no filter.
  • A local git config greengate.rootRunsMembers can only remove names from the committed line (or set none); it can never add one.
  • A root whose script was gated at commit time does not run it at push, so its members run: a safe repeat, never a skipped suite.
  • Each package that runs is announced, npm run test: 2 of 3, in packages/a.
  • greengate 3.1 and earlier do not know the key and report the line as not a policy-settable key at every run, without blocking, until they are upgraded.

Rehearsing the push gate

A push-time gate that passes stamps the tips it vouched for — the same refs/notes/greengate-gate record the commit-time gates use, keyed by tree, so it survives a reword or a rebase that keeps the content. The next push of that content skips the gate and says so:

✓ pre-push-run-tests-js passed on this exact tree earlier — not repeating it here

Two things fall out of one record:

  • A retry after a dropped connection is instant. The gate passed, the remote closed the idle session while it ran, the push died; git push again sends the same tips, finds their stamps, and is on the wire in seconds.
  • The suite can run before git connects at all. greengate run pre-push drives the same dispatcher with no push in flight — on a branch that has never been pushed it measures against origin/HEAD, origin/main or origin/master — and stamps HEAD when every block gate passes. Then git push holds its connection open for the seconds the transport takes, not the minutes the suite does. An agent that runs greengate run pre-push before every git push never meets the idle timeout; amont-agent's push-preflight rule says so when a push is about to run without one.

Only scoped gates — test suites, whose verdict is a function of the tree — are stamped or skipped; branch-protect, secrets and the other unscoped checks ask questions about the push and always run. A stamp is written only for content the suite actually tested:

  • with greengate.testPushedTree, that is the tip itself, for each gate that actually ran in its checkout — the stamp is written from the record of which gates were handed the snapshot, never from the config flag — unless the snapshot could not be made. A worktree add that fails, or a preparation that fails (a refused greengate.snapshotCarry, an install, an greengate.snapshotPrepare that exits non-zero), falls back to the working tree and says so; that tip is then stamped by nothing, because the suite that passed never saw its content;
  • in the default working-tree mode it is the tip only when HEAD is the tip and no tracked file was modified when the gate started — captured before any check runs, so a formatter or a snapshot-updating suite cannot disqualify the stamp for work it just did. Untracked files do not count, and that is a known gap rather than an oversight: the file was there while the suite ran and is not in the tree the stamp vouches for, but counting it would mean any repository whose gates leave an artefact (a log, a coverage directory) stopped earning stamps permanently — which puts the suite back inside the push, the failure stamping exists to prevent. Use greengate.testPushedTree to close it;
  • inside a rehearsal the checkout is the commit, because git made it, so what preparation added to make it runnable is not a reason to distrust it: dependencies installed from the commit's lockfile, and only untracked carried files — greengate.snapshotCarry refuses anything that would overwrite committed content.

git config greengate.pushStamps false turns both the writing and the honouring off.

Rehearsing in the background

greengate run pre-push is still a wait somebody has to remember to start. greengate rehearse starts it for you and gets out of the way:

$ git commit -m "feat: the thing"
rehearsing the push gate in the background (`greengate rehearse --status`)
$ git push
✓ pre-push-run-tests-js passed on this exact tree earlier — not repeating it here

With git config greengate.rehearseOnCommit true, post-commit spawns a detached worker — its own process group, output on $GIT_DIR/greengate-rehearsal.log, nothing for git to wait for. The worker checks out HEAD into a throwaway worktree (the greengate.testPushedTree machinery) and runs the ordinary pre-push dispatcher there, with the branch and its upstream as the ref line. The snapshot is what makes this safe while you keep editing: the suite reads a tree nobody is touching, and the stamp it earns is for exactly that tree. Only the test gates run — branch-protect, secrets and the auto-rebase ask about a push that is not happening, and run when it is. A fresh worktree has no node_modules, so the snapshot is prepared first: the untracked files greengate.snapshotCarry names, then each lockfile's dependencies (greengate.snapshotDeps: npm ci / pnpm install --frozen-lockfile / yarn install --frozen-lockfile (--immutable for yarn 2+) by default, or a clone of your installed tree that the package manager accepts; a bun lockfile is refused with the fix named), then greengate.snapshotPrepare if set. The worker registers itself before preparing — --status reports preparing, a push waits for it, a newer commit cancels it, installer included — and a preparation that fails is recorded with its reason and fails the rehearsal rather than leaving nothing behind.

A rebase rewrites every commit it replays, and a stamp vouches for one commit: after git rebase, nothing covers the branch. git calls post-commit for each replayed commit while the rebase is still in progress, and the rehearsal stands down then — the commit being made is not the one you will push. post-rewrite is the moment the rebased branch exists whole, and with greengate.rehearseOnCommit it starts one rehearsal of the new tip. (git commit --amend needs nothing extra: its post-commit already rehearsed.)

A push that arrives mid-rehearsal waits for it rather than starting the suite over — but not forever. greengate.rehearsalWait (default 300s, 0 for no limit) bounds that wait, because it happens after git has opened its connection to the remote: holding it open for a wedged worker is the same failure the rehearsal exists to prevent. When the budget expires the gate runs here, and the rehearsal is left alone to finish and stamp the tree for next time.

The stamp is the whole hand-off; there is no second record to keep in step. What the state file beside the log adds is whether someone is still working on it, so a push can choose:

  • stamped — the push skips the suite, as above;
  • still running — the push waits for the verdict rather than starting over (⚠ a background rehearsal of this tree started 2m ago is still running — waiting for it rather than starting the suite over): less remaining work than a fresh run, and no extra CPU;
  • failed, or died without a verdict — said, with the log's path, and the gate runs again in the terminal you are looking at. A failed rehearsal is never honoured.

Latest wins. A worker that finds another one running on a different tree kills it — the whole process group, suite included — and removes its snapshot; a rebase replaying ten commits does not queue ten suites. One on the same tree is left alone. Nothing starts during a rebase, merge or cherry-pick: the commit being made is not the one that will be pushed.

greengate rehearse by hand starts one for HEAD in the background; --wait follows the running one, or runs it in the foreground if none is (the shape an agent wants before git push); --status says which tree the last one was for and how it ended; --stop cancels. Every path that goes wrong ends in the gate running at push time exactly as it would have without any of this: the background run can only remove work from the push, never let it skip work nobody did.

The detached worker is Unix-only for now. On Windows a child process inherits its parent's pipes, so a worker started from a hook whose output is captured would hold the commit until the suite ended; there greengate rehearse says so, and --wait runs the rehearsal in the foreground.

A push whose commits all carry the test stamp skips the pre-push line with the same ✓ test gated at commit instead message; a --no-verify commit brings it back with the same warning; and the dodge lands in the bypass ledger under its own name. A pushed tip whose own stamp key holds the pair's token covers its ref even when an older commit in it never earned a stamp (a hookless commit-tree, a deferral): the tip's gate ran on the whole tree, so a second line says what the skip rests on:

✓ test gated at commit instead — not repeating it here
    the code at tip 1a2b3c4d passed at commit

(ADR-0019). A push whose commits are all stamped prints the first line alone. A pair with the files marker never covers by its tip. cargo test, pytest, go test — the contract is identical because the machinery never looks at the command, only at the name, the severity, the scope, and the stamps.

Only a declaration that would actually run, and actually cover the push, counts. All of these leave the push gate exactly as it was:

  • an untrusted manifest, an unusable line, a hook.skip, or a declaration on the pre-push stage — a declaration that never runs is not a check;
  • an effective severity of warn, whether declared or arrived at through an greengate.severity.* override — a check that lets a failing commit through cannot stand in for one that blocks a failing push;
  • a push whose JS changes fall even partly outside the declaration's scope — *.ts,*.tsx above says nothing about a .js change, so a push carrying one runs the full gate for that ref;
  • every package but the repo root — the declared command runs at the root, so a monorepo sub-package's gate is never skipped on its account;
  • a pushed commit with no stamp — see below. A declaration that qualifies on all the points above is still only a promise; the stamp is the proof it was kept.

The failure being avoided is the one worth stating plainly: a repository that declared pre-commit typecheck, never trusted it, and had types checked at neither end while both ends reported green.

The stamp is how the push gate trusts the event rather than the paper. When the moved check runs at commit time, the post-commit hook records that fact against the commit — a local notes ref, refs/notes/greengate-gate, never pushed, invisible to git log, garbage-collected with the commits it annotates, and removed by greengate uninstall. At push, the gate skips a script only when every pushed commit inside the declaration's scope carries its stamp. A commit created with git commit --no-verify, made by a client that runs no hooks, made on a machine without greengate, or whose hash a rebase or amend rewrote has no stamp — and the push says so and runs the script itself:

⚠ typecheck is declared at commit time, but 1 pushed commit carries no record of it — running it here

Merge commits and cherry-picks never run post-commit, so they re-run the gate the same way. Every failure mode points in one direction: a missing stamp can only cost a redundant run, never skip a check that did not happen. The residual trade of moving a gate entry earlier is therefore latency, not safety — an unchecked commit makes the push slower, not greener.

The missing stamp is also counted. Every commit that a gate declaration covered but that carries no record its gate ran appends one line per dodged script to $(git rev-parse --git-common-dir)/amont-bypasses — a plain local file, never a ref, never pushed, never sent anywhere; the no-telemetry promise applies in full. --no-verify is only the commonest cause: a blocked attempt retried with it, or a gate whose tool was missing, count the same way, which is why greengate list labels the tally unverified commits rather than guessing at intent. A rising count is the first symptom of a gate people have started routing around — a slow check, a flaky one — and until it was counted, the hooks detected that signal on every commit and threw it away. greengate uninstall deletes the file; git config greengate.recordBypasses false stops the counting.

Trying it before you impose it

The question a team lead asks before adopting anything that can block a commit is will this annoy my team into switching it off? One line answers it:

git config greengate.severity.pre-commit warn

Every blocking check still runs and still reports; nothing stops a commit. Work normally for a fortnight, then read what happened:

problems that did not block
  pre-commit-usual-name    61   last 2h ago
  pre-commit-ban-terms      4   last 1d ago
  pre-commit-secrets        1   last 3d ago
  66 events over 41 commits, since 12d ago
  66 of them would have blocked — set greengate.severity.<check> to keep one
  advisory when you go back to block

That is a configuration worksheet: turn off the one or two checks your team disagrees with before the rollout, rather than discovering them one angry message at a time. Events and commits are different facts — forty commits each tripping a check once is a check nobody agrees with, while one commit tripping it forty times is one person losing an afternoon — so both are shown. A check that ships as warn is marked (advisory) and excluded from the would-have-blocked count: it was never going to block, and counting it would inflate the only number being read.

The events land in $(git rev-parse --git-common-dir)/amont-downgrades, on the same terms as the bypass ledger above: a plain local file, never a ref, never pushed, never sent anywhere. It follows that this cannot aggregate across a team — each developer's ledger is their own machine's, and a lead runs the trial on their own checkout or asks people to paste. greengate uninstall deletes the file; git config greengate.recordDowngrades false stops the counting.

A rehearsal (greengate run, greengate run --all-files) deliberately records nothing: it is not a commit, and letting it count would make the number mean something other than what it says. Neither does a check that actually blocked — there is nothing to report about a problem that did its job.

What a push actually tests

By default pre-push runs your suite against the working tree, and says so. That is fast and usually what you want, but it is not what you are pushing: an uncommitted fix makes a broken commit look green.

git config greengate.testPushedTree true

turns on the accurate answer — the suite runs in a throwaway checkout of the commits being pushed, and your tree is not touched. It costs a second checkout and a build that cannot reuse your target/ cache, which is why it is opt-in.

Telling CI about it

The gate stamps above stay local by design — an unsigned note is only as honest as whoever can write the ref. Their signed successor can travel: with git config greengate.attest true, a push whose block gates all passed leaves an ssh-keygen-signed note on each pushed tip in refs/notes/greensummit and sends that ref along, and CI may then skip the test steps the attestation names — but only for exactly the attested tree, and only after the signature verifies. The whole contract, including what CI must check and why every failure mode falls back to running the tests, lives in the CI backstop.

Tree gates

Besides the checks above, a repository may declare tree gates in greengate.conf (tree lines, see custom checks). A tree gate runs a whole-tree lint or format command, the one CI runs, next to the pre-commit checks. It never decides the commit. When it passes on exactly the tree being committed, greengate stamps that tree. The push then attests tree-<name>, and CI skips its step (the CI backstop).

Adding one

A check is a module plus one registry entry in crates/greengate-runtime/src/registry.rs; see hook architecture and CONTRIBUTING.md.

If the check belongs to your repository rather than to everybody's, declare it in greengate.conf instead — no fork required.

Where the hooks fit in your flow

One commit, start to finish, with every place a hook steps in.

greengate catching a commit and letting the fixed one through

You hit git commit

If you set commit.template, the footer scaffold opens in your editor to help you write something meaningful. Or you are in a hurry and write git commit -m "Add to Cart", which is the interesting case, because that is the one that gets stopped.

pre-commit

Git runs it before the commit exists. Every pre-commit check that applies here fans out concurrently, each reporting its own line, and a panic in one is isolated so the others still report.

On an interactive terminal you watch this happen: a live region shows one spinner line per check still running (⠹ clippy 2.3s), shrinking as they finish, while each finished check's full output lands above it as one contiguous block — never interleaved with another check's, however many run at once. Piped or in CI the region stays silent and only the blocks appear. git config greengate.progress false restores plain streaming output.

Most of them will say nothing, because most are inert in any given repository: a check fires only when the commit touches files it understands and the repository carries the configuration that opts into that tool. greengate list tells you which ones are live where you are standing.

Some checks fix rather than complain — cargo fmt, prettier, ruff — and stage the result. What exactly they are allowed to touch, and how your unstaged work survives it, is the subject of index fidelity and run modes; it is the most carefully argued part of this codebase, because the failure it guards against is losing work you had not committed.

If a blocking check fails, the commit is aborted and nothing has happened.

commit-msg

Then git hands the message to commit-msg, which lints it against the conventions, wraps the body at 72 columns and groups the footers.

This is the hook that rejects Add to Cart: no type prefix. git commit -m "feat: a cart the checks agree with" passes.

--no-verify skips commit-msg along with pre-commit — that is git's behaviour — but neither hook.skip nor a severity override names it, so there is no way to turn it down and leave it on. So this is the one hook whose rules are adjustable in themselves: greengate setup sets the subject and description limits, the body wrap, and where the type's gitmoji goes (nowhere, by default).

git push

pre-push runs its checks in sequence, cheapest and most decisive first — refuse a forbidden push before validating a branch name, and validate everything structural before paying for a test suite.

It refuses a direct push to main or master; it requires a branch name of the form feat/3002-image-crop, unless the branch is already on the remote; it rebases your branch onto its own upstream, never onto the default branch, and never when your tree is dirty; and then it runs the test suite of whatever your commits actually touched.

By default that suite runs against your working tree, and says so — which is fast, and is not what you are pushing. git config greengate.testPushedTree true runs it against a throwaway checkout of the commits being pushed instead. See the checks.

Where a check can only recommend rather than act, it recommends. pull-rebase warns when the default branch has moved ahead of you; it does not go and do anything about it.

Asking the same questions without committing

The hooks are not the only way to run the checks, and during adoption they are the wrong way:

greengate run                 # would my commit pass? (the staged set)
greengate run --all-files     # does my working tree pass? (git ls-files)
greengate run pre-commit-prettier

Those two questions differ on purpose. --all-files on a dirty tree reports on content that is not committed and may never be — which is exactly what you want when adopting a check into an existing repository, where git add . is not an acceptable way to measure the mess.

greengate rehearse --wait asks the push question early: it runs the push gate on a snapshot of HEAD before git opens a connection and stamps the tree, so the git push that follows skips the suite. greengate land is the push itself, with proof: it pushes the branch and reads the remote back, so a push that was accepted but did not move the ref is an exit code, not a green terminal. greengate restore brings back unstaged work a killed hook left parked.

For coding agents

greengate list --json is the same answer as greengate list, machine-readable: declared and effective severity, whether each check fires here and why not, and the command if it is a declared external. --stage filters to one trigger, --pushed scopes to what your next push would carry. The contract is described in the checks.

greengate agents-md writes that guidance into a generated block in AGENTS.md, plus a CLAUDE.md signpost pointing at it; greengate agents-md --check reports drift only, and the pre-commit-agents-md check warns when the block is behind the binary that would generate it now.

Before you type git commit at all

Everything above happens once the work is finished, staged, and described. That is the latest possible moment to learn that line 7 has a debugger; in it.

greengate check asks about files instead of about a commit:

greengate check src/app.js                          # a path
greengate check src/*.ts --format json              # several, structured
greengate check --stdin-filename src/app.js < buf   # a buffer you have not saved
src/app.js:7:3: error: 'debugger' is a banned term here [ban-terms]
src/app.js:41: error: an AWS access key id — unstage it; once pushed it is not
history, it is an incident [secrets]

It is a read: no index, no staging, no stash, no writes. Exit 1 if anything blocking was found, 0 otherwise — a warning is not a failure.

Only the content checks answer here — ban-terms, secrets, merge-conflict, large-files. branch-pattern and pull-rebase are not about a file, and clippy, ruff and eslint already talk to your editor better than anything proxied through greengate could.

Wiring it to an editor

file:line:col: severity: message is the format every editor's error parser already reads, so there is no greengate plugin to install — anywhere.

Neovim, with nvim-lint:

require("lint").linters.amont = {
  cmd = "greengate",
  stdin = true,
  args = { "check", "--stdin-filename", function() return vim.fn.expand("%:p") end },
  ignore_exitcode = true,          -- exit 1 means "found something", not "broke"
  -- `col` is optional: a whole-file finding (large-files) has no column, and
  -- `secrets` reports a line without one.
  parser = require("lint.parser").from_pattern(
    "([^:]+):(%d+):?(%d*): (%w+): (.+)",
    { "file", "lnum", "col", "severity", "message" },
    { error = vim.diagnostic.severity.ERROR, warning = vim.diagnostic.severity.WARN }
  ),
}
require("lint").linters_by_ft = { javascript = { "greengate" }, rust = { "greengate" } }

VS Code, as a task with a problem matcher:

{
  "label": "greengate check",
  "type": "shell",
  "command": "greengate check ${file}",
  "problemMatcher": {
    "owner": "greengate",
    "fileLocation": ["relative", "${workspaceFolder}"],
    "pattern": {
      "regexp": "^(.+?):(\\d+):?(\\d*): (error|warning): (.+)$",
      "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
    }
  }
}

Anything else — efm-langserver and Emacs flycheck both take the same pattern. --format json (greengate-check-v1) is there if you would rather not parse a line.

Commit and branch conventions

Two vocabularies, kept in one place — crates/greengate-runtime/src/vocabulary.rs — with a test that fails unless every name is either shared between them or declared an exception with a reason.

That test exists because they drifted: 8 of 12 commit types were rejected as branch prefixes, so docs/… and refactor/… could not be pushed even though docs: and refactor: were valid commit types. It cost two branch renames before anyone looked.

The commit subject

<type>[optional scope][optional !]: <description>

Enforced by commit-msg:

  • a subject is present, and is at most 72 characters;
  • it carries one of the types below, followed by a required colon and space;
  • a description follows the prefix, and is at most 50 characters.

Messages git itself writes are passed through, not judged: Merge …, Revert "…", Reapply "…", and the autosquash shapes fixup!, squash! and amend! all carry no conventional type by design, and blocking them would block git merge, git revert and git commit --fixup themselves.

An optional scope is a noun in parentheses naming a section of the codebase: fix(parser): …. A ! before the colon marks a breaking change.

Both numbers are defaults, not laws — see if the defaults do not fit below.

If the defaults do not fit

commit-msg is the one hook hook.skip and greengate.severity do not reach — --no-verify skips it for a single commit (git's rule, and an emergency exit, not a dial). So it is the one hook whose opinions have to be adjustable in themselves, and they are — four git config keys, walked by greengate setup and listed in configuration:

greengate setup                                   # ask me the four questions
git config greengate.commit.descriptionMax 68     # or set one directly

68 is the number worth knowing if 50 feels tight. It is the longest description that still fits a 72-column subject after a short type and a colon, so it buys you eighteen characters without breaking the line-length convention that the 72 comes from.

By default nothing decorates your subject: you write feat: add a cart and that is what is stored. If you want the type's gitmoji, choose where it goes:

git config greengate.commit.gitmoji suffix
stored as
nonefeat: add a cart
prefix✨ feat: add a cart
suffixfeat: add a cart ✨
replace✨ add a cart

Prefer suffix over replace unless you have decided otherwise on purpose: it keeps a clean conventional subject at the start of the line, where commitlint, changelog generators and git log --grep '^feat' look for it. replace puts the emoji where the type word was, which is a real trade — an emoji is not something conventional-commit tooling knows how to parse.

Write the bare subject with no emoji of your own. The limits measure what you wrote, so a gitmoji this hook adds never counts against your budget — but one you type yourself is yours, and does.

The types

This table is derived from COMMIT_TYPES in the source, which is the authority — what you read here is what the hook enforces and prepends.

icontypefor
👷buildthe CI or build system
🔧choreconfiguration, auxiliary tooling, generated docs
📝️docsdocumentation only
✨feata new feature
🐛fixa bug fix
⚡️perfa performance improvement
♻️refactorneither fixes a bug nor adds a feature
⏪️revertreverting; ideally via git revert
🎨stylestructure or formatting of the code
🚨testadding, updating or fixing tests
➕addadding files as part of a larger feature
➖removethe opposite of add

The rest of the message

commit-msg also reformats what you wrote, rather than rejecting it for whitespace:

  • hard-wraps the body at 72 columns (greengate.commit.bodyWrap, or 0 to leave a pasted stack trace or a fenced code block exactly as it is);
  • ensures one blank line after the subject;
  • groups the trailing footers, with one blank line before them.

Reformatting is idempotent: an amend, a rebase reword and a --no-verify retry all hand the hook a message it wrote itself, and it gives the same one back.

prepare-commit-msg appends an issue id found in the branch name — JIRA first (ABC-1234), else a bare Kanbanize id (1234) — but only for a commit you are authoring. -m, -t, a merge, a squash and --amend all pass a source in $2 and are left alone.

The footer scaffold lives in message:

git config --global commit.template ~/.config/git/git-templates/message

Branch names

pre-push-branch-pattern requires prefix/branch-name — for example feat/3002-image-crop — unless the branch already exists on the remote, in which case renaming it is nobody's idea of an improvement.

Prefixes: add, automation, build, chore, docs, feat, fix, hotfix, perf, refactor, remove, revert, style, test.

Only chore/ allows dots, because they suit version-bump branches (chore/duro-1.50.50) and would only be noise elsewhere. Git already rejects the dangerous forms (.., a trailing .lock).

Two prefixes are deliberately not commit types, and the reason is recorded in the source rather than in anyone's memory:

  • hotfix — an urgency, not a kind of change. The commits inside it are still fix:.
  • automation — bot-authored branches; their commits carry their own types.

The rejection message is rendered from the same lists, so what you are told always matches what is enforced.

Where these come from

Configuration

Everything is git config. There is no config file of ours, no .amontrc, nothing to keep in sync — the settings live where a git user already looks for settings, and --local/--global mean what they always mean.

To bypass or disable rather than tune, see opting out.

Naming a check

Every check has an id, <trigger>-<name> — pre-commit-clippy. Three things name it, and every config surface reads all three the same way:

keyreaches
pre-commit-clippythat one check
clippythat check, on either trigger
pre-commitevery check on that trigger

Where several keys reach one check, the most specific wins: full id, then short name, then trigger. So you can downgrade a whole trigger and then exempt one check from that downgrade.

Nothing matches by substring. hook.skip e reaches nothing at all, and skipping lint-js leaves lint-json-yaml alone — a skip can never silently couple two checks whose names happen to share a prefix.

Where committed policy sits. A trusted greengate.conf can carry severity, skip, and set lines. For one key, the ladder is: built-in default < system < global < policy < local < worktree < command — the team's committed decision beats your global preferences, and your local config in that repository beats the team. Between different keys naming the same check, specificity (full id > short name > trigger) decides regardless of source. Skips union across every source. On a git too old for --show-scope (< 2.26) this degrades fail-safe to "all git config beats policy". A set line reaches an allowlist of the keys on this page — the thresholds, commit style, autoRebase, timeout, testPushedTree, minVersion, planExempt — and never fix, trusted, conventions, or the observability opt-outs, which stay per-machine.

hook.skip — do not run it

Multi-valued; add as many as you need.

git config --add hook.skip pre-commit-clippy   # that one check
git config --add hook.skip clippy              # on either trigger
git config --add hook.skip pre-commit          # the whole trigger
git config --unset-all hook.skip               # start over
git config --get-all hook.skip                 # what is set here

A skipped check is announced on every commit. A config line nobody remembers writing cannot go on silently disabling things — that silence is how a repository ends up with a check everyone believes is running.

For one commit only, without touching config:

git -c hook.skip=clippy commit -m "fix: …"

greengate.severity.<key> — run it, but do not block

Takes the same three spellings, and keeps the signal: the check still runs and still reports, it just stops failing the commit.

git config greengate.severity.clippy warn       # runs, reports, does not block
git config greengate.severity.pre-commit warn   # the whole trigger
git config greengate.severity.clippy block      # back to blocking

warn is usually the right first move when adopting a check into an existing repository: you get the report immediately and pay down the backlog on your own schedule, rather than choosing between a blocked commit and a hook.skip you will forget to remove.

greengate.commit.* — what a commit message must look like

Four keys, and greengate setup walks you through all of them:

keydefaultmeans
greengate.commit.gitmojinonewhere the type's emoji goes
greengate.commit.subjectMax72longest the whole subject may be
greengate.commit.descriptionMax50longest the part after type: may be
greengate.commit.bodyWrap72column the body is hard-wrapped at; 0 never wraps

These matter more than they look, because commit-msg is the one hook hook.skip and greengate.severity do not reach, and git exempts it from --no-verify. Without these keys the only answers to "I do not want a gitmoji in every subject" were to comply or to uninstall.

The four placements

git config greengate.commit.gitmoji prefix
stored as
nonefeat: add a cartthe default — your subject, untouched
prefix✨ feat: add a cart
suffixfeat: add a cart ✨commitlint and changelog tools still see the type
replace✨ add a cartthe emoji stands in for the type word

You always write feat: add a cart, and it is always validated as that — the placement only decides what gets stored. replace costs you interop, and that is the trade it is: an emoji is not a type any conventional-commit tool knows how to read.

Two things hold whatever you choose. The limits measure what you wrote, so the emoji never eats your description budget. And running the hook again over its own output — an amend, a rebase reword — changes nothing.

The limits

git config greengate.commit.descriptionMax 68
git config greengate.commit.bodyWrap 0

68 is the useful number if 50 feels tight: it still fits a 72-column subject with a short type and no scope. bodyWrap 0 leaves the body exactly as written, which is what keeps a pasted stack trace or a fenced code block intact.

A value git cannot parse, or one outside 1..=1000, takes the shipped default and says so on the commit it happened on — because a limit you believe you raised and did not is the whole failure mode this project refuses to be quiet about. A pairing that cannot do anything (a description budget the subject limit can never accommodate) is reported by greengate list, not by the hook: the commit path says what is in effect, and the config-reading commands say what makes no sense.

greengate.conventions

$ git config --global greengate.conventions declared

everywhere (the default) or declared. In declared mode the house rules — commit-message shape, branch patterns, lint/format gates, test suites, audits, auto-rebase — run only in repositories that commit an greengate.conf (an empty one declares), while the safety net (merge-conflict, secrets, large-files, ban-terms) keeps running everywhere. This is what makes a machine-wide standing grant (greengate enroll, init.templateDir) safe on a machine that also clones other people's projects. A held-back stage announces itself in one line; greengate list reports the state, and --json carries it as "conventions_apply". An unrecognised value falls back to everywhere, loudly.

greengate.largeFileWarn / greengate.largeFileBlock

$ git config greengate.largeFileWarn 25
$ git config greengate.largeFileBlock 500

The two thresholds of pre-commit-large-files, in megabytes: a staged file over the first is named (default 10), one over the second blocks (default 100 — GitHub's own refusal line).

greengate.recordBypasses — whether a dodged gate is tallied

git config greengate.recordBypasses false   # default true

When a commit that a commit-time gate declaration covered lands without that gate having run — git commit --no-verify, a blocked attempt retried with it, a gate whose tool was missing — post-commit silently appends one line per dodged script to $(git rev-parse --git-common-dir)/amont-bypasses. greengate list shows the tally as "unverified commits". The file is local: never a ref, never pushed, never sent anywhere.

false stops the counting from now on. The switch exists because "my tool counts my bypasses" can reasonably read as surveillance, and the answer to that reading should be a documented off-switch rather than an argument — though the count is also the first place a slow or flaky check becomes visible as the thing people route around.

greengate.recordDowngrades — whether a warning is tallied

git config greengate.recordDowngrades false   # default true

The companion to the switch above, for the other half of the signal. When a check FAILS but the severity that applies says warn, the hook silently appends one line to $(git rev-parse --git-common-dir)/amont-downgrades, and greengate list shows the tally as "problems that did not block".

That file is what makes a trial readable: set greengate.severity.pre-commit warn, work for a fortnight, then read which checks your team would actually have fought. See Trying it before you impose it.

Local on the same terms as the bypass ledger — never a ref, never pushed, never sent anywhere — and false stops the counting from now on, for the same reason its sibling has an off-switch.

Nothing is recorded by a rehearsal (greengate run), and nothing by a check that actually blocked: the first is not a commit, and the second has nothing to report.

greengate.progress — one check, one block

git config greengate.progress false   # default true

On (the default): everything a pre-commit check says — its own lines and its tools' captured output — is buffered and emitted as ONE contiguous block when the check finishes, so twenty concurrent checks stop shuffling their failure output together. Blocks arrive in completion order. And when stderr is a real terminal, a live region under the blocks shows one line per running check — spinner, name, elapsed — so a slow cargo test is a ticking clock instead of a frozen prompt. The region only ever paints on an interactive terminal; piped or redirected output, TERM=dumb, and CI logs never see a control code.

Off: raw streaming, exactly as before — every line lands the moment it is written, interleaved across whatever else is running. The honest cost of the default is that a long-running tool's output arrives when the check ends rather than as it happens; this key is the way back if you want to watch a test suite scroll.

greengate land — push, then prove the ref moved

greengate land            # push this branch, read the remote back
greengate land --force    # a non-fast-forward, leased on the tip it just read
greengate land --json     # one JSON document on stdout, everything else on stderr
greengate land --dry-run  # say what a land would push; touch nothing

Not a setting, but the place its contract is written down. It pushes the current branch (never main or master, and never with uncommitted tracked changes) to the one URL git remote get-url --push names, as an explicit <sha>:refs/heads/<branch>, with the pre-push hooks running as for any push. It then reads the same URL back, re-reading up to three times two seconds apart on a mismatch.

exitstatusmeaning
0landedthe remote ref equals the pushed sha
1refuseda hook, the server, or a precondition said no (including more than one push destination)
2usagewrong invocation (also printed as a status under --json)
3unreachable, unverifiedthe remote could not be read, or the push was accepted and could not be read back
4not-observedaccepted, but the expected tip was not observed; remote_after holds what was
128+ninterruptedkilled by signal n; no retry

4 does not say an update was lost: another writer may have advanced or replaced the ref after your push. Look at remote_after before pushing again, and think twice before --force.

The last line on stderr is always a plain-text verdict, at most 80 columns wide whatever the branch is called; any commands worth running next are printed in full on the lines before it. --json prints {branch, remote, push_url, pushed, remote_before, remote_after, retried, status} on stdout and nothing else.

There is exactly one retry: when the pre-push hook rebased or fast-forwarded HEAD and said push again, the new HEAD descends from the tip that was read, and the first push failed. The hook only brings a strictly-behind branch up to date, so the retry lands nothing new; a diverged branch is a refusal.

The push has no deadline of its own, because its hook runs the whole gate. Without a terminal it runs with the no-prompt environment, which bounds the network legs only; a custom ssh command, a credential helper or an established session can still stall, and Ctrl-C ends it (exit 128+signal). A branch whose upstream is main or master under another name (what git worktree add -b <b> origin/main sets up) lands under its own name: that upstream is its base, not where it publishes. After a verified landing the remote-tracking ref is moved to the proven sha, and the upstream is set the first time.

Dry run and landing receipts

greengate land --dry-run runs only the first two steps of a land: the branch, its upstream, and the refusals (detached HEAD, main or master, a dirty tracked tree, not exactly one push URL). It stops before the remote is read: no network, no push, no ref written, no receipt. It combines with --force. --json prints {branch, remote, push_url, pushed, dst, retried, status, receipt_dir, lease}: pushed is the HEAD sha, dst is refs/heads/<branch on the remote>, retried is always false, lease is true under --force, and receipt_dir is the directory below. status is would-land (exit 0) or refused (exit 1, the reason on stderr); the verdict line is still the last line on stderr.

Every land that is not a dry run writes one receipt, <git-dir>/amont/land/<started-unix-nanos>-<pid>.json, with the final outcome: {started, ended, branch, remote, push_url, dst, pushed, retried, status}. It is written for every status once the branch is known (a detached HEAD has none), and its pushed is the sha the last push attempt carried, so after a retry it names the retried sha whatever happens to the tracking ref. The git directory is the worktree's own. A receipt that cannot be written prints a warning naming the path and does not change the exit code. Receipts older than seven days are deleted by the next land.

greengate.quiet — say it once, or once per check

git config greengate.quiet never    # auto (default) | never | always

A hook that passes prints one line per check, and on a clean run that is the whole output: fourteen lines to say nothing happened. At a terminal those lines are the reassurance that the gate ran at all. Captured — an agent's tool result, a CI log — they are read again on every later turn and say no more the tenth time than the first.

So the setting names who is reading:

valueeffect
autothe default: quiet when stderr is not a terminal, verbose when it is
neverevery check says it passed, whoever is reading
alwaysquiet everywhere

Only the success lines go. A failure, a warning, a check that could not run, a repaired file and the blocked summary print under every setting. Quiet is about the uneventful path and nothing else — it is not a way to lose a refusal, and quiet_never_swallows_a_failure pins that.

In their place, one line:

  ✓ 14 check(s) passed

That count is not decoration. A run that says nothing at all is indistinguishable from a gate that never ran, which is the confusion this whole crate exists to prevent — so quiet gets quieter, never silent.

auto is the default because it is free for the reader it does not help. At a terminal watching() is true, so committing by hand looks exactly as it did. What changes is the reader who cannot skim — a captured log, an agent's tool result — who was paying fourteen lines of nothing on every commit of every session. Set never to have it back.

One consequence worth knowing: the ✓ N check(s) passed roll-up comes from a full stage. Running a single check — greengate run pre-commit-yamllint — has no roll-up to print, so under quiet it succeeds in silence.

greengate.pushStamps — remember what the push gate already proved

git config greengate.pushStamps false   # default true

A push-time gate that passes stamps the pushed tips in refs/notes/greengate-gate, keyed by tree, and the next push of the same content skips it: the retry after a remote dropped the idle connection mid-suite, and the git push after an greengate run pre-push rehearsal. Only scoped gates (test suites) are stamped or skipped, and only for content the suite actually tested — see "Rehearsing the push gate" on the checks page. false turns off both the writing and the honouring.

greengate.order — attempt the push gates in the order the record justifies

git config greengate.order evidence   # default: declared

declared is the registry's order, and it is what every repository gets unless it says otherwise. evidence orders the push gates by this repository's own record of them (refs/notes/greengate-gate, the same notes the stamps live in): the gates that have actually failed in the last 90 days go first, ordered by failures per unit of time, so a push that is going to be refused is refused at minute two instead of minute twenty.

It is an ORDER and nothing else. Every gate still runs, none is assumed to pass, and only the scoped gates — the suites and audits — are permuted: branch-protect, branch-pattern, secrets and pull-rebase keep their positions, because discovering a protected branch after a test suite is the waste this is meant to remove. With no record the declared order is kept exactly. When the order does differ, the push says so.

Settable in a committed greengate.conf (set order evidence) as well as by git config, because which suite is worth attempting first is a property of the project. It is the only set key that changes how checks are RUN rather than what they are — safe on the terms above, and a local git config still outranks it. See gate evidence.

greengate.commitStamps — do not repeat a commit-time gate on the same tree

git config greengate.commitStamps false   # default true

A blocking commit-time gate that already ran clean against exactly the tree being committed is not run again: the record pre-commit leaves for post-commit is bound to the tree and survives a commit-msg refusal or a closed editor, and the stamp post-commit writes on the tree answers for a reset --soft and re-commit. The reuse is announced in the push gate's words ("passed on this exact tree earlier"). A changed byte, a changed declaration, or a gate that failed all run the gate. false turns the reuse off; the record is still written. See "Moving a gate entry earlier" on the checks page.

greengate.failFast — skip the heavy checks of a commit already refused

git config greengate.failFast false   # default true

Pre-commit runs its Light checks first and starts the Heavy ones (clippy, go vet, pyright, declared heavy and moved gates) only when no Light check blocked (ADR-0020). A Heavy check that would have judged something is reported as skipped, with an greengate run <name> for each one. It earns no stamp. A passing commit starts its Heavy checks once the slowest Light check has finished. <common-dir>/amont-waves records that wait and what was skipped, one line per commit.

The order, stated once: GREENGATE_FAIL_FAST (true or false, one run), then git config greengate.failFast (any scope), then a trusted set failFast in greengate.conf, then on. false runs every check at once, as before 2.1.

greengate.rehearseOnCommit — run the push gate in the background after every commit

git config greengate.rehearseOnCommit true   # default false

post-commit starts greengate rehearse for you: a detached worker checks out HEAD into a throwaway worktree, runs the test gates there — the push-shaped checks (branch-protect, secrets, the auto-rebase) wait for the push — and stamps the tree when they pass. By the time you git push, the suite has usually already run; if it is still running, the push waits for it rather than starting over. A newer commit cancels a rehearsal of the older tree, suite and snapshot included, so committing often does not queue work. Off by default because every commit then costs a suite's worth of CPU in the background. A finished git rebase starts one too (post-rewrite), since it leaves no commit on the branch stamped. See "Rehearsing in the background" on the checks page for what it prints and what greengate rehearse --wait, --status and --stop do. Needs greengate.pushStamps (the default) — the stamp is the hand-off. Unix only for now: on Windows a detached child would hold its parent's pipes until the suite ended, so the hook says so instead and greengate rehearse --wait runs the rehearsal in the foreground.

greengate.rehearsalWait — how long a push waits for a running rehearsal

git config greengate.rehearsalWait 300   # default 300; 0 waits indefinitely

A push that finds a rehearsal of its own tree still running waits for it: less remaining work than a fresh run, and no extra CPU. That wait happens after git has opened its connection to the remote, though, so it is the same idle connection the rehearsal exists to keep short — and it used to be bounded only by the worker's own greengate.timeout, an hour by default and unbounded at 0. Five minutes is under every idle timeout we have measured (Forgejo's git timeout is six), so a wait that expires still leaves the connection alive for the gate that follows it. When it expires, the gate runs in the push and the rehearsal is left running — it may still finish and stamp the tree for next time. greengate rehearse --wait has no budget: nothing is connected there.

greengate.pushGates — never run a heavy gate on an open connection

git config greengate.pushGates inline   # default refuse

git opens its connection to the remote before it runs pre-push, so a test suite or an audit run there holds the connection for as long as it takes, and a forge may drop the idle session after every check passed (ADR-0018). With refuse, the default since 2.0, a push whose heavy gates (the scoped push gates its range touches) carry no stamp for the pushed tree is turned away at once, before any gate starts, naming the gates and how to run them first:

  • greengate land runs every gate the push owes on a snapshot of the exact commit, with no connection open, then pushes;
  • greengate rehearse --wait (or greengate run --stamp) stamps the tree, and the push that follows skips the gates.

inline runs them in the push, as before 2.0. A deletion owes nothing, and a gate that completed earlier without passing is not asked for again while its record holds: a warning for good, a failure under warn severity while the gate is still warn, a missing tool for an hour. With greengate.pushStamps false nothing can be stamped, so the refusal names that setting instead of offering a rehearsal, and greengate land refuses before running anything.

A tag push is refused the same way, and offered greengate land --tag <name>: it pushes one existing local tag after running, on a snapshot of the tagged commit, the gates its range owes and, for a v* tag, the release audits. A tag already on the remote is refused (a tag is never moved), and --dry-run reports would-land without reading the network.

greengate land --json reports what the pre-stage did in a gates object: owed (the gates the push owed) and prestage — stamped (nothing left to run), ran, failed, refused, interrupted, or empty when land stopped before it. ref is the ref pushed (refs/heads/… or refs/tags/…); branch is empty for a tag.

greengate.auditMaxAge — how long an audit's record answers

git config greengate.auditMaxAge 24   # hours, 1..720; default 24

The dependency audits (pre-push-audit-{go,js,python,rust}) depend on the day's advisories, not only on the tree, so they are never stamped. Wherever one runs on the content being pushed — land's pre-stage, a rehearsal, greengate run --stamp, an inline push of a clean HEAD — its report is recorded in refs/notes/greengate-audit (local, never pushed), keyed by the lockfiles' content for a branch push and by the tree for a v* tag. A push with a fresh record replays it, judged against today's waivers and that push's stakes, without running the tool. A record answers for greengate.auditMaxAge hours; one that could not check anything (offline, tool missing) for one hour.

greengate.unstampedPush — refuse a push nothing has tested yet

git config greengate.unstampedPush refuse   # default run

When a check is declared at both stages and a pushed commit carries no record of the commit-time run — rewritten by a rebase or an amend, or made with --no-verify — the push runs the check itself, with git's connection to the remote held open for as long as the suite takes. That happens only under greengate.pushGates inline: by default, greengate.pushGates refuse turns the push away before the check runs, and greengate land runs it first. Under inline, a long suite can outlive the forge's idle timeout, and the push fails after passing. There, greengate.unstampedPush refuse turns that push away at once instead, and says how to earn the stamp with nothing waiting on it: greengate rehearse --wait, then push again. A rehearsal of the tree that is still running or has failed is reported the same way. Pairs with greengate.rehearseOnCommit, which usually earns the stamp before you push.

greengate.snapshotDeps — how a snapshot gets its JavaScript dependencies

git config greengate.snapshotDeps install   # default; or reuse, off

A worktree git just created is a checkout, not a workspace: no node_modules, and a suite started there fails on Cannot find module having tested nothing. Every snapshot — the background rehearsal's and greengate.testPushedTree's alike — is prepared before any suite runs, one unit at a time: each directory holding a tracked package-lock.json, pnpm-lock.yaml or yarn.lock, read from the snapshot's own index, so the pushed commit decides, not HEAD and not what you have staged. A nested project with a lockfile of its own is its own unit. A directory with more than one manager's lockfile is settled by package.json's packageManager, or refused.

A bun.lock or bun.lockb is a unit too, so that a push which does not touch it is skipped like any other — but greengate does not install bun dependencies: a unit the push needs fails the preparation with the fix named, greengate.snapshotPrepare set to the install command, or greengate.snapshotDeps off. Failing there is deliberate: a gate run over a checkout with no dependencies fails every workspace at once, and that reads like a broken branch rather than a missing install.

  • install does what CI does: npm ci --prefer-offline, pnpm install --frozen-lockfile --prefer-offline, yarn install --frozen-lockfile --non-interactive --prefer-offline for yarn 1 and yarn install --immutable for yarn 2+ ("berry"; the committed yarn.lock says which — berry's opens with a __metadata: block — so the pushed commit decides, and each flavour gets the spelling it accepts without a warning). Exact, and it refuses a package.json its lockfile does not satisfy — so does the snapshot.
  • reuse (pnpm and npm) clones the working tree's node_modules copy-on-write — clonefile(2) on macOS, cp --reflink=always on Linux (btrfs, XFS with reflinks), about 2% of the tree's size in metadata — and never falls back to a plain copy: on another volume or a filesystem that cannot clone, it refuses in one line that names the fix (TMPDIR on the working tree's volume, or snapshotDeps install) and installs instead. A clone is kept only when the package manager vouches for it against the snapshot's committed manifests and lockfile; any refusal removes every directory cloned for that unit, says why, and installs instead. Before any copy, a lockfile that differs from the commit's refuses, and so does any file in the working tree's node_modules newer than the manager's install record — an edit made after the install, which no manager checks (.bin/, .cache/ and .vite*/ aside, which installs and tools write afterwards). That rests on timestamps, not content, which is why reuse is not the default. After the copy, a link that resolves back into the working tree refuses.
    • pnpm: the root's and each workspace member's node_modules, as pnpm ls -r lists them; the record is node_modules/.modules.yaml. The clone must be laid out the way pnpm's isolated linker leaves it (every package a link; a stray directory is refused, since pnpm's own check ignores it and a suite could import it), and pnpm install --frozen-lockfile --offline must accept it — which also refuses a manifest the lockfile does not satisfy, and relinks small drift from the store.
    • npm: the root's node_modules, and a member's when it has one, as npm query .workspace lists them; the record is node_modules/.package-lock.json. Any link in the clone that resolves outside the snapshot refuses (npm link, an absolute link; npm's own relative workspace links stay). The vouch is npm install --dry-run --offline --ignore-scripts: the clone is kept only when it exits 0, would add, remove and change nothing, and leaves package-lock.json byte-identical. npm reads the installed tree, not its record (the clone's .package-lock.json is removed before the dry-run), so a package whose version was raised in place is caught even with its timestamps set back; a file edited in place without a version change is not, as with pnpm. The JSON is read by a short node script; without node on PATH the unit installs and says so. Measured on a 25,143-file tree: the clone and the vouch take 43% of npm ci's time and 2.5% of its disk.
    • yarn is never reused: even with the timestamp scan and the link check, yarn 1's yarn check --integrity and --verify-tree accept a tree with a package missing, so nothing yarn offers can vouch for a clone; a yarn unit installs under reuse too, saying so. Yarn 2+ and bun are not reused either.
  • off prepares nothing.

Only the units the push touches are prepared: the root one, and each unit that is the nearest enclosing unit of a file changed between the tip and where it forked from its upstream. The rest are named in one line and skipped — a repository with side projects of their own (spikes, examples) no longer pays an install for each on every snapshot. A unit the push does not touch cannot hold a failure the push introduced; a gate that reaches into one anyway finds no dependencies and fails loudly, never falsely passes, and greengate.snapshotPrepare is the override. With no upstream to measure against, every unit is prepared.

A failed install is the snapshot's failure; see greengate.snapshotPrepare below for what each caller then does. Nothing is needed for a Rust crate (cargo resolves from the shared registry; the build is cold, which is the cost the testPushedTree section describes).

The install runs lifecycle scripts, so a "prepare": "greengate init" runs inside the snapshot — and the snapshot is a linked worktree, sharing the repository's hooks directory. To keep that init from baking every hook to a binary in a temp directory deleted minutes later, the snapshot marks itself with a greengate-snapshot file in its own git admin dir (git rev-parse --git-path greengate-snapshot), and greengate init writes nothing where it finds one; if it cannot tell, it fails rather than guess. Both halves must be a version carrying this — the greengate that runs the rehearsal writes the marker, and the greengate the pushed commit's lockfile installs reads it — so bumping only one of them is not enough. The install and greengate.snapshotPrepare also get GREENGATE_SNAPSHOT=1, for a custom prepare script that wants to know; the marker, not the variable, is the guard.

greengate.snapshotCarry — untracked files a snapshot needs

git config greengate.snapshotCarry ".env .npmrc"

or committed, set snapshotCarry .env in greengate.conf. The files a suite reads and git does not track — a .env, an .npmrc with a registry token — are copied from the working tree into the snapshot, before the dependencies, so an install can use them. Only untracked content may be carried: an entry that is tracked, holds tracked files or sits under a tracked path would put your uncommitted copy where the commit's belongs, and the stamp would vouch for a tree nobody committed. Refused too: absolute paths, ., .. and .git components, and a symlink anywhere on the way — in the working tree, the snapshot, or inside a carried directory. Every refusal is listed in one message and fails the preparation; an entry that is simply absent (no .env in CI) is skipped and said.

greengate.snapshotPrepare — the escape hatch

git config greengate.snapshotPrepare "pnpm prisma generate"

Or committed, so every clone has it:

set snapshotPrepare pnpm prisma generate

in greengate.conf (see custom checks). A local git config still outranks the committed value.

For what greengate cannot know — a code generator, a database client, a build step. It runs through the shell inside the snapshot after the carry, with $GREENGATE_SOURCE_WORKTREE naming the working tree the snapshot came from. When it is set it owns the dependencies: greengate.snapshotDeps stands down, so a repository whose command already installs does not install twice.

A preparation that fails — carry, install or this command — is the snapshot's failure, and each caller says so. At push time (testPushedTree) the gate falls back to the working tree and stamps nothing for that tip: the suite that then passes never saw the content the stamp would have vouched for. In a rehearsal the worker records the failure with its reason (greengate rehearse --status shows it), exits 2, and the next push treats it as a failed rehearsal.

greengate.autoRebase — whether pre-push may sync a behind branch for you

git config greengate.autoRebase false   # default true

On (the default, and the behaviour every install so far has had): pre-push-pull-rebase rebases a clean, behind, non-diverged branch onto its own upstream — then stops the push and asks for a second one, because the refs git handed the hook predate the rebase; the suite would otherwise judge commits git is no longer pushing, and the server refuses the stale objects regardless.

Off: the check becomes a pure advisor. It performs no network I/O at all (no ls-remote, no advisory fetch — behind is judged from your last fetch) and never runs a rebase you did not type; a behind branch stops the push with the command to run. A hook that rewrites your branch is a bigger claim than most teams want a "check" to make — this is the key that unmakes it.

greengate.idleTimeout — how long a check may be silent

git config greengate.idleTimeout 300  # seconds; default 120, 0 disables

A hung tool is silent — a captive portal, a deadlocked lock file, a prompt nobody will answer. A slow tool talks: cargo test prints a line per test. So the clock that decides "stuck" counts silence: a command that writes nothing for this long is killed and the check fails, saying so and naming this key. Two minutes catches a real hang faster than the old ten-minute wall clock did, and lets a chatty twenty-five-minute suite finish.

Only commands whose output greengate observes answer to this clock — every check runs its tools that way by default. With greengate.progress false the tool inherits your terminal, nobody sees the bytes, and only the ceiling below applies.

Busy is not stuck

Not every slow tool talks: vitest without a terminal prints its summary and nothing before it, and a passing suite used to be killed as a hang. So on Linux and macOS, once a check has been silent for a while (a third of this budget, at most 30 seconds), greengate also measures the CPU its process tree is using — the command, its descendants, and the work of every child they have already reaped. A check keeps its budget as long as that tree does at least 0.1 of a core of work; it is killed only when it has been silent and idle for the whole budget. A quiet suite then runs on to greengate.timeout, and the progress line says it is busy (· quiet 2m10s · ~3.9 cores).

The trade-off is written down in ADR-0008: a silent tool that spins — a busy loop, a polling watcher — now answers to the ceiling rather than this budget, and the ceiling message says so. Work done by a daemon outside the tree (a build daemon, a container engine) is not counted. On Windows, or with greengate.idleCpuCredit false, silence alone counts, and the messages say CPU was not measured rather than claiming it was idle.

When sampling is on but a measurement is incomplete — the walk came back partial on a loaded machine, or no sample has landed yet — the check answers to the extended budget, this budget × greengate.idleLoadScale (eight minutes by default), never to the bare two minutes: a kill must rest on a measurement somebody made. One partial snapshot no longer throws the measurement away; the next complete one spans the gap, may count as busy, and never as measured idle (ADR-0009).

git config greengate.idleCpuCredit false  # silence alone, everywhere

GREENGATE_CPU_TRACE=<file> appends the processes each measurement saw — a diagnostic for when a check was kept alive, or killed, and you want to know what greengate was looking at. GREENGATE_CPU_MAX_PROCS=<n> caps the walk, which forces an incomplete measurement on purpose.

Waiting is not stuck

A tool that is waiting on a lock says so and then says nothing: cargo prints Blocking waiting for file lock on build directory while another cargo — a second worktree, rust-analyzer, a build in another session — holds it, and uv prints Waiting to acquire … lock for …. Those exact lines, on stderr, pause this clock: the wait answers to greengate.lockWait instead, and the progress line says · cargo lock 1m30s/10m00s. A check that passes after such a wait says how long it waited and for what.

A line that only looks like a wait (waiting for lock on …) does not pause anything. If the silence budget kills a built-in check whose last line read like that, greengate runs it once more, under what is left of the same ceiling, and says so; the first kill prints no failure. A declared check is never retried: a command you wrote may not be safe to run twice.

The silence budget also stretches with the host's load: on a machine whose one-minute load average is twice its core count, two minutes become four, up to greengate.idleLoadScale. The progress line and the kill message name the stretched figure, the load and the key.

Worst case for a genuinely stuck, silent tool, at the defaults:

situationkilled after
CPU measured idle, host not loaded2 minutes
CPU measured idle, host loadedup to 8 minutes (idleLoadScale 4)
CPU could not be measured8 minutes, even with greengate.timeout 0
in a declared cargo or uv lock wait10 minutes (greengate.lockWait)
retried after a wait-like last lineboth attempts inside one greengate.timeout
waiting for a host slotup to greengate.timeout, before it starts
anythinggreengate.timeout, one hour

greengate.timeout — the ceiling one check's command may run for

git config greengate.timeout 900     # seconds; default 3600, 0 disables

The backstop behind idleTimeout: a tool that keeps printing and never finishes is killed here, and the message says whether it was still printing (slow — raise this) or had gone quiet (stuck — look at the tool). The default was ten minutes when this was the only clock and had to catch hangs; with silence doing that job, the ceiling can afford an hour.

The kill reaches the command itself; a grandchild it detached may survive, orphaned, but the commit is no longer hostage to it.

While a stage runs, a terminal shows a live line per check with its elapsed time, a · quiet 45s/2m note once a check has been silent for half a minute (· quiet 2m10s · ~3.9 cores instead while its CPU is busy, · idle 40s/2m counting what the budget counts once busy work has pushed it back, · cargo lock 1m30s/10m00s during a declared wait, and · queued 42s (slots 2/2) while it waits for a host slot), and · 50m/1h once it is within 80% of the ceiling — the cliff, shown before the fall. Piped (an agent, CI), the same information arrives as one plain line a minute per running check: elapsed, time since its last output, what its CPU is doing (busy ~3.9 cores, CPU idle 40s, CPU unmeasured), and, the first time, both budgets.

The same clock bounds the push path's own network verbs: pull-rebase's sync runs under the full budget, and the reachability probes (ls-remote before a sync, the initial-push check) under the smaller of this and 30 seconds — a probe answers in a second or two when the network is there at all, and a captive portal must not get ten minutes to say nothing. 0 disables these deadlines too.

greengate.lockWait — how long a check may wait on a lock

git config greengate.lockWait 900   # seconds; default 600, 0 = until the ceiling

How long a tool may sit in a declared lock wait (see "Waiting is not stuck" above) before it is killed. The kill message names the lock and who probably holds it. 0 leaves the wait to greengate.timeout; with that off too, the extended silence budget bounds it, so nothing waits forever. Settable from greengate.conf (set lockWait 900): how long a workspace's cold build holds its lock is the project's to know.

Host keys: greengate.idleLoadScale, greengate.hostSlots and greengate.hostCores

These describe the machine, not the repository, so they are read from --global or --system git config only. A value set in a repository is ignored, with one warning naming the key and --global; greengate.conf cannot set them. Precedence, highest first: the environment variable (GREENGATE_IDLE_LOAD_SCALE, GREENGATE_HOST_SLOTS, GREENGATE_HOST_CORES), then --global, then --system, then the default. An invalid environment value is warned about and the next source is read; an invalid git value is warned about and the default is used.

greengate.idleLoadScale — how far a loaded host stretches the silence budget

git config --global greengate.idleLoadScale 2   # default 4, 1 = never stretch, up to 16

The silence budget is multiplied by the host's one-minute load average over its core count, floored at 1 and capped at this. The same factor sets the extended budget a check answers to while its CPU could not be measured. Linux and macOS read the load; elsewhere the factor is 1.

greengate.hostSlots — how many heavy checks one machine runs at once

git config --global greengate.hostSlots 2   # default: automatic, from the machine; 0 = off

Clippy, go vet, pyright and the test suites compile or execute the product, and each already uses every core. Several worktrees, sessions or agents running them at once thrash the same cores and the same cargo lock. So a heavy check takes one of these slots before its first tool runs, and waits — its clocks not yet started — while all are taken; the progress line says · queued 42s (slots 2/2). A check that turns out to have nothing to do never queues. A check declared in greengate.conf is heavy when its line carries the heavy marker, or when it moves a built-in heavy gate (its name is that gate's short name, as pre-commit cargo-test is for pre-push-cargo-test).

The slots are flock locks on files in /tmp/greenharness-slots-<uid> ($XDG_RUNTIME_DIR/greenharness-slots on Linux when set), a fixed path so every session shares one queue whatever its $TMPDIR. greengate refuses that directory unless it is a real directory you own with mode 0700, and then runs the check unqueued with one line saying why. What a slot that never frees means is the repository's busy policy: by default, after greengate.timeout, the check runs unqueued with a note. Waiters are served first come, first served. A held slot is released when the check ends, and by the kernel if greengate dies. An greengate started by a check that holds a slot (GREENHARNESS_HOST_SLOT set) does not queue. Windows has no slots.

Unset, the count follows the machine (ADR-0021): at most half the physical cores (max(1, cores/2), see greengate.hostCores). A free slot is taken only while the one-minute load is below the core count, and at most one new holder is admitted every 60 s. The first waiter on an empty host always gets one. A number fixes the count, with no load test.

Each holder is also bounded in width: a heavy check or greengate slot run command runs max(1, weight × cores / cap) jobs, through MAKEFLAGS, CARGO_BUILD_JOBS, RUST_TEST_THREADS and NEXTEST_TEST_THREADS. The check's own environment wins, then the parent's, then greengate's computed width. See docs/host-slots.md.

The same queue serves everything heavy on the machine, not only greengate's hooks: relais's verification commands, and any command run as greengate slot run -- <command>. A waiter says whom it waits behind (queued behind relais: cargo test (amont-wt-x, 4m)), and greengate slots lists the holders. The protocol is docs/host-slots.md.

greengate.hostCores — the core count the slots are sized from

git config --global greengate.hostCores 12   # default: the physical cores; 1 to 1024

The cap, each holder's width and the admission load test all use one core count: the physical cores, never more than the logical count. On a 6-core, 12-thread laptop that is 6: 3 automatic slots of 2 jobs, admitted while the load is below 6. A number replaces it, for a machine where another count suits better; 12 there restores the sizing from before ADR-0021. GREENGATE_HOST_CORES overrides it for one process. relais reads the same key through the slots crate. See docs/host-slots.md.

greengate.onBusy — what a heavy check does on a busy host

set onBusy defer   # in greengate.conf; default wait
set slotWait 60    # seconds, 1 to 3600; only under defer

The host keys above say how many heavy checks one machine runs; this one, set by the repository (ADR-0013), says what happens when no slot frees.

  • wait (the default): wait up to greengate.timeout, then run unqueued, with a note.

  • defer: wait up to slotWait, then defer the check to CI. It does not run, it never blocks (a block check included), it earns no stamp and it is never attested, so CI's attest step does not list it and CI runs it. The hook says so, with the command to run it now:

    ! 1 check(s) deferred to CI, no host slot freed: pre-commit-cargo-test
      run now: GREENGATE_ON_BUSY=wait greengate run pre-commit-cargo-test · stop deferring: set onBusy wait
    

Declare defer only where the repository's CI runs every heavy gate: a deferred gate is still required, and CI is where it now runs.

Three rules keep defer from deferring work it should not:

  • Never behind its own checks. A check defers only when this greengate holds no slot. Two heavy checks of one commit on an otherwise idle machine wait for each other, as under wait.
  • One wait per push. Once a push gate defers, the later heavy gates of that push defer without waiting again.
  • The push twin defers too. A commit-time gate deferred at commit leaves a deferred <gate> line on its tree's note. Its pre-push twin (the same name, or the built-in it moves) then defers rather than run the suite with the remote's connection held open. That line can only move a gate to CI, never stamp it.

Precedence, highest first: GREENGATE_ON_BUSY in the environment (GREENGATE_ON_BUSY=wait git push runs what the file would defer), then git config greengate.onBusy in the repository, then set onBusy in a trusted greengate.conf, then --global, then wait: the same ladder as every set key. A rehearsal (greengate rehearse) always waits: it is how a gate runs with no push waiting on it. Load from processes outside the hooks holds no slot and causes no deferral.

greengate.executor — where a platform=any gate runs

set executor cluster              # in greengate.conf; default local
set clusterPrepare pnpm install --frozen-lockfile --prefer-offline --ignore-scripts
git config --global greengate.cluster.kubeconfig ~/.config/greengate/kube/homelab.yaml   # the file your cluster tooling writes (the homelab: scripts/greengate-gates-kubeconfig.sh)
git config --global greengate.cluster.image 'forgejo.example/gate-runner:1.2.0@sha256:<64 hex>'

A gate declared platform=any (see custom checks) in a repository whose trusted greengate.conf says set executor cluster runs as one Kubernetes Job on the homelab cluster, not on this machine (ADR-0016). It takes no host slot: the cluster has its own slots.

The cluster proves only passes. greengate reads the verdict from what Kubernetes recorded: the Job Complete with no DisruptionTarget, the prepare and gate containers exited 0, fetch reporting the expected tree, the pod's imageID. Anything else re-runs the gate here, unchanged, and the local outcome is the verdict. That covers a gate failure, OOMKilled, a deadline, a pod not Running within the start wait, a failed prepare, a tree mismatch, every slot taken or refused by the quota, a bundle over the cap, kubectl missing or failing, and any of the keys below missing. Each fallback appends <epoch> <gate> <reason> to greengate/cluster.log in the common git directory (git rev-parse --git-common-dir). In one hook run, once the apiserver has failed, the later gates run here without asking it again.

On the terminal, a clean run says one line, <gate>: running on the cluster. A gate that fails there says <gate> failed on the cluster (exit N); running it here for the verdict, and any other fallback <gate> runs here: the cluster is unavailable (<reason>). A machine with no cluster (the kubeconfig or the image unset) says nothing, so a repository that sets set executor cluster does not warn on every hook of such a machine; a key that is set but cannot be used warns once per run and names the fix.

A cluster pass is recorded in refs/notes/greengate-gate-cluster, on the judged tree, under its own identity: the gate's command and flags, the clusterPrepare command, the image digest and the version of the cluster contract. The laptop's own executable is not part of it, so a gate whose tool exists only in the image is still reused. Changing greengate.cluster.image makes the gate run again. A cluster pass never becomes a local stamp (refs/notes/greengate-gate) or a laptop attestation.

The machine keys, read from git config (--global is the usual place):

KeyDefaultMeaning
greengate.cluster.kubeconfignone: requiredThe kubeconfig greengate passes as kubectl --kubeconfig. The default context is never used. ~ is expanded.
greengate.cluster.imagenone: requiredThe gate-runner image, pinned as name:tag@sha256:<digest>. Without @sha256: the gate runs here.
greengate.cluster.namespacegreengate-gatesThe namespace of the Jobs.
greengate.cluster.slots2How many Jobs, greengate-gate-slot-0 and up, may run at once. At most 2.
greengate.cluster.maxBundleMiB50Above this size, the bundle of the judged tree is not sent and the gate runs here.
greengate.cluster.startWait30Seconds the pod has to reach fetch Running before the gate runs here.

The Job's deadline is greengate.timeout plus 60 seconds, so greengate.timeout 0 (no ceiling) keeps every gate here. Off switches: unset greengate.cluster.kubeconfig, or git config greengate.executor local in one clone, or set executor local in the file.

greengate.rehearse.cluster — a rehearsal that outlives the laptop

# One private repository per project in a snapshot org (greengate-snapshots here).
git config --global greengate.cluster.snapshotRemote 'git@git.example:greengate-snapshots/{repo}.git'
git config --global greengate.cluster.snapshotFetch  'http://forgejo-http.forgejo.svc.cluster.local:3000/greengate-snapshots/{repo}.git'
git config --global greengate.cluster.mirrorRemote   'git@git.example:greengate-snapshots/{repo}-mirror.git'   # optional
git config --global greengate.cluster.mirror         'http://forgejo-http.forgejo.svc.cluster.local:3000/greengate-snapshots/{repo}-mirror.git'   # optional
git config --global greengate.rehearse.cluster true   # default false

greengate rehearse --cluster, or greengate.rehearse.cluster true for the post-commit rehearsal (greengate.rehearseOnCommit), sends the gates the rehearsal would run and the cluster may take to one Argo Workflow, and returns (ADR-0017). A gate goes only if it is platform=any, in a trusted manifest that says set executor cluster, and nothing vouches for it on this tree yet; the rest of the rehearsal runs here as before. The command prints one line per Workflow submitted, with its name and gates, on stderr (stdout stays for asked-for data: --status). Close the lid: the next commit or push, in any worktree of the repository, collects what finished into cluster tokens, and the push skips those gates and signs the x86_64-linux attestation as it does for a Job-lane pass (greengate cluster collect does it on demand, so does greengate stamps).

The code goes in one of two ways:

  • A snapshot. A commit of HEAD's tree with HEAD as its parent, dated now, pushed with your own git credentials to refs/snapshots/<run label> on greengate.cluster.snapshotRemote, then read back with git ls-remote. A push that is not read back submits nothing: the gates run here and greengate/cluster.log says why.
  • The mirror. When git ls-remote <mirrorRemote> advertises an object equal to HEAD, nothing is pushed and the cluster fetches that commit from greengate.cluster.mirror. Mirror detection is the only thing the laptop does with mirrorRemote, which is why it is its own key rather than a naming convention on the snapshot remote; set both or neither.

In both URL templates {repo} stands for the repository's name: the last segment of origin's URL, without .git.

KeyDefaultMeaning
greengate.cluster.snapshotRemotenone: requiredThe URL the laptop pushes the snapshot to. Pushed over ssh with your own credentials; no prompt is ever shown.
greengate.cluster.snapshotFetchnone: requiredThe URL the cluster fetches the same repository from (an in-cluster address, http:// only for *.svc.cluster.local).
greengate.cluster.mirrorRemotenoneThe pull mirror's URL as this machine lists it.
greengate.cluster.mirrornoneThe pull mirror's URL as the cluster fetches it.
greengate.rehearse.clusterfalseThe post-commit rehearsal goes detached on its own.
greengate.cluster.signerlaptopWho signs the x86_64-linux attestation of a detached pass: laptop, or in-cluster for the block greengate cluster sign writes. Any other value warns once and counts as laptop.
greengate.cluster.signer-namespaceattest-signerThe namespace of the in-cluster signer's ConfigMaps.

With none of them set there is no detached lane: a rehearsal is what it was. The kubeconfig, image, namespace and greengate.timeout are the Job lane's, above; the Workflow is created as the kubeconfig's user. greengate rehearse --status shows each pending Workflow's phase and the gates collected, --stop asks the cluster to terminate them, and kubectl get wf -n greengate-gates follows a run.

What a pass needs. Collect reads the pod, not the Workflow: fetch terminated 0 reporting the expected tree, prepare 0 when set, main terminated 0, an imageID, no disruption, from a pod owned by the Workflow greengate created and running the image and command it submitted. A Workflow or node that says Succeeded while main exited 1 is no pass. The token written is the one worked out at submission: change the command, clusterPrepare or the image after submitting and the push does not accept the pass, it runs the gate. Anything else writes one line in greengate/cluster.log and nothing more.

The in-cluster signer. With greengate.cluster.signer in-cluster, collect also asks the signer namespace, once per cluster, for the ConfigMaps of the pending runs (greengate.signer=block). A Workflow's block is checked with greensummit against the repository's allowed_signers (the one a push verifies with, which must list cluster-signer@x86_64-linux): one block, platform x86_64-linux, the record's tree, every gate that passed, signed by a principal bound to x86_64-linux. It is then filed in the local refs/notes/greensummit under the tree, and the next push publishes that block instead of signing the linux block itself. A block not written yet keeps the run pending ("signer":"awaiting") until the Workflow's TTL; a refused or skipped block, a signer that never answers, or a tree with no filed block is signed by the laptop at the push, as with laptop. A push never waits for the signer. A filed block lives in the local notes ref until a push publishes it: a later sync of that ref from origin (greengate stamps, a push of another tree) drops it, and the laptop signs instead.

greengate cluster collect exits 0 when it asked the cluster (or another collect is already running, which it says), and 1 when the cluster was not reached or the pending file could not be written; rehearse --stop exits 1 when a Workflow could not be terminated and prints the kubectl patch that does it by hand. rehearse --status also lists the runs that ended since the last look, with the gates that did not pass.

The record of what is pending is $GIT_COMMON_DIR/greengate/cluster-pending; deleting it forgets the Workflows, and refs/snapshots/* on the remote are pruned by the cluster. Unix only.

greengate cluster sign — the in-cluster signer

greengate cluster sign [--watch] runs in a pod in the cluster, not on a laptop. It signs finished detached runs from what Kubernetes recorded. Each pass makes one batched read of the Workflows and pods carrying greengate.run in greengate-gates. It considers a Workflow that is finished, has no ConfigMap yet, and was submitted by greengate: it carries its tree and gate ids as greengate writes them. Each gate is judged on its pod with the same rules as collect's, above. Only a pod that the Workflow owns, by ownerReferences and by its own node record, counts. A Job's pod, or a pod wearing a borrowed run label, counts for nothing.

The gates that passed go into one signed greensummit block for platform x86_64-linux, with no input lines. The block is written to a ConfigMap named after the Workflow, under data.block, in the signer namespace. The ConfigMap is labelled greengate.run and greengate.signer=block, and annotated with the Workflow's namespace, the tree and an expiry 7 days out. When no gate passed, the ConfigMap holds an empty block and the reason, under data.skipped, so the Workflow is not judged again. A ConfigMap that already exists counts as done. A pod not listed yet, or whose status cannot be read, holds the Workflow for a later pass while it finished 5 minutes ago or less; after that it is skipped like the rest. Each pass also deletes the expired ConfigMaps. It logs how many finished Workflows older than 5 minutes still have none.

After each pass it writes <unix-seconds> clean or <unix-seconds> failed to $HOME/heartbeat. A liveness probe can read the time to tell that the loop turns, and the word to tell a live signer whose passes fail.

VariableDefaultMeaning
GREENGATE_SIGNER_KEYnone: requiredThe ed25519 private key it signs with, checked once at start. The principal is the verifier's allowed_signers business.
GREENGATE_SIGNER_KUBECONFIGnoneA kubeconfig. Without it, kubectl uses the pod's ServiceAccount.
GREENGATE_SIGNER_NAMESPACEattest-signerWhere the ConfigMaps are written.

It writes one plain line on stderr per Workflow it acts on: signed <workflow> <gate,…> tree <short>, skipped <workflow>: <reason>, or error <workflow>: <reason>. Stdout stays empty, except for the usage that -h or --help prints, with exit 0.

Without --watch it does one pass and exits:

  • 0: the pass was clean.
  • 1: the pass failed: the cluster could not be read, or signing or writing a ConfigMap failed.
  • 2: a usage or configuration error: an unknown option, or GREENGATE_SIGNER_KEY unset or not a usable private key (the line names the path and why).

With --watch it runs a pass every 30 s. A failed pass is logged and the loop goes on. The first SIGTERM or SIGINT is said on stderr (stopping after the current run (SIGTERM)). It lets the run in progress finish: the stop is noticed before the next kubectl call, so within one call (20 s). The runs left unrecorded are judged again on the next start. The process then says stopped: SIGTERM after the current run and exits 0 after SIGTERM (the pod's graceful stop), or 130 after SIGINT. A second signal of either kind ends the process at once, killed by that signal.

greengate.minVersion — the greengate this repository means

git config greengate.minVersion 1.11.0

Rarely set by hand — the committable spelling is set minVersion 1.11.0 in a trusted greengate.conf, which is the point: a binary one release behind answers every hook name and simply lacks a check, silently, and nothing in the repository could say which greengate the team meant. A binary older than the floor gets one warning line per stage naming both versions. Warn-only, deliberately: blocking commits for being out of date teaches --no-verify, and a binary too old to know this key cannot honour it anyway.

greengate.knownIdentity — identities usual-name has vouched for

Written by the tool, not by you: when pre-commit-usual-name finds your user.name <user.email> in history once, it records the identity here (local config, never committed) and never walks the full history for it again — git shortlog --all on every commit is milliseconds today and a scale cliff on a long history. Multi-valued; greengate uninstall removes it with the rest of greengate's bookkeeping. Delete a value to make the check walk again.

greengate.fix — let a check repair what it finds

git config greengate.fix true

Off unless you ask. A hook that edits your files without being asked is a larger surprise than one that complains. See custom checks.

greengate.planExempt — reusing gates across a plans-only commit

set planExempt off in a committed greengate.conf turns off the canonical-tree route (attest 1.5.0): a result is then reused only on the exact tree, or by a spec's declared inputs. It exists for a repository whose gate reads the contents of a plan, which the canonical route would otherwise skip when only a plan changed.

  • The default is on; the value is exactly on or off, and the line appears once. Anything else (off # because, a second line) is a broken line, because attest's verifiers read this one line from the committed bytes with a reading that matches only exactly set planExempt off, and a shape they would read as "on" must not look like "off" here.
  • off only narrows what is reused, so it is honoured trusted or not, and by every producer and verifier, CI included. An unreadable greengate.conf counts as off.
  • Because greengate.conf is part of the canonical tree, adding or removing the line changes the fingerprint and the next push runs everything once.
  • Deprecated as the opt-out's home (attest 1.6.0, decisions ADR-0037): the opt-out is now @plan-exempt off in .github/greensummit-inputs (or .forgejo/), attest's own file, so attest reads no other tool's configuration. Until attest 2.0.0 write both lines: verifiers before attest 1.6.0 know only this one. greengate list says so on stderr while only this line is present. A repository whose greensummit-inputs already declares gates adds the directive only once its CI pins attest 1.7.0 or later and its greengate.conf sets minVersion 1.58.0, because to older tools the directive invalidates the spec.

greengate.testPushedTree — test what you are pushing

git config greengate.testPushedTree true

By default pre-push runs your suite against the working tree, and says so. That is fast and usually what you want, but it is not what you are pushing: an uncommitted fix makes a broken commit look green.

With this set, the suite runs in a throwaway checkout of the commits being pushed, and your tree is not touched. This covers every pre-push gate that runs a suite — the built-ins and any pre-push line in your greengate.conf alike, each once per pushed ref. It costs a second checkout and a build that cannot reuse your target/ cache, which is why it is opt-in rather than the default. A checkout that needs a step before it can run anything — a pnpm install, say — names it in greengate.snapshotPrepare, above.

greengate.attest / greengate.attestKey — sign what pre-push proved, for CI

git config greengate.attest true

Off by default. With it on, a push whose pre-push block gates all passed leaves an ssh-keygen-signed note on each pushed tip in refs/notes/greensummit — binding the pushed tree, the names of the gates that passed, and the greengate version — and pushes that ref to the same remote, so CI can verify the note and skip the test steps it names. greengate.attestKey points at the signing key; unset, it means ~/.ssh/greengate-attest. The verifying side, the trust statement being made, and why every failure falls back to CI running the tests are in the CI backstop.

greengate.trusted

Set by greengate trust, read by everything that decides whether a declared external may run. --local only, never committed. Do not set it by hand — see the trust model.

commit.template

Not ours, but worth setting: it puts the footer scaffold in front of you when you write a commit.

git config --global commit.template ~/.config/git/git-templates/message

Environment variables

variableeffect
GIT_HOOKS_BINAbsolute path to the binary a shim should use. First candidate in the shim's resolution order.
GREENGATE_BIN_DIRWhere greengate install and the installer script put binaries. Default ~/.local/bin.
GREENGATE_VERSIONPins the version the installer script fetches.
GREENGATE_ATTEST_PUSHSet by greengate itself on the notes push greengate.attest makes, so the recursive pre-push stands down. Not for humans.
GREENGATE_FAIL_FASTfalse runs this commit's checks in one wave, true in two; outranks greengate.failFast.
NO_COLORHonoured, as is a non-tty stdout: output to a pipe, a file or a CI log carries no colour. TERM=dumb too.
FORCE_COLORColour through a pipe anyway, for a caller that renders it (non-empty, not 0 or false). NO_COLOR and TERM=dumb still win.

Repository-declared checks

A repository can add checks of its own without anybody forking anything, in a committed greengate.conf. They obey every control on this page, addressed the same three ways, and they are inert until trusted.

Full reference: custom checks · the trust model.

Seeing the result

greengate list              # what would run here, and why not
greengate list --json       # the same, machine-readable
greengate setup             # walk the commit-style keys, with the current values
greengate-fleet             # the same, across every repository

greengate list ends with the commit style in effect, and names the key and the scope of anything you set:

commit style
  gitmoji            suffix     greengate.commit.gitmoji (global)
  subject max        72
  description max    68         greengate.commit.descriptionMax (global)
  body wrap          off        greengate.commit.bodyWrap (local)

  `greengate setup` to change any of these

greengate list reports the effective severity, after overrides — so a check you downgraded three months ago is visible as downgraded rather than having to be inferred from config. Across a fleet, greengate-fleet shows skips and severities per repository, with TRIGGER as its own column.

Gate evidence — reading the record the hooks already keep

A gate that stopped checking anything passes faster than one that works. That is the failure this page is about, and nothing inside the hook can see it: the exit code is 0, the output says what it always said, and the only thing that changed is the clock.

A fleet audit here on 2026-09-19 found four mechanisms in that state at once — a lockfile audit run from a directory whose lockfiles were one level down, a govulncheck built with a Go too old to read the vulnerability database, uv invoked with no .venv to resolve against, and an npm that timed out without saying so. Between them they hid 99 Python and 12 Go findings. Every one of them had been green for weeks, and every one of them had gone from minutes to milliseconds on the day it broke.

The hooks have been recording that number all along, one gate at a time, and nothing read it back.

The record

Every push writes one line per gate it ran into the note it already keeps in refs/notes/greengate-gate, keyed by the tree the gate ran against:

greengate-gate-v1 pre-push-cargo-test
run 1726900000 pre-push-cargo-test pass 412391
run 1726903600 pre-push-audit-js fail 903

run <epoch> <gate> <outcome> <milliseconds>. Line one is the stamp, exactly as it has always been — greengate.pushStamps reads that line and nothing else, so every version of greengate that predates these lines reads a note that carries them and sees no change at all. The run lines are additive, optional, and are never consulted by any decision about whether a check may be skipped.

That separation is deliberate and it is the safety property of the whole feature:

Evidence never gates. A stamp is a record that a check RAN on exactly this content; a run line is a record of how it went. Forging a run line gets you a wrong row in a report. Nothing here can make a check be skipped, because skipping is decided by line one, which this feature does not touch.

Four things are worth knowing about the shape:

  • Failures are recorded. The stamp deliberately has no opinion about a gate that failed — there is nothing to vouch for — but a dataset of only the pushes that succeeded could never produce a failure rate, so the blocked-push path records before it leaves.
  • The key is the tree, so the fingerprint is free. Two runs filed under one tree read identical content. If they disagree, the content is not what changed.
  • It is local. Notes in this ref are never pushed, never travel, and are deleted by greengate uninstall along with the rest of greengate's own bookkeeping. Nothing here is a statement to anybody else's system — that is what greengate.attest is for, and its signed payload is a separate, versioned contract that this does not touch.
  • Only pre-push is recorded. Pre-commit checks run concurrently and every failure is reported, so neither of the questions below has an answer there; and the commit path's subprocess budget is guarded at 26 git spawns, which a note read and write on every commit in every repository would break for a report nobody is blocked on. A commit-time gate's twin is recorded when the push side runs it.

Stamps a runner earns, and asking for them

The hooks are not the only writer (ADR-0015). A tool that verifies a tree in a clean worktree of its own — relais, in a candidate worktree that shares this repository's notes — runs:

greengate run --stamp [<gate>…]

It runs the named gates (by default every blocking commit-time declaration and every scoped push gate this repository opted into) on HEAD, and writes the tokens the hooks would:

  • A blocking commit-time declaration goes on the tree note, under its script name. The pre-commit hook's reuse and the push twin's pairing read it there. The one-shot marker is not used, because it lives in the worktree's own gitdir and dies with a throwaway worktree.
  • A push gate goes on the tree and the commit, as a rehearsal does. One whose commit-time twin passed in the same run is reported as covered and does not run again.
  • A built-in pre-commit check gets its built-in token on the tree note, as evidence. The commit hook still reruns built-ins, because they read the index.

It refuses a worktree with tracked changes (exit 2), because the gates would judge content no tree holds; untracked artefacts a gate leaves behind do not count. A gate that fails (exit 1), is deferred by the busy policy, cannot run or judges nothing (exit 4) writes no token. Nothing is signed here: the pre-push hook signs what it finds stamped, with the key it already uses.

To ask which gates a tree carries a verdict for:

greengate stamps [--json] [--tree <rev>] [<gate>…]
{"tree":"<oid>","platform":"x86_64-macos","gates":{"pre-commit-cargo-test":"stamped","pre-push-cargo-test":"stamped"}}

Each gate, for the gate as it is declared now:

  • stamped: a valid local token. For a push gate, its commit-time twin's token counts.
  • attested: a signed attestation on this platform, read only for the tree checked out here.
  • deferred: a deferral the commit hook recorded.
  • absent: none of these.

It exits 0 with an answer, and 2 on usage.

The report

greengate-fleet gates                       # every repository under the scan root
greengate-fleet gates --root . --depth 1    # just this one
greengate-fleet gates --json

Per repository and gate: runs in the window, pass and fail counts, median and last duration, how long ago it last ran — and the flags below. A gate that has never run does not appear: this record knows what ran, and greengate list is the answer to what is declared.

no-op suspect

Two shapes of one failure, and both are needed.

  1. The collapse. The last run took less than 10% of the median, for a gate whose median is at least 30 s. Eleven minutes to four hundred milliseconds is the signature of a runner that found nothing to run.
  2. Born broken. The last run passed in under 1 s and no earlier run of that gate ever finished that fast. A gate misconfigured from its first day has no collapse to measure; what it has is a history that never once did real work.

Both are stated with their numbers attached, so the row can be argued with:

pre-push-audit-python  NO-OP SUSPECT: last run 210 ms against a median of 41.3 s
                       (0% of it, threshold 10%)

flaky

Two runs against the same tree disagreed — one passed, one failed. The content could not have changed between them, so something outside it decided the verdict: a port, a clock, a shared fixture, a test that depends on another test's order.

stale

It has stopped running while its neighbours kept going: 10 later trees were judged by other gates and not by this one, or its last run is more than 30 days old while another gate ran more recently. A repository where nothing has run is quiet, not stale, and is reported as having no record.

Abstention

Under 5 verdicts in the window, no flag is computed and the row says so:

pre-push-cargo-test  2 runs  2 pass  0 fail  …  insufficient history (2 verdicts) — no flag computed

This is not politeness. A two-run history can be made to look like anything, and a column that cries wolf on one is a column people stop reading. The same rule covers a repository whose notes were pruned: no record is reported as no record, never as zero problems.

The thresholds are flags

Every number above is a default, printed at the top of every report and overridable per invocation:

flagdefaultdecides
--window <days>90how far back the report looks
--min-runs <n>5verdicts below which nothing is flagged
--noop-ratio <pct>10a last run under this share of the median
--noop-median <secs>30…for a gate whose median is at least this
--fast-pass <ms>1000a pass under this, never once seen before
--stale-pushes <n>10later trees other gates judged and it did not
--stale-days <days>30…or this long since it last ran

gates reports; it does not gate. A finding is printed, not exited on — the one non-zero exit is a scan that found no repositories at all, which is the rest of the tool's rule.

Evidence ordering (opt-in)

git config greengate.order evidence    # default: declared

Pre-push runs its checks serially and stops at the first blocking failure (see hook architecture). Which means the ORDER decides how long a push that is going to fail takes to say so — and the registry's order is a fixed guess made once, for every repository.

With evidence, the push gates are ordered by this repository's own record: the gates that have actually failed in the last 90 days are attempted first, ordered by failures per unit of time — failures / runs / median duration — and everything else keeps its declared order behind them. The ratio, rather than the failure rate alone, is what minimises the time a failing push spends before it fails: a five-second audit that catches one push in six is worth attempting before a twenty-minute suite that catches one in three.

What it does not do, stated because an optimisation that quietly changes enforcement would be a much worse deal than a slow push:

  • It never skips a check. The order is a permutation. Every gate that would have run still runs, and a gate is never assumed to pass because the record says it usually does. A prediction is not a run, and a check that does not run cannot be stamped or attested — the whole chain from the stamps to the attestation rests on a record of something that happened.
  • It never moves the push-shaped checks. Only the scoped gates — the suites and audits, the ones whose verdict is a function of the content — are permuted, and only among the positions they already occupy. Branch-protect, branch-pattern, secrets and pull-rebase keep theirs absolutely: the registry orders them "cheapest and most decisive first", and discovering a protected branch after twenty minutes of tests is exactly the waste this feature exists to remove.
  • With no record it is the declared order, exactly. A fresh clone, a pruned ref, a git that would not answer: all of them fall back, and the first push after turning the key on changes nothing.
  • It is reported. When the order differs from the declared one, the push says so and names the order it took.

It can be set per machine (git config greengate.order evidence) or committed for the team (set order evidence in greengate.conf, which is trust-gated like every other policy line). A local git config outranks the committed value, as it does for every key.

What this is not

  • It is not a test selector. Nothing chooses which tests a suite runs; greengate does not know what is inside one.
  • It is not a prediction, and it does not act on one. Every flag above is a statement about runs that happened, and the only thing the ordering does with a prediction is decide what to try first.
  • It does not replace looking. no-op suspect is a suspicion, named as one. Its job is to put a number in front of somebody, not to conclude. The 2026-09-19 audit found its four mechanisms by hand, and the point of this page is that it should not have had to.

Opting out

Four different things get called "turning it off". They are listed here smallest first, because the right answer is usually the smallest one.

0. Tune it instead of turning it off

If what you want gone is a rule rather than a check — the gitmoji in every subject, the 50-character description budget, the body wrapping — none of the four answers below is the right one. Those are settings:

greengate setup      # walks you through them, with the current values

This matters most for commit-msg, which is the one hook hook.skip genuinely cannot reach (see below). Changing what it asks for is the only lever there is, and it is a real one. See commit conventions.

1. One command: --no-verify

git commit --no-verify
git push --no-verify

git commit --no-verify skips pre-commit and commit-msg for that one commit; git push --no-verify skips the whole pre-push stage. prepare-commit-msg and post-commit still run — that is git's behaviour, not ours, and it is why a bypassed commit still gets its message prepared and still fails to earn a gate stamp.

Bypassing stays a supported escape hatch, and it is now counted: a commit that dodged a commit-time gate adds a line to a local ledger ($(git rev-parse --git-common-dir)/amont-bypasses) that greengate list summarises as "unverified commits". Local means local — the file is never pushed and never leaves the machine. git config greengate.recordBypasses false turns the counting off; greengate uninstall, or deleting the file, erases it.

Neither commit-msg nor prepare-commit-msg takes hook.skip or a severity override: they are entrypoints rather than checks, so the keys below do not name them. To get a message past commit-msg without bypassing everything else, fix the message — or change what it asks for, which is what §0 is about.

2. One run, one check: -c

git -c hook.skip=clippy commit -m "fix: …"
git -c hook.skip=clippy -c hook.skip=prettier commit -m "fix: …"
git -c hook.skip=clippy,prettier commit -m "fix: …"    # the same, joined by commas

A comma only separates names; each one is still matched exactly, never as a glob. A check name cannot contain a comma, so there is nothing to escape.

Nothing is written to config, so there is nothing to remember to undo.

3. Permanently, in this repository

git config --add hook.skip pre-commit-clippy   # that one check
git config --add hook.skip clippy              # that check, either trigger
git config --add hook.skip pre-commit          # every pre-commit check

These are exact names, not globs. hook.skip e reaches nothing at all, and skipping lint-js leaves lint-json-yaml alone — a skip can never silently couple two checks whose names happen to share a prefix.

To see and undo:

git config --get-all hook.skip
git config --unset-all hook.skip

A skipped check is announced on every commit, on purpose. A hook.skip line nobody remembers writing is exactly how a repository ends up with a check everyone believes is running.

Usually better: warn instead of skip

git config greengate.severity.clippy warn
git config greengate.severity.pre-commit warn

The check still runs and still reports; it just stops failing the commit. You keep the signal, which is the thing hook.skip throws away. This is the right first move when adopting a check into an existing repository with a backlog.

4. Remove the hooks entirely

greengate uninstall              # this repository
greengate uninstall --repo       # this repository only: the template dir stays
greengate uninstall --binary     # …and the binary from ~/.local/bin
greengate-fleet uninstall --root ~/Developer

This removes our six shims and nothing else. A hook you wrote yourself is left alone and named in the output, whatever it is; a hook it cannot even read is named too, rather than passed over in silence. hook.skip and greengate.severity are never touched — those are your statements about your repository.

If init.templateDir is still set, uninstall says so loudly and gives you the command to unset it. Without that, an uninstall you believed had finished would leave every future git clone re-installing the hooks:

git config --global --unset init.templateDir

Do not use rm .git/hooks/*

That glob deletes every hook in the directory — including ones other tools installed and ones you wrote — in order to remove six files that belong to us. greengate uninstall exists precisely so that removing our hooks never means removing yours.

A repository is asking to run its own checks

If greengate list shows a check with:

declared in an untrusted greengate.conf — review it, then `greengate trust`

then that repository has declared checks and they are already not running. There is nothing to opt out of. Opting in is greengate trust, after reading the file. See the trust model.

The trust model

A repository you clone cannot run code on your machine until you say it may.

That is the whole claim. This page is how it is enforced and where it stops.

The problem it solves

A repository can declare checks of its own in a committed greengate.conf, and those declarations are shell commands. Committing the file is the point — it is how a team shares a check.

The consequence is that cloning a repository and committing to it would otherwise run commands that repository chose, and neither of those acts is one anybody performs as a decision about trust. Reviewing a diff before running it is such a decision. Nothing asked for that.

This matters most for people who set init.templateDir (see install), because for them the hooks are already present in every repository they clone — including one cloned only to read.

What happens instead

A manifest is inert until trusted. Its declared checks are listed by greengate list with the reason they will not fire:

declared in an untrusted greengate.conf — review it, then `greengate trust`
greengate trust          # show what this repo declares, and accept it
greengate trust --show   # what is trusted here
greengate trust --revoke # forget it

greengate trust prints the declarations before asking. That is not politeness: "trust this file" is not a question anybody can answer without seeing it, and a prompt that does not show the file is a prompt that trains people to press y.

greengate trust outside a repository is refused rather than falling back to .. Trust is recorded per repository, keyed by the root that resolves — so a . fallback would let greengate trust in ~ read ~/greengate.conf, show its declarations, and record trust against a repository that does not exist, in a state no later --revoke would find.

The record is a fingerprint of the file, stored in --local git config under greengate.trusted — local, never committed, so a repository cannot declare itself trusted.

The key is multi-valued: it holds every manifest you have accepted here, most recent last, capped at sixteen. --local config is shared by all of a repository's worktrees, so a single value made them fight — accepting one checkout's manifest reported every other checkout on a different branch as TRUSTED ONCE, AND CHANGED SINCE and stopped its declared checks, until somebody re-accepted there and broke the first one. With a worktree per task the record never settled. Since consent is keyed on content rather than on place, a set is the honest shape: two worktrees with the same greengate.conf need one acceptance between them.

One consequence, stated rather than buried: reverting a manifest to bytes you accepted earlier no longer asks again. Those bytes were reviewed, and the cap bounds how far back that reaches — but it is a weaker guarantee than a single value gave.

Because it is keyed on content, a git pull that adds a command does not inherit the consent given to the file before it. That state is reported distinctly from "never trusted", because somebody changed it is a different thing to tell a reader than you have not looked at this yet:

greengate.conf changed since it was trusted — review it, then `greengate trust`

That is a gap, not a block, when the change arrived from somewhere else: the checks it declares show as "could not run" and your commit proceeds, because a command that never ran has judged nothing. It is a block when the commit at hand is the one changing greengate.conf (pre-commit-manifest-trust). You are the author of that content, and without it every check the file declares would stand down for exactly the commit that introduces them — letting everything else in that commit through ungated. The check names the fix and trusts nothing itself; accepting is still greengate trust, and still yours. It stays quiet during a merge, rebase, cherry-pick or revert, where a manifest arriving from another branch is the pulled case. Downgrade it like any check: git config greengate.severity.pre-commit-manifest-trust warn.

Why git hash-object --no-filters

greengate links no external crates (and CI enforces that), and the only hash in std is DefaultHasher — SipHash with a fixed key, not collision-resistant, so a crafted manifest could be made to match a trusted one's fingerprint. Hand-writing SHA-256 is a hundred lines nobody would review as carefully as they should.

git is already a hard dependency of every path in this binary, and git hash-object is the identity git itself uses for content. It is SHA-1 (or SHA-256 in a repository configured for it) — not a guarantee against a determined attacker with a chosen-prefix collision, but enormously better than SipHash, it costs no dependency, and you can reproduce it by hand to check what you trusted:

git hash-object --no-filters greengate.conf
git config --local --get-all greengate.trusted   # every manifest accepted here

--no-filters is the load-bearing flag. Without it, git applies the clean filter and eol conversion that the repository's own committed .gitattributes asks for — so the repository would be choosing the transform its consent is taken through, and two manifests the parser reads differently could be given the same id. Consent is bound to the bytes that are parsed.

For the same reason, where a caller already holds the file's bytes, the state is decided about those bytes rather than by re-opening the path. Two reads of a file somebody is deciding about can disagree, and the decision would then be recorded about bytes nobody was shown.

Two windows that were closed, and how

Between showing and answering. greengate install prints the manifest, then blocks on a keypress — sometimes for several seconds — before recording anything. Re-hashing at that point would trust whatever is on disk then, which is not necessarily what was shown. So callers fingerprint what they show before asking, and pass that same value back to be verified again once the answer is in. If the file changed in the window, nothing is trusted and the prompt says so.

Concealing a declaration inside the listing. Every field in that listing is repository-controlled text, and it is the text somebody is about to say yes to. It is sanitised before the column padding is computed: a terminal escape sequence is zero columns wide, so it would silently shift the alignment even if it did nothing worse — and a repository that can move the rendering can hide a line from the person consenting to it. A repository must not be able to pick how its own consent is rendered any more than it can pick how it is hashed.

A vendored pack is consented to like anything else

greengate add (custom checks) copies declarations from somebody else's repository into your greengate.conf. It grants no trust, and it gets no exemption:

  • the append changes the file's content, so the fingerprint no longer matches and every declared check goes inert — including ones you had already trusted — and pre-commit-manifest-trust blocks the commit that carries the append until you have reviewed it;
  • the pack's rows are shown by greengate trust alongside your own, in the same listing, with no marking that would invite skimming past them;
  • editing a vendored row by hand revokes consent exactly as editing a hand-written one does.

The commit id recorded in the block says where the text came from. It is provenance, not authority: it tells you the bytes are the ones that repository published, and says nothing about whether the commands are a good idea. Reading them is still the gate, and it is still yours.

What this does not protect against

Stated plainly, because a security boundary described only by what it stops is a marketing claim:

  • It is not a sandbox. Once you trust a manifest, its commands run with your privileges. Trust is a review gate, not containment.
  • It says nothing about the built-in checks. Those are code in the binary you installed, and are governed by hook.skip and severity, not by trust.
  • It does not protect a repository you wrote the manifest in. Your own greengate.conf is trusted by you, once.
  • SHA-1 is the floor, in a repository using git's default object format. See above for why that trade was taken.

To report something this model gets wrong, see SECURITY.md.

The provenance record: greengate-provenance-v1

A second, separate note (decisions ADR-0036): a signed record of what a push carried besides its tests — the plan it implements and the verdicts given on it. It is not an attestation. CI never reads it, and attest's verifier does not either. greengate produces it with the same key and the same publishing rules as an attestation, from the payload amont-agent writes. Each line has one owner: amont-agent records what it witnessed (the plan, the review, the preview), and the signer states the tree facts it checks or computes itself (tree, canon).

greengate-provenance-v1
commit 9f1c2ab0d6e4c1b2a3f405e6d7c8b9a0f1e2d3c4
tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
canon 1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e9d0c
patch 7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d
plan docs/plans/2026-10-15-provenance-recorded-at-the-push.md 031240153fa4ecee3f2f1f7e1ab3eae5403dd1990dbc1b104b8c6569069944cd
review reviewed 5be1b4e3a1d0c7f2e9a8b6d4c3f1e0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3
preview not-required
producer amont-agent 2.43.0

-----BEGIN SSH SIGNATURE-----
…
-----END SSH SIGNATURE-----

Payload and signature are separated exactly as in an attestation block (attest SPEC.md, "The note") (the payload's trailing newline is signed), fields are read by prefix, the first occurrence wins, and an unknown line is ignored.

linemeaning
greengate-provenance-v1format token, always first; any other value means absent
commit <oid>the pushed commit
tree <oid>its full tree
canon <oid>canon(T) of tree (attest SPEC.md, "Canonical tree"), whatever planExempt says; written by the signer, never by amont-agent (see "The handoff")
patch <id>optional: git diff --binary <merge-base(origin/main, commit)> <commit> -- . ':!docs/plans' piped to git patch-id --verbatim; omitted when it cannot be computed
plan <path> <body-sha>the plan file in tree and its body-sha (amont-agent plan-sha)
review <how> <content-id>reviewed, by-patch (the hook's reviewed-by-patch) or overruled, and the content id (see "Content id") of the tree the review read
code-review <role> <how> <content-id>optional, one line per code-review profile the plan declares, in profile order, after review. role is the profile (backend, lang:rust, …), how is reviewed, by-patch, carried or overruled, and the content id is the tree that profile's review read. This is the one repeated field: a reader takes every code-review line, not the first. A push with no declared profile writes none (amont-agent 3.11.0)
preview <outcome>approved, evidence or not-required
producer <name> <version>who wrote the payload, informational

commit, tree, canon, plan and review are required in a signed record.

Where it lives. refs/notes/greengate-provenance, one or more blocks per object, keyed by the tree and by the commit, as attestations are, and published by the same append-and-push loop (attest SPEC.md, "Producing"). The signature's ssh-keygen namespace is greengate-provenance, never greensummit: a provenance block can never be replayed as an attestation, and an allowed_signers entry accepts it only once it lists that namespace (namespaces="greensummit,greengate-provenance,amont-provenance").

The handoff. amont-agent writes the unsigned payload to <config dir>/amont-agent/provenance/<repo>/<commit>, where <config dir> is $CLAUDE_CONFIG_DIR, else $HOME/.claude, else %USERPROFILE%\.claude (amont-agent's settings::config_dir), and <repo> is spelled as in amont-agent's implementation-review/by-tree/<repo>/: the name of the directory holding the repository's common git directory. Only amont-agent's hook writes there. The payload it hands over has no canon line. greengate's pre-push reads that one path — never a path a git config key could redirect — and:

  1. refuses a payload whose tree is not the pushed commit's tree;
  2. refuses a payload that already carries a canon line (a pre-release amont-agent wrote it), names the file to delete, and neither signs nor removes it;
  3. computes canon(T) of the pushed tree in the repository's own object format and inserts canon <canon(T)> right after the tree line. planExempt does not apply: it governs skipping a gate, not a tree's identity. If there is no canon(T), it signs nothing and keeps the payload for the next push;
  4. signs and publishes the result, and deletes the file once published.

What the signature says, and no more. This machine's amont-agent recorded plan, review and preview, greengate checked tree against the pushed commit and computed canon from it. A reader checks plan itself, against the plan file in tree, and can recompute canon and the review content id from tree. Nothing checks the verdicts review and preview state: only amont-agent's guard on its store protects them, and that guard is best-effort against a shell command that writes the file. Anyone holding the key can sign any payload, as for attestations.

Reading it. A record whose commit is not reachable from origin is ignored: greengate publishes before the push delivers, so a push that failed can leave a note behind. A record is found on the pull request's head commit, else on the merge commit's tree, else by its patch line. To match by patch, a reader hashes the merge commit's own change the same way: the diff from its first parent, docs/plans excluded, through git patch-id --verbatim.

Content id

The value an implementation review and a preview approval bind to (decisions ADR-0034), and the one amont-agent tree-sha prints. It is not canon(T), on purpose: canon(T) counts whether a plan file exists, and the content id does not, so adding the plan a branch implements leaves its review standing.

Definition. Take the raw records of git ls-tree -r -z --full-tree T, in git's order, each <mode> <type> <oid>TAB<path>, unquoted and undecoded. Leave out every record whose raw path starts with docs/plans/ (whatever its mode: a symlink or a gitlink there is left out too; a nested x/docs/plans/ and a docs/plans-… are kept). Follow each kept record by one NUL, the last one included, and take the lowercase hex sha256 of the bytes: always 64 hex digits, in a sha1 or a sha256 repository. No records left hashes the empty string.

Known answers, where O1 is forty 1s, O2 forty 2s and ⇥ a TAB (amont-agent's tests pin each one):

recordscontent id
nonee3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
100644 blob O1⇥README.md6f0214fffd79cb8eb5afb2283e46911f5f9022a25b3f339ae8a50a1ee223a0b2
100644 blob O1⇥README.md, 100644 blob O2⇥docs/plans/a.md, 100644 blob O2⇥docs/plans-old/a.md, 120000 blob O1⇥docs/plans/link, 100644 blob O1⇥x/docs/plans/a.md0fca850e419d8a202129087fd90f00fe285c4b9cc63b42f4db6162e0a2b12eaf, the same as without the two docs/plans/ records
100644 blob O1⇥docs/a LF b.md, 100644 blob O2⇥docs/plans/c LF d.md (raw newlines in the paths)88a9c5d4a7b3892be98a8492631b3c436954c2000a038b5d641bd054e76e19e0

The quiet-run active entry

greengate (greengate run, pre-commit checks) and amont-agent quiet keep a check's output out of the agent's context: the output goes to a .log.tmp file. So that a person can still see such a run live, each tool writes one small JSON file while the run is active, and a reader such as relais's relais quiet watch --protocol turns those files into something it can draw. A writer never depends on a reader.

This page is the contract for that file. greengate owns it (decisions ADR-0039, harness.cross-tool-reads), and it has one implementation, the std-only greenharness-quiet crate, which greengate and amont-agent write through and relais finds the directory with (harness.shared-code). A reader documents only what it does with the file. relais's watcher protocol, with its own retention rules, is in relais docs/quiet-runs.md.

The directory

$QUIET_ACTIVE_DIR when set and not empty (every test sets it), else ${XDG_STATE_HOME:-$HOME/.local/state}/quiet/active, and %LOCALAPPDATA%\quiet\active on Windows. A writer creates the directory 0700.

An empty variable counts as unset. With no HOME, or an empty one, and no XDG_STATE_HOME, there is no directory and nothing is written: never a relative .local/state under the working directory. A writer also writes nothing outside a Claude Code session (an empty CLAUDE_CODE_SESSION_ID): only a session's runs are ever drawn.

The entry file

<pid>-<n>.json, mode 0600, written atomically: a temp file .<pid>-<n>.json.tmp, created new, then a rename over the entry. An existing temp, a symlink included, fails the write rather than being followed or truncated. A reader ignores dotfiles and anything not ending in .json. <n> tells apart the concurrent checks of one process. The file's name without .json is the run's id.

fieldtypemeaning
vnumberformat version, 1: the version token a reader checks; a reader ignores any other
toolstringgreengate or amont-agent
sessionstring or nullCLAUDE_CODE_SESSION_ID of the starter; null outside Claude Code
checkstringthe check name, or the program name for amont-agent quiet
repostringthe git toplevel, else the working directory
logstringabsolute path of the .log.tmp the output goes to
pidnumberthe writing process
startednumberunix milliseconds
exitnumber or nullonly once ended: the exit code, null when the run was killed
endednumberonly once ended: unix milliseconds

Unknown fields are ignored. A new field that a reader may ignore keeps v at 1; anything else is a new version.

The writer's lifetime

  1. The tool writes the entry when its capture opens.

  2. When the run ends, the tool rewrites the entry with exit and ended (and log where the log now is) and leaves it, so a reader that polls still sees a run that ended between two of its polls.

  3. Before writing, a tool sweeps the directory. It removes:

    • an ended entry, of either tool, whose ended is more than 60 s old;

    • an entry of its own tool without ended whose pid is dead.

    • a temp file older than an hour: .<id>.json.tmp, and the two forms writers used before greenharness-quiet, <id>.json.tmp and .amont-agent-tmp-*.json.

    A pid is gone only when kill(pid, 0) fails with ESRCH; any other answer keeps the entry. A pid that is no process, zero, negative or wider than an i32, is dead and is never passed to kill. Off unix every real pid counts as alive, and such an entry waits for its own ended or for a reader to remove it. The sweep is best-effort: a file that cannot be read or removed is left for the next one.

A reader may also delete an entry, by the rules of its own protocol.

Host slots

The contract of the greenharness-slots crate (greengate ADR-0014, decisions ADR-0049). A test suite, a build or a type checker already uses every core on its own, so a heavy job takes a host slot before it runs. Every heavy job on the machine takes its slot through this one queue: greengate's git-hook gates, relais's verification commands, and any command run through greengate slot run. relais links the crate; it does not carry a copy.

The directory

GREENHARNESS_SLOT_DIR, else $XDG_RUNTIME_DIR/greenharness-slots on Linux, else /tmp/greenharness-slots-<uid>. It is a fixed path, never $TMPDIR, which macOS and agent sandboxes set per session. It must be a real directory owned by this user with mode 0700. Otherwise slots are off for the job, and it says why.

PathWhat it is
slot-0 … slot-{cap-1}the slots. A slot is held while a process holds flock(LOCK_EX) on its file.
admissionthe one admission lock. Every admission decision is made under it, taken with LOCK_NB and retried inside the caller's own deadline, so a stopped holder of it never holds a hook past its own deadline.
admitted-atthe time of the last admission, in ms since the epoch, for the ramp.
queue/<nanos>-<pid>-<n>a waiter's ticket, flocked for as long as it waits. It is created hidden (.new-…), locked, then renamed into place, so a visible ticket is never unlocked. A visible ticket whose lock is free belongs to a waiter that died, and is removed.
holders/slot-N.whowho holds slot N, as a JSON object (pid, tool, repo, command, session, started_ms, and jobs when the writer knows it). It is written after the slot is won and removed before it is released. A reader trusts it only while pid is alive. A hidden .slot-N.who.<pid>.tmp beside it is a rename in flight; when a slot is granted, those whose pid is dead are removed, as dead queue tickets are. It lives in a subdirectory so an old client counting slot-* files never mistakes it for a slot.
waits.jsonlone line per acquisition: at_ms, tool, weight, waited_ms, load1, outcome (admitted, deferred, unqueued, timeout, handed), pid, and jobs when the writer knows it. Lines written by greengate's checks also carry name (the check), session when one is known, and "rehearsal":true / "prestage":true inside a rehearsal snapshot / land's pre-stage.

Admission

Only the oldest live ticket may take slots. It takes weight slots, all or none, under the admission lock, when:

  • no slot is held: the floor. The first waiter on an empty host is always admitted, whatever its weight up to the cap;
  • greengate.hostSlots is unset (automatic): a free slot exists, the one-minute load is below the core count, and at least 60 s have passed since the last admission, unless the waiter's own process already holds a slot (one commit's checks are not spaced apart). The cap is max(1, cores/2), with cores as Cores counts them;
  • greengate.hostSlots N: N free slots are enough, with no load test and no ramp. 0 turns slots off.

The 60 s ramp is the load average's own lag: 10 s after a new holder starts, the one-minute load shows only about 15% of it.

A waiter that is not admitted says why, after whom it waits behind: (2 ahead), (slots full 3/3), (load 31.0 >= 6 cores) or (one new holder per minute). The first such line is followed, once, by see: greengate slots.

Cores

One count sizes the cap, the width and the load test (ADR-0021): the physical cores, never more than the logical count, which also honours a cgroup or affinity limit. macOS reads hw.physicalcpu; Linux counts the distinct core_cpus_list entries in sysfs, then the distinct (physical id, core id) pairs in /proc/cpuinfo, and falls back to the logical count where neither says (aarch64 VMs). Hyper-threads share a core's execution units, so on a 6-core, 12-thread host the count is 6: 3 automatic slots, each 2 jobs wide.

greengate.hostCores N (1 to 1024) replaces the detected count, and GREENGATE_HOST_CORES overrides it for one process. The slots crate resolves both host keys for every client (greenharness_slots::host::resolve), so greengate and relais always size the queue from the same numbers. Detection reports how it found the count: detected, detected (logical fallback) where the OS gave no physical count, or limited by affinity where an affinity or cgroup limit allows fewer cores.

greengate slots names the threads only where they differ from the cores, and tags a count that plain detection did not set, inside 80 columns (6 cores, 12 threads, 4 cores, 12 threads (env), (git), (logical), (affinity)). --json carries cores and cores_source, whose value is a stable token: env, global, system, detected, logical_fallback or limited_by_affinity. greengate doctor prints the full sources on stderr, one line per key:

host cores: 4, 12 threads (GREENGATE_HOST_CORES)
host slots: auto (detected)

An invalid value is a warning that names the fix for its source (unset GREENGATE_HOST_CORES, or the git config command).

Who holds a slot

Only the process that took the slot holds it. Slot descriptors are close-on-exec, so a command's children, and any daemon it leaves behind, never hold it. greengate slot run frees the slot when its command exits. GREENHARNESS_HOST_SLOT=held in a command's environment means its parent holds a slot, and an greengate or wrapper started under it does not queue again.

Handoff inside a rehearsal

Inside a rehearsal snapshot a pre-push keeps its slot from one heavy gate to the next. The finished gate parks its lease and renames the holder record to pre-push, between checks; the next heavy gate takes it with a handed line in waits.jsonl (a wait of 0, the same pid). The pre-push releases a parked slot when it ends, however it ends. While a slot is parked, a light check's tools run under it, width-bound, and a child greengate slot run does not queue. A gate that runs on the cluster executor releases the parked slot first. A plain push and a commit release their slot after each check.

The ceiling in land's pre-stage

Only in land's pre-stage, a heavy warn check waits at most greengate.warnSlotWait seconds (default 600, range 1 to 3600, never above greengate.timeout), then runs unqueued. Precedence: git config, then set warnSlotWait <s> in a trusted greengate.conf, then the default. A block gate and a background rehearsal wait as before.

Width

A slot bounds how many heavy jobs run, and the width bounds how hard each one runs. Left alone, cargo builds and its test harness runs on every core, so cap holders ran cap × cores jobs at once. A holder of weight slots therefore runs jobs = max(1, weight × cores / cap) wide, with cores as Cores counts them. greengate sets MAKEFLAGS=-j{jobs}, CARGO_BUILD_JOBS, RUST_TEST_THREADS and NEXTEST_TEST_THREADS on every heavy hook check and every greengate slot run command (amont_slots::bound_width). relais uses the same formula for its verification commands.

  • Precedence: the check's own environment first, then the parent's environment, then greengate's computed width. A key already set to a non-empty value is kept, so a check that sets its own width, or a relais run that bounded its command, wins. An empty value counts as unset. A MAKEFLAGS that carries flags but no job bound gains -j{jobs}.
  • Unqueued runs are bounded too. A check that runs after its slot wait timed out runs when the host is busiest.
  • Nothing is set when slots are off (greengate.hostSlots 0), unsupported (Windows), or the command is nested under a holder (GREENHARNESS_HOST_SLOT=held), whose bounds it inherits.
  • greengate slots shows each holder's jobs, or - for a record written without it.

Old clients

greengate up to 1.61 and relais before it linked this crate take slot-0..N with no ticket and no load test. They jump the queue until they are upgraded. Their slots show as unknown (old client), because they write no holder record.

Commands

  • greengate slot run [--weight N] [--max-wait S] [--on-timeout run|exit] -- <cmd…> waits for a slot, then runs the command with GREENHARNESS_HOST_SLOT=held and passes its exit status through. After --max-wait (default 90 s, under Claude Code's 120 s Bash timeout) it exits 75 and runs nothing, unless --on-timeout run is given.
  • greengate slots [--json] lists the holders, the old-client slots and the number of waiters.

Custom checks — greengate.conf

A repository can declare checks of its own. Put a greengate.conf at the repository root, commit it, and the hooks run it alongside the built-ins.

# stage       name        scope         severity  command
pre-commit    lint-shell  *.sh          block     scripts/lint-shell.sh
pre-commit    protos      *.proto,*.pb  block     buf lint
pre-push      smoke       *             warn      make smoke

Five whitespace-separated fields, in file order. Alignment is cosmetic; tabs and single spaces parse identically.

Why the file is committed

.git/hooks is not committed, so a hook script dropped in there can never actually be shared: every member of the team has to install it by hand, and nothing tells them when it changes. A committed manifest is reviewed like any other change, arrives with a git pull, and is visible in the fleet dashboard.

The fields

stage — pre-commit or pre-push.

name — the short name. Together with the stage it forms the check's id, <stage>-<name>, exactly as a built-in has: a line reading pre-commit lint-shell … declares pre-commit-lint-shell.

That id is what greengate list and the dashboard show, and either the id or the short name addresses it in hook.skip and in a severity override — the same three-way vocabulary the built-ins take:

git config hook.skip pre-commit-lint-shell   # that check
git config hook.skip lint-shell              # that check, on either stage
git config hook.skip pre-commit              # every pre-commit check, declared ones included

The same name on both stages is two checks, and that is allowed: show-unicorn on pre-commit and on pre-push gives you pre-commit-show-unicorn and pre-push-show-unicorn, each separately skippable and separately downgradable. See What a repository cannot do for the limits.

scope — * for every change, or a comma-separated list mixing *.<ext> extensions and bare filenames: *.ts,package.json,.prettierrc. A bare token matches the path's basename exactly, anywhere in the tree — an extension list cannot say package.json without also matching not-package.json, which is why this is its own kind of token.

A directory is a token of the form dir/**/*.ext: a path is in scope when it sits under dir/ and ends with .ext. claude-plugin/**/*.md covers claude-plugin/skills/x/SKILL.md and never claude-plugin-old/SKILL.md. The directory is whole segments, with no glob characters, no empty segment and no . or ..; the extension is a plain suffix. Anything else containing a / or a glob (claude-*/**/*.md, claude-plugin/*.md, x/**/*) is refused as a parse error. Evaluated against the files staged for a commit, or against the range being pushed. This gate is real: a *.sh check does not run on a commit that touches no shell.

A + adds the second half — what the repository must carry:

pre-commit  rubocop  *.rb+.rubocop.yml  block  rubocop

"a staged .rb, and this repository has a .rubocop.yml." Both sides are comma-separated and each is an OR — any trigger, any one of the opt-ins — while the two halves are an AND. With nothing on the left, +Gemfile reads "any change, in a repository that carries a Gemfile".

The separator is the one greengate list already prints between the halves:

○ rubocop (declared)   inert here — needs .rb + .rubocop.yml

What you read in the listing is what you write in the file.

Why it exists. Every builtin has this: clippy stays inert without a Cargo.toml, yamllint without a .yamllint.yaml. Declarations did not, because the manifest was the opt-in — you typed the line, so you wanted the check. greengate add ended that: a vendored line is in your file because you took a whole pack, and without a condition a packaged rubocop fires on every .rb in a repository that never wanted it and just errors.

A + that names no file (*.rb+) is refused rather than read as "no condition" — that is the opposite of what it was reaching for. A filename containing + is not expressible.

severity — block fails the stage; warn runs the check, prints whatever it prints, and lets the commit through. It is your choice, per check.

command — the rest of the line, split on whitespace and executed directly from the repository root, through the same program resolution the built-ins use — so npx and friends work on Windows, where a bare Command::new cannot start a .cmd. On pre-push it runs once per pushed ref, over that ref's changed files, and — with greengate.testPushedTree — in a throwaway checkout of that ref's tip rather than your working tree, exactly as the built-in test suites do. A scoped pre-push gate does not run while git holds the connection open: by default a bare git push whose gates have not run on its tree is refused, and greengate land runs them first (greengate.pushGates).

Your command gets the file list

Two ways, both carrying exactly the paths the scope matched — the same set the gate above judged, which a wrapper re-running git diff --cached can diverge from (greengate run --all-files overrides the set in-process):

  • $GREENGATE_FILES, always: the matched paths, newline-separated, relative to the repository root. Empty when the set would not fit in an environment variable (very large change sets) — treat empty as "derive it yourself".
  • the files marker, opt-in: prefix the command with files and the matched paths are appended to the argv, the way a built-in hands its tool the staged list:
pre-commit  lint-shell  *.sh  block  files scripts/lint-shell.sh --strict

With files, a commit whose matched set is empty does not run the command at all — most linters error on an empty argv, and a commit must not be blocked over nothing.

A pair declared without files is read as judging the whole tree: when its commit-time side passed on the tip of a push, the push-side twin is skipped for the whole ref, older unstamped commits included (ADR-0019). A command that judges only $GREENGATE_FILES, or picks the staged paths itself (lint-staged, git diff --cached, --staged), must carry the files marker if it has a pre-push twin, or a later passing commit would vouch for files it never looked at. On 2026-11-06 no such pair existed in the fleet: the three suppressions --staged gates (amont-agent, decisions, grh) have no twin.

  • the docs-skip marker, opt-in, pre-commit only: prefix the command with docs-skip and the check does not run when the staged change only edits existing documentation. Documentation is a .md, .mdx, .rst or .adoc file, outside adr/, that is a modification: an added, deleted or renamed file, a code file, a .txt (a requirements.txt is a dependency manifest) or a decision record always runs the check. The skip is printed as skipped — the commit only edits existing documentation. A docs-skip on a pre-push line is a parse error.

    This is a trade, and the adr line in greengate's own greengate.conf takes it: a documentation edit that adds a link to a file that does not exist will pass commit time. A skipped check is not recorded as having passed: it earns no commit-time stamp, so a same-named pre-push declaration still runs and an attestation never tells CI the gate is covered. CI and the push-side checks see it.

  • $GREENGATE_INDEX_FILE and $GREENGATE_INDEX_GIT_DIR, at pre-commit whenever git names an index: the absolute path of the index git commit is sealing, and the absolute git dir of the repository it belongs to. A command runs with no GIT_* variable (a test suite's fixture repositories must not write into this one), so under git commit -a or git commit <paths>, whose index is a temporary file git names only to the hooks, a command reading git diff --cached alone sees the old index. Read the staged state with GIT_INDEX_FILE="$GREENGATE_INDEX_FILE" git diff --cached, and only where your own git rev-parse --absolute-git-dir is $GREENGATE_INDEX_GIT_DIR: anywhere else (a suite's fixture repository) the index is not yours, and the variables are ignored. Treat the index as read-only: under a plain git commit it is git's own lock file. Neither variable is set on a pre-push command, and a suite that runs pre-commit can unset both for its fixtures, as it does the GIT_* ones.

  • the index marker, opt-in, pre-commit only: prefix the command with index when it reads the index through git and cannot be taught $GREENGATE_INDEX_FILE: it is handed GIT_INDEX_FILE too, the one git variable a declared command keeps. Declare it only on a command that makes no repositories of its own. When greengate cannot locate the index, every pre-commit command is refused rather than run blind, with git's reason. index on a pre-push line, or beside platform=any, is a parse error. An older greengate reads index as the program name, cannot start it, and only warns, so the line stops blocking until everyone reading the file has upgraded.

    A pre-commit pass recorded by an greengate that did not set these variables does not count: each declared pre-commit gate runs once more after the upgrade, and once more when index is added or removed.

    pre-commit  staged-lint  *.rs  block  index my-staged-linter
    
  • the heavy marker, opt-in: prefix the command with heavy when it compiles or executes the product (a test suite, a type checker, a build). A heavy check takes one of the machine's host slots before it runs, and the repository's busy policy (set onBusy) says what it does when none frees. A check that moves a built-in heavy gate (pre-commit cargo-test) is heavy without the marker. An greengate older than 1.61 reads heavy as part of the command, so add it once everyone reading the file has upgraded.

    pre-commit  plugin-test  *.ts  block  heavy make plugin
    
  • the platform=any marker, opt-in: prefix the command with platform=any when the gate's verdict does not depend on the platform it runs on (a lint, a type check, a cycle check, never a test suite that executes the product). In a repository whose trusted greengate.conf also says set executor cluster, and on a machine with a cluster configured (greengate.executor), the gate runs as one Kubernetes Job on the homelab cluster instead of here, and takes no host slot (ADR-0016). The cluster proves only passes: any failure, there or of the cluster, re-runs the gate here, unchanged, and the local result is the verdict. platform=any with fix or with files is a broken line: the pod rewrites nothing and is not handed the matched files. platform= with any other word is broken too. From an untrusted manifest the marker does nothing, like the line it is on. An greengate older than 1.67 reads platform=any as the program name, so the gate fails: add it once everyone reading the file has upgraded.

    set executor cluster
    pre-commit  typecheck  *.ts  block  heavy platform=any pnpm -r typecheck
    

A platform=any gate can outlive the laptop

A platform=any pre-push gate of a repository that says set executor cluster may also be handed to a detached Argo Workflow by greengate rehearse --cluster (or git config greengate.rehearse.cluster true for the post-commit rehearsal): the rehearsal submits it and returns, and the next commit or push collects the pass, whether or not the laptop was awake meanwhile (ADR-0017). The rules above hold unchanged: no fix, no files, the verdict independent of the platform. Two things are specific to this lane. The pod gets a shallow checkout of the tree (depth 1), so the gate must read only the working tree and need no git history. And it gets the gate's command as written, in the pinned image, with clusterPrepare first when set: a gate whose tool exists only on your machine fails there, and runs here: in greengate land (or in the push itself under greengate.pushGates inline). The machine keys, what a pass needs and the off switches are in configuration.

There is no shell

No pipes, no redirection, no globbing, no quoting. make smoke works; find . | xargs foo does not — put that in a script and invoke the script.

Two reasons, and the second decided it. Windows has no sh, and every emulation of one this project has tried has been a source of bugs. And a manifest line that silently gained shell semantics would be a much larger thing to have introduced than it looks.

Exit codes

0 passes. Anything else fails, and whether that stops you depends on the severity column.

A command that cannot be started at all — a typo'd path, a tool nobody installed — is neither. It is reported as a gap:

⚠ greengate.conf: lint-shell could not run scripts/lint-shel.sh — No such file
⚠ 1 check(s) could not run: lint-shell

It does not block, because a command that never ran has not judged anything; reporting it as a lint failure sends someone hunting for an error that does not exist. But it is never silent, because a check that has quietly never executed is the one failure this whole design is arranged against.

A line nobody can parse is not skipped

The same rule applies to the manifest itself. A malformed line still produces a check — one that reports on every commit and says which line and what was wrong:

⚠ greengate.conf: oops — line 3: severity "LOUD" must be `block` or `warn`

Silently ignoring it would mean a check somebody committed months ago has never run once and nothing ever said so.

Repo policy — severity, skip, and set lines

The manifest can also carry the TEAM's decisions about the built-ins, so "clippy is warn-only here" is a committed, reviewed line instead of sixty people running the same git config incantation:

severity  clippy          warn     # runs, reports, does not block — here
severity  pre-push-pytest block    # and this one always blocks
skip      yamllint                 # never runs in this repository

Targets use the same three-way naming as hook.skip — full id, short name, or a whole trigger — and a target that names no check here is reported once per run, with its line number, rather than silently doing nothing.

Trust-gated, like everything else this file says. Untrusted policy is inert and announced (greengate.conf policy not applied: …) — a repository you cloned to read cannot weaken your safety net until you consent, and the trust prompt shows the policy lines you are consenting to.

Precedence is a specificity ladder, per key: built-in default < system config < global config < policy < local config < worktree < command (git -c). Your git config --global preferences yield to the team's committed decision; your LOCAL config in that repository still beats it — the developer owns their machine, and every documented escape hatch keeps working. Between DIFFERENT keys naming the same check, key specificity decides regardless of source: a policy severity pre-commit-clippy … outranks a local greengate.severity.pre-commit, and vice versa a local full id outranks a policy trigger. Skips are a union of all sources — nothing can un-skip, so there is no conflict to order.

(On a git too old for --show-scope, this degrades fail-safe: ALL git config beats policy. See configuration.)

set — committed thresholds and commit style

The same file can carry the numeric and style knobs the checks consult:

set  largeFileWarn     1      # warn above 1 MB, in this repository
set  commit.subjectMax 50     # the whole team's subject budget

set <key> <value> takes the key exactly as you would write it after git config amont. — matched case-insensitively, values parsed by git itself, so set largeFileBlock 2k means what git config would mean by it and a bad value complains the same way. The same ladder applies: a policy value beats your global config, and your local config in that repository still beats the policy.

Only these keys are settable: largeFileWarn, largeFileBlock, commit.gitmoji, commit.subjectMax, commit.descriptionMax, commit.bodyWrap, autoRebase, timeout, lockWait, testPushedTree, snapshotPrepare, snapshotDeps, snapshotCarry, order, treeLint, treeLintSlack, treeLintWait, treeLintRehearsalTimeout, snapshotPrepareOutputs, planExempt, onBusy, slotWait, executor, clusterPrepare, and minVersion — the last being the team's version floor: a binary older than set minVersion 1.11.0 says so once per stage, warn-only, instead of silently lacking the checks the team added since.

The three snapshot* keys say how a checkout of the commit becomes runnable, which the repository knows and every clone would otherwise have to discover by hand: snapshotDeps how dependencies arrive (install, reuse, off), snapshotCarry which untracked files are copied in, and snapshotPrepare anything else. snapshotPrepare is the one whose value is a whole command. It runs in the snapshot, through the shell, before any suite, and consent covers it exactly as it covers a declared check's command: policy binds only on a trusted manifest, the trust prompt prints the command, and editing the line revokes the trust. See configuration.

A set value runs to the end of the line, so a command with spaces and flags is written plainly:

set snapshotPrepare pnpm prisma generate
set snapshotCarry .env

onBusy (wait or defer) and slotWait (whole seconds, 1 to 3600) are strict like planExempt: any other value, or the key set twice, is a broken line. set onBusy defer moves a heavy gate to CI when the machine is busy, so declare it only where CI runs that gate; see configuration.

executor (cluster or local, default local) and clusterPrepare (a shell command) are strict the same way: another executor value, or either key set twice, is a broken line. set executor cluster sends this repository's platform=any gates to the cluster; set clusterPrepare <cmd> is what the Job's prepare container runs in the checkout before the gate (pnpm install --frozen-lockfile --prefer-offline --ignore-scripts, say). Both are policy: they bind only from a trusted manifest, and the trust prompt shows them. A local git config greengate.executor local turns the cluster off for one clone; nothing local can turn it on, or name the prepare command. See configuration.

Any other key is refused with its line number — most deliberately greengate.fix, because a committed file must not change what already-trusted commands may DO to your working tree (see below). One caveat worth reading before committing it: set timeout accepts the full configured range, including 86400 and 0 (which disables the per-check deadline entirely) — a review of that line is a review of how long a hook may hang everyone.

What a repository cannot do

Take a built-in's id. pre-push branch-protect … is refused: it would either shadow pre-push-branch-protect or silently lose to it, and a text file should not be able to do either. The same name on the other stage is fine — pre-commit branch-protect … is a different check and shadows nothing.

Write the stage into the name. pre-commit pre-commit-clippy … is refused. It would declare a check whose short name is another check's full id, so a single hook.skip pre-commit-clippy would silence both and no rule could pick between them. So is a name that simply is a stage. The stage column already says which one this is.

Declare the same id twice. The second is refused: it could not be addressed by hook.skip or by a severity override, so it would run anonymously. Two lines with the same name on different stages are two ids, and both run.

Grant its own trust, or reach the machine-level knobs. Policy stops at severities, skips, and the allowlisted set keys: greengate.fix (rewriting your working tree), the trust decision itself, greengate.conventions, and the observability opt-outs stay per-machine — a committed file must not change what already-approved commands are permitted to DO, which is a different consent than "I read these commands".

Run before the built-ins. Externals are appended to each stage, always. A third-party command must not be able to delay pre-push-branch-protect, and appending is the only arrangement in which it cannot. On pre-push, which stops at the first blocking failure, that means a built-in failure means your check does not get a turn.

A manifest is inert until you trust it

A repository you cloned can declare checks, and running them is a decision you make — not one git clone makes for you. So nothing in greengate.conf runs until somebody accepts it here:

greengate trust            # shows what it declares, then records it
greengate trust --show     # what it declares, and whether it is trusted
greengate trust --revoke

greengate install asks once, with the declarations in view. Declining still installs the built-ins.

Until then the checks are reported, not dropped — the point is that you can see there is a decision waiting:

⚠ greengate.conf: lint-shell — declared in an untrusted greengate.conf …
⚠ 1 check(s) could not run: lint-shell

Acceptance is recorded against the file's CONTENT (git hash-object, which you can run yourself), so a git pull that adds a command does not inherit the trust you gave the file before it. When that happens the message says so — changed since it was trusted — because "somebody edited this" is a different thing to be told than "you have not looked at this yet".

This is a floor, not a ceiling. A built-in check still runs your repository's own toolchain: prettier and eslint are taken from node_modules/.bin when present, so a hostile node_modules needs no manifest at all. That is the same exposure npm install already carries.

Pinning tool versions

The checks run whatever prettier, ruff or shellcheck this machine has — and when two machines disagree, the hook "passes here, fails in CI", which reads as flakiness and trains people toward --no-verify. A tool line turns that skew into a printed fact:

# tool  <program>  <version-substring>
tool  ruff  0.6.
tool  shellcheck  0.10

Once per hook run (both stages), each pinned tool's --version first line is checked for the substring; a mismatch or an unrunnable tool warns, naming both sides. Warn-only, always — skew never blocks a commit, because the fix is a human decision about which side to move.

A substring, not a semver range: 0.6. pins a minor, 0.6.3 a patch, and the point is agreement between machines, not range arithmetic. Pins are trust-gated like every declaration — verifying one executes <program> --version for a name the repository chose, which is exactly the consent greengate trust collects.

Whole-tree gates — tree lines

A tree line declares a whole-tree check whose pass may be attested, so CI skips the step that runs the same command (ADR-0024 in the fleet's decisions, ci.attested-skip):

# tree  name         tool     scope  attest  [options]           command
tree    eslint       eslint   *      attest                      npm run lint -- {cache}
tree    ruff-check   ruff     *      attest                      uvx ruff@0.16.0 check packages
tree    ruff-format  ruff     *      attest                      uvx ruff@0.16.0 format --check packages
tree    pyright      pyright  *      attest  cwd=services/api    uv run pyright

A tree gate never decides a commit. It is not a pre-commit or pre-push check, so it has no severity column: attest stands where the severity would be, and says what the line is for. The commit is judged by the checks it always was.

  • name — the gate's token in the attestation note is tree-<name>, which is what CI's if: names. It matches [A-Za-z0-9][A-Za-z0-9._-]* (59 characters at most) and, like every name here, must not start with a trigger.

  • tool — one of eslint, prettier, ruff, pyright, gofmt. It is declared, never guessed from the command: npm run lint does not say what it runs, and greengate needs to know what {cache} expands to and which version the gate really executes.

  • scope — the same column as a check's.

  • options — lowercase key=value tokens directly after attest:

    • cwd=<dir>: the directory the command runs in, relative to the repository root;
    • inputs=<path>,...: extra paths that belong to the gate's cache namespace.

    Paths are literal. A glob, an absolute path or a .. is refused. An uppercase NAME=value is not an option; it begins the command, so NODE_OPTIONS=… npm run lint is still expressible.

  • command — the exact command the CI step runs. {cache} is the only thing greengate may add, and it is allowed once, for eslint and prettier only. It expands to the tool's cache flags, which never change a verdict.

The command CI must run is the normalized declaration: {cache} removed, then a dangling trailing --, then whitespace collapsed. npm run lint -- {cache} becomes npm run lint. See the CI backstop for how the two are kept identical.

A tree line is trust-gated like every other line: until you trust the manifest, no tree gate runs. A pack may not carry one.

When a tree gate runs, and what it proves

At commit, a tree gate starts beside the pre-commit checks. It gets at most greengate.treeLintSlack seconds (default 2) after those checks finish. It starts only when its cache is warm: a full run already completed in the gate's current namespace. The namespace is a hash of:

  • the command;
  • the version of the tool it runs;
  • every lockfile and config-like file (*.json, *.toml, *.yaml, *config*, .*rc*, .*ignore, by basename);
  • the gate's inputs=.

A plugin upgrade therefore starts a new, cold namespace, and the old cache is deleted. A warm gate also has to fit. greengate remembers how long each gate's last run took, and how long the repository's own declared commit checks took. When nothing long is in scope, as on a docs-only commit where no test run covers it, a gate that would outlast the slack is skipped, not started and cancelled: the commit stays fast, and CI lints. It shows up as slow in the evidence. A cold gate does not slow the commit either: greengate starts greengate warm --worker in the background (log: .git/greengate-warm.log), and the next commit can prove it. greengate warm does the same in the foreground. There is no background warm-up on Windows, where tree gates do not run at all.

When it passes on exactly the committed tree, the commit and its tree are stamped tree:<name>. The push then attests tree-<name>, and CI skips its step. No gate starts, and nothing is stamped, when:

  • tracked files have unstaged edits;
  • an untracked file is present;
  • an ignored file is present outside snapshotPrepareOutputs, which admits tool caches (node_modules/, .venv/, __pycache__/, …) by default. Add the repository's own reproducible outputs, the ones CI recreates too, with set snapshotPrepareOutputs build/ .react-router/;
  • a merge, rebase, cherry-pick or revert is in progress.

A failing, slow or cancelled gate never blocks: it prints one line, and CI lints.

Letting a check fix what it finds

Prefix the command with fix and the check may rewrite files, with whatever it changed re-staged:

pre-commit  format  *.js  block  fix npx prettier --write

Two conditions, both deliberate:

  • Off unless you ask. git config greengate.fix true, per repository — and the consequence is worth stating in bold: with greengate.fix off, a fix-declared check does not run at all, not even in check-only mode. It reports "not run" (a warn, never a block) on every commit, because the one command you declared is a rewriting command and running it would edit files nobody asked to have edited. A team that commits a fix declaration gets zero enforcement from every member who has not personally opted in — if you need the check to always judge, declare a second, non-fix line with the tool's check mode. A hook that edits your files without being asked is a larger surprise than one that complains.
  • pre-commit only. fix on a pre-push line is a parse error, reported on every commit like any other bad line. A pre-push hook must not modify the worktree or index: the pushed commit would then differ from the tree you are looking at.

Re-staging is safe because the pre-commit stage holds your unstaged changes aside first, so the tree contains what you staged and nothing else — anything a formatter touches is by definition part of this commit. Work you deliberately kept back is never swept in.

The built-in prettier check does this too, under the same greengate.fix gate.

Turning one off

Exactly as for a built-in:

git config hook.skip lint-shell                 # do not run it
git config greengate.severity.lint-shell warn    # run it, do not let it block

Both surfaces read the same three names, and nothing matches by substring: the full id (pre-commit-lint-shell), the short name (lint-shell, on either trigger), and the trigger (pre-commit, meaning all of them). Three exact comparisons, in runtime::names_check — hook.skip = e reaches nothing at all, and skipping lint-js leaves lint-json-yaml alone.

Prefer the severity downgrade anyway. The two do different things:

runsreportsblocks
greengate.severity.<key> warnyesyesno
hook.skip <key>nono (only that it was skipped)no

A downgrade keeps the check working and keeps you looking at what it finds; you have decided the finding should not stop a commit, not that you no longer want to know. A skip removes the signal along with the block, so the problem it was watching for grows silently until somebody turns it back on. Reach for skip when a check is genuinely inapplicable to a repository, and for severity when it applies but should not be a gate.

Seeing what you declared

greengate list
pre-commit
  ● merge-conflict
  ● lint-shell (declared)
  ✗ oops (declared)            greengate.conf line 3: severity "LOUD" …
pre-push
  ● branch-protect
  ● smoke (declared)

  ● runs here   ○ inert   ⊘ skipped via hook.skip   ✗ declaration unusable

Across the fleet, greengate-fleet has a DECL column — 2 for two declared checks, 2!1 when one of them cannot run — and lists them per repository in the detail pane.

Shipping a check — packs

A check you wrote could always be run; until greengate add it could not be shared, except by pasting a line into somebody's manifest or upstreaming it into greengate itself.

A pack is any git repository with an greengate.pack at its root, written in exactly the syntax above:

# greengate-pack-java — Spotless for a JVM repository, Maven or Gradle
pre-commit  spotless-maven   *.java+pom.xml                        block  mvn -q spotless:check
pre-commit  spotless-gradle  *.java+build.gradle,build.gradle.kts  block  ./gradlew -q spotlessCheck
$ greengate add github:fredericrous/greengate-pack-java@v1.1.0
github:fredericrous/greengate-pack-java @ e72a544 declares:
    pre-commit  spotless-maven   *.java+pom.xml                        block  mvn -q spotless:check
    pre-commit  spotless-gradle  *.java+build.gradle,build.gradle.kts  block  ./gradlew -q spotlessCheck

greengate.conf changed — these commands cannot run until you review them:
    greengate trust

<source> is github:owner/repo, forgejo:host/owner/repo, or any git URL — including a local path, which is all a test fixture needs. --dry-run shows without writing.

That pack is real, and it is the worked example for everything below: fredericrous/greengate-pack-java. Its README is the long-form version of this section.

What ships is text, not execution

This is the whole design, and it is what separates it from the ecosystem model pre-commit built. pre-commit clones a repository and executes it, building an isolated environment per hook. greengate add copies rows into your greengate.conf, and stops:

  • the rows land between # greengate:pack:start / # greengate:pack:end markers with the pack's commit id, so what you got is recorded next to what you run (blocks written under the # amont:pack: markers before 4.3 are still read, and a re-add replaces one in place under the new markers);
  • the manifest's content changed, so its fingerprint no longer matches and every declared check — the pack's and your own — is inert until you trust it;
  • editing a vendored row by hand revokes consent exactly like editing any other line. A pack's rows are not privileged.

Adding a pack is therefore never the moment anything becomes runnable. It is a way to avoid typing.

Pinning, and what "verify" means here

@v2 is a tag, and a tag moves. greengate add resolves it with git ls-remote before fetching, then refuses whatever arrives unless it is that commit — so a ref that moves between the two steps is an error, not a surprise. The commit id, never the tag, is what gets written into your manifest.

That is also why the transport is git and not HTTP. greengate links no crates and has no TLS stack; git is already a hard dependency, it is content-addressed, and it brings SSH, private repositories and self-hosted forges with it for free.

Making a packaged check well-behaved

A pack's rows land in somebody else's repository, so gate them on that repository actually using the tool:

pre-commit  rubocop        *.rb+.rubocop.yml  block  rubocop
pre-commit  terraform-fmt  *.tf               block  terraform fmt -check

The first is inert in a Ruby repository with no rubocop config; the second needs no opt-in because a .tf file in the diff already says everything. Without that condition a pack is a promise to run somebody's linter on every matching file whether or not they configured it — which is how a useful pack becomes an uninstalled one.

What a pack may not carry

Checks, and nothing else. tool pins, severity, skip and set lines are refused, and the whole pack with them.

Those lines are policy about the repository installing the pack — see What a repository cannot do. A skip could silence your secrets scan; a set could raise your large-file ceiling. A third party proposing commands you will read is one thing; a third party quietly changing what your existing checks do is another, and the second is not on offer.

A pack is refused whole: one bad row and nothing is written, because a half-applied pack is a manifest neither side asked for.

Publishing one

A pack repository is the greengate.pack and nothing else — no schema to satisfy, no registry to join, no build step. The example above is three files, and two of them are the README and the licence:

greengate-pack-java/
├── greengate.pack
├── README.md
└── LICENSE

Test it before it goes anywhere. A local path is a source, so the whole loop is:

greengate add ../my-pack --dry-run

Then tag it, and let people pin the tag:

git tag v1.0.0 && git push origin v1.0.0
git tag -f v1 && git push -f origin v1     # moving major alias, optional

A moving alias is safe here in a way it is not for a CI action, because what lands in a consumer's manifest is the commit id and never the tag: @v1 resolves once, at install time, and then stops moving. The cost of that is that a consumer does not get your fixes by pulling — they get them by running greengate add again, which is also a fresh greengate trust. That is the trade the whole design makes, and it is the right way round: nothing you publish later can start running on somebody's machine without them reading it first.

Updating and removing

greengate add the same source again and its block is replaced — not appended, which would declare the same id twice and break the manifest. To remove a pack, delete its block; it is plain text, and the markers say where it ends.

Why this format and not TOML

TOML would be nicer to write and costs a dependency tree that would then run on every commit in ninety-six repositories. For four fields and a command, twenty lines of std parsing wins. See scripts/check-no-deps.sh for the reasoning behind that default; it is a judgement about the commit path's supply chain, not a prohibition, and a genuinely rich format would be worth reopening it for.

Ideas, not a roadmap

Nothing here is planned, promised, or assigned. Ideas are kept with their objections attached, because a rejected-for-now idea with its reason is more useful than a list that quietly loses the ones somebody already thought about.

Already landed

  • Lint more languages. Python (ruff, pyright), Rust (cargo fmt, clippy, cargo test), YAML (yamllint) and Kubernetes (kubeconform, kube-linter, Argo) all have checks now. See the checks.
  • A repository declaring its own checks, which was the general answer to most of the "add a hook for X" requests: greengate.conf means a check that belongs to one repository does not need to be in everybody's binary. See custom checks.

Still open

  • post-commit: tag automatically when the package version is bumped. Noted at the time as possibly harmful depending on your CD workflow, and that objection has if anything got stronger: a tag that triggers a publish should not be created by a hook nobody invoked deliberately.
  • pre-commit: check the other lockfiles — Gemfile.lock, Pipfile.lock, Cargo.lock, composer.lock — the way pre-commit-package-lock already does for npm.
  • pre-commit: check you are committing with the usual GPG key. Same shape as pre-commit-usual-name. Flagged as possibly slow, which is the thing to measure before building it: this runs on every commit.
  • pre-push: require a JIRA id in the branch name. prepare-commit-msg already extracts one when it is there; requiring it is a different, more opinionated thing, and probably belongs in a repository's own greengate.conf rather than in the built-in branch-pattern.
  • pre-push: prevent a force-push to a remote branch with a different name. The original note asks "almost impossible?" and does not answer it.
  • commit-msg: a message alias — "." expanding to "(previous prefix): more on <previous subject>".
  • commit-msg: require a description of more than three words and a body of more than five. Word counts are a poor proxy for a meaningful message and are easy to satisfy meaninglessly; the current rules constrain shape (a type, a description, lengths) rather than trying to measure effort.

Out of scope

Functionality already covered by .gitattributes and .gitignore should not be reimplemented as a hook.

Before proposing one

Ask whether it belongs in the binary at all. A check that is right for your repository — a house lint, a schema check, a smoke test — can be declared in greengate.conf today, shared with your team by committing it, and skipped or downgraded by the same hook.skip and greengate.severity keys as any built-in — or by committed severity/skip policy lines in the same file. A built-in earns its place by being right for most repositories, and by being inert in the rest.

Everything in the commit path also has to be paid for in dependencies, which is to say: in nothing. See CONTRIBUTING.md.

How it compares

The field is good. pre-commit, lefthook and husky are all mature, widely used and worth your time. This page is what you get by choosing greengate instead — and what you give up.

At a glance

greengatepre-commitlefthookhusky
Runtime it needsnone — one binaryPython (hooks bring their own environments)none — one binaryNode.js — already present in the projects it targets
Useful before you write any config39 built-in checks, scoped to what the repo usesstarts emptystarts emptystarts empty
On the commit pathzero external crates, CI-enforcedPython + a managed environment per hookGo binaryNode + node_modules
A cloned repo's committed config runs code…only after you review it and greengate trustafter pre-commit install, unreviewedafter lefthook install — often automatic via a package postinstallafter npm install — the prepare script activates it
Your unstaged work during a runheld aside without git stash, restored even if a check panicsgit stash around the rununtouched — checks see the worktree, not the staged setyour problem — hooks are your scripts
Uninstallremoves exactly the five files it wrote, names everything elsepre-commit uninstalllefthook uninstalldelete .husky/, unset core.hooksPath
Commit-message conventionsbuilt in — validated, wrapped, limits and gitmoji configurablevia a separate hookvia commitlint etc.via commitlint etc.
One view across all your reposgreengate-fleet — bulk install, report, dashboardper repoper repoper repo
Machine-readable state for coding agentsgreengate list --json, greengate agents-mdnonono

The three arguments

It works before you configure it. Every other manager on this list installs a framework and hands you an empty file: nothing runs until you have decided what a good commit looks like and written it down, per repository, in that tool's YAML. greengate ships the decision — conventional commit subjects, no merge-conflict markers, no describe.only leftovers, the linters and formatters for the languages your repository actually uses, a test-suite gate on push — and scopes it automatically: a repository with no ruff.toml never needs ruff, a JavaScript repository never invokes cargo. What is left for you to configure is the exception, not the baseline, and every knob is plain git config.

The commit path is the smallest attack surface in the field. A hook manager runs on every commit, with your credentials, reading every staged file. husky puts node_modules on that path; pre-commit puts a tree of cloned hook repositories with their managed language environments there. The greengate binary links no external crates — std only, with a CI script that fails any build that changes it — and the installer verifies its download against published checksums before placing the binary. And where the others run a cloned repository's committed config as a side effect of routine setup — npm install, a postinstall, an unreviewed pre-commit install — greengate holds a repository's declared checks inert until you have read them and said greengate trust. Nobody else on this list has that gate.

It is built for the failure cases. What happens to your unstaged work when a formatter rewrites files mid-commit — and when it panics mid-rewrite? What happens when a check's tool is not installed, a config line is malformed, or a hook.skip was set three years ago and forgotten? greengate has a designed answer to each: unstaged work is held aside without git stash and restored even on panic; a check that cannot run is reported as a gap rather than passed or silently dropped; a skipped check is announced on every commit. These cases decide whether a hook manager is trusted or worked around, and most of this project's engineering lives there.

What the others do better

Stated plainly, because a comparison that finds no trade-offs is an advertisement:

  • pre-commit's ecosystem is enormous. Hundreds of ready-made hooks, and it bootstraps each hook's language environment for you. greengate deliberately refuses to be a package manager — a check that cannot find its tool warns or fails loudly, and the tool stays your problem. For turnkey environments around many exotic tools, pre-commit is the right call.
  • lefthook's config is very expressive — glob routing, piped commands, scripts, tags, per-OS overrides — where greengate.conf is deliberately five columns and no shell.
  • husky is nearly nothing, which is a real virtue: two lines of shell in a committed file and you are done. An all-Node team that reviews everything may never fall into the gaps husky leaves open.
  • The built-ins carry opinions — conventional commits, branch naming, a set of commit types. Every check can be downgraded or skipped with exact, announced config, and the commit-message rules are themselves tunable — but a blank slate is the one thing this tool is not.

Credit where due

Ideas taken from the others, with the full record in index fidelity and run modes:

  • From pre-commit: a repository declaring its own checks in a committed file, so a team shares a check by committing it rather than by each member installing it by hand — taken as greengate.conf, with a trust gate added in front, because a committed manifest is a committed command and cloning is not consent.
  • From all three: the observation that filename-prefixed .git/hooks/pre-commit-* scripts can never be shared, because .git/hooks is not committed.

Also in the neighbourhood: overcommit [Ruby], lint-staged, commitlint, devmoji, git-fancy-message-prefix.

Hook architecture: one Check trait

Status: shipped. PRs 1–3 below are done, and docs/rust-migration.md carried the result the rest of the way; what came after this document is index-fidelity-and-run-modes.md. Kept as the design record — the "what is wrong today" section describes the state before this landed, not the state now.

What is wrong today

Four tables keyed by check name, kept in step by reconciliation tests:

tablewhereholds
REGISTRYgreengate-runtime/registry.rsname → fn pointer
PRE_COMMIT_CHECKSsame fileorder, pre-commit
PRE_PUSH_CHECKSsame fileorder, pre-push
LANGUAGESgreengate-fleet/checks.rsname → language scope

Adding a check means editing three of them and writing a module. The tests that keep them aligned are good tests, but they exist to police a shape that should not be splittable in the first place.

Three entry-point signatures and eight differently-named entry points, reconciled by closures in the registry. The signatures are (&[OsString]), (&str, &[OsString]) and (&[PushRef]); the eight functions not called run are ruff, pyright, argo_lint, kube_linter, kubeconform, fmt, clippy and test.

Three shapes is not itself scandalous — the closures adapt them fine. It matters because a uniform signature is what lets a check be a value rather than a special case, and that is what makes an external check indistinguishable from a built-in to the dispatcher.

Two models of "does this apply here". Each check scopes itself internally from staged files and the nearest manifest; the dashboard separately infers applicability from root manifests, and checks.rs documents its own answer as an approximation. Two implementations of one question, one of which admits it is guessing.

No extension point at all. File-discovered sub-hooks were removed when checks moved in-process (they had two users in 96 repos). A third party now has no way to add a check without recompiling the binary.

Severity is implicit in a return value. Fifteen sites warn and then return 0. Those collapse two different situations, which is the finding that most changes this design — see below.

The pattern

One trait, two implementors. Strategy, with the metadata attached to the strategy rather than kept in a parallel table.

#![allow(unused)]
fn main() {
pub trait Check {
    fn name(&self) -> &str;
    fn stage(&self) -> Stage;          // PreCommit | PrePush
    fn scope(&self) -> Scope;          // declarative; see below
    fn severity(&self) -> Severity;    // Block | Warn
    fn run(&self, ctx: &Ctx) -> Outcome;
}
}
  • Builtin wraps a fn pointer. One const descriptor per check carries name, stage, scope and severity beside the function.
  • External runs a command declared in a committed manifest.

The dispatcher holds Vec<Box<dyn Check>> — built-ins in declared order, then externals — and stops caring which is which.

What this removes: four tables become one declaration per check, and the reconciliation tests become unnecessary rather than merely passing. That is the win. Three signatures and eight entry-point names become one shape. scope() becomes authoritative, so the dashboard asks the check instead of guessing, and the approximation caveat can be deleted rather than documented.

Outcome distinguishes three things a check can mean

#![allow(unused)]
fn main() {
pub enum Outcome {
    Passed,
    Failed,       // ran, found a problem
    Warned,       // ran, found something non-blocking
    Fixed,        // ran, found a problem, REPAIRED it
    Unavailable,  // COULD NOT RUN
}
}

There are FIVE. Fixed arrived with Fix::Rewrite (see docs/index-fidelity-and-run-modes.md §2): the check ran, found a problem, and repaired it, and the commit proceeds with the repair staged. That is neither Passed — something happened and the author's files changed, which they should be told — nor Failed, since nothing is blocking. Reachable only from a Stage::PreCommit declaration, which the compiler enforces: a pre-push hook must not modify the worktree or index, or the pushed commit would differ from the tree the developer is looking at.

Shipped without the detail / reason payloads the sketch carried. Every check already prints its own diagnosis at the moment it has the context to phrase it; threading the same string back for the dispatcher to print again produced two messages about one problem. The variant is the whole signal.

Failed is NOT Default — there is no Default, deliberately. It was Failed, to fill the slot of a check whose thread died, and check.rs records why that was removed:

Deliberately NO Default. It used to be Failed, to fill the slot of a check whose thread died — a real rule, but Default means "the neutral value" to every reader and to every #[derive(Default)] that might later contain one. The rule is now written where it applies, in the runner.

So the rule survives and only its location changed: dispatch::run_stage passes Outcome::Failed explicitly as the fill value, under a comment saying "a check whose thread died has not passed". Stated where the slot is filled, rather than hidden in a trait impl that any future #[derive(Default)] would silently inherit.

Unavailable is the important addition. Today ruff config found but no ruff/uvx binary prints a warning and returns 0, which is indistinguishable from ruff running clean — to the dispatcher, and to the dashboard. A repo where a check has silently never executed reads as a repo where it passes.

That is the same failure that hook.skip had before the dispatcher announced skipped checks, and it cost three PRs to notice there. Modelling it means the dashboard can show ran clean separately from never ran, which is the difference between a green fleet and an unverified one.

Classifying the fifteen sites turned up an ordering bug it would not otherwise have found. Three checks — yamllint, kube-linter, kubeconform — tested for their binary BEFORE testing whether the repo had opted in, so a repo that never wanted yamllint was told to install it, and under Outcome would have reported a gap it did not have. One repo in the fleet configures yamllint; the nag reached the other ninety-five. All three now test the opt-in first, and Unavailable means what it says: this repo asked for the check and the tool was missing.

One site was reclassified in the other direction. An unpinned uvx ruff prints a caveat about which ruff spoke — but it RAN, and a clean verdict from it is a pass. The caveat is advice, not a gap.

Severity is declared, and choosable

Block fails the stage; Warn reports and continues. It lives on the check, so a built-in and an external are governed the same way.

Two consequences worth stating:

Fail-fast applies only to Block. pre-push stops at the first failure because later steps are expensive and their preconditions are gone. A Warn check that finds something must not stop the chain — it has not invalidated anything.

A severity override is a better escape hatch than hook.skip. git config greengate.severity.<check> warn downgrades a check instead of disabling it. hook.skip is all-or-nothing and, as measured, invisible enough that a one-line config edit could disable everything unnoticed. A downgrade keeps the signal and removes only the block, which is what people usually want when they reach for --no-verify. I would ship this alongside, and expect it to become the common case.

Severity::parse and Severity::as_str are the ONE mapping between the configured words and the enum, and registry::effective_override is the one answer to "what will the dispatcher apply here". There were four of the former and two of the latter — the dashboard's copies being its PREDICTION of the dispatcher, which is the one thing it must never get wrong. It did: the dispatcher asks --get (last entry wins), the dashboard listed every entry from --get-regexp and treated each as authoritative, so a global warn overridden by a local block was reported as a live downgrade.

Shipped, with one property the sketch did not state: an unrecognised value falls back to the declared severity rather than to warn. Git validates nothing here, so a typo would otherwise be a silent disable — the exact failure this feature exists to replace.

And the dashboard has to show it. A downgrade is quieter than a skip: the check runs, prints its failure in red, and the commit passes. Nothing on screen distinguishes it from enforcement, so the fleet view carries a WARN column and a per-repo greengate.severity block. That block separates three cases a config line cannot: a real downgrade, an explicit block (the default written out), and a line that changes nothing because the check name or the value is misspelt.

Scope, declared rather than reimplemented

Scoping is a conjunction, not a choice between alternatives:

ruff       .py/.pyi     AND  ruff.toml | .ruff.toml | pyproject [tool.ruff]
yamllint   .yaml/.yml   AND  .yamllint.yaml | .yamllint.yml | .yamllint
prettier   js-ish       AND  .prettierrc | .prettierrc.json | …
clippy     .rs          AND  Cargo.toml

So it is a struct, not an enum:

#![allow(unused)]
fn main() {
pub struct Scope {
    /// Extensions that trigger it. Empty = any change.
    files: &'static [&'static str],
    /// Config paths that opt the repo in. Empty = always on.
    opt_in: &'static [&'static str],
}
}

An earlier draft made these alternatives — StagedFiles(..) or Manifest(..) — plus a Custom escape hatch for anything that fitted neither. That was wrong twice over. Neither variant expresses "both", so every check with an opt-in config would have fallen into Custom; an escape hatch that absorbs most of the set leaves the dashboard knowing nothing, which is precisely the guessing this trait exists to remove.

All twenty checks fit the struct. merge-conflict is files: [], opt_in: []. package-lock is files: [], opt_in: ["package.json"]. kube-linter — one of the cases Custom was invented for — reads repo-root .kube-linter*.yaml, which is just an opt_in entry.

Coarse declaration, precise execution

rust_tools resolves the NEAREST ancestor Cargo.toml, which no static declaration captures. Its Scope therefore says opt_in: ["Cargo.toml"], meaning "somewhere in this repo" — coarser than what the check enforces when it runs, and deliberately so.

That is safe because the two readers ask different questions. The dispatcher asks "does this apply to the staged files of this commit" and the check answers precisely, as it does today. The dashboard asks "would this ever fire here", for which the coarse answer is correct. One declaration, evaluated against staged files in one case and tracked files in the other.

Over-approximating is also the safe direction: showing a check as applicable when it happens not to fire for a given commit is a small inaccuracy, while Custom meant the dashboard could not answer at all.

External checks

A third party cannot add a Rust module without rebuilding the binary, so extension means declared commands.

The manifest is committed at the repo root, which is the point. .git/hooks is not committed, so a team could never share a custom hook — a worse flaw than the lexicographic ordering usually cited against the old filename-prefix mechanism.

# greengate.conf — stage  name        scope     severity  command
pre-commit        shellcheck  *.sh      block     scripts/lint-shell.sh
pre-push          smoke       *         warn      make smoke

Whitespace-delimited, order of file, ~20 lines of std parsing. Full reference in custom-checks.md.

Three rules the sketch left open, all decided the same way — by asking what a committed text file should be able to do to a hook chain:

  • A built-in's name is refused. An external calling itself pre-push-branch-protect would either shadow the built-in or silently lose to it.
  • A duplicate ID is refused — the same name on two triggers is two checks and both run; the same name twice on one trigger is the clash. It could be addressed by neither hook.skip nor a severity override, so it would run anonymously.
  • A line that cannot be parsed is not skipped. It becomes a check that runs to Unavailable and says which line and why, appearing in the same "could not run" roll-up as a missing binary. Dropping it silently would mean a check somebody committed months ago has never run and nothing ever said so.

On the format: this is a judgement, not a constraint. The dependency guard (scripts/check-no-deps.sh) is a strong default about the commit path's supply chain, not a prohibition — see its comment. TOML would be nicer to write and costs a dependency tree running on every commit in 96 repos. For four fields I take the twenty lines; for a genuinely rich format the trade is worth reopening.

Externals run after built-ins, and cannot be reordered ahead of them: a third-party command should not be able to delay branch-protect.

Developer experience

  • greengate list — every check, stage, scope, severity, and whether it would run here. Externals are listed too, marked (declared), and a line that could not be parsed gets its own glyph: correctly-inert, disabled, and unusable are three different things and none may look like another.
  • Adding a built-in: one module plus one descriptor; the compiler names what is missing.
  • Adding an external: edit a committed file, no rebuild.
  • greengate-fleet gains third-party checks in its views, which it cannot see today at all.

Named future: greengate explain <check>

Not built. It was in the list above, among shipped DX, which made "why didn't prettier run" look like a question the tool answers.

Half of it exists: greengate list says whether a check would run HERE and why not — inert, skipped, or an unusable declaration, as three distinct glyphs. What is missing is the other half, the retrospective one: why a check did or did not fire on the commit you just made. Today that is a code-reading exercise.

Migration

PR 1 — the trait, no behaviour change. All 19 modules and the dispatcher. High mechanical risk, no user-visible payoff, so it lands alone, proved inert by a differential over hook output rather than by the test suite (tests will legitimately change shape).

PR 2 — Outcome and Severity. DONE. The 15 warn-and-return-0 sites are classified one at a time: 12 Unavailable, 2 Warned (a waived-past lockfile, a first-time author identity), 1 left Passed (unpinned ruff, which ran). Config override shipped. Dashboard shows downgrades apart from enforcement.

PR 3 — external checks. DONE. Manifest, parser, External, greengate list, and the fleet views. Two things the sketch did not anticipate:

Scope had to gate externals at RUN time. For a built-in it is a declaration the dashboard reads, because the check enforces its own scope in its first three lines. A declared command cannot — it has no idea what was staged — so without a gate here *.sh would have run on every commit and the column would have been decoration. Which files it is judged against depends on the stage: what is staged for a commit, what is in the range being pushed for a push.

Parsing had to be split in two. External holds a Scope, whose &'static slices are leaked; that is fine in a hook process which reads one manifest and exits, and wrong in a dashboard that reads ninety-six and may re-read them on every refresh. parse_lines returns owned Lines and only External::from leaks, with a test pinning the two to the same answers.

What came next

Built, in docs/: this document's plan shipped as #57–#67. The comparison against pre-commit, lefthook and husky that followed is index-fidelity-and-run-modes.md — four ideas worth taking, one refused on the record, and one correctness gap this document did not notice.

Open decisions

  1. Does Custom scope survive? RESOLVED: no, and the question was better than it looked. Checking what the checks actually key on showed the Scope enum modelled alternatives where the truth is a conjunction, so Custom would have swallowed most of the set rather than the one case it was written for. Scope is a struct now and every check fits it.
  2. Can an external check be Block at all? Decided: yes, severity is on the trait and the author chooses. Worth revisiting if a repo ever ships a hostile or flaky one. 2b. Can an external run before a built-in? RESOLVED: no, and not configurably. Externals are appended to each stage.
  3. Does greengate list belong in the hook binary or the fleet tool? The fleet tool has the nicer output; the hook binary is what is installed everywhere.

Index fidelity, fixes, and run modes

Status: mostly shipped. This began as a specification and said so — "Nothing here is built" — and stayed saying it for six sections after five of them landed. README links here twice as the authority on trust and on run modes, so a reader was being sent to a design document for an answer about behaviour they already had.

§whatstatuswhere it lives
0activation, uninstall, bulk installshippedinstall.rs, greengate-fleet install/uninstall
0bmanifest trustshippedtrust.rs, greengate trust [--show]
1index fidelity (staged-only)shippedstaged_only.rs, dispatch::pre_commit
2stage_fixedshipped as Fix::Rewrite + Outcome::Fixedcheck.rs, hooks/common.rs::restage
3not_during git-state conditionsshippedcheck.rs::GitState, registry.rs::MID_OPERATION
4greengate run [--all-files]shippedmain.rs, dispatch::run_named
4bgreengate check <paths…>shippedcontent.rs, finding.rs
5shebang detectionnot built—

§5 is the only one still a proposal. Everything below the numbered sections — What we are not taking and What this does not solve — is unchanged and still current: those are refusals and known gaps, not a backlog.

The prose in each section is kept in its original tense, because the argument for a thing is worth more than a description of it, and rewriting the reasoning into the past tense would lose why each decision went the way it did. Where the implementation ended up somewhere other than where the design pointed, that is called out in the section itself rather than quietly edited away.

Read against pre-commit, lefthook and husky, then re-read as somebody who would have to get this through an adoption review. Four of their ideas are worth taking, one is worth refusing on the record, the first is not a missing feature at all — it is a correctness gap we have been describing as a trade-off — and before any of them there is a trust problem that has nothing to do with the three tools and everything to do with a decision we already shipped.

The last two sections are the ones an adoption review reads first: What we are not taking and What this does not solve. The second is a list of honest noes — pinned tool versions, CI enforcement, DCO — and it is deliberately not a backlog.


0. A cloned repository can run its own commands

Shipped. Per-repository activation is the default; greengate install / uninstall and greengate-fleet install / uninstall are all real verbs. install.rs carries the routine, and crates/greengate/tests/it/ install.rs and crates/greengate-fleet/tests/it/uninstall.rs carry the guards. uninstall also removes the shims from the template directory and says so loudly if init.templateDir is still set.

greengate.conf is committed, which is the point: a team shares a check by committing it. The consequence had not been written down.

git clone seeds .git/hooks from init.templateDir, so a fresh clone arrives with our shims already installed. The manifest is then read from that repository and its commands are executed. No prompt, no trust decision:

$ git clone hostile victim && cd victim
  hooks present after clone: commit-msg post-commit pre-commit pre-push prepare-commit-msg
$ git commit -m "feat: an innocent commit"
  >>> arbitrary code from the cloned repo <<<

Cloning a repository and committing to it is not an act of trust that anyone performs deliberately. Reviewing a diff before running it is; nothing here asks for that.

pre-commit has the same property. That is not a defence — it is a decade-old known quantity with an ecosystem that has argued about it in public, and ours is undocumented. docs/custom-checks.md presents externals purely as a convenience. §2 of this document then proposes stage_fixed, which upgrades the primitive from run a command to run a command that rewrites my files and stages the result, and that must not ship into an untrusted manifest.

Where the exposure actually comes from

Not from the manifest, and not from the shims. From one line in our own README:

git config --global init.templatedir ~/.config/git/git-templates/templates

We never set that key in code — greengate install writes files and touches no config. The README asks the user to make every future clone on the machine managed, and that ambient grant is what turns a committed manifest into a drive-by.

It also quietly undermines the fleet's own model. managed vs unmanaged is supposed to be a decision the dashboard reports; with init.templateDir set, everything cloned since is managed and "unmanaged" means "cloned before I configured this". A category that records the date you ran a git config command is not a category.

The design: activation is the boundary, and templateDir opts out of it

Two modes, both supported, and the difference is what you granted.

Per repository is the default. Hooks run where somebody put them and nowhere else:

greengate install              # this repo
greengate uninstall            # this repo — remove shims, leave the binary
greengate-fleet install        # every managed-eligible repo under a root
greengate-fleet uninstall

greengate install already does the per-repo half. greengate-fleet has scan, fix and tui, with --apply behind fix — bulk activation exists but is named after repair rather than intent, which is why nobody reaches for it when they mean "set this up".

A clone is then inert until asked. The drive-by case is gone, not mitigated: there is no hook to run.

Everywhere is init.templateDir, and it stays supported as a deliberate opt-in rather than being removed. Git copies the template into .git/hooks on every init and every clone, so hooks are never forgotten and the fleet never shows an uncovered repository. That is a real benefit and people who want it should be able to say so.

What matters is that setting it is a standing grant, made once, for every repository you will ever clone — and it therefore opts out of activation being the trust boundary. It cannot be otherwise: the whole point of the key is that nobody is asked again.

So the honest statement is a conditional, and the README now carries it:

modewho decides a repo runs hookswhat closes the drive-by case
per repositoryyou, per repositoryactivation itself
init.templateDiryou, once, for all future clonesonly manifest trust

That is not an argument against the key. It is an argument that §0b is not a second layer of defence for the people most likely to set it — it is the only one — which raises its priority rather than lowering it.

It is necessary and not sufficient

Worth being precise, because it is tempting to stop here.

Explicit installation removes the case where you clone something to read it. It does not remove the case that matters most in open source: you clone a stranger's repository because you intend to contribute, you run greengate install because you want your own checks while you work, and their greengate.conf runs on your first commit.

greengate install means I want my hooks here. It does not mean I have read this repository's committed commands and accept them. Those are two different grants and only one of them was made.

So: one prompt, at the moment of the deliberate act

Shipped — this is §0b. crates/greengate-runtime/src/trust.rs, surfaced as greengate trust and greengate trust --show, with greengate install offering it interactively. The record is keyed on the manifest's CONTENT (via git hash-object, because the binary links no crates and std's only hash is a fixed-key SipHash a crafted manifest could collide), so a git pull that adds a command does not inherit consent given to the file before it. crates/greengate/tests/it/trust_display.rs.

Which is where activation-as-the-boundary improves on the direnv design rather than replacing it. direnv must prompt lazily, on cd, because there is no install step to hang the question from. We have one:

$ greengate install
  ✓ installed /Users/me/.local/bin/amont
  ✓ baked 4 shims into .git/hooks

  ⚠ greengate.conf declares 2 checks that would run on your commits:
      shellcheck  pre-commit  *.sh  block  scripts/lint-shell.sh
      smoke       pre-push    *     warn   make smoke
    Trust them? [y/N]

One question, asked once, at a moment the user is already thinking about this repository. Declining still installs the built-ins — the manifest simply stays untrusted, and reports as Unavailable with a reason rather than being silently skipped:

⚠ greengate.conf declares 2 checks and is not trusted here — `greengate trust`
⚠ 2 check(s) could not run: shellcheck, smoke

Trust records a hash of the file in git config, so a later edit re-arms it — manifest changed since you trusted it — and a git pull that adds a command cannot inherit the consent given to the file before it.

What none of this fixes

A built-in check still runs tool binaries the repository can influence: resolve_tool prefers <root>/node_modules/.bin/<tool>, so a hostile node_modules is executed by prettier or eslint with no manifest involved and no trust prompt to decline. That is inherent to running a repository's own toolchain — the same exposure npm install already carries — but it means both halves above are a floor, not a ceiling, and the README should say so rather than implying the manifest was the only door.

The cost of the per-repository mode, and why the fleet absorbs it

Not setting init.templateDir means a fresh clone has no checks at all until somebody installs them. For a codebase whose whole argument is do not look protected when you are not, that deserves stating rather than burying: the failure mode moves from "a hostile repo ran code" to "my repo was never covered", and the second is quieter.

It is also the failure the fleet dashboard already exists to catch — and this is what makes the unmanaged column earn its place. With init.templateDir set it is close to noise, because everything cloned since is managed and "unmanaged" records the date you ran a git config command. Without it, the column is the point of the tool: which of your ninety-six repositories are not covered, with greengate-fleet install as the fix.

Both modes are legitimate. They trade a quiet failure for a loud grant, and the tool should let you pick which one you would rather explain.

uninstall, which is missing regardless

We can disable a check (hook.skip), downgrade one (greengate.severity) and install everything. There is no supported way to take it off — a user who wants out deletes five files by hand and leaves a stale binary in ~/.local/bin.

uninstall at both levels, and it must be honest about what it removes: shims yes, the binary only when asked, hook.skip/severity config never, since those are the user's statements about their own repository and not our artefacts.

Ordering

This lands before stage_fixed, and arguably before anything else here. It is the only item on the list that is a security property rather than a correctness or ergonomics one.

The two halves can ship separately and in this order: activation and uninstall first, which is a README change plus two verbs and closes the drive-by case on its own; then the trust prompt, which needs the install flow to hang from and is much smaller once it exists.


1. We name the staged files and then read the unstaged ones

Shipped, as crates/greengate-runtime/src/staged_only.rs, wrapped around the whole pre-commit check stage in dispatch::pre_commit. The mechanism is NOT the one designed below — see The design and The danger for what changed and why. crates/greengate/tests/ index_fidelity.rs is its suite, including the Ctrl-C case.

staged_files() asks the index for the path list, which is right:

#![allow(unused)]
fn main() {
git::stdout(&["diff", "--diff-filter=d", "--cached", "--name-only"])
}

Those paths are then handed to a tool that opens them from the working tree:

#![allow(unused)]
fn main() {
pub fn run(root: &str, argv: &[String], extra: &[String]) -> bool
// …cmd.args(extra).current_dir(root)   ← `extra` is the path list; the tool reads the file
}

So a partially-staged file is judged by content that is not being committed. git add -p half of a.js, commit, and prettier reads the whole working-tree file: it fails on lines you did not stage, or passes on lines you did.

This is systemic, not local. Of the fifteen pre-commit checks:

checkshow
reads the tree — affected11prettier, lint-js, lint-json-yaml, yamllint, ruff, pyright, argo-lint, kube-linter, kubeconform, cargo-fmt, clippy
reads the index — correct2merge-conflict (git grep --cached), ban-terms (git show :<file>)
reads no file content2package-lock (path names only), usual-name

We already have the technique. ban_terms selects candidates with git diff --cached and then reads each one with git show :<file> — the index blob, never the tree. The two checks that get this right are the two that were ported most carefully, which is a hint about the other eleven rather than a coincidence.

That suggests a second possible fix, and it is worth saying why it is not the one to take. git show :<file> is enough when a check only needs CONTENT, which is why it works for ban-terms. It is not enough for a tool invoked on a path: prettier resolves its config by walking up from the file, kubeconform needs the kustomization directory around it, and ruff needs the file to sit where its pyproject.toml can be found. Feeding those a temp file changes their answer. The stash puts the right content at the right path, which is the only fix that serves all eleven.

pre-push has the same bug, from the other end

pre-push has no index at all, so this looks like a pre-commit problem. It is not. rust_tools::test and run_tests::run compute the changed file set from the pushed refs — correct, that is what is being pushed — and then run the suite with current_dir(dir), i.e. against the working tree:

#![allow(unused)]
fn main() {
let changed = crate::pushrefs::changed_files(refs);   // what you are pushing
let roots = cargo_roots(&root, changed.iter()…);      // where to run
each_root(&roots, None, &["test", …])                 // runs in the WORKING TREE
}

So the suite can pass on an uncommitted fix, or fail on an uncommitted experiment, and in neither case has it tested the commits being pushed.

The fix is not the same one. Stashing is wrong here: a push is not a staging operation, and the honest question is "does the pushed tree pass", which means running against the pushed commit — a worktree or git archive of the tip rather than the developer's tree. That is more expensive and wants its own decision, which is why it is named here and scheduled separately rather than folded into the stash work.

rust_tools.rs:149 calls it out and then accepts it:

Note this inspects the WORKING TREE, not the index, so a partially-staged file is judged by its unstaged form too. Same trade-off cargo fmt gives everyone; scoping it to staged paths would need the edition resolved by hand.

The first sentence is true of all eleven. The second is the mistake: it is not a trade-off cargo fmt gives everyone, it is one pre-commit removes for everyone. Their wording is worth quoting because it names both failure directions:

Running hooks on unstaged changes can lead to both false-positives and false-negatives during committing. pre-commit only runs on the staged contents of files by temporarily stashing the unstaged changes while running hooks.

The design

A guard around the whole pre-commit stage, not per check. Per-check stashing is wrong: twenty checks run concurrently and would fight over one working tree. It belongs around the whole fan-out.

That much shipped unchanged. The mechanism did not, and the difference is the most important thing on this page, because the design below said git stash --keep-index and the implementation refused it — twice.

#![allow(unused)]
fn main() {
// WHAT WAS SPECIFIED, and is not what runs:
struct StagedOnly { stash: Option<StashRef> }   // `git stash --keep-index`
}
#![allow(unused)]
fn main() {
// WHAT SHIPS — crates/greengate-runtime/src/staged_only.rs
pub struct StagedOnly { held: bool }
impl StagedOnly {
    pub fn enter() -> Result<StagedOnly, String>;
}
impl Drop for StagedOnly { /* restore, ALWAYS */ }
}

Saving is the easy half; restoring is the whole problem, and both stash-shaped mechanisms failed it:

  • git stash --keep-index was tried first. stash pop MERGES into a tree that already holds the staged content, so it writes conflict markers into the author's file. Measured, not predicted.
  • git diff + git apply was tried second — deterministic on Unix, and what pre-commit itself does. But it applies PATCH semantics to text, and Git for Windows converts line endings by default. Every restore test failed on Windows and passed everywhere else, which is the worst possible shape for the one routine here that can lose somebody's work.

So: byte-exact copies. Read the file, put it back. No patch to apply, no newline policy to agree about, and binary files need no special case. It costs a temporary copy of only the files that have unstaged changes.

The store is $GIT_DIR/greengate-held/, and its layout is itself the result of an incident:

$GIT_DIR/greengate-held/
  index              NUL-delimited, one record per parked path:
                     format tag, then kind + path + (mode | symlink target)
  files/<rel>        the payloads, byte for byte

Metadata used to be encoded in the payload FILENAMES — <name>.amont-absent, <name>.amont-symlink beside the copies — and a repository is allowed to contain files with those names. A repo tracking both notes and a modified notes.amont-absent had notes DELETED from the working tree on restore, because a suffix strip turned one file's payload into a statement about another. The symlink form was worse: the repo chose both the link name and an arbitrary absolute target, so committing in it planted a symlink pointing anywhere on the machine. Escaping cannot fix it, because greengate restore runs in a later process with only the filenames to go on. So the metadata moved out of band into index, and everything repo-controlled moved under files/, where it cannot collide with index whatever it is called. The index carries each entry's KIND (modified / absent / symlink) and, for a modified file, its working-tree FILE MODE — without which an unstaged chmod +x deploy.sh came back non-executable, invisible to every content-based assertion.

The danger, stated plainly

A stash that is taken and not restored loses uncommitted work. That is a worse failure than any this repository has had, including the two that overwrote tracked files, because there is nothing on disk to recover from.

Rules, all of which wanted tests and all of which now have them, in crates/greengate/tests/it/index_fidelity.rs and the commit flow (crates/greengate/tests/it/flows/commit.rs):

  • Nothing unstaged → do nothing, and silently. The common case must not touch the tree, and it is not a degraded run — there is no unstaged content for a check to be confused by.
  • Restore in Drop, so a panicking check (which we catch — #64) and an early return both restore. Drop runs on unwind.
  • Drop does not run on a signal, and that is the likely case. Ctrl-C during a slow pre-commit — eslint over a large tree, a cold cargo fmt — kills the process without unwinding, and the parked work is orphaned. An interrupt is the most probable route to losing work, not the least, so StagedOnly installs a SIGINT/SIGTERM handler that restores and then dies BY the signal. Restoring from a thread of its own rather than from the interrupted call stack introduced a race with enter(), which ENTER_LOCK closes; the test that found it is ctrl_c_mid_run_still_restores_and_dies_by_the_signal. Windows has the same net via SetConsoleCtrlHandler (Ctrl-C, Ctrl-Break, console closed) — the handler already runs on its own thread there, restores under the same lock, and then lets the default action terminate.
  • A recovery path for when even that fails: greengate restore puts back what this tool parked. Belt and braces, because the handler can itself be interrupted.
  • Restore failure is fatal and loud: print the STORE'S PATH, do not swallow it, block the commit. Not git stash list — nothing here is a stash ref, so the work is findable as files on disk under $GIT_DIR/greengate-held/.
  • Never park when the tree is already mid-operation — merge, rebase, cherry-pick. §3's GitState predicate is what answers this, which is why it landed first.
  • Conflicted paths abort the stage rather than being worked around. This is now true, and it was not for a while. StagedOnly::enter tests for unmerged paths FIRST and returns an Err that dispatch::pre_commit turns into a printed message and Verdict::Block; the conflict test comes before the mid-operation test deliberately, because the other order made an ordinary conflicted merge take the mid-operation branch and warn instead of aborting. It is safe by construction: git itself refuses a commit with unmerged entries, so nothing that would have succeeded now fails.

Reproduced

$ git show :x.json      # staged:      {"a": 2}       ← valid
$ cat x.json            # working tree: { THIS IS NOT JSON
$ greengate pre-commit
  ✗ Invalid JSON: x.json
  🚨 Error raised by: pre-commit-lint-json-yaml

The commit that was about to be made is valid. The hook blocked it anyway. This is now a test rather than a transcript.

Decision

cargo fmt joins staged-only mode. Its scope is a crate, not a file list, but that is exactly why the stage-level guard is the right fix: once unstaged changes are held aside, cargo fmt --check sees staged content at the normal crate paths and still resolves the manifest, edition and rustfmt config the same way it does today. The misleading comment in rust_tools.rs should be deleted when this lands; the trade-off was an implementation gap, not an inherent cargo constraint.

Done. rust_tools.rs now records the correction in place of the claim.


Writes that land while the checks run

Two kinds of process write to the tree during the hold, and they are treated differently:

  • An editor save is work. The restore compares each held file against the content the checkout put there; a file that changed mid-run is KEPT, and the held (pre-commit unstaged) version is parked in $GIT_DIR/greengate-preserved/ with a printed pointer. Before this guard existed, the restore overwrote the save silently — the one way this module could destroy something.
  • A fixer (greengate.fix true) rewrites held files as its job, and telling its writes apart from an editor's is not possible from inside the restore. With fixing on, the guard stands down and the documented contract holds unchanged: the tree returns to your unstaged version, the fix lives in the index. greengate.fix is an explicit opt-in; the guard protects everyone else.

The checkout that starts the hold is also scoped to exactly the held paths (spelled :(literal) — a file named *.rs is a name, not a glob), so a dirty commit costs git a walk of the changed files, not of the whole tree.

2. stage_fixed — a formatter that fixes should re-stage

Shipped, under different names: the declaration is Fix::Rewrite on a check in registry.rs, the opt-in is git config greengate.fix true, the re-staging is hooks::common::restage, and the result is Outcome::Fixed. Three checks declare it — prettier, ruff and cargo-fmt — and all three now genuinely repair; two of them declared the fix for a while without having any fixing code, which greengate list --json reported to agents as a capability. crates/greengate/tests/it/fixing.rs.

From lefthook's job options: "automatically add modified files back to git staging".

Three of our checks currently print an instruction and stop:

✗ Prettier found unformatted files. Run prettier --write on:

You then run the command yourself and commit again. lefthook's users run prettier --write in the hook and get the result staged.

This depends on §0 and §1, and must not ship before either. An untrusted manifest that can rewrite files and stage the result is a worse primitive than one that can only run a command, so the trust model is a hard precondition, not an ordering preference.

On §1: Without the stash, "re-stage what the formatter touched" re-stages unstaged work the author deliberately kept back. With the stash in place, the tree contains exactly the staged content, so anything the formatter changed is by definition part of this commit.

The design

Opt-in per check, declared, not global:

#![allow(unused)]
fn main() {
pub enum Fix {
    /// Reports only. Every check today.
    None,
    /// A command that rewrites files, and whose result should be staged.
    Rewrite { argv: fn(&Ctx) -> Vec<String> },
}
}

Enabled by config, off by default — git config greengate.fix true — because a hook that edits your files without being asked is a bigger surprise than one that complains. Reported as a new Outcome::Fixed, which is neither Passed (something happened) nor Failed (the commit proceeds).

Candidates: prettier (--write), ruff (format + check --fix), cargo fmt. Not eslint --fix: its fixes are semantic and occasionally wrong.


3. Declared skip conditions, replacing one ad-hoc guard

Shipped. check::GitState with the five states, Scope::not_during, and registry::MID_OPERATION as the shared set applied to the checks that need it. lib.rs::git_states_in_progress does the detection and dispatch.rs consults it for BOTH stages, closing the pre-push gap the section names. crates/greengate/tests/it/git_state.rs.

lefthook:

pre-commit:
  commands:
    lint:
      skip: [merge, rebase]

and skip: {ref: main}, and skip: {run: test "$NO_HOOK" -eq 1}.

We have exactly one of these, hard-coded, in one dispatcher:

#![allow(unused)]
fn main() {
// dispatch.rs
if cherry_pick_in_progress(ctx.hooks_dir) { return Verdict::Proceed; }
// …and, twelve lines down:
// NB: no CHERRY_PICK_HEAD check here — the zsh pre-push had none either.
}

That comment is an admission: pre-push has no such guard because the shell version had none, which is history rather than a decision.

The design

Scope already declares when a check applies to files. This is the missing half — when it applies to repository state:

#![allow(unused)]
fn main() {
pub struct Scope {
    pub files: &'static [&'static str],
    pub opt_in: &'static [&'static str],
    /// Git operations during which this check does not run.
    pub not_during: &'static [GitState],   // Merge | Rebase | CherryPick | Revert | Bisect
}
}

Detected from the files git writes into $GIT_DIR: MERGE_HEAD, rebase-merge//rebase-apply/, CHERRY_PICK_HEAD, REVERT_HEAD, BISECT_LOG. Not REBASE_HEAD: git leaves that one behind after rebase --continue finishes, so it says a rebase happened rather than that one is happening, and reading it paused every push gate forever in a worktree that had once hit a conflict. cherry_pick_in_progress becomes one arm of that, and its hard-won comment about parent() being lexical while join("..") is not moves with it.

Only not_during, not lefthook's full set. ref: conditions duplicate hook.skip, which is already per-repo and already visible in the dashboard; run: conditions are a shell escape hatch in a design that has deliberately refused shells (see greengate.conf). Taking the useful third is not a failure to copy the other two.


4. greengate run [--all-files]

Shipped, exactly as specified, plus --hooks-dir. greengate run, greengate run --all-files, greengate run <check>. crates/greengate/tests/it/run_mode.rs.

pre-commit run --all-files runs every hook over the whole repository rather than the staged set. Two uses, both of which we currently cannot serve:

  • Adopting a check in an existing repo — you want to know how big the mess is before you turn it on, and git add . is not an acceptable way to find out.
  • CI parity — running the same checks in CI over the whole tree.

We have greengate list (would it run here?) and greengate <check> (run one, staged). We have no "run everything, over everything".

Scope::matches already answers against an arbitrary path list, so the file selection is done. The work is:

greengate run                 # every applicable check, staged files (what a commit does)
greengate run --all-files     # …over `git ls-files` instead
greengate run <check>         # one check, either way

--all-files skips the §1 stash: there is no staged/unstaged distinction to protect when the answer is "all of it".


4b. greengate check <paths…> — the read that is not a rehearsal

Shipped. crates/greengate/tests/it/check_verb.rs, greengate-runtime/src/content.rs, greengate-runtime/src/finding.rs.

run answers "is this commit ready?" — a question about the index. It is entitled to everything in §1 and §2: the staged-only hold, the stash, the re-staging of fixes, and restore as the way back.

An editor asks a different question — "what is wrong with this buffer?" — and the buffer is not staged, may not match HEAD, and via --stdin-filename may never have been written to disk at all. Serving that from run would drag index fidelity into what is a read-only lookup, and an editor asking about a buffer would inherit a stash. So it is a separate verb with a separate contract:

greengate check src/app.js                          # a path
greengate check src/*.ts --format json              # several, structured
greengate check --stdin-filename src/app.js < buf   # a buffer never saved

It is a read. No index, no staging, no stash, no writes — checking_never_touches_the_index_or_the_worktree asserts the repository is byte-identical afterwards, index included.

Findings, and why positions had nowhere to live

Outcome has five variants and no payload — correct for git, which needs proceed-or-block, and the reason a report could only name the file:

✗ Unwanted terms found
  The following files contains 'debugger' in them:
  - app.js

The line was always known. ban_terms blanks comments and strings preserving length and line count precisely so offsets stay valid, and secrets::scan has always returned line numbers — there was simply nowhere to put them. Finding is that place, and the hooks improved on the way past:

✗ Unwanted terms found
  app.js:7:3 — 'debugger' is a banned term here

file:line:col: severity: message [check] is the output format because every editor's error parser already reads it and every modern terminal makes it clickable — which is what lets efm-langserver, nvim-lint, a VS Code problemMatcher or flycheck consume greengate with no editor-side code in this repository. --format json (greengate-check-v1) is there for anything that would rather not parse a line.

What is deliberately not in it

Only the checks that are about a file's content: ban-terms, secrets, merge-conflict, large-files. branch-pattern, branch-protect and pull-rebase are not about files; package-lock is about a relationship between two; and clippy, ruff and eslint already have editor integrations of their own that are better than anything proxied through here.

What remains is exactly the set docs/ci.md says CI deliberately does not reproduce — the checks only greengate has are the ones only greengate can surface early, which is the whole argument for the verb.

Positions are a reporting concern and never a decision input: a check decides pass or fail exactly as it did before, and a finding says where. Where a position cannot be pinned down — large-files is about the file, not a place in it — line is None and every renderer degrades to naming the file, which is what it did for everything until now.


5. Shebang detection

The one section still unbuilt. Scope::files is suffix-only today — matches() in check.rs calls path.ends_with(ext) and nothing reads a file head. Nothing is waiting on it; it is here because it is the gap greengate.conf inherits from Scope, not because it is next.

pre-commit classifies files with identify, which reads shebangs, so an extensionless scripts/deploy starting #!/bin/sh is a shell file.

Our Scope.files is suffix-only, and greengate.conf's *.sh inherits that — a repository whose scripts have no extension cannot scope an external check onto them at all.

Smallest useful version: Scope.files accepts a #! pattern.

#![allow(unused)]
fn main() {
Scope::files(&[".sh", "#!/bin/sh", "#!/usr/bin/env bash"])
}

Reading file heads costs an open per extensionless staged file, so it happens only when a scope actually asks for a shebang, and only for files with no matching suffix.

Lowest value on this list. Listed because it is the gap our own manifest format inherits, not because anything is waiting on it.


What we are not taking, and why

core.hooksPath (husky). Husky sets one config key and ships no per-repo hook files. Our entire drift model — greengate-fleet apply, BakeState, the SHIMS column, recover_baked — exists because we copy five files into ninety-six repositories. A global core.hooksPath deletes that problem class outright.

Refused, and the reason matters more than the refusal: core.hooksPath is all-or-nothing per repository. "Managed vs unmanaged", which the fleet view is built around, becomes unexpressible; a repository with hooks of its own silently loses them; and a colleague who has never heard of this tool can read .git/hooks/pre-commit and see what runs. That legibility is worth five files.

And the failure is not hypothetical — we were on the receiving end of it. Eleven repositories on the author's machine ran husky, so core.hooksPath was .husky/_, so git rev-parse --git-path hooks answered .husky/_ and install cheerfully baked four shims into a directory husky's own prepare regenerates. They were gone by the next npm install. Every one of those repositories reported as merely "drifted" in the fleet view while running no checks at all, and a direct push to a protected branch went through unchallenged for as long as it lasted. That is exactly "a repository with hooks of its own silently loses them", arrived at from the other direction, and it is now refused by name.

None of which the npm packaging contradicts. greengate init writes the same five files to the same .git/hooks; what a prepare script changes is who types the command, not where the hooks live or whether they can be read.

repo + rev pinning, per-hook language isolation, autoupdate (pre-commit). These solve distributing hooks to strangers. We compile checks in and distribute one binary through the fleet — the same problem, already solved differently. Adopting the mechanism would mean adopting the problem.

remotes: (lefthook). The fleet's job.

piped:, priority: (lefthook). pre-commit runs concurrently and reports every failure; pre-push runs serially and stops at the first. Those two shapes are load-bearing and documented as such. A configurable ordering invites a third shape nobody has asked for.


What this does not solve

Named because an adoption review asks these first, and an honest "no" is worth more than silence.

Tool versions are pinned by the repository, and greengate says when they are not. §1 fixes which content is checked; ADR-0019 (build.toolchain-source) fixes which tool: the repository pins it. For prettier and eslint, resolve_js_tool reads the root package.json of the checkout being committed (only the root one: a tool declared in a workspace package alone counts as undeclared unless a node_modules/.bin copy exists):

  • a node_modules/.bin copy (this checkout's, or the main worktree's) runs as before, with no new line;
  • a tool package.json declares but nobody installed does NOT run: PATH's copy is not the version the repository asked for. The check says to install (pnpm install, or the checkout's manager) and is Unavailable, so the commit goes through;
  • an undeclared tool taken from PATH or npx's cache still runs, with two warning lines: what ran (prettier 3.9.10 from /usr/local/bin/prettier, or from npx's cache), and the command that pins it.

The version comes from one --version probe, bounded at five seconds with its whole process group killed after (tree_run::run_output). Nothing compares a node_modules copy with the range package.json asks for: a stale install still runs. pre-commit reaches determinism with rev pinning per hook repository; here the repository's own lockfile is the pin, and the hook's job is to stop running anything else silently.

Nothing here enforces anything. Hooks are advisory by construction: --no-verify and hook.skip are each one command away, deliberately. So the question "what stops an unformatted commit reaching the default branch" has no answer in this document. An earlier draft of this paragraph proposed making greengate run --all-files CI-grade — exit-code contract, SARIF, JUnit. The decision went the other way: greengate deliberately does not run in CI at all. CI wants the real tools, called directly, with the platform's own caching and attribution — see the CI backstop, which ships copyable workflow templates saying exactly that.

No DCO / Signed-off-by check. commit-msg enforces a gitmoji prefix and length rules, which are house style. Any project that requires a Developer Certificate of Origin needs a different check, and today it would have to be an external — which lands it squarely in §0. It is a good candidate for a built-in precisely because it is a policy many organisations cannot adopt the tool without.

musl is untested. CI covers ubuntu, macOS and Windows. A glibc-dynamic binary does not start in the Alpine containers a lot of pipelines use. Probably a one-line target addition; worth knowing before somebody finds out from a pipeline rather than from here.

Order

All of this shipped, in this order. It is left as written rather than converted to a changelog: the argument for each ordering — why trust had to precede stage_fixed, why not_during had to precede index fidelity — is the part worth keeping, and it reads as advice only in the future tense.

PR 0a — activation and uninstall (§0). Add uninstall at both levels and name bulk activation greengate-fleet install rather than hiding it behind fix --apply. The README presents per-repository activation as the default and init.templateDir as a stated opt-in with its consequence spelled out. Closes the drive-by case for the default mode and makes the fleet's unmanaged column mean something for anyone in it.

PR 0b — the trust prompt (§0). Small once 0a exists, because it hangs off the install flow. Must precede stage_fixed, which cannot ship into an untrusted manifest — and it is the only thing standing between a cloned repository and your shell for anyone who set init.templateDir, which is the convenient mode and therefore the popular one.

PR 1 — greengate run [--all-files]. Small, useful immediately, no risk, and it gives the later work a way to be exercised over a whole repository.

PR 2 — not_during git-state conditions. Generalises the CHERRY_PICK_HEAD special case and closes the pre-push gap. Independently useful, and §1 needs its predicate.

PR 3 — index fidelity. The correctness gap. Alone, no fixing.

PR 4 — stage_fixed. Only after 3 is proven in the fleet for a while: this is the first feature that would write to someone's index, and it should not be the change that also introduces the stash.

PR 5 — pre-push runs against the pushed commits, not the working tree. Its own decision: a worktree or git archive of the tip is more expensive than anything else here, and the cost is the whole question.

Shipped as pushed_tree.rs, and the cost is what made it OPT-IN: git config greengate.testPushedTree true. The instrument is git worktree add --detach <tip>, not the stash — a push is not a staging operation, so the difference that matters is tree-versus-the-commit-you-are- sending, which includes staged-but-uncommitted work too. Holding all of that aside for the length of a test suite would leave the developer looking at a tree that is not theirs for minutes at a time.

Shebang detection is unscheduled. So is everything under What this does not solve, which is a list of known gaps rather than a backlog.

Decisions

  1. --all-files implies no stash. There is no staged/unstaged distinction to protect when the input set is git ls-files, so taking a stash would be surprising extra mutation with no correctness upside. If a future explicit --no-stash flag exists for diagnostics, greengate run --all-files --no-stash should be accepted as redundant rather than rejected.

    Corollary, stated because it is the inverse of §1: on a dirty tree, --all-files reports on content that is not committed and may never be. That is correct — the question it answers is "does my working tree pass", not "would my commit pass" — but §1 spends a page arguing that judging unstaged content is a bug, and a reader who meets this without warning is entitled to think one of the two is wrong. They are different questions; the mode's help text should say which one it answers.

  2. Outcome::Fixed is invalid in pre-push. A pre-push hook must not modify the worktree or index: silently proceeding after a write would make the pushed commit differ from the tree the developer is now looking at.

    Refused where every other bad declaration is refused, rather than at push time. A pre-push line declaring a fix is a ParseError, alongside NameTaken and Duplicate — reported on every commit, named, located, and visible in the dashboard's DECL column. A "hook contract violation" raised at push time would be the same fact discovered later, by fewer people, in the one place where blocking is most expensive.

    A built-in cannot express it at all: Fix::Rewrite is reachable only from a Stage::PreCommit declaration, which the compiler enforces.

  3. The stash applies to the pre-commit check stage only. commit-msg reads and rewrites the message file Git passes as $1; prepare-commit-msg appends to that same message file based on the branch name and commit source. Neither hook selects paths from the index or asks tools to read repository files, so wrapping them in StagedOnly would add stash risk without fixing a real fidelity problem.

    pre-push is excluded from the stash and NOT from the problem. It has the same bug by a different route (§1) — the pushed refs choose the files and the working tree supplies the content. Stashing is the wrong instrument there, so it gets its own item rather than an exemption. Saying "pre-commit only" and stopping is precisely the move §3 criticises: pre-push has no cherry-pick guard today because the zsh version had none, and nobody wrote down that it was a choice.

Interactive hook.skip management

Status: shipped, with one section kept as history because the reasoning is worth more than the design it produced.

Extends docs/fleet-dashboard.md, which listed the s toggle as a v2 item without saying what it should do.

Naming a check

A check's id is <trigger>-<name> — pre-commit-clippy. Exactly three things name it, and both config surfaces resolve all three identically:

writtenmeansexample
the full idthat one checkpre-commit-clippy
a triggerevery check on that triggerpre-commit
a short namethat check, on any triggerclippy

Three exact comparisons. No substring. So:

git config --add hook.skip pre-commit-clippy   # one check
git config --add hook.skip clippy              # that check, either trigger
git config --add hook.skip pre-commit          # all fifteen pre-commit checks
git config greengate.severity.clippy warn       # same vocabulary, other surface

hook.skip e matches nothing. Where several severity keys reach one check, the most specific wins — full id > short name > trigger — so you can downgrade a whole trigger and then exempt one check from it.

Declared checks in greengate.conf have ids too, so hook.skip pre-commit covers them. See docs/custom-checks.md.

History: the problem this was written to solve

Kept because the sequence — measure, ship the cheap safety net, then find the real fix — is the reasoning, and a rewritten doc that hid it would read as though the right answer had been obvious.

hook.skip used to match by substring: check_name.contains(skip_value). Measured against the 20 checks of the day:

hook.skip valuesuppressed
pre-commit-clippy1 / 20
cargo2 / 20
lint5 / 20
pre-commit15 / 20
t19 / 20
e20 / 20

None of those are adversarial. t is a plausible shorthand for "tests"; pre for "prettier". Either silently disabled the whole suite, in a config file nobody reads, with no output at commit time saying so.

Worse, no value could express "this check only": pre-commit-lint-js is a prefix of pre-commit-lint-json-yaml, so skipping the first unavoidably skipped the second. The full id was not a safe value either, and an earlier revision of this document was wrong to imply it was.

Two things followed, in order.

First, the announcement, because a UX review against usage traces changed the priority. 1 of 96 repos had any skip at all, and its value (run-tests-js) was hand-written at a terminal. Nobody reached for a dashboard, because editing config takes ten seconds — while the consequence landed on every commit. So the dispatcher started saying what it skipped:

  ! 15 checks skipped by hook.skip: pre-commit-argo-lint, pre-commit-ban-terms, …

Silent when nothing is skipped. It reaches every skip however it was created, needs no dashboard, and turned hook.skip = e from invisible into unmissable within one commit.

Then the vocabulary, which removed the hazard rather than reporting it. It was prompted by a different bug: hook.skip matched by substring and greengate.severity.<key> matched exactly, on the same identifiers, so hook.skip clippy worked and greengate.severity.clippy warn silently did nothing. Fixing the disagreement meant picking one rule, and the only rule that serves both is exact naming.

Three parts of this document were built and are now retired by that change:

  • The typed confirmation for a skip reaching more than one check. It existed because a value could silently take four when you asked for one. An id names exactly one check, so the dashboard's toggle can no longer over-reach and the gate had become unreachable code.
  • The fragment diagnosis — recognising run-tests-js as a fragment and offering pre-push-run-tests-js instead. It is not a fragment; it is the short name, and it means what its author meant.
  • "Over-broad" as a warning. A value reaching fifteen checks now means somebody wrote a trigger, which is a thing you can only do on purpose. The detail view says so plainly instead of raising an alarm.

What replaced them is one predicate worth alarming about: inert. Under substring matching almost any string hit something, so "matches nothing" was rare; under exact naming it is the normal shape of a typo.

Non-goals

  • Not a replacement for --no-verify. A one-off bypass is git's job. hook.skip is for a persistent decision, and the UI should not blur them.
  • Not a scheduler. No expiry dates, no "skip until Friday". A skip that expires silently is a different surprise, not a smaller one.
  • Not fleet-wide bulk writes. See Scope — for a fleet-wide skip the correct mechanism is one global config entry, not 96 local ones.

Rules

1. The UI writes an id, never a short name. pre-commit-clippy, not clippy. Both work, but the short name is a bet on every future check name: a clippy check added to pre-push later would widen an existing skip without anyone touching it. The id cannot widen.

2. Lead with what protection is lost, not with a count. "Suppresses 19 of 20" is an aggregate, and aggregates do not move people the way a named consequence does. It also treats every check as interchangeable, which they are not: pre-commit-yamllint reformats, pre-push-branch-protect is what stops a push to main. Name them, most consequential first; the count is a subtitle.

3. A skip that reaches nothing is reported as a finding. The UI cannot stop someone writing hook.skip = clipy by hand, so it surfaces it. A value matching no check appears in the repo detail view saying exactly that, and a value naming a trigger is shown with its expansion — informative, not alarming:

 hook.skip
   pre-commit-clippy    local   -> pre-commit-clippy
   pre-commit           local   -> the whole pre-commit trigger — 15 checks
   clipy                global  -> ! matches no check

4. Removal is exact, and the exit code is not evidence.

git config --unset hook.skip <value> takes a value-pattern that is a regex, not a literal. Measured:

  • --unset hook.skip 'pre-commit-lint.js' removes pre-commit-lint-js — the . is a wildcard. Any value the UI does not escape can over-match.
  • When the pattern matches more than one value, git prints warning: hook.skip has multiple values, removes nothing, and exits 5. An earlier revision of this document said it exits 0 and called that a silent no-op; that was a mis-measurement — $? was read after a pipe, so it reported the last command in the pipeline rather than git. git does signal the refusal.
  • --unset-all with the same pattern removes both, which is the opposite surprise, and duplicates are legal so an anchored pattern can match twice.

So the UI passes an anchored, escaped pattern (^pre-commit-clippy$) and then re-reads the config to confirm. Not because the exit code lies, but because a status code reports what the command believes it did while a re-read reports what is true. Config is small and the read is cheap; there is no reason to prefer the weaker evidence.

5. Prefer undo to confirmation. A toggle writes immediately and offers u to take it back. An undo helps when the user was wrong, where a confirmation only interrupts when they were right (Nielsen's third heuristic; the Undo Send precedent).

The draft required typing the check name whenever a skip reached more than one. That gate is gone with the substring rule that made it necessary — see History.

The UI never refuses. Showing the consequence is the intervention; refusing invites working around the tool by hand, which is worse and unobservable.

6. Idempotent. --add on a value already present creates a duplicate that must then be unset twice. The UI checks first and reports "already skipped" rather than writing.

Scope: local, or global

Two scopes, and the distinction matters more than it looks.

  • Local (git config --add, writes .git/config) — this repo only. The default, because it is the reversible one and it is where a repo-specific decision belongs.
  • Global (git config --global --add) — every repo on the machine, including ones cloned later.

What ships: the UI writes LOCAL, only. skips::plan builds git config --add / --unset with no --global, so every toggle lands in that repository's .git/config. And it goes further than not offering global — it REFUSES to touch an entry that is not local. Toggling a check whose skip came from ~/.gitconfig produces

that entry is global, not local — edit it where it lives

rather than a write. That refusal is the right default: a keystroke in a per-repository detail pane should not silently change every repository on the machine, and an --unset aimed at the wrong file is exactly the kind of write this tool has already been burned by.

The argument for global is still a good one, and it is a stated gap. A fleet-wide skip should be one global entry, not a loop over 96 local writes: one entry is one thing to find and one thing to undo, while 96 entries are a migration in their own right, and the tool has already learned what a half-applied sweep costs. Nothing in the UI offers that today. Whoever builds it should treat "affects every repository, present and future" as text the user must read, not a mode they can fall into — which is why it was not bolted onto the existing local toggle.

configured_skips reads via plain git config --get-all, so global and local entries are already merged with no way to tell them apart at dispatch time. The detail view shows which scope each value came from (git config --show-origin --get-all hook.skip), or a developer deletes a repo's .git/config line and is baffled that the check is still skipped. This part is real: SkipEntry carries a scope field of Local | Global | Other { origin }, resolved by skips::scope_of from --show-origin, and Other exists precisely so a system config, an include or a worktree config is not silently relabelled as one of the two the UI can reason about.

Where it lives in the UI

Repo detail (Enter, then s) — the check list is selectable, and s toggles the highlighted check for that repo. This is the common case: "not in this repo, not right now". u takes it back.

Hook view (h) — the transposed matrix, one row per check, with TRIGGER as its own column. Answers "where does this check actually apply?", which the CHECK column alone could not once two checks could share a short name.

Data model

SkipEntry {
  value      : String                  // as written in config
  scope      : Local | Global | Other { origin }
  suppresses : Vec<&'static str>       // resolved against the check registry
}

SkipPlan {
  check      : &'static str            // the check being toggled
  action     : Add | Remove
  command    : Vec<String>             // exactly the argv that will run
  suppresses : Vec<&'static str>       // what changes as a result
  refuse     : Option<String>          // why not, in words the user reads
}

SkipPlan carries no repo or scope: the repository is the argument to plan() rather than a field of its result, and there is no scope to choose because every plan is local — see Scope above. refuse is a plain String rather than a Refusal enum because every refusal is shown to a human and none is branched on: "already skipped", "already covered by a broader entry", "that entry is global, not local".

suppresses is resolved through amont_runtime::names_check, the same function the dispatcher uses. Reimplementing the match differently is how a UI comes to claim a check is active while the dispatcher skips it.

Tests

The important ones are about honesty, not mechanics:

  • A value naming no check is reported as reaching nothing — not silently dropped.
  • A trigger value is expanded to the checks it covers, by name.
  • The written value is always an id — falsified by writing a short name and asserting the test fails.
  • Adding an existing skip is refused, not duplicated.
  • Removal uses an anchored pattern and is verified by re-reading config.
  • A global skip is labelled as global in the detail view, with its origin.
  • The resolver agrees with dispatch::selected for the same inputs.

How we would know it worked

  • Zero inert skips. Measurable from greengate-fleet --json at any time. A skip that names nothing is a developer who believes a check is off when it is not.
  • Time-to-discover a skip. The announcement drives this to one commit; before it, the honest answer was "possibly never".

Rendering

Inherits the dashboard's constraints and must not quietly drop them: the preview is legible under NO_COLOR, degrades below 100 and 60 columns rather than scrolling sideways, and encodes nothing by colour alone.

Open questions

  1. Should the UI ever refuse a write? RESOLVED: no. Show the consequence. Refusing protects against a mis-keystroke but invites working around the tool by hand, which is both worse and unobservable.
  2. Should skips in the fleet table show a count or the values? RESOLVED: a count in the table, the values with their reach in the detail view. A count alone hid an over-broad entry back when one could happen by accident; the detail view now carries the expansion.
  3. Is --show-origin fast enough per repo at fleet scale? It is one extra git config invocation across ~96 repos. Measure before adding it to the scan rather than the detail view.

greengate-fleet — a TUI for the 96-repo hook fleet

Status: built. PRs #41-#47 implement v1 and v2; scripts/propagate.sh is gone, replaced by greengate-fleet fix.

the greengate-fleet dashboard over a small fleet: overview, repo detail, and the hook-centric view

The recording is real: real repositories, shims written by the release binary, scanned by the shipped dashboard — rebuilt any time with assets/fleet-demo.sh.

The s toggle for hook.skip is BUILT. This paragraph called it deliberately unbuilt for longer than it was true. s toggles the highlighted check in the repo detail pane and u takes it back; it writes to that repository's .git/config and refuses to touch an entry that is global or from another config file. It is specified in hook-skip-management.md, which is also where the one genuine gap is recorded — there is no way to write a FLEET-WIDE skip, and a loop over 96 local writes is not one.

It was specified as a safety feature rather than an ergonomic one, back when hook.skip matched by SUBSTRING and hook.skip = e silently disabled all 20 checks. Matching is exact now: a value names a check by its full id, its trigger, or its short name, and e reaches nothing. The friction the original design carried — typing a check's name whenever a skip reached more than one — went with the rule that made it necessary.

Unbuilt, and named rather than half-built: the : command palette, r (rescan), ? (a key sheet), and f (fix from inside the TUI). f is deliberate rather than pending: the dry-run/--apply split on the fix CLI already enforces the property f was designed to give, and does it without a modal confirmation. See Interaction model.

Why this exists

scripts/propagate.sh prints a text summary. That summary has misled its author twice, on the same day:

  • It reported 192 removals per hook name across 96 repos that hold one copy each. Two overlapping loop conditions were both claiming the same files. The number is arithmetically impossible, and it still read as plausible.
  • A consistency sweep reported 0 copies / 0 distinct for every hook. The -maxdepth was wrong, so it matched nothing. Zero findings and a broken check produce identical output.

Both are the same failure: a scalar with no denominator, printed with the same confidence whether it measured everything or nothing. Neither is fixed by writing the script more carefully — the next one will make a third version of it. It is fixed by rendering the fleet as a grid you can look at, where "this column is empty because nothing was scanned" cannot look like "this column is empty because everything is clean".

That is the entire justification. If the dashboard does not make those two states visually distinct, it has failed and should not be built.

Non-goals

  • Not part of the commit path. The hook binary stays dependency-free; see "Packaging". A TUI in pre-commit would break GUI clients, CI, and piped output, and would seize the alternate screen during a commit.
  • Not a wrapper around the old migration scripts. The scanner, previewer, and fixer are Rust code. scripts/propagate.sh is historical reference only and should disappear once the Rust path can prove the same removals/writes.
  • Not a git client. No staging, committing, diffing. lazygit and tig exist and are better at it.
  • Not a linter runner. It reports on hook installation and configuration, never on the content of your code.
  • Not a remote/CI dashboard. Local .git/hooks state only. gh dash covers the remote side.

Prior art worth stealing from

ProjectWhat to take
k9sResource table as the primary object; / to filter, : for a command palette; a context-sensitive hotkey footer that changes with the selected row.
lazygitContextual keymap always visible; panels that own their own keys; ? for a full sheet.
gh-dashThe closest analogue — many remote items, sectioned, with per-row status glyphs and a detail pane.
brootIncremental fuzzy filter that narrows as you type, with the match count always shown.
btop / bottomDense status rendering that stays legible at small widths.
helixSelection → action ordering, and which-key style discoverability after a prefix.
deltaRestraint. Colour carries meaning, never decoration.

Design principles, and where they come from

Overview first, zoom and filter, then details on demand. Shneiderman's visual information-seeking mantra (The Eyes Have It, 1996) is the literal structure of this tool: a fleet summary band, a filterable repo table, a detail pane on Enter. Do not invert it — no screen should open on a single repo.

Visibility of system status (Nielsen heuristic 1). A fleet scan takes ~8s (2.9s to enumerate 98 .git directories, 4.9s to hash 96 shims). That is well past the ~400ms Doherty threshold at which interaction stops feeling immediate, so the scan MUST stream: rows appear as they are discovered, with a live scanned N/98 counter. A spinner over a blank screen is not acceptable.

Recognition over recall (Nielsen heuristic 6). The 20 check names are not memorable. Anything the user must type — a check name, a repo path — is offered as a filterable list first.

Every count carries its denominator. This is the local rule that follows directly from the two failures above. Never render 0 drifted; render 0 drifted / 96 scanned. A table with no rows renders as an explicit diagnostic state, never as an empty success.

Preattentive encoding, redundantly. Colour and position are processed pre-attentively (Ware, Information Visualization), which is what makes a grid scannable at all. But roughly 8% of men have red-green colour vision deficiency, so state is encoded twice — glyph and colour — and never by colour alone. NO_COLOR must produce a fully usable screen.

Data-ink ratio (Tufte). No box-drawing around every cell, no gradients, no progress bars where a number is clearer. Chrome competes with the data for the same 80 columns.

Data model

One row per repository. Collected read-only; the dashboard never writes without an explicit action.

FleetScan {
  root               : PathBuf
  depth              : usize
  git_dirs_found     : usize
  hook_dirs_seen     : usize
  managed_seen       : usize
  unmanaged_seen     : usize
  unreadable         : Vec<PathBuf>
  hooks_outside_seen : usize      // repos whose hooks resolve somewhere we will not touch
  excluded_dirs      : usize
  dirs_visited       : usize      // how much of the tree was actually walked
  repos_with_deprecated_opt_out   : usize  // only `set planExempt off`: read until a later greensummit major
  repos_pinning_attest_before_1_7 : usize  // an attest pin older than 1.7.0, or an unnamed sha
  repos              : Vec<Repo>
}

Repo {
  path              : PathBuf        // displayed repo-relative to the scan root
  managed           : bool           // ≥1 shim dispatches to the binary
  shims             : Vec<ShimState> // one per git-invoked hook, in DISPATCHERS order
  baked             : BakeState      // which binary path the shims point at
  stale_ours        : Vec<String>    // OUR old shims that are no longer shipped
  foreign_subs      : Vec<String>    // hand-written pre-commit-* / pre-push-* sub-hooks
  hook_pkgjson      : bool           // a vestigial hooks/package.json from the node era
  languages         : Vec<String>    // manifests at the repo root — DISPLAY ONLY
  applicable        : Vec<String>    // checks that would ever fire here, from each Scope
  skips             : Vec<SkipEntry> // hook.skip, resolved: what it hits and where it came from
  severities        : Vec<SeverityOverride>  // greengate.severity.*, and which one git applies
  declared          : Vec<DeclaredCheck>     // this repo's own greengate.conf checks
  trusted           : Option<bool>   // None when there is no manifest at all
  agents_md         : AgentsMdState  // UpToDate | Missing | Drifted | Malformed
  aval_hook         : AvalHook       // { state, ignored: Vec<String> } — see below
  hooks_dir         : HooksDir       // where the hooks are, and whether we may touch them
  shares_hooks_with : Option<PathBuf> // a repo already seen that owns this hooks dir
  attest            : AttestState    // what it says to attest, from HEAD — see below
}

SkipEntry        { value, scope: Local|Global|Other{origin}, suppresses: Vec<&str> }
SeverityOverride { check, value, level, scope, effective: bool }
DeclaredCheck    { name, stage, state: Usable{severity, exts} | unusable }
AttestState      { deprecated_opt_out, spec_with_gates, pins: Vec<AttestPin> }
AttestPin        { file, action: attest|attest/sign, reference, version: Option<X.Y.Z> }

ShimState = Ok            // installed bytes match the expected baked template
          | Drifted       // present, readable text, not the expected baked template
          | Missing
          | Symlink{target}    // a link — writing here would rewrite something else
          | Unreadable{why}    // a binary, a directory, a permissions error, a hard link
AvalHookState = NoCorpus  // no .adr.yaml — not applicable, and nothing was spawned
              | NoAval    // a corpus, and no `aval` on PATH to judge it with
              | Current   // `aval hook install --check` exited 0
              | Stale     // …exited 1: the hook is behind the installed aval
              | Unknown{why}   // aval answered something it did not promise
BakeState = Current       // == installed binary path
          | Stale(path)   // points somewhere else — the GUI-client failure mode
          | Unbaked       // __GREENGATE_BIN__ placeholder intact
          | Mixed         // shims disagree with each other
HooksDir  = In{path}      // inside the repo's worktree, or its git common dir
          | Outside{path} // reported, never created, never written to
          | Unknown{why}  // git would not say — not a state to guess out of

FixPlan {
  repo      : PathBuf
  repo_abs  : PathBuf
  intent    : "repair" | "activate"
  hooks     : HooksDir
  refuse    : Vec<Refusal> // suppresses the WHOLE repo
  warn      : Vec<Warning> // printed; suppresses NOTHING
  remove    : Vec<Removal>
  write     : Vec<WriteShim>
  write_agents_md   : Option<WriteAgentsMd>    // --agents-md only
  install_aval_hook : Option<InstallAvalHook>  // --aval-hook only; runs aval, renders nothing
}

Refusal = unmanaged | unreadable_hooks | tracked{path}
        | tracked_unknown{path, why}      // git could not answer — never read as "no"
        | foreign_hook{names} | agents_md_malformed{path} | unbakeable_binary{binary}
        | hooks_dir_outside_repo{path} | hooks_dir_unknown{why}
Warning = unrecognized_sub_hook{path}     // a hook we did not write. NOT deleted.
        | hooks_dir_outside_repo{path}
        | aval_hook_ignored{paths}        // .gitignore drops the session hook. NOT edited.
        | aval_hook_unjudged{why}         // --aval-hook asked, no aval (or an odd answer)

Four of these fields deserve a sentence, because each exists to make something that was invisible visible:

  • languages is display only, and applicable is the real answer. Language detection used to double as "would a check fire here", which made it a fourth copy of a rule that lives in each check's Scope. applicable now evaluates those scopes against the repo's tracked files; languages is a column a human reads.
  • skips is Vec<SkipEntry>, not Vec<String>. Bare strings hid both halves of what a reader needs: a value need not be a check id (a trigger silences fifteen), and once git config --get-all has merged local and global they are indistinguishable.
  • severities exists because a downgrade leaves no trace on screen. A skipped check is announced on every commit; a check downgraded to warn runs, prints its failure, and lets the commit through, so a repository that enforces nothing reads exactly like one that enforces everything. effective matters too — --get-regexp lists every entry while the dispatcher asks --get and takes the last, so listing both as authoritative reported a downgrade git does not apply.
  • declared and trusted are the manifest. A repo could be running a command on every commit that no column mentioned; and trusted: None (there is no manifest) must read differently from Some(false) (it declared something and that something is not running).

Two channels, and why a warning is not a weak refusal

A refusal suppresses the whole repository: a half-applied fix is how a repo ends up with both pre-commit-ruff.zsh and pre-commit-ruff, running ruff twice. A warning prints and changes nothing about what gets done — a stranger's pre-push-mine.sh must not block repairing five broken dispatchers in the same directory.

Folding the two together forces a choice between "say nothing" and "do nothing", and this tool has been on both sides of it. hooks_dir_outside_repo is the one condition on both channels, deliberately: the warning names the directory so somebody can go and look at their core.hooksPath, the refusal is what stops the write.

foreign_subs is REPORTED, not removed

install and fix --apply used to delete every .git/hooks file matching pre-commit-* / pre-push-* that did not carry our marker, in repositories they had never touched, reported only as a number. That was inherited wholesale from a one-time migration sweep in scripts/propagate.sh (see git show 90b0d30^:scripts/propagate.sh, around lines 82-87) and then pinned as golden by tests/it/parity.rs.

They are now Warning::UnrecognizedSubHook and are left exactly where they are. --remove-unrecognized puts them back on the removal list, and is deliberately not spelled --remove-stale: "stale" means stale_ours, which IS ours and is still removed by default, and reusing that word for other people's files is what would get somebody to type it casually.

hooks_dir and shares_hooks_with

hooks_dir exists because a scanned repository's core.hooksPath may be an absolute path anywhere on the disk, and activation used to create_dir_all it and write five 0o755 files into it. The fleet now refuses anything that does not resolve inside the repository's own worktree or its git common directory.

Note the deliberate asymmetry: per-repo greengate install keeps honouring its own repository's core.hooksPath, absolute or not — you are standing in that repository and configured it yourself. The fleet refuses, because it is walking ninety-six repositories it did not configure.

shares_hooks_with exists because a submodule's and a linked worktree's hooks live in the superproject/main repo. Both now appear in repos (their .git is a FILE, which the walk used to skip outright, making every submodule on the machine invisible), so one hooks directory is reachable from two rows. The first repository seen in the walk's sorted order owns it; the others plan nothing and display as covered-by.

attest

attest measures the step that retires greengate's opt-out from attest (decisions ADR-0037). A later greensummit major stops reading set planExempt off in greengate.conf (2.0.0 still reads it), so it waits for repos_with_deprecated_opt_out to reach zero. The sweep that gets it there adds @plan-exempt off to greensummit-inputs. Where the spec declares gates (spec_with_gates), the new line voids the input fingerprints of an attest before 1.6.0. So the sweep also waits for repos_pinning_attest_before_1_7 to reach zero.

The answers are read from HEAD's tree through the greensummit library. A moving v1 follows the releases and is never counted. A sha counts unless a # vX.Y.Z comment beside it names a release.

languages matters because a check that never fires is not the same as a check that is broken: pre-commit-clippy in a Python repo is correctly inert. The dashboard must distinguish inert from failing, or it will manufacture 90 false problems out of pre-commit-cargo-fmt.

Shim comparison is against the rendered template for the intended binary path, not the raw tracked template. A correctly baked shim must never be reported as drifted merely because __GREENGATE_BIN__ was replaced. The placeholder keeps its 3.x spelling until the fleet's shims are re-baked (the step after 4.0).

Screen 1 — Fleet overview (default)

┌ greengate fleet ──────────────────── scanning 98/98 · 8.1s ── /Users/me/Developer ┐
│ 96 managed · 2 unmanaged (skipped) · 384 shims · 20 checks                       │
│ consistency  commit-msg 96/1 ✓   pre-commit 96/1 ✓   pre-push 96/1 ✓             │
│              prepare-commit-msg 96/1 ✓          ← copies/distinct blobs          │
├─────────────────────────────────────────────────────────────────────────────────┤
│   REPO                       SHIMS  BAKE     LANG      SKIPS  WARN  STATE        │
│ ▸ Perso/homelab              ●●●●   current  k8s js    –      –     ✓ ok         │
│   Perso/application-landscape ●●●●  current  js        –      –     ✓ ok         │
│   Perso/git-templates        ●●●●   current  rust      –      –     ✓ ok         │
│   Perso/trade-agents         ●●●○   current  python    –      –     ✗ missing 1  │
│   Perso/frontjutsu/mvp       ●●●●   stale    js        2      1     ! stale bake │
│   Volkswagen/pos-fr-services ●●●●   current  js        –      –     ✓ ok         │
│   …                                                                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│ 96 rows · 0 filtered   ↑↓ move  ⏎ detail  / filter  : command  h hooks  ? help   │
└─────────────────────────────────────────────────────────────────────────────────┘
  • The consistency band is the headline, because copies/distinct is the one number that actually proves fleet health, and it is the number the text script got wrong. It is always N/M, never a bare adjective.
  • SHIMS is five glyphs, one per dispatcher, in fixed order. ● ok, ◐ drifted, ○ missing, ! a symlink, ? unreadable. Position encodes which hook without spending a column on its name. ! and ? are deliberately OFF the ●◐○ scale: those three run from healthy to absent, and a dispatcher that is a link to a tracked file is not "somewhat installed" — writing there rewrites the other file, and it must not read as a milder ◐.
  • STATE is a redundant text summary of the same information, so the screen survives NO_COLOR and CVD. It also carries the two states that are not about the shims at all: covered by <path> (a linked worktree or submodule whose hooks another row owns) and ! hooks elsewhere (a core.hooksPath we will not follow), both of which would otherwise read as ! unmanaged and send somebody looking for a missing install.
  • A repository whose dispatchers are SYMLINKS no longer counts as managed, even when the link points at one of our own shims. That is the intended trade: fix reports it instead of writing through the link.
  • DECL counts the checks a repository declares in greengate.conf, and reads 2!1 when one of those lines cannot be parsed — a check somebody committed that has never once run. 2 and 2!1 describing the same repository is the distinction the column exists for.
  • WARN counts only the override git would actually APPLY. --get-regexp lists every configured entry, but the dispatcher asks --get, which returns the last — so a local block beats a global warn. Counting every entry made the column report a downgrade that never happens; the shadowed entry is still shown in the detail pane, marked overridden, because somebody wrote it. A trusted greengate.conf contributes rows too — its skips and severity lines appear with origin greengate.conf, folded into the same ladder the dispatcher uses (policy above global, below local), so a policy warn a local config re-blocks is shown but not counted.
  • SKIPS and WARN are deliberately two columns, not one total. A skipped check does not run; a downgraded one runs, prints its failure, and lets the commit through. Summing them would hide the second — which is the one that looks like enforcement and is not. WARN counts only overrides that actually weaken something: an explicit block, a misspelt check name and an unrecognised value all change nothing, and inflating the count with them is how a column stops being read. The detail pane names all three.
  • BYPASS is not folded into WARN for the same reason: a downgrade is a policy statement about the repository, a bypass is an event that happened. It counts unverified commits — commits carrying no record their commit-time gate ran — read from the runtime's local ledger through the runtime's own parser. The count is a floor once the runtime compacts the ledger; the tint follows recency (an event in the last 30 days), because three dodges this month and three from two years ago must not paint alike. A rate needs a denominator (commits over the same window, rev-list --count at scan time); that is deliberately v-next rather than half-implemented here.

The empty state, which is the point

├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   No repositories found under /Users/me/Dev                                     │
│                                                                                 │
│   Scanned 0 directories in 0.1s. This is a SCAN FAILURE, not a clean fleet.     │
│   • is --root correct?        (currently: /Users/me/Dev)                        │
│   • is --depth deep enough?   (currently: 6)                                    │
│                                                                                 │

An empty table must never render as a calm empty list. Zero scanned is stated as a failure in words. This single screen is the reason the tool exists.

Screen 2 — Repo detail (Enter)

┌ Perso/trade-agents ─────────────────────────────────────────────────────────────┐
│ /Users/me/Developer/Perso/trade-agents          python · managed · bake current │
├─────────────────────────────────────────────────────────────────────────────────┤
│ DISPATCHERS                                                                     │
│   ✓ commit-msg           blob 7914a85  matches template                         │
│   ✓ pre-commit           blob 7914a85  matches template                         │
│   ✓ pre-push             blob 7914a85  matches template                         │
│   ✗ prepare-commit-msg   MISSING       → `greengate fleet fix`                    │
│                                                                                 │
│ CHECKS (20)                        pre-commit                                   │
│   ● ban-terms      ● merge-conflict   ● package-lock   ● usual-name              │
│   ● lint-json-yaml ● yamllint         ○ lint-js        ○ prettier                │
│   ● ruff           ● pyright          ○ cargo-fmt      ○ clippy                  │
│   ○ argo-lint      ○ kube-linter      ○ kubeconform                             │
│                                    pre-push                                     │
│   ● branch-protect ● branch-pattern   ● pull-rebase    ○ run-tests-js            │
│   ○ cargo-test                                                                  │
│                                                                                 │
│   ● will run here   ○ inert (no matching manifest)   ⊘ skipped via hook.skip     │
├─────────────────────────────────────────────────────────────────────────────────┤
│ ⏎ back  s toggle skip  f fix this repo  o open  y copy path  ? help              │
└─────────────────────────────────────────────────────────────────────────────────┘

The ● / ○ / ⊘ distinction is the important one. A Python repo showing ○ clippy is healthy; the same glyph must never be used for "broken". Three states, three glyphs, three words in the legend — no colour required to read it.

The detail pane also carries, above the dispatchers, the resolved hooks dir (always, not only when something is wrong with it — a reader who cannot see the directory cannot tell a repo we declined to touch from one that had nothing to do) and, when set, shares hooks covered by <path>.

Below them, leftovers are TWO blocks, not one:

│ LEFTOVERS OF OURS (nothing dispatches these — fix removes them)                 │
│   pre-commit-ruff                                                               │
│                                                                                 │
│ NOT OURS (left alone — nothing dispatches these either)                         │
│   pre-push-branch-protect.sh                                                    │

They shared a heading for two releases while fix --apply silently deleted the second list. Same word, opposite fates.

Screen 3 — Hook-centric view (h)

Transposes the matrix. Answers "where does pre-commit-pyright actually apply, run, get skipped, or stay inert?" Checks are no longer installed as per-repo files; the view is about runtime applicability, not file presence.

│   CHECK                 APPLICABLE  ACTIVE   SKIPPED   INERT                    │
│ ▸ pre-commit-ban-terms      96        96        0        0                      │
│   pre-commit-ruff           11        11        0       85                      │
│   pre-commit-pyright        11        11        0       85                      │
│   pre-commit-clippy          3         3        0       93                      │
│   pre-push-run-tests-js     41        39        2       55                      │

Rows sum across; APPLICABLE = ACTIVE + SKIPPED. A row where APPLICABLE is 0 is highlighted, because a check that can never fire anywhere is either dead or misconfigured — and that is invisible in today's text output.

Interaction model

Modal and keyboard-first, following k9s and helix. No mouse dependency; mouse scroll may be supported but nothing is mouse-only.

The keys that exist. This table was aspirational and is now a list of what tui.rs actually binds; the footer of each screen shows the same set.

KeyWhereAction
↑↓ j keverywheremove selection
Enterfleetdetail of the selected repo
Esceverywhereback, or clear the filter
/ then text, Backspacefleetincremental filter — match count always shown
hfleettoggle fleet ↔ hook-centric view
sdetailtoggle hook.skip for the highlighted check
udetailtake that toggle back
ffleet, detailshow the repair for the selected repo — what would be removed and written
y / Entersync previewcarry that repair out
Escsync previewdiscard it, nothing written
qeverywherequit — including during a scan

And the ones that do not, removed from this table rather than left as promises: : (a command palette), r (rescan), ? (a key sheet). All three are still reasonable ideas.

Destructive actions are diff-first. In the TUI, f never writes: it builds the same FixPlan the CLI's fix preview prints, for the one selected repository, and puts it on screen — removals, writes, the shims that are already current, and anything worth noting. y applies exactly that value, and apply re-verifies every refusal at the moment of writing, so a tree that changed between the preview and the keypress is refused rather than acted on. f uses the safe defaults only — Repair, no AGENTS.md, nothing deleted that this tool did not write; the two opt-in flags below stay CLI-only because each is a materially bigger action than restoring four untracked shims. A repository that is not ours, or whose hooks are somewhere we will not touch, is refused in place with a one-line reason, no modal. On the command line the same split is enforced by the verb rather than a prompt:

greengate-fleet fix                    # DRY RUN — prints the plan, writes nothing
greengate-fleet fix --apply            # carries it out
greengate-fleet install                # implies applying; named after intent
greengate-fleet fix --apply --agents-md          # opt in, per invocation
greengate-fleet fix --apply --aval-hook          # opt in, per invocation
greengate-fleet fix --apply --remove-unrecognized

fix with no --apply is the preview, built from the same typed FixPlan the apply consumes, so the preview cannot drift from the act. The TUI's f / y pair is the same property in a different shape: y is only bound while a plan is on screen, and it applies that plan and no other, so there is no keystroke that skips the preview and "yes" can only ever mean what was last shown. install is the one verb that implies --apply, because requiring both would be ceremony over an unambiguous intent; it has no TUI equivalent, since adopting a repository is not a repair.

Three flags are opt-in per invocation and never bundled into a plain --apply: --agents-md, which writes into a tracked file; --aval-hook, which does the same for another tool's tracked files; and --remove-unrecognized, which deletes pre-commit-* / pre-push-* files this tool did not write. The last is spelled that way rather than --remove-stale on purpose — "stale" means our own retired shims, which are removed by default and are a different thing entirely. --binary <path> chooses what the shims are baked to point at, defaulting to $HOME/.local/bin/amont.

--aval-hook keeps aval's session hook current across every repository that keeps an .adr.yaml. aval hook install writes .claude/hooks/aval-heads.sh and a SessionStart entry in .claude/settings.json, so an agent session opens with the decision heads and adopted rules in front of it; the script's bytes are its version, and every aval release that changes it leaves every corpus behind until somebody re-runs the command there. The fleet does not render that script — the template is aval's, and a copy here would be a second way to be stale. It runs aval hook install --check per corpus and reads the exit code (0 current, 1 behind), plans aval hook install for the stale ones, and re-asks at the moment of writing. A repository without .adr.yaml is never asked; one with a corpus and no aval on PATH is not judged — a warning, not "current", because a missing binary is exactly how "up to date" would be faked by silence. What git would do with the files is reported alongside from git check-ignore: a .gitignore that excludes .claude/ wholesale makes the hook work for whoever ran the command and ship to nobody, and the fleet names the negations to add (.claude/* then !.claude/settings.json, !.claude/hooks/, .claude/hooks/*, !.claude/hooks/aval-heads.sh) rather than editing an ignore file it does not own.

Given make install has destroyed tracked source twice in this repo's history, the dashboard's write path gets the same fail-closed treatment: it refuses any path git reports as tracked — and any path git will not answer about, which is a distinct state (tracked_unknown) and not a "no". fatal: detected dubious ownership is what git says about every repository owned by another uid, which is every repository inside a container bind mount, and a guard that reads that as "untracked" fails open in exactly the environment where the user cannot see what happened.

Every write and every remove — in fix, in install, and in uninstall — goes through amont_runtime::hookfile, the single owner of "is this ours, and may we touch it?". It never follows a symlink, never treats an unreadable file as absent, and stages each write to a sibling temporary that is renamed into place, so replacing a link is the only thing that can happen and writing through one is not a code path that exists.

Performance

  • Stream, never batch. Enumerate .git directories first (2.9s) and paint rows immediately in scanning state; hash shims on a worker pool and update rows in place. Sorting is stable so rows do not jump under the cursor.
  • Never block the UI thread. A 16ms frame budget; scanning runs on threads and posts results over a channel. q must work during a scan.
  • The plain commands stream too. scan, fix, install and uninstall share the walk, and the same rule applies to them: a live status line on stderr carrying elapsed time, the two counts, and the path being looked at right now. It is the path that matters when a scan stalls — a frozen count says something is slow, and only the path says what. Gated on stderr being a terminal, and erased before the report prints, so a piped or redirected run emits exactly the bytes it always did.
  • Bounded work. Respect --depth (default 6) and skip node_modules, target, .venv, vendor — the same exclusions the existing sweep uses.
  • No cache in v1. An 8s scan does not justify a cache and its invalidation bugs. Revisit only if the fleet grows past a few hundred repos.

Accessibility and degradation

  • NO_COLOR (and TERM=dumb) → glyph-and-text rendering, fully usable.
  • CVD-safe: state never encoded by colour alone; every colour is paired with a distinct glyph and a word in the legend.
  • Narrow terminals: below 100 columns drop LANG, SKIPS, WARN, DECL and BYPASS together; below 60, fall back to a single-column list. Never horizontal scrolling.
  • Screen readers do not meaningfully work with TUIs. The accessible path is therefore greengate fleet --json, emitting the full data model for scripting and assistive tooling. This is a first-class output, not a debug flag, and the TUI is a renderer over it.

Packaging

A cargo workspace, so the commit path keeps its posture:

crates/
  greengate-runtime/ # registry + hook logic. std-only.
  amont/         # the hook binary. ZERO external dependencies.
  greengate-fleet/   # scanner, fixer, JSON, TUI. ratatui + crossterm.

greengate must not gain an external dependency, directly or transitively; that property is the reason the Rust migration happened at all. The TUI is a separate artifact that a developer opts into, and make install continues to install only the hook binary.

Extracting greengate-runtime has an independent benefit: there is currently no lib target, which is why cargo test --lib fails outright. Unit tests for hook logic would move into a library where they belong, without letting TUI dependencies into the commit path.

Version plan

v1 — Rust-native fleet truth

Build the minimum useful tool, but build it in the final architecture:

  • Workspace split into greengate-runtime, greengate, and greengate-fleet.
  • Rust scanner for --root and --depth, with explicit counters for found git dirs, seen hook dirs, managed/unmanaged repos, unreadable paths, and excluded directories.
  • Rust shim inspection: five dispatcher states, baked path state, stale managed files, foreign sub-hooks, vestigial hook package.json, languages, skips.
  • greengate-fleet --json, emitting FleetScan.
  • Default TUI overview and repo detail views.
  • Rust greengate-fleet fix [repo|--all] --dry-run, producing a FixPlan. Shipped inverted, and better: dry run is the DEFAULT and --apply is the flag, so the writing form is the one you have to type.
  • Rust apply path for that exact FixPlan, with a second confirmation in the TUI and tracked-file refusal before any remove/write. The tracked-file refusal shipped. The TUI confirmation did not, because there is no f — the CLI split does the same job; see Interaction model.
  • Tests for broken root, too-shallow depth, baked-template comparison, managed detection, stale file classification, tracked-file refusal, and dry-run/apply parity.

v1 may omit the hook-centric view and skip toggling if they slow down the first usable release. It may not shell out to propagate.sh.

v2 — operational dashboard

Add the workflows that make the grid more than a safer propagation report:

  • Hook-centric view (h) over applicability, active, skipped, and inert counts.
  • Detail drilldown from a check row to the matching repos.
  • s toggle for hook.skip, backed by Rust git config calls and a preview of the exact config mutation.
  • Command palette entries for :root, :depth, :rescan, :export json, and :fix.
  • Optional activity signal after measuring cost: last commit date or another cheap recency marker, never on the initial UI thread.
  • Remove scripts/propagate.sh once v1/v2 fix coverage has replaced its last practical use.

Shipped alongside — greengate-fleet gates

Not in either list above, because the question it answers was not one this design knew to ask. The scan says whether a repository's hooks are installed; it cannot say whether the checks they run still check anything. A fleet audit on 2026-09-19 found four mechanisms that had silently stopped — a lockfile audit run one directory too high, a govulncheck built with an old Go, uv with no .venv, an npm that timed out — all of them green, all of them fast.

greengate-fleet gates reads the run record the hooks keep in each repository's refs/notes/greengate-gate and reports, per repository and gate: runs in the window, pass/fail, median and last duration, last-run age, and the flags no-op suspect, flaky and stale. Same shape as the rest of this tool — read-only, --json as a first-class output, every threshold on the command line, and an honest abstention (insufficient history (2 verdicts)) rather than a guess. The statistics belong to amont_runtime::gate_evidence; this crate contributes the Serialize coat and the table, for the same reason downgrades defers to the runtime's parser.

It is a CLI table today and deliberately not a TUI screen: the overview grid is one row per repository, and this is one row per gate per repository with a sentence attached to each flag. A screen for it is worth designing once somebody has read the table for a few weeks — see gate evidence.

Decisions

  1. Scan root. Use a CLI flag in v1. Add persistent config only after using the tool enough to know where it belongs.
  2. Fix path. Native Rust. Do not shell out to propagate.sh.
  3. Delivery target. Build through v2. v1 is the first shippable slice, not the end state.
  4. Activity signal. Sorting by last-commit date would surface "the repos you actually use are drifted" — but it costs a git log per repo. Measure first.

Delivery plan

Seven PRs. The ordering is not cosmetic: the destructive code is written only after a differential has proven the model it destroys with, and the TUI is last because it is the least risky part and the least useful if the data beneath it is wrong.

1. Workspace split, zero behaviour change. greengate-runtime (lib, std-only) and greengate (bin), no features. The proof is that all 174 tests pass UNCHANGED, plus a differential running every hook over the same fixtures before and after, comparing bytes and exit codes — the technique that caught four bugs during the zsh port. This PR must also land the zero-dependency CI guard (cargo tree for greengate shows nothing external); without it the packaging rule is a comment, and ratatui arrives transitively three PRs later. Highest mechanical risk, no feature value, therefore alone.

2. Scanner and --json, no TUI. FleetScan with every counter. This already replaces the ad-hoc find/hash-object pipelines that misled twice, so it is useful before any UI exists. Tests: broken root, too-shallow depth, excluded directories counted, unreadable paths recorded.

3. Shim classification. Expected shim = the embedded template rendered for the intended binary path. The trap is symmetrical and silent in both directions: compare against the RAW template and all 96 repos report drifted, so the tool cries wolf and gets ignored; compare too loosely and real drift is never seen. Both directions get a test.

4. FixPlan dry-run and the parity gate. A differential over all 96 repos: the Rust plan against propagate.sh --dry-run, normalised and compared. This is what earns the right to delete the shell script, and it is the long pole of the project — not the TUI.

5. Apply path, fail closed. Refuses tracked paths, unmanaged repos and unreadable hook directories. Dry-run/apply parity plus idempotence: applying twice must produce an empty second plan. Written only after 4 proves the model.

6. TUI v1 — overview and detail. ratatui's TestBackend renders into an assertable buffer, so the success criterion becomes an automated test: a deliberately broken scan must render SCAN FAILURE. Same for NO_COLOR and the 60/100-column fallbacks. A success criterion nobody can run is a wish.

7. v2, then remove propagate.sh. Hook-centric view, s skip toggle, command palette. The script is deleted once 4 and 5 have replaced its last practical use.

Two details settled before starting

  • Invocation is greengate-fleet, not greengate fleet. A subcommand would require the hook binary to locate and exec the TUI binary, coupling the commit path to a tool it must never know about. The screens' greengate fleet prompt is shorthand for the separate binary.
  • Templates are embedded with include_str! against the workspace root, so the tool reports correctly from any directory rather than only inside a checkout. All five dispatcher templates are currently ONE blob, so this is a single embedded string, not five.

Success criteria

The tool is worth building only if, on a deliberately broken scan (wrong root, wrong depth), the screen says scan failure rather than showing a clean, empty, green fleet. Everything else is convenience.

Migrating the hooks to a single Rust binary

Status: complete — all four phases. See Outcome for what the plan got wrong.

Phase 4 is done, not "optional and not started" as this line said for a while. There is no .zsh file anywhere in the repository; the "19 zsh suites" it described porting ARE the cargo integration tests under crates/*/tests/, and Windows CI runs the same suite every other platform does rather than a smoke. The one thing left of the shell era is the five sh shims, and they are shims on purpose.

This document is history, kept for its reasoning. Everything below is in the tense it was written in: the argument for a phase order, for a safety rule, for a distribution shape, is worth more than a description of the result. Where the plan and the code diverged, the divergence is called out where it happens.

Why

Two requirements the current design cannot meet:

1. No unconditional runtime dependency. Three hooks run on every commit in every repo, whatever the language:

  • commit-msg — node
  • prepare-commit-msg — zsh
  • the pre-commit / pre-push dispatchers — zsh

So a pure-Python repository needs node and zsh installed to make a commit — not because it uses either, but because the hook framework does. Per-hook scoping cannot fix this: the dependency is in the entrypoint, before any scoping runs.

2. Windows. 17 of 20 hooks are #!/bin/zsh. Git for Windows ships MSYS2 bash, not zsh, so those hooks do not execute at all. Re-shebanging is not enough — they use zsh-only syntax throughout (23 ${0:a:h}-style modifier expressions, 45 bare-word arrays, 5 (N) glob qualifiers, 2 setopt).

A single static binary answers both: nothing to install alongside it, and Windows is a build target rather than a rewrite.

What this is NOT for. The nine linter-orchestration hooks shell out to eslint / prettier / ruff / pyright / yamllint / kubeconform / kube-linter / argo. Rust does not remove those, and should not: they are opt-in per repo already (each hook no-ops unless the tool's config is present), which is exactly the "only the tools I actually use" behaviour we want. A Python repo pulls ruff, not eslint. That part of the design is already right.

Scope

groupfileslineswhy it moves
entrypoints + always-onpre-commit, pre-push, commit-msg, prepare-commit-msg, ban-terms, branch-pattern, usual-name, pull-rebase, run-tests-js~700runs regardless of repo language — the actual dependency
linter orchestration9 × pre-commit-*.zsh~576only for Windows parity; otherwise optional
tests15 × tests/*.zsh~859see below — these are an asset, not a cost

The thing that de-risks this

The existing test suite is interface-level. Every test invokes the hook by file path and asserts on exit code and stdout; none reaches inside. So once a hook file becomes a shim that execs the binary, all 14 suites keep working unchanged against a Rust implementation.

This only holds under a constraint that is easy to get wrong, so state it as a contract: every hook keeps a file at its current path, forever. The tests resolve templates/hooks/<name> from their own filename — pre-push-branch- pattern.test.zsh runs templates/hooks/pre-push-branch-pattern.zsh, pre-commit-ban-terms.test.zsh runs the .js. Porting a hook therefore means replacing its body with a shim, never deleting the file. Delete it and the unmodified test cannot run at all, and the safety property this whole plan rests on evaporates.

That is not just a testing concern: the dispatcher discovers sub-hooks by globbing <hook-name>-* in its own directory, and hook.skip filters that glob by substring on the path. Keeping every path alive keeps both working, unchanged, throughout the migration. It is ~20 shims, not 4.

Renaming the shims (dropping the now-misleading .zsh / .js suffixes) is a tidy-up for after the migration, and costs a test edit plus a propagation sweep. Not worth bundling into it.

That means a behavioural regression net for the whole migration, on Linux and macOS via the CI added in #12, before writing a single line of Rust test. Port a hook, run make test, and the same assertions that guarded the zsh version now guard the Rust one. Port the tests to cargo test later, or never.

Treat this as a hard rule: a hook is not ported until its existing .zsh test passes against the binary, unmodified.

The two genuinely hard parts

1. Shim resolution (the part that will bite)

Git requires an executable file at each of the four entrypoints (commit-msg, pre-commit, pre-push, prepare-commit-msg), and — per the contract above — every sub-hook keeps its path too, so every ported hook becomes a shim of this shape:

#!/bin/sh
exec git-hooks pre-commit "$@"

The trap: git hooks do not inherit an interactive shell's PATH. GUI clients (VS Code, Tower, SourceTree, JetBrains) launch git with a login-ish environment that frequently lacks ~/.local/bin or ~/.cargo/bin. A shim that only does exec git-hooks works in the terminal and fails silently in the GUI — the worst possible failure shape for something standing between a person and their commit.

Resolve in this order, and bake the install path in at make install time:

  1. $GIT_HOOKS_BIN (escape hatch, and how the tests point at target/debug)
  2. the absolute path written into the shim by make install
  3. command -v git-hooks (PATH, last resort)
  4. fail loudly — never silently skip a check

Windows: the #!/bin/sh shim runs under Git for Windows' bundled sh, which is always present, and MSYS resolves git-hooks to git-hooks.exe. Keep the shim rather than installing a bare .exe as the hook file.

2. Distribution

A PLAN NOT TAKEN. None of the release pipeline below was built, and make install does not work the way this describes. What ships is: make install runs cargo build --release and then greengate install, which writes the binary and bakes the shims — building from source is the ONLY path, so the "contributor fallback" became the whole story and the make install-from-source target this bullet list asks for never existed. make install-fleet does the same for the dashboard.

The section is kept because the reasoning still applies the day somebody wants binary releases: five targets, musl for the static Linux build, checksums, and a source path for unlisted triples are all still the right list. It is a backlog item nobody has needed, not a description of today.

This is the real new cost, and it is permanent machinery we do not have today.

  • Build 5 targets in CI: aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-musl (static — no glibc-version coupling), aarch64-unknown-linux-musl, x86_64-pc-windows-msvc.
  • Publish on tag, with checksums. cargo-dist generates most of this.
  • make install fetches the artifact for the host triple, verifies the checksum, installs the binary, then writes the shims with the resolved path.
  • Contributor fallback: cargo install --path ..
  • Keep a make install-from-source path so a machine without network (or on an unlisted triple) is not stuck.

Offsetting win: updating today means copying N files into 96 repos (done twice this week). After this, it is replacing one binary — the shims change almost never. Net, install gets simpler, not harder.

Behaviour that must be preserved

Verified against the current dispatcher — easy to lose in a rewrite:

  • The two dispatchers behave DIFFERENTLY, and both behaviours are load-bearing:

    • pre-commit backgrounds every sub-hook, waits for all of them, then reports every failure as a list. Running it serially would be a visible slowdown on each commit; stopping at the first failure would hide the rest, so you'd fix one lint error, commit, and immediately meet the next.
    • pre-push runs sub-hooks serially and exits on the first failure, naming just that hook (Error raised by hook <path>). That is correct for push: the steps are ordered and expensive (branch-pattern, then pull-rebase, then the full test suite), and there is no point running tests after a rebase conflict.

    A Rust port must reproduce both, including the two distinct message formats, and should have a test for each — a single shared "run all sub-hooks" helper is the obvious accidental way to lose the distinction.

  • git config --get-all hook.skip filters by substring match against the hook path. git -c hook.skip=package-lock commit must keep working.

  • CHERRY_PICK_HEAD short-circuit: the dispatcher exits 0 during a cherry-pick.

  • HOOKS_FORCE_GREP exists only to exercise the grep fallback in tests; it disappears with the shell hooks, along with the rg/grep split itself — the binary uses the regex crate and needs neither.

Phases

Each phase ships and leaves the repo working. Nothing is a flag day.

Phase 0 — scaffold, no behaviour change. Cargo crate, CI build job, shim mechanism, make install writing shims. The Rust dispatchers do nothing themselves yet: they glob and run the existing pre-commit-* / pre-push-* script files, honouring hook.skip — pre-commit in parallel collecting every failure, pre-push serially stopping at the first, each with its existing message format. Done when: all 14 zsh suites pass unchanged with shims installed.

Phase 1 — the always-on set. In this order (cheapest correctness first): branch-pattern → usual-name → prepare-commit-msg → pull-rebase → commit-msg → ban-terms → run-tests-js. Each: implement in Rust, replace the script with a shim (do not delete it), make test must stay green.

Phase 1 also moves the config gating into the dispatcher. Today every pre-commit-*.zsh is spawned unconditionally and each decides for itself whether to no-op — which means a Python repo still starts a zsh process for the eslint hook purely to have it exit. The Rust dispatcher should evaluate the same signals (an eslint config, [tool.ruff], pyrightconfig, staged .yaml, …) and not spawn what cannot apply. Fewer processes per commit, and it is what makes the dependency claim below true rather than nearly true.

Done when: the unconditional dependency is gone — a repo whose staged files trigger no linter hook needs neither zsh nor node to commit.

Note precisely what this does not yet deliver: a repo that does trigger a still-zsh linter hook (a Python repo with [tool.ruff] reaching pre-commit-ruff.zsh) continues to need zsh. Full removal is Phase 3. Requirement 1 is met for the framework; it is met for every repo only after Phase 3.

ban-terms earns a real parser here. Its comment/string blanker is explicitly "not a parser" and mis-handles a regex literal containing an escaped slash; a proper tokenizer removes that whole class of false negative.

(Written of the JS implementation. The Rust port gained a Regex state that handles escaped slashes and character classes, so the escaped-slash defect was gone by Phase 1 — this paragraph outlived it. The defect that actually survived was a different one: see the tokenizer note below.)

Phase 2 — Windows. Add windows-latest to CI, running the suites for the ported hooks only.

Be clear about what this proves and what it does not: a real end-to-end git commit on Windows still fails while any applicable hook is zsh. Phase 1's gating helps — a repo triggering no linter hook commits fine — but a Python repo with [tool.ruff] reaches a zsh script that Windows cannot execute. So Phase 2 demonstrates the always-on path, and Phase 3 is a prerequisite for Windows being genuinely usable, not an optional extra, if the goal is "work on Windows" rather than "the framework is portable".

Done when: the ported hooks are green on windows-latest, and the doc says plainly which hooks a Windows user cannot yet run.

Phase 3 — linter orchestration. Port the nine pre-commit-*.zsh. Optional only if Windows is a "commit hygiene" goal; mandatory if a Windows user must be able to commit to a repo that uses any of these linters (see Phase 2). Done when: zsh is absent from the repo entirely, and requirement 1 holds for every repo rather than for the framework.

Phase 4 — retire the shell test suite (optional). Port tests/*.zsh to cargo test. Deliberately last: those tests are the migration harness, and rewriting them early would remove the net while walking the wire.

Done, and it stopped being optional the moment Windows mattered. The suites are crates/greengate/tests/it/ and crates/greengate-fleet/tests/it/, each Repo an isolated temp repository so they run in parallel — which the old one-repo-per-suite runner could not, and which is why several old cases depended on state left by earlier ones. Windows CI runs the full suite rather than a smoke, because the tests no longer need an interpreter Git for Windows does not ship.

Rollout to existing repos

96 local repos hold copies from git init time. The established recipe (compare each installed copy against every historical blob of that file, replace only exact matches so a customised copy is never clobbered) applies unchanged to the shims — see the propagation note in the ban-terms memory. Survey found zero customised copies, twice.

After Phase 0 the shims are stable, so subsequent phases need no repo sweep: updating the binary updates every repo at once.

Decisions to make before starting

  1. Binary name. git-hooks collides conceptually with git hooks (git may resolve git-hooks as a subcommand). Prefer something unambiguous.

  2. One binary or one per hook? One, with the hook name as argv[1]. Five binaries would mean five downloads and five things to keep in sync.

  3. Config format. The zsh hooks read git config (hook.skip). Keep that, or introduce a .amont.toml? Keeping git config avoids inventing a second source of truth and preserves git -c hook.skip=… push.

  4. MSRV and dependency budget. regex and ignore (ripgrep's own crates) cover matching and file walking. Resist more.

  5. Does Windows need the linter hooks? Determines whether Phase 3 is optional or mandatory — see Phase 2. If a Windows user must commit to a repo using ruff/eslint/prettier, Phase 3 is part of the Windows story, not a follow-up, and the honest total cost is ~1,500 lines rather than ~700.

  6. Do the shims keep their .zsh / .js suffixes? RESOLVED: no, they were dropped after Phase 4.

    The rest of this answer was wrong, and is corrected rather than deleted because somebody will otherwise rely on it. It said "the suffix STRIPPING in main.rs stays permanently — a repo seeded before the rename still passes the old filename through". There is no such stripping, and there never was. registry::lookup is an exact match against ENTRYPOINTS and the check names; a repo still holding pre-commit-ruff.zsh hands the binary a name it does not know, and gets unknown hook and exit 2.

    That is deliberate and it is fine, because the repair path is the fleet, not a compatibility shim in the binary. greengate-fleet fix / install is what moves the 96 repos, and Repo::stale_ours — "our files that we no longer ship" — is exactly the field that finds those leftovers and turns them into a removal. The binary and the repos DO move independently; the mechanism is a sweep with a plan you can read first, not silent name rewriting inside the hook that runs on every commit.

Honest cost

~700 lines of shell/JS to port for Phase 1, plus a release pipeline that must be maintained forever. Against that: the framework stops imposing node and zsh on every commit, Windows becomes a build target, and the BSD/GNU divergence class disappears — that class produced two of the three bugs CI found on its first two runs (realpath -s, and the \w-vs-POSIX-class dialect split).

If Phase 1 alone lands, the framework stops imposing anything and Phase 4 stays optional. Phases 2-3 are optional only if Windows is not a real target; if it is, budget for Phase 3 too — roughly 1,500 lines rather than 700.


Outcome

All 20 hooks are sh shims over one dependency-free binary (~430 KB). A repo that triggers no linter needs neither zsh nor node to commit or push, which was the requirement. Phase 2 (Windows CI) and Phase 3 (the nine linter hooks) landed too, so zsh is gone from the hook set entirely.

What the plan got wrong

"All 14 zsh suites passing is Phase 0 done." They were necessary but not sufficient: every suite invokes a SUB-HOOK directly, so the dispatchers — the exact code Phase 0 replaced — had no coverage at all. Phase 0 had to bring its own tests.

The safety rule contradicted itself. "Existing tests pass unchanged" only holds if every hook keeps a file at its original path; the plan said Phase 1 would delete the scripts. Corrected before implementation: porting replaces the body with a shim, never deletes the file. ~20 shims, not 4.

"Phase 1 delivers no zsh." The dispatcher still globs and spawns pre-commit-* scripts, which need zsh before they can no-op. Phase 1 removes the UNCONDITIONAL dependency; full removal needed Phase 3.

Phase 3 was listed as optional. It is a prerequisite for Windows being usable, not an extra — a real commit there fails while any applicable hook is zsh.

What the method actually caught

Seven bugs in code that had already shipped:

  • four hooks used rg unguarded — a missing rg makes ! rg … true, so branch-pattern rejected EVERY branch name (silent wrong answers, not errors);
  • make test had never run on a clean macOS (realpath -s is GNU-only);
  • CI could not go red (make test | tee without pipefail);
  • [] is truthy in JS, so run-tests-js selected every package regardless of what changed;
  • prepare-commit-msg appended a dangling Issue: #id (tested $? after a pipeline ending in head -n 1);
  • pull-rebase read the ahead-count with head -c 1, so 12 printed as "1";
  • 54 of 96 installed commit-msg copies matched no known template blob and were silently skipped by the propagation sweep.

Plus five in the ports themselves, each caught by the existing suite before merge, and three tests that could not fail (the dispatchers had none; pull-rebase's dirty-tree case was satisfied by an unrelated early exit; my own Windows smoke read a commit subject without first asserting the commit existed).

Two bugs were found only by the Windows leg, on its first two runs — and both were silent-wrong rather than loud. which missed .exe, so resolve_tool would have skipped the repo's PINNED linter for an ambient one. And Windows has no shebang support, so every sub-hook the dispatcher spawned failed with %1 is not a valid Win32 application.

Rules worth keeping

  1. A hook is not ported until its existing test passes untouched — then break the implementation once to confirm the test can fail. Vacuous tests are the characteristic failure here.
  2. "Verified against the original first" is only as good as the environment it was verified in. A kubeconform test asserting silence encoded the machine it was written on; CI has neither tool, hits the gate first, and warns.
  3. A sweep reporting "0 customised" is not proof of a clean fleet. Check the DISTINCT-BLOB count per hook; consistent means 1.
  4. For hooks that REWRITE (commit-msg) or filter (ban-terms), diff the old and new implementations over the same inputs. Both were byte-identical across 11 and 14 cases.

Still open

  • Phase 4 — port the 19 zsh suites to cargo test. Done. They are crates/*/tests/*.rs, and Windows runs them all.

  • The ban-terms tokenizer. Done. The documented defect (escaped slash in a regex) turned out to be already fixed by the port's Regex state — the note was stale. Probing 20 hard constructs found the real survivor: template literal substitutions were blanked as string content, so any banned call written inside ${…} was missed. Now handled as code, with a DEPTH STACK because substitutions nest.

    Differential over 39,378 real fleet files: blanking changed on 10,567 of them, with 0 new alarms and 0 dropped detections — the path is heavily exercised and the stricter rule costs nothing in false positives.

  • The rename. Done. Shims carry no extension; scripts/propagate.sh swept all 96. The sharp edge was the dispatcher's <hook>-* GLOB: a repo left holding both pre-commit-ruff.zsh and pre-commit-ruff runs ruff TWICE, silently. Removal and installation therefore happen per repo, in that order, which is why the sweep is a script and not a typed loop.

  • pre-commit-pyright in 6 of 96 repos Done — it self-scopes on a pyright config, so installing it everywhere changes nothing for the 90 repos without one. governance-ts had it for months and it never fired.

Checks moved in-process (PR #36)

Git invokes exactly four hook names — pre-commit, pre-push, commit-msg, prepare-commit-msg. The other 16 files in every .git/hooks were our own dispatcher's business: byte-identical sh shims whose only job was to re-exec the binary and tell it their own filename. One commit cost 27 processes to run work the binary already had in a table.

Fleet-wide 1920 files → 384; steady-state pre-commit ~383 ms → ~293 ms. Most of a commit is the linters, so 24% is the whole timing prize; the structural wins are larger: order is declared rather than emerging from a lexicographic filename glob, the Windows shebang emulation is deleted, and stdin is read once.

That last one fixed a silent bug. git feeds pre-push its ref list on stdin, consumable once. As separate processes with INHERITED stdin, whichever check ran first drained it — two repos carried a pre-push-branch-protect.sh sorting before pre-push-run-tests-js, so the JS gate saw EOF and ran nothing, for as long as both existed.

branch-protect is now built in, first in pre-push, protecting main/master everywhere; it matches the REMOTE ref and treats a delete as a write.

Rust checks (PR #38)

checkdispatchercommand
pre-commit-cargo-fmtpre-commitcargo fmt --all -- --check
pre-commit-clippypre-commitcargo clippy --workspace --all-targets --all-features -- -D warnings
pre-push-cargo-testpre-pushcargo test --workspace --all-features

Split by cost as the other languages are: fmt/clippy with ruff and pyright, test with run-tests-js. Three separate checks so hook.skip disables them individually. Scoping runs on the nearest ancestor Cargo.toml, not the repo root, so a Rust component in a subdirectory works; --workspace covers the members from there. Cargo.toml/Cargo.lock count as touching Rust for clippy.

Two bugs the tests caught:

  1. Availability was probed with cargo <sub> --version. That works for rustfmt and clippy, which are separately installable components, but cargo test --version is "unexpected argument" — so the probe reported test as unavailable and the gate silently passed. It would never have run a test in any repo. Built-in subcommands need no probe; only components do.

  2. git exports GIT_DIR/GIT_INDEX_FILE/GIT_WORK_TREE to every hook, and they OVERRIDE the working directory. Running a project's test suite from a hook therefore hands it the hook's repository. This repo's own suite creates throwaway repos and commits to them — so the first real run of the gate put a stray commit, authored by the test fixture, onto a live branch and pushed it. strip_git_env now clears them before spawning any tool, npm included; a suite must behave exactly as it does when run by hand.

propagate.sh is gone (PR #47)

Replaced by greengate-fleet fix, after a differential proved the Rust plan removes exactly the same set on a fixture covering every actionable case. That comparison is what earned the deletion; the expectation it produced is kept as a golden test, because deleting the gate along with the script would have thrown away the only evidence the rewrite was faithful.

make propagate now runs the Rust path. Dry-run by default, APPLY=1 to write.

Why the dependency guard exists (corrected)

scripts/check-no-deps.sh asserts that greengate resolves to nothing outside the workspace. Its original comment said the migration existed because a Python repo needed node and zsh to commit, so a dependency tree "would undo it".

That reasoning was wrong and is corrected in the script. node and zsh were RUNTIME requirements — they had to exist on PATH in every repo or the hook failed. A Rust crate is compiled in and statically linked; adding serde would make nobody install anything. The two are not the same problem.

The guard is still worth having, for reasons that survive scrutiny:

  1. Supply chain. The binary runs on every commit in 96 repos, with the developer's credentials, reading every staged file. Every transitive crate is code executing in that position. This argument is specific to THIS binary — greengate-fleet pulls ratatui and a dozen crates without concern, because it is opt-in.
  2. Offline reproducibility. A std-only crate builds without a registry, indefinitely. Real but modest.
  3. A forcing function. It makes each dependency in the commit path an argued decision rather than a default.

So it is a strong default to argue with, not a wall. If the commit path ever needs a real parser, weigh that crate's tree against the code it replaces. The answer today is still "hand-roll the twenty lines", because the config format under discussion is trivial — not because a dependency is forbidden.