monochromatic-git-policy-cli 0.2.5

Repository-owned Git policy wrapper: forwards Git commands and checks commits against configured policies.
Documentation

monochromatic-git-policy-cli

A Git wrapper that enforces repository-owned policies. It is installed as git ahead of the real Git on PATH, forwards every command to the real Git, and checks the commands and the commits that pass through it against policies the repository configures as data.

The executable is cli-git-native. The library inside the crate is named git_policy_cli.

What it does

Every Git command goes through the wrapper first. Read-only commands, and commands the wrapper has no rule for, run the real Git unchanged.

  • Rules before forwarding. require-root demands the repository top level as the working directory. linked-worktree-only keeps every command form that can discard uncommitted work out of the main worktree, and out of a linked worktree while it holds uncommitted work (see "Discarding commands"). branch-worktree-only sends branch creation through git worktree add. add-explicit rejects bulk staging patterns such as git add ..
  • Commits as transactions. A git commit is prepared in a private index and a shadow repository. Hooks run there, the content policies check the exact bytes, and only then is the commit landed on the real index and branch. When another commit lands first, the wrapper replays its own commit on top of the new state. Concurrent commits from several worktrees or sessions therefore never overwrite each other. A transaction that an interrupted process left behind is recovered by the next invocation.
  • Content policies. final-newline, markdown/autofix, mono/forbidden-root-context, mono/dependent-version-bump and security/forbidden-strings check or rewrite what a commit contains. The same content policies scan what a manual git push newly publishes.
  • After a landed commit. The wrapper checks the committed bytes again, then pushes the branch. A branch without an upstream is pushed to origin with --set-upstream when that remote exists. A branch with an upstream is pushed to it. When the remote refuses that push because its branch moved after the commit landed, the wrapper merges the remote tip into the branch tip from Git objects alone and pushes the merge without force, at most three times. While the merge is computed and pushed, the local branch, the index, the worktree and untracked files are not read or changed, so another session's uncommitted files cannot block the push. Afterwards the local branch follows the published merge by a fast-forward when nothing can be lost: a worktree with uncommitted work follows too, as long as the move writes none of the files that work touches, and the report says the work was left as it is. Otherwise the branch stays behind and the report names the overlapping files. A conflict is reported with the conflicting paths and publishes nothing. An amended or rebased branch is not merged, and its rejection is shown as before. A failed push never fails the commit, and no configuration key turns the push off. Automatic maintenance, as native Git runs it after a commit, runs after each landing, because a landing stores its objects in one new pack.
  • Linked worktrees. When a Git command creates a linked worktree, the wrapper copies the ignored state of the source worktree into it under one settlement lock per repository.
  • Signals. The wrapper catches SIGINT, SIGTERM, SIGHUP and SIGQUIT while it waits for Git. A signal sent by another process is relayed to the Git child, and the wrapper then releases its locks and removes its transaction instead of leaving it for recovery.

Requirements

  • Linux with glibc 2.39 or newer. Release archives exist for x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu only. They are built on the ubuntu-latest runner and link pidfd_spawnp and pidfd_getpid, which glibc added in 2.39 (measured on the 0.2.2 x86_64 archive with objdump -T), so they do not start on Debian 12 or Ubuntu 22.04. The crate does not compile for Windows: cargo check --target x86_64-pc-windows-gnu --lib fails with 16 errors in eight files (the tempfile and ignore dependencies are unix-only and several modules use std::os::unix), so the Windows-specific branches in the sources have never run; each is marked UNTESTED ON WINDOWS in the source. A Windows port is deferred to a later version (owner decision, 2026-10-15).
  • Real Git 2.55.0 or newer on PATH after the wrapper. The wrapper checks the version before work that depends on Git's behavior, such as a commit, and refuses older Git. The wrapper finds the real Git by walking PATH, skipping itself and any shim that leads back to it.
  • monochromatic-lint on an absolute PATH entry, only when markdown/autofix is configured.
  • The scanner is linked into the executable and needs no separate installation.

Install

The crate is published on crates.io. Install it as a cargo: tool of mise, the way the repository installs monochromatic-lint:

