commit-rewriter · 干货攻略

链接: https://x.com/simonw/status/2099310866021916710
分类: x-tips
来源: X @simonw
作者: Jay
更新: 2026-09-15
仓库: simonw/commit-rewriter

这是什么

commit-rewriter 是 Simon Willison（@simonw）9 月 14 日发布的本地 Web 应用，用于批量编辑 Git 仓库的提交信息。核心使用场景是：Coding Agent 生成的提交记录往往带有大量"机器腔"——冗长的内部 ID 引用、不适合公开的 issue 编号、重复的 agent 生成 boilerplate。Simon 本人用它清理 Datasette 安全版本发布时的提交记录，将一批"不适合发布"的 commit message 改写成干净可读的对外版本。

文件命名 slug：simonw-commit-rewriter（仓库全名规范 slug）

为什么值得关注

Coding Agent 的工程化落地正在催生一系列"后处理"工具链。Agent 写代码很快，但 commit message 质量普遍是痛点——要么过于冗长，要么暴露内部信息。commit-rewriter 解决的是这个链路上的最后一公里：在保持 Git 历史完整性的前提下，对批量提交记录进行人工审核式编辑。

相比 git rebase -i，它的核心优势是所见即所得的 Web UI + 操作原子性保证： - 可以看到每条 commit 的完整 diff 和当前 message - 支持搜索过滤（按 message 内容、author、hash） - 改完后一键重写，工具自动处理链式依赖

核验过程

官方来源（已读取）：

GitHub README（https://raw.githubusercontent.com/simonw/commit-rewriter/main/README.md） - 确认 v0.1，Apache 2.0 许可证 - 确认 CLI 入口：uvx commit-rewriter /path/to/repo，默认 127.0.0.1:8000 - 确认安装方式：pip install commit-rewriter 或 uv tool install commit-rewriter - 确认特性：Web UI + 自动创建 backup branch + 支持 --port 切换端口
pyproject.toml（https://raw.githubusercontent.com/simonw/commit-rewriter/main/pyproject.toml） - Python >= 3.11 - 依赖：starlette>=0.47,<1、uvicorn>=0.35,<1 - 无其他第三方依赖（实现相当轻量） - 打包资源：index.html、app.js（前后端一体的单文件 Web 应用）
核心源码 commit_rewriter/__init__.py（~300 行） - 确认安全机制：
- CSRF token 校验（每个会话 32 字节 URL-safe token）
- 只允许 localhost 访问（TrustedHostMiddleware）
- Content Security Policy 严格限制
- 确认 rewrite 安全保障：
- 操作前检查：非 shallow clone、无 unmerged 文件、无进行中 Git 操作（rebase/merge/bisect 等）
- 先创建 timestamped backup branch（如 commit-message-backup/2026-09-15-123045-123456-abc123）
- 使用 git update-ref 的 compare-and-swap 模式确保原子性
- GPG 签名和 mergetag 在 rewrite 时被移除（源码注释明确说明）
- 确认 Git 操作范围：仅限 main 分支、最近 100 条 commit
- 确认改写链式逻辑：从用户编辑的第一条 commit 到最新 commit 的完整链都会重写（不是单条孤立修改）
PyPI 页面（https://pypi.org/project/commit-rewriter/） - 确认包名 commit-rewriter，版本 0.1，正常发布状态

交叉验证： - Simon 博客（https://simonwillison.net/2026/Sep/14/commit-rewriter/）与 GitHub README 内容一致，确认是同一天（Sep 14, 2026）正式发布 - shot-scraper 1.12 发布说明（同一博客 9/13）确认 Simon 用 shot-scraper 拍了 commit-rewriter 的产品截图

上手步骤

安装（任选一种）

# 方式1：通过 uvx 直接运行（无需安装）
uvx commit-rewriter /path/to/your-repo

# 方式2：安装为本地工具
uv tool install commit-rewriter
commit-rewriter /path/to/your-repo

# 方式3：pip 安装
pip install commit-rewriter
commit-rewriter .

基本使用

# 进入目标仓库目录
cd your-project

# 启动（默认端口 8000）
uvx commit-rewriter

# 切换端口（如 8002）
uvx commit-rewriter -p 8002

启动后打开 http://127.0.0.1:8000，会看到： - 左侧：最近 100 条 commit 列表（带 hash、作者、时间） - 主面板：每条 commit 的可编辑 message 框 + 查看 diff 的 toggle - 工具栏：pending edits 计数、Discard drafts / Rewrite commit messages 按钮

编辑流程： 1. 在 UI 中修改想要改的 commit message 2. 点击 "Rewrite commit messages" 3. 工具先创建 timestamped backup branch，再执行 rewrite 4. 完成后可切到 backup branch 确认，或继续在 main 上工作

运行测试

uv run pytest

坑与适用边界

适用场景 ✅ - Coding Agent 提交记录的清理（如 Datasette 安全发布案例） - 批量重写一段时间内的 commit message（如统一风格、去除内部信息） - 提交信息中含有敏感内容（issue ID、内部代号）需要对外发布前的脱敏

不适用/限制 ⚠️ - 不支持非 main 分支：代码硬编码 ref = "refs/heads/main"，其他分支无法使用 - 不保留 GPG 签名：重写后原有 GPG signed commit 的签名会被移除（源码明确注释） - 仅支持最近 100 条：git log -100 硬限制，更早的 commit 不可见 - 不处理 rebase/merge 状态：有进行中的 rebase、cherry-pick、merge 等操作时拒绝执行 - 不支持 shallow clone：完整 clone 才能工作 - 无 GitHub/GitLab 远程操作：纯本地工具，不涉及 remote

安全注意 🔒 - 默认只监听 127.0.0.1，不暴露到网络 - CSRF token 每个会话随机生成，与 Git repo identity SHA256 绑定 - CSP 严格限制脚本来源

一句话结论

commit-rewriter 是 Coding Agent 时代必备的 Git 提交记录清理工具——轻量（仅 2 个依赖）、安全（原子性 rewrite + 自动 backup）、所见即所得的 Web UI，300 行 Python 实现，值得加入日常工具链。