ai-repo-sanitize：从 git 历史中安全清除 AI 署名

ai-repo-sanitize

Last reviewed: 2026-10-09

Safely strip AI attribution trailers from git history — preview, rewrite, verify, publish. A check mode for CI, a rewrite mode that never pushes unless you say so, and a commit-msg hook that keeps new trailers out.

The default is no: nothing is rewritten and nothing is pushed unless you pass the explicit flags.

Why this repo

A live blog post documented what happens when an AI agent signs your commits: GitHub's contributors widget listed the agent beside the author, the commit history carried a Co-authored-by: trailer and a "Ultraworked with ..." branding line, and hundreds of similar complaints were filed against coding agents. The cleanup sequence the article develops — backup, preview, message-only rewrite, tree verification, force-with-lease push — is exactly what this tool automates, with the safety gates made mandatory instead of optional.

• Article: When an AI Agent Signs Your Commits
• The removal pattern this tool applies is the single source of truth in src/ai_repo_sanitize/patterns.py, mirrored by the article's example.

Design principles

• Tested, not trusted — the test suite runs on every push and pull request across Python 3.10-3.14, including an end-to-end rewrite exercised against a local bare remote; no code path ships without a test.
• Research-based — every mechanism traces to a RESEARCH.md decision and an empirical verification: the silent parser bug, the bad action SHAs, the missing PYTHONPATH, the remote-URL parsing bug, the YAML-anchor failure, the URL-checker backtick capture (RESEARCH.md §2).
• Check-the-checker — the docs validator, the freshness gate, the doc-coverage checker, and the doc-claims checker are themselves unit-tested, so the guards cannot rot.
• Portable — stdlib-only runtime, POSIX-only hooks and greps (never -P or \b), macOS/BSD-safe, Python 3.10+.

Modes

What gets removed (see src/ai_repo_sanitize/patterns.py — the single source of truth):

• Co-authored-by: trailers that name a known agent (sisyphus, claude, opencode, codex, copilot, cursor, devin). Human Co-authored-by: trailers are preserved.
• (ultraworked|generated|assisted) with ... branding lines.

Only the matching lines are dropped; subjects, bodies, and line-ending style (CRLF included) are preserved.

Install

uv tool install .            # or: pip install .
uv tool install git-filter-repo   # external tool, used only by `rewrite`

git-filter-repo is deliberately a dev-tool dependency, not a runtime one: the rewrite path fails with an install hint if it is missing.

Quickstart

ai-repo-sanitize check --path .        # exit 1 if attribution is found
ai-repo-sanitize preview --path .      # list matching commits, subject only
ai-repo-sanitize rewrite --path . \
  --remote-url your-owner/your-repo --backup-dir /tmp/copy \
  --branch master                       # rewrite messages, push nothing
ai-repo-sanitize rewrite --path . --remote-url ... --backup-dir ... --push

Run ai-repo-sanitize --help for every flag (including --nudge-cache, the opt-in GitHub sidebar-cache refresh, documented in RESEARCH.md).

Hooks

git config core.hooksPath .githooks

• pre-commit runs the fast gates (ruff, ty, docs validator).
• commit-msg rejects AI-attribution trailers at commit time. Use --no-verify only in a documented emergency.

Validation

The canonical gate — run all four, in this order, before claiming completion:

uv run ty check
uv run ruff check .
uv run pytest
uv run python scripts/validate-docs.py

scripts/validate-docs.py is the drift guard: it fails when README or CONTRIBUTING stop listing these commands, when the required docs disappear, when ci.yml or the pre-commit hook drift from the canonical commands, or when an internal link breaks. If a command above stops being the truth, the repository tells you instead of the docs silently rotting.

Exit codes

scripts/validate-docs.py and scripts/verify-urls.py also exit 0/1.

Architecture

src/ai_repo_sanitize/
  patterns.py    the one attribution pattern set — the contract of this tool
  git_utils.py   thin shell-free wrappers around git subprocesses
  verify.py      the two invariants: same tree, no attribution remains
  rewrite.py     git-filter-repo wrapper; callback generated from patterns.py
  publish.py     re-add origin, fetch, --force-with-lease push
  platform.py    token-aware GitHub contributors snapshot + opt-in cache nudge
  pipeline.py    run_check / preview / run_rewrite — every mode shares the checks
  cli.py         argparse front end; exit codes 0/1/2

Every mode reuses the same checks from verify.py; the pipeline never re-implements an invariant a second way.

Documentation

Maintainer ownership

See also

• py-review-skill — the Python review checklist this project's quality gates are modelled on.
• repo-architecture-skill — the documentation conventions this README follows.

License

MIT — see LICENSE.