# mise.toml
[tools]
"cargo:monochromatic-git-policy-cli" = { version = "0.2.5", os = ["linux"] }

mise install downloads the release archive of the crate's GitHub release when one exists for the host. Otherwise it compiles the crate from source with the Rust toolchain. cargo install monochromatic-git-policy-cli --locked compiles the same executable into ~/.cargo/bin.

The installed file is cli-git-native, not git. Link it as git in a directory that comes before the real Git on PATH:

# Run in the repository once per checkout, after the installation.
mkdir --parents .cache/cli-git-bin
ln --symbolic --force "$(mise which cli-git-native)" .cache/cli-git-bin/git

Never name a file git inside the tool's own bin/ directory. mise would then create a git shim for the whole account, and every Git command would run through the wrapper.

PATH shadowing covers only processes that find git through PATH. An absolute path to the real Git, a PATH without the link directory, a GUI with an embedded Git library and direct libgit2 consumers bypass the wrapper completely, including its recovery of interrupted commits and its policies.

Commands

The wrapper adds one namespace to Git.

# Check or fix the whole repository, or the named pathspecs.
git cli-git check --all
git cli-git fix -- docs/ README.md
git cli-git check --all --policy final-newline
git cli-git --help

Exactly one scope is required: --all, or pathspecs after --. --policy <id> limits the run to one policy and may be repeated. Events are JSON lines on standard output.

The former trust, untrust and status commands are retired. Configuration is data, so nothing needs approval. They print an explanation and change nothing.

Wrapper-only options

A wrapper-only option is removed before Git sees the arguments and applies to that one invocation.

  • --no-enforce-<policy id> skips one policy, for example --no-enforce-final-newline or --no-enforce-security/forbidden-strings.
  • --no-enforce-worktree skips linked-worktree-only for the forms listed in "Discarding commands". Write it directly after the subcommand, for example git restore --no-enforce-worktree -- <path>.
  • --no-enforce-worktree-branch skips branch-worktree-only.
  • --no-enforce-bulk-add skips add-explicit.
  • --no-worktree-copy skips the ignored-state copy into a new linked worktree.
  • --cli-git-keep-going reports every finding of the command in one run instead of stopping at the first blocking one.

Discarding commands

linked-worktree-only rejects a command form that can overwrite or delete uncommitted work by itself. The rule is:

  • In the main worktree such a form is always rejected, clean or not.
  • In a linked worktree it is rejected while the worktree holds uncommitted tracked changes (for git clean, also untracked files), and runs when the worktree is clean.
  • A form that only moves HEAD (git checkout <branch>, git switch <branch>) is rejected in any worktree only while it holds uncommitted tracked changes.
  • A status Git cannot read stops the command instead of reading as clean.
  • Repositories under an allowlisted tool cache are exempt.

Every rejection names the form, what it would destroy, the alternative that fits the most likely intent, and the deliberate way to discard anyway. The deliberate way is always the same: save a copy (git diff > backup.patch) and pass --no-enforce-worktree directly after the subcommand. git apply backup.patch brings the edits back.

Each decision about a discarding form (rejected, run in a clean worktree, run in an exempt cache, or run with the escape) is appended as one JSON line to cli-git-audit.jsonl in the common Git directory, with the time, the process and its parent, the worktree kind, the form, the working directory and the arguments. When uncommitted work disappears, git rev-parse --git-common-dir locates the file; a line that says allowed or hatch near the time of the loss names the command that was let through. The file moves aside to cli-git-audit.jsonl.1 at one mebibyte, and a failed write never changes a command's result.

