Git Finalizer
Authorization-boundary Git delivery for developers and coding agents: stage exactly the files you name, create the commit, push only when the remote provably accepts a non-force fast-forward, and then verify the live remote instead of trusting the push exit status.
Git Finalizer does not run tests, review code, resolve conflicts, call a model, create releases, or decide on your behalf. It performs one Git write you explicitly authorized and reports what actually happened in machine-readable JSON. Authorization comes from the caller: an existing task grant can cover consecutive deliveries within its stated scope; passing tests does not create a new grant.
Current source version: 2.0.0.
当前版本:2.0.0
This is the source version. Source delivery and local installation do not imply a GitHub tag, release or downloadable asset.
Detailed rules for unified-diff artifacts, already reviewed merges and remote synchronization are in docs/advanced-modes.md; exact content reviews and scanner classifications are in docs/content-review.md.
Why it exists
Ordinary git commit && git push does not check whether the staged files match the reviewed scope,
whether hooks changed that content, or whether earlier unpublished commits are safe to publish.
Git Finalizer turns these into explicit gates with precise blockers, so both a human in a
terminal and an automation layer can rely on "it stopped, and here is why".
- Explicit scope. Files are listed after
--;git add .andgit add -Aare never used. - Explicit authorization. Commit-only, verify-only and publication are separate requests, and a commit authorization is never widened into a push authorization.
- Non-force, branch-only publication with tag following disabled, then live remote
post-verification (
HEAD = upstream = remote OID,ahead/behind = 0/0). - Refusals, not repairs. Diverged remote, protected branch, staged surprises, sensitive content, unexplained deletions, oversized binaries and unknown authority state all block instead of being auto-resolved.
- Compare-and-set for governed writes. Branch retirement and lease-bound integration publication require exact expected OIDs and re-check authoritative state under a lock before touching a ref.
- Auditable results. One deterministic JSON object per run with a closed classification triple, documented in docs/agent-contract.md.
- Narrow, explicit reviews. Exceptions to content checks name an exact path, blob and detector; see docs/content-review.md.
Requirements
- Git and POSIX userland utilities; zero GNU-only extension dependencies (portable across Linux and macOS). Verified baseline:
Ubuntu 24.04 LTS with system Git. Plan-bound retirement also requires a Controller that
advertises the public verification and execution protocols. Integration publication requires
integration_publication_execution_version1 and the public locked stdio session. - Python 3.12–3.14 (
>=3.12,<3.15), with the standard library only (zero runtime dependencies;pyproject.tomlexposesgit-finalize,tool-skill-sync, andtool-temp-dirconsole scripts, while repository-root thin wrappers remain executable directly offline). Verified baseline: Python 3.12, including clean installation with no optional tools or personal configuration. - Run as an ordinary user. Git Finalizer has no privilege escalation and no daemon, database or plugin framework.
- Nothing else. No remote hosting service, no Worktree Controller, no Snapshot Runner, no Context Loader, no installed Skill and no agent runtime is required for the core lifecycle. See Standalone contract.
Core Git commands have a 120-second deadline followed by a five-second forced-stop grace period. A timed-out push remains uncertain and retains its local commit for explicit recovery. Content scanning accepts at most 64 MiB per raw file or Git blob, including clean-filter output; larger inputs fail closed without excerpts. This bounds scanner input, not arbitrary hook/filter code or its temporary object output. Existing 5 MiB/25 MiB binary rules remain separate.
The managed production installer coordinates activation and rollback with running Finalizer invocations through a shared execution lock. Active invocations finish before production files are replaced; new invocations wait up to 30 seconds. Source checkouts and manual tarball installs without that lock retain their ordinary installation behavior. The first upgrade from a version without the reader protocol cannot protect invocations already running that older version.
Installation
There is no package index. Releases are published as GitHub Release assets:
each one carries git-finalizer-<version>.tar.gz plus a SHA256SUMS.txt that names it, from
https://github.com/xuanheng-tech/git-finalizer/releases. GitHub carries every release from v1.5.0
onward; earlier versions were published on the governed delivery remote described in
docs/release-governance.md, so they are not listed here. Fetch both,
verify the artifact, then install it. Select an actual published release from that page and set
GF_RELEASE_VERSION to its version number without the v prefix; it can differ from the source
version above.
GF_RELEASE_VERSION='<published-version>'
curl -fsSLO "https://github.com/xuanheng-tech/git-finalizer/releases/download/v${GF_RELEASE_VERSION}/SHA256SUMS.txt"
curl -fsSLO "https://github.com/xuanheng-tech/git-finalizer/releases/download/v${GF_RELEASE_VERSION}/git-finalizer-${GF_RELEASE_VERSION}.tar.gz"
sha256sum --check SHA256SUMS.txt
From the verified tarball (keep src/ beside the entrypoints or install as a Python tool via uv tool install --offline "./git-finalizer-${GF_RELEASE_VERSION}"):
tar -xzf "git-finalizer-${GF_RELEASE_VERSION}.tar.gz"
install -d -m 0755 "$HOME/.local/share/git-finalizer" "$HOME/.local/bin"
cp -R "git-finalizer-${GF_RELEASE_VERSION}/src" "$HOME/.local/share/git-finalizer/"
cp "git-finalizer-${GF_RELEASE_VERSION}/git-finalize" \
"git-finalizer-${GF_RELEASE_VERSION}/tool-skill-sync" \
"git-finalizer-${GF_RELEASE_VERSION}/tool-temp-dir" \
"$HOME/.local/share/git-finalizer/"
ln -sf "$HOME/.local/share/git-finalizer/git-finalize" "$HOME/.local/bin/git-finalize"
export PATH="$HOME/.local/bin:$PATH"
git-finalize --version
The bundle ships the pure-Python git-finalizer package (pyproject.toml, src/git_finalizer/),
the root executable wrappers (git-finalize, tool-skill-sync, tool-temp-dir), and the shared Skill.
During packaging, docs/… links in
the shipped Markdown files become public source links pinned to the release tag. The documentation
stays outside the tarball; checkout links remain relative.
From a checkout:
./git-finalize --version
The package also ships tool-skill-sync and tool-temp-dir, which manage the optional shared
git-change-delivery Skill, multi-client links, and registered /tmp task directories on this machine.
They are not required to use git-finalize; see docs/tool-skill-sync.md.
Quick start
Read-only validation of an explicit candidate scope (no index, HEAD, worktree, ref or remote mutation; requires no upstream):
git-finalize --mode verify-only --repo /absolute/path/to/repo -- src/app.py tests/test_app.py
Verification checks the candidate after Git's clean filters and encoding conversion, including its content signatures and binary size. Its temporary object store is isolated from the repository and removed when the check finishes; hooks and commit signing remain outside verification. If that temporary directory is unavailable, verification reports the missing temporary-write precondition and preserves repository state. Use an executor-authorised writable temporary directory or native channel; permission refusal must not be bypassed.
Local commit only, no remote access at all:
git-finalize --mode commit-only --repo /absolute/path/to/repo \
--message "fix: handle empty response bodies" -- src/app.py tests/test_app.py
Commit and publish, when you have authorization for both and the branch has a configured upstream:
git-finalize --repo /absolute/path/to/repo \
--message "fix: handle empty response bodies" -- src/app.py tests/test_app.py
Publish commits that already exist locally, without creating one:
git-finalize --resume-publish <full-head-oid> --repo /absolute/path/to/repo
First publication of a committed feature branch that has no upstream and no remote counterpart:
git-finalize --publish-existing-branch <full-head-oid> --remote origin \
--remote-branch feat/example --repo /absolute/path/to/repo
Ask for machine-readable output by adding --summary to any of the above. The result is one JSON
object with status, final_phase and next_action even when the run is blocked.
Content refusals and dry-run content risks include an optional diagnostics object identifying
the actual entrypoint and scanner by path and SHA-256, plus the detector, file, scan stage and
exact scanned byte/blob digest. Add --diagnostics to core --summary to include runtime identity
without a content finding. It never includes the matched value or a source excerpt. The existing result triple and
scanner guards are unchanged; see the diagnostics contract.
Modes
| Goal | Interface | Touches the remote |
|---|---|---|
| Validate only | --mode verify-only |
no |
| One local commit only | --mode commit-only |
no |
| Root commit in an unborn repository, local only | --initial-commit-only |
no |
| Commit and publish (default) | no --mode |
yes, non-force |
| First publication of an unborn repository into an empty remote | --initial-publish |
yes |
| First publication of a new branch while creating the commit | --initial-branch-publish |
yes |
| Publish existing commits on a branch with upstream | --resume-publish <oid> |
yes |
| First publication of an existing clean branch | --publish-existing-branch <oid> |
yes |
| Publish existing history into a verified-empty repository | --publish-existing-history <oid> |
yes |
| Recover an interrupted existing-history publication | --resume-existing-history-publish <oid> |
yes |
| Retire an integrated branch ref (local / remote), compare-and-set | --retire-local-branch, --retire-remote-branch |
remote variant yes |
| Plan or create one empty Gitea repository | --repo-plan, --repo-ensure |
repository API only, never commit/push |
The complete per-mode preconditions, guarantees and recovery rules are in
docs/cli-guide.zh.md (中文) and in
tool_cli_contract.json, which is the machine-readable public CLI
contract (contract_version 10).
Agent and automation usage
--summary emits a single deterministic JSON object per run. Classify on the
(final_phase, status, next_action) triple; reason is human-oriented prose that may be localized
and is truncated with the omitted character count reported separately. Exit codes are 0 for
success and 1 for everything else on the bash-owned commands.
- Full vocabulary tables, exit-code mapping and real captured examples: docs/agent-contract.md
- Optional-integration blockers and the adapter boundary matrix: docs/integration-boundaries.md
- Which operation class needs which approval, and who asks the human: docs/authorization-boundary.md
- Work deferred on purpose, each entry with the condition that unblocks it: docs/maintenance-backlog.md
Never upgrade a result. A push.result of uncertain means "not confirmed", not "failed, try
harder": re-inspect the remote with a resume interface rather than force-pushing.
Optional integrations
Every integration below is request-triggered. None of them is a runtime dependency, and a missing dependency produces a precise blocker instead of a degraded success. Worktree Controller in particular is optional: ordinary commit and publication work needs only Bash, Git and Python.
| Integration | Enabled by | Without it |
|---|---|---|
| Worktree Controller governance (branch retirement, integration publication lease, reviewed sensitive-source linkage) | --retire-*, --publish-integration-candidate, --reviewed-sensitive-source |
exact blocker, fail closed |
Snapshot Runner evidence binding (reads through snapshot-runner read on PATH) |
--initial-publish --snapshot <id> |
evidence-required blocker |
| Gitea repository bootstrap | --repo-plan, --repo-ensure with an explicit --gitea-url |
usage error; there is no default host |
| Context Loader | not used at runtime — the CLI never invokes it | nothing |
Shared git-change-delivery Skill |
optional agent workflow documentation and helpers | not a dependency and not an authorization source |
Each integration's knowledge of another project's layout lives only in the adapter modules
under src/git_finalizer/ that carry a single # GF-INTEGRATION-ADAPTER marker per file.
That confinement is machine-checked by tests/test_integration_boundaries.sh.
Coding agents
The CLI uses the same arguments and JSON results for every caller; it does not inspect a model provider, an agent's private session state or its approval settings. A shell-capable agent can use the standalone lifecycle without the optional four-tool workflow.
For Skills, Codex discovers .agents/skills, while
Claude Code discovers .claude/skills. The shared personal
payload can be linked into each client's discovery directory; keep one source and preserve existing
links. Project instructions remain in AGENTS.md. This repository supplies a CLAUDE.md
import (@AGENTS.md) for older Claude clients; the Claude memory documentation
describes both the import and newer native discovery. Other clients can read the same instructions
explicitly according to their own discovery rules.
tool-skill-sync doctor observes instruction fingerprints and pending changes. It supports
CODEX_HOME, CLAUDE_CONFIG_DIR, --codex-home and --claude-home; --agents-root controls the
shared payload without moving either client's configuration. A passing check cannot prove that an
already-running agent reread its context.
Security model
- Branch retirement refuses a protected branch name or the remote's live default branch, and
publishing a first branch refuses protected names; updating the upstream of the branch you
already stand on is deliberately allowed, because that is the ordinary delivery path. Two
interfaces —
--publish-existing-historyand its resume form — may target a protected branch, only while the entire remote is proved empty, or during exact interrupted-publication recovery. Repository creation authority and host owner/name/visibility verification belong to the caller; Git Finalizer verifies the configured Git endpoints, empty remote and exact publication result. Use--repo-plan/--repo-ensurefor Gitea creation, or the host's authorized client for GitHub. - Pushes are non-force with an explicit branch refspec and
--no-follow-tags; deletions are--force-with-lease-style expected-OID compare-and-set, never unconditional force operations. - No amend, rebase, history rewrite, automatic conflict resolution, duplicate commit creation, tag creation or tag pushing. Git Finalizer never creates or pushes tags; a release is a separate, explicit act.
- Credentials are never accepted as arguments, printed, or stored by this tool; repository bootstrap resolves them through your configured Git credential helper and sends them only to the endpoint you named.
- Diff content, commit messages and Snapshot Runner artifacts are data, not instructions. If you route them to an agent, treat them as untrusted input.
- Pending merge, cherry-pick, revert, rebase, sequencer or bisect state blocks commit lifecycle operations. Hooks remain enabled; a created commit must match the checked index tree and parent before publication. Hook failures preserve any commit already created and report its OID.
- Publication checks earlier local commits that are absent from the target remote, as well as the newly staged files. Content signatures are heuristic checks, including quoted JSON assignments; they are not a guarantee that every secret format can be detected.
Please report security issues as described in SECURITY.md.
Standalone contract
The core lifecycle (verify, commit, publish, resume and initial series) runs against an ordinary
repository with no governance tooling, no sibling tools, no installed Skill and no private hosting
configuration. tests/test_standalone_operations.sh proves this in a minimal HOME/PATH
environment, and asserts the mirror property as well: governed requests still fail closed with their
precise blockers and zero mutation in that environment.
Development and releases
just check # shell suites, unit tests, Skill validation, contract check
just lint # shellcheck over the bash entrypoint, scripts and test harness
just release-check # required before tagging; lint and checks with real Controller and Runner
bash tests/run.sh # shell test suites alone
just check ends with a PASS/SKIP/FAIL table, including reasons for each skipped group or unit test.
Optional real-Controller retirement tests and real Snapshot Runner evidence tests are reported as
SKIP when worktree-controller or snapshot-runner is absent from PATH (the Runner suite also
skips as root, which Snapshot Runner refuses). A green check proves the listed executed groups passed; it does not imply skipped
integrations ran. Any executed group failure keeps the check nonzero and stops later groups.
Before creating a release tag, maintainers run just release-check in the clean candidate checkout.
It requires exactly one executed PASS result from each of the real-Controller retirement suite and
the real Snapshot Runner evidence suite; missing, skipped, duplicated or failed results stop release
preparation. Ordinary and hosted just check
keep the standalone contract and optional SKIP behavior.
Contributing guidance, including the hash-bound file rules you must respect when changing the contract or the Skill payload: CONTRIBUTING.md.
Version-relevant work updates, in one preparation batch: the git-finalize VERSION, the companion
VERSION literals, the two current-release declarations above, tool_version in
tool_cli_contract.json and tool_skill_manifest.json, and the matching CHANGELOG.md section.
Different gates own different parts of that list: scripts/release.py preflight <tag> binds the
version literals, the contract digest and the Skill-payload pins, while just check binds the README
declarations and the presence of the CHANGELOG.md section, which the release job then extracts as
the release notes. docs/release-governance.md is the authoritative
list. CHANGELOG.md is the authoritative record and the source of release notes. Merging to the
default branch is not a release: a release happens only when a separately created annotated tag is
pushed, which triggers the release workflow. That workflow re-verifies the version batch, builds a
deterministic tarball, rebuilds it to prove byte-identical output, checks the file set against the
installation contract, and publishes the artifact with SHA256SUMS.txt.
just check deliberately needs only Bash, Git, Python and just, so a clean clone runs the
contract gate without extra tooling; just lint (shellcheck) is a separate CI step. Both hosts —
Gitea Actions (.gitea/workflows/) and GitHub Actions (.github/workflows/) — run the same gates
and the same build recipe through scripts/release.py. Each quality job also runs
tests/test_clean_install.py with Python 3.11 and 3.12, a restricted PATH and an empty user
configuration. It installs only the CLI and companions from a verified source-built bundle,
checks commit/publish/resume, and distinguishes unavailable temporary storage from filter failure.
Before a GitHub release, scripts/release.py publication-status <tag> --remote github observes
the explicit host and reports whether to prepare, inspect an interrupted tag/draft, or verify an
existing release. It requires the existing authorised gh client; core CLI use does not. Recovery
states and the independent source-digest check are in the release runbook below.
By default a version is published on exactly one host. An explicitly authorised mirror uses the same
candidate and annotated tag, independent builds and verified cross-host digest equality.
GitHub is the public distribution entry
(release notes, tarball, checksums); Gitea is the governed delivery remote and holds the
v0.4.0 – v1.4.0 release record. Trigger rules, permissions, cross-host artifact parity, and the
step-by-step first-public-release runbook are in
docs/release-governance.md.
Support
- Supported: the standalone CLI on Linux/POSIX — Bash, Git and Python 3 with the standard library only, verified on Ubuntu 24.04 LTS — and the machine-readable result contract described in docs/agent-contract.md. Only the latest stable release receives fixes.
- Supported as opt-in, not as an upstream promise: Worktree Controller governance, Snapshot Runner evidence binding, Gitea repository bootstrap and the review-file contracts. Git Finalizer guarantees that a missing, unreadable or drifted external authority produces a precise blocker and zero mutation; it does not guarantee that an unpublished or still-moving external contract keeps working, and it will not weaken its own gates to accommodate one.
- Not supported: Windows,
file://or non-HTTP(S) hosting endpoints, destructive Git operations (force push, amend, rebase, history rewrite, tag creation), and any workflow that requires the tool to infer authorization it was not given. - Not a security boundary: the tool executes Git as your own user. Treat repository content, diffs and captured evidence as untrusted input. See SECURITY.md.
License
Apache License 2.0. See LICENSE.
Acknowledgements
Built and hardened through real production delivery use, with adversarial review before every release decision. Git Finalizer belongs to a three-tool family — Snapshot Runner (read-only repository evidence) and Context Loader (deterministic repository context) — each with its own repository; Git Finalizer depends on neither to work.
Metadata
Release files for git-finalizer 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| git_finalizer-2.0.0.tar.gz | 467.1 kB | With provenance | Details for git_finalizer-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| git_finalizer-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for git_finalizer-2.0.0-py3-none-any.whl |
Total release size: 628.5 kB
Release files / git_finalizer-2.0.0.tar.gz
| Download URL | git_finalizer-2.0.0.tar.gz |
|---|---|
| Size | 467.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
893d8d2c001aa249988ab96431a1209348a74b670c91a6aecbdce0dd2fc2150f
|
|
BLAKE2b-256 checksum How to use checksums |
13ff563418a8ce34b0ce6507e8c5a7274b5c2edb9bf2724ea49a553e983f7b27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / git_finalizer-2.0.0-py3-none-any.whl
| Download URL | git_finalizer-2.0.0-py3-none-any.whl |
|---|---|
| Size | 161.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ccf78c94b0e616a6fcbb63450ce4bfefd7f27658cc3a2ebe220dc24f8cdaa068
|
|
BLAKE2b-256 checksum How to use checksums |
ddd2f23d1519e8bdb7bca22f1a5211a20a66957ce69a861d9f2a1cb96579ae16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for git-finalizer 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for git_finalizer-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.