The forms and their alternatives follow. Each alternative is run through the built executable by src/native/binary_discard_tests.rs.

  • git stash (every form except list, show and create): commit work in progress with explicit paths on a topic branch in its own linked worktree (git worktree add -b <branch> <path>).
  • git clean without --dry-run: git clean -n lists what would go, delete specific files with rm, or use the project's own clean task.
  • git reset --hard, --merge, --keep: git reset --soft <commit> undoes a commit and keeps its changes, git diff <commit> compares, git worktree add <path> <commit> gives a clean copy.
  • git reset in the default or --mixed mode: git commit --message <message> -- <paths> commits only the named paths and ignores other staged entries, git diff --cached --name-only lists what is staged.
  • git restore --staged (unstaging): the same two commands as git reset.
  • git restore and git checkout with paths, --force, --patch, --ours or --theirs (reverting files): git diff -- <path> and git show HEAD:<path> compare, git worktree add <path> <branch> opens another branch, or save a patch and use the hatch.
  • git checkout <branch> and git switch <branch> while the worktree is dirty, and git switch --force: commit with explicit paths first, or open the branch with git worktree add <path> <branch>.
  • git rm --force: git rm <path> refuses a modified file, and git rm --cached <path> stops tracking and keeps the file.
  • git mv --force: pick a destination that does not exist, or git rm <destination> first.
  • git checkout-index --force: git checkout-index --prefix=<directory>/ --all writes copies elsewhere.
  • git read-tree --reset: git read-tree -m merges, or reset in a clean linked worktree.
  • git merge --abort, git rebase --abort, git cherry-pick --abort, git revert --abort, git am --abort: the same command with --quit stops the operation and keeps the index and files, --continue finishes it after resolving conflicts, and --skip drops the current commit or patch.

The forms are read with Git's own option grammar, so abbreviations, clustered short flags (-rf) and a path after -- are handled as Git handles them. Commands without a table of their own (rm, mv, checkout-index, read-tree, restore and the --abort commands) take the hatch directly after the subcommand.

Output and exit status

Policy events of a wrapped command are JSON lines on standard error, one object per line, with schemaVersion 1. Real Git keeps the normal standard streams.

  • When real Git does not run: 0 means clean or warnings only, 1 means final error findings, and 2 means a usage, configuration, transaction or engine failure.
  • When real Git runs, its exit status is preserved. A landed commit that a post-commit policy then blocks exits 2 and stays local.

Configuration

The wrapper reads cli-git.config.jsonc at the repository top level. The file is JSON with comments, at most 1 MiB, and it is data: it never names code to run. Without the file, the defaults apply. The former TypeScript wrapper read cli-git.config.mjs and cli-git.config.ts; those files are never executed or read. With no JSONC file beside them, they are a configuration failure that asks for the translation. Beside a JSONC file, they are reported and ignored. The keys plugins and trust are refused.

// cli-git.config.jsonc
{
  "policies": {
    // A severity alone: "off", "warn" or "error".
    "final-newline": "error",
    // A severity with options.
    "markdown/autofix": ["warn", { "rules": ["lfs-image-url"], "exclude": ["package/ssg/"] }],
    "mono/forbidden-root-context": "error",
    "mono/dependent-version-bump": "error",
    "security/forbidden-strings": ["error", { "builtinRules": true, "rulesFile": ".cache/forbidden-strings.rules.txt" }]
  },
  "hooks": { "concurrentCommits": false },
  "indexLock": { "unprovenOwnerTimeoutMs": 1000 },
  "landing": { "reserveAfterLostRaces": 1 }
}

An unknown key, a wrong type or an unknown policy id is a configuration failure that exits 2 before any policy runs.

Policies

The wrapper ships these policies and no others. The first five run at their default severity without being listed. The last four run only where the file lists them.

  • require-root: default error.
  • linked-worktree-only: default error.
  • branch-worktree-only: default error.
  • add-explicit: default error.
  • final-newline: default warn. Text files end with exactly one line feed.
  • markdown/autofix: default warn. Runs monochromatic-lint --fix over staged Markdown inside the commit. Options: rules (only lfs-image-url exists) and exclude (gitignore-style patterns).
  • mono/forbidden-root-context: default error. No CONTEXT.md at the repository top level enters a commit.
  • mono/dependent-version-bump: default error. Packages that depend on a package with a bumped version follow the bump.
  • security/forbidden-strings: default error. Scans candidate bytes and path names with the linked scanner. Options: builtinRules (boolean, load the scanner's built-in baseline) and rulesFile (a rules file path relative to the repository top level). The rules file is rulesFile, else the environment variable FORBIDDEN_STRINGS_RULES, else forbidden-strings.local.txt in the repository top level, which may be absent. A file named by rulesFile or by the variable must exist.

A warn setting reports findings without blocking. A policy whose protection warn would remove produces a configuration warning event when the file sets it to warn.

Concurrency

  • hooks.concurrentCommits: boolean, default false. false serializes the hooks of concurrent commit transactions; true lets them overlap.
  • indexLock.unprovenOwnerTimeoutMs: non-negative integer, default 1000. How long the wrapper backs off for an index.lock whose owner is dead or unproven.
  • landing.reserveAfterLostRaces: positive integer, default 1. How many lost landing races pass before a transaction asks for the landing reservation.

The concurrent transaction itself cannot be turned off.

Waiting and time limits

The wrapper never waits for another process without a limit. Three environment variables set the limits, each a positive whole number of seconds; a zero, negative, fractional or non-numeric value is ignored.

  • CLI_GIT_LOCK_WAIT_SECONDS, default 1800. How long a command waits for a lock that a live process holds: the capture, landing, hook and registry locks, the landing reservation, the worktree-copy settlement and a live index.lock holder. After five seconds of waiting the command prints one line naming the process and the limit. At the limit it stops with a message that names the holder, leaves the lock in place and changes nothing else, so the command can simply be run again.
  • CLI_GIT_PUSH_DEADLINE_SECONDS, default 600. How long the push after a landed commit may run before it is stopped. The commit stays saved, the failure is reported, and git push can be run by hand. Git's own read-only queries before the push stop at this deadline or 120 seconds, whichever is shorter.
  • CLI_GIT_PUSH_LOCK_WAIT_SECONDS, default the push deadline plus 65. How long a commit waits behind another process's push before it gives up and reports its push as failed.

A command that passes through to Git unchanged, and the user's own hooks, run as long as they run and receive Ctrl-C like any Git command.

State on disk

The wrapper keeps its state beside the repository's Git data under cli-git* paths in the common Git directory. Delete nothing there while a Git command is running. The next invocation recovers what an interrupted one left.

The ignored-state copy into a new linked worktree stages its files in a .cli-git-worktree-copy-* directory beside the new worktree, which can hold gigabytes. The wrapper records that directory's name in the common Git directory before it creates it, so a copy that was killed while staging cannot leak it: the next invocation in the repository removes the directory and says so on stderr. Delete a .cli-git-worktree-copy-* directory by hand only when no git command is running in that repository.

Development

The commands below run in the repository that holds the crate, Aquaticat/Monochromatic, from the repository top level. Every task runs through mise.

# Run from the repository top level.
mise run //package/git-policy/cli:native:check
mise run //package/git-policy/cli:native:clippy
mise run //package/git-policy/cli:native:build
mise run //package/git-policy/cli:native:test:host -- <test name filter>
mise run //package/git-policy/cli:native:test:binary:host -- <test name filter>
mise run //package/git-policy/cli:native:test:container
  • native:check type-checks every target. native:clippy lints every target with warnings denied. native:build writes the debug executable to package/git-policy/cli/target/debug/cli-git-native.
  • native:test:host runs the unit tests and native:test:binary:host runs the tests that start the built executable, both against the host's Git while iterating.
  • native:test:container is the authority. It builds the crate and runs the tests and Clippy in bounded containers with Git 2.56.0 and no network. Set GIT_POLICY_NATIVE_IMAGE_TAG=<name> to keep the images of parallel runs apart.
  • native:format formats the Rust sources. native:lock:members records a changed dependency list or version in Cargo.lock without moving any other locked version.

A release build of the executable:

# Run in package/git-policy/cli.
cargo build --release --locked --bin cli-git-native

The release profile keeps panic = "unwind" and overflow-checks = true. The linked scanner turns a matcher panic into a failing finding by catching the unwind, and the crate refuses to compile under panic = "abort".

License

LGPL-3.0-or-later. The license texts are in LICENSES/.