将 AI 快速生成的 Git commits 转换为符合人工开发节奏的提交历史
- 🤖 使用 Agent Skill? → 查看 agent-skill/ 目录
- 💻 命令行使用? → 继续阅读本文档
- 📚 详细文档? → 查看 docs/ 目录
git-fisher/
├── agent-skill/ # 📦 完整的 Agent Skill 包（核心代码在这里）
│ ├── git_humanize/ # 核心源码
│ ├── setup.py # 安装脚本
│ ├── skill.json # Skill 定义
│ └── ...
│
├── docs/ # 📚 额外文档
│ ├── QUICKSTART.md # 快速开始
│ └── ...
└── ...
- 复制
agent-skill文件夹到你的 Claude skills 目录 - 进入该目录运行
pip install -e . - 即可在 Claude 中使用
/git-fisher命令
进入 agent-skill 目录安装核心工具：
cd agent-skill
pip install -e .然后使用 git-humanize 命令。
- 🕐 智能时间调度：根据代码量和复杂度自动估算开发时间
- 📅 工作时间建模：自动避开午休、周末和法定节假日
- 🎯 复杂度评估：基于代码行数、文件类型和提交类型的智能分析
- 🔒 安全操作：自动备份、dry-run 模式、一键回滚
- ⚙️ 灵活配置：支持多层级配置（全局/项目/命令行）
- 🤖 AI 优化：Agent 模式无需 API Key，直接使用 Claude 能力
## 🤖 Agent Skill 使用（推荐）
### 快速开始
1. **将项目添加到 Claude 的 skills 目录**
2. **关注 `agent-skill/` 目录** - 这是 Agent Skill 的专用文件夹
3. **直接用自然语言与 Claude 交互**
### 使用示例
请帮我预览一下这些 commits 调整后的时间分布
帮我将这些 AI 生成的 commits 转换为人工开发节奏
请优化这些 commits 的 messages，使其符合 Conventional Commits 规范
### 详细文档
- **快速入门**: [agent-skill/README.md](agent-skill/README.md)
- **完整文档**: [agent-skill/SKILL.md](agent-skill/SKILL.md)
- **Agent 使用指南**: [docs/AGENT_USAGE.md](docs/AGENT_USAGE.md)
## 🚀 快速开始（命令行）
```bash
# 基础使用 - 预览模式（不会实际修改）
git-humanize
# 执行转换（会实际修改 git 历史）
git-humanize --no-dry-run
# 自定义工作时间
git-humanize --work-hours "9-18" --lunch-break "12:00-13:00"
# 添加真实感的"摸鱼"时间
git-humanize --add-breaks
# 调整开发速度系数
git-humanize --speed-factor 1.2
# AI 在 20 分钟内生成了 500 行代码
# 但这在现实中可能需要 4 小时开发时间
git-humanize --speed-factor 0.8 --no-dry-run# 1) 先做规划（默认从最早未 push 提交时间开始排期）
git-humanize --dry-run
# 2) 查看 git log，确认时间线合理后手动 push
# 如有问题，使用备份分支回滚再调整参数# 10 个小提交需要分散到一整天
git-humanize --add-breaks --no-dry-rungit-humanize --country US --timezone "America/New_York" --no-dry-run# 使用规则自动规范化 commit message（添加 conventional commits 前缀等）
git-humanize --optimize-message --no-dry-run
# 使用 AI 智能优化 commit message（需要设置 ANTHROPIC_API_KEY）
export ANTHROPIC_API_KEY="your-api-key"
git-humanize --ai-optimize-message --no-dry-run
# 先预览 AI 优化效果
git-humanize --ai-optimize-message --dry-run💡 通过 Claude Agent 使用时更简单：
如果您通过 Claude Code (Agent) 使用 Git Fisher，无需配置 API Key！直接告诉 Agent：
请帮我优化这些 commits 的 messages，使其符合 Conventional Commits 规范
Agent 会使用自己的能力来分析和优化，详见 AGENT_USAGE.md。
创建 ~/.git-humanize.json:
{
"speed_factor": 0.8,
"work_hours": "9-18",
"lunch_break": "12:00-12:30",
"country": "CN",
"skip_weekends": true,
"timezone": "Asia/Shanghai",
"add_breaks": false
}💡 提示: 可以复制 .git-humanize.json.example 作为起点。
在项目根目录创建 .git-humanize.json（会覆盖全局配置）
export GIT_HUMANIZE_SPEED_FACTOR=0.8
export GIT_HUMANIZE_WORK_HOURS="9-18"git-humanize --speed-factor 1.0 --work-hours "10-19"命令行参数 > 项目配置 > 全局配置 > 环境变量 > 默认值
| 参数 | 说明 | 默认值 | 示例 |
|---|---|---|---|
--repo-path |
Git 仓库路径 | 当前目录 | --repo-path /path/to/repo |
--speed-factor |
开发速度系数（0.5=超快，1.5=保守） | 0.8 | --speed-factor 1.2 |
--work-hours |
工作时间范围（24小时制） | "9-18" | --work-hours "10-19" |
--lunch-break |
午休时间段 | "12:00-12:30" | --lunch-break "12:00-13:00" |
--country |
国家代码（用于节假日识别） | "CN" | --country US |
--timezone |
时区 | "Asia/Shanghai" | --timezone "America/New_York" |
--add-breaks |
添加休息时间（每2小时10-20分钟） | false | --add-breaks |
--optimize-message |
使用规则优化 commit message | false | --optimize-message |
--ai-optimize-message |
使用 AI 优化 commit message | false | --ai-optimize-message |
--dry-run |
预览模式（不实际修改） | true | --no-dry-run |
--backup |
创建备份分支 | true | --no-backup |
--start-time |
指定开始时间 | 最早未 push 提交时间 | --start-time "2024-01-15 09:00" |
--include-overflow |
包含超出当天窗口提交 | false | --include-overflow |
--force-fit-today |
自动加速适配当天窗口 | false | --force-fit-today |
--branch |
指定分支 | 当前分支 | --branch develop |
--stats |
显示统计信息 | true | --no-stats |
--config |
自定义配置文件路径 | - | --config custom.json |
- 10-50 行：0.5 小时
- 50-200 行：1-2 小时
- 200-500 行：2-4 小时
- 500+ 行：4-8 小时
- 配置文件：×0.5
- 测试文件：×0.7
- 业务代码：×1.0
- 架构重构：×1.5
fix/bugfix：×0.8refactor：×1.2feat/feature：×1.3test：×0.6docs：×0.3
- 扫描 Git 仓库，识别未 push 的 commits
- 分析每个 commit 的代码量（行数变化）
- 识别文件类型（配置/测试/业务代码/架构）
- 识别 commit 类型（feat/fix/refactor/test/docs）
- 根据代码量计算基础开发时间
- 应用文件类型权重调整
- 应用 commit 类型权重调整
- 应用用户自定义的速度系数
- 将 commits 分类为 tiny/small/medium/large/xlarge
- 根据复杂度分配合理的时间间隔
- 确保所有 commits 在工作时间内（如 9:00-18:00）
- 自动跳过午休时间（如 12:00-12:30）
- 自动跳过周末和法定节假日
- 可选添加"摸鱼"休息时间（每2小时休息10-20分钟）
- 使用
git filter-branch安全重写 Git 历史 - 修改每个 commit 的 author date 和 committer date
- 可选优化 commit message 格式
- 保持原有的 commit SHA、内容和顺序不变
- 显示修改前后的时间对比
- 统计时间跨度变化
- 提供备份分支信息
- 验证所有 commits 都在合理时间内
- 评估：自动估算未 push commits 的工作量
- 规划：默认从最早未 push 提交时间开始排期（跨周末自动跳过）
- 处理：仅对计划内提交进行时间重写与 message 优化
- 确认：用户查看
git log，确认无误后手动git push
- 只处理“当天能完成”的提交，超出部分保持不动
- 输出明确提示：“剩余 X 个提交建议明天再处理”
- 若需包含超出部分，可使用
--include-overflow
当计划内/超出混在一起时，建议采用如下方式隔离提交（不会丢失提交）：
# 1) 备份当前分支（保留全部提交）
git branch backup/full-commits
# 2) 回到远端基线（使用当前跟踪分支）
git reset --hard @{u}
# 3) 仅恢复计划内提交（按旧→新顺序）
git cherry-pick <sha1> <sha2> <sha3>
当用户必须当天提交时，可使用 --force-fit-today 启用加速模式自动降低 speed_factor，直到全部提交能排进当天工作时间。
- 建议最小速度系数：
0.5 - 若仍无法排入当天，提示失败并建议分天处理
- 推荐安装
pre-pushhook，阻止推送计划外提交 - 可提供
GIT_HUMANIZE_BYPASS=1作为临时绕过方式
在执行实际重写前，建议确认以下条件：
git status工作区干净- 当前分支有上游跟踪分支（
@{u}可用） - 先执行一次
--dry-run预览 - 确认已创建备份分支（如
backup/<branch>-<timestamp>） - 任何问题可用
git reset --hard <backup-branch>回滚
若满足以下任一条件，应直接拒绝执行并提示用户修复：
- 工作区不干净
- 当前分支没有上游跟踪分支
- 发现已 push 的提交（不允许重写）
- 未能创建备份分支
- 自动备份：执行前自动创建
backup/<branch>-<timestamp>分支 - Dry-run 模式：默认预览模式，需明确使用
--no-dry-run才实际执行 - 仅处理未 push：不会修改已经推送到远程的提交
- 一键回滚：执行失败时提供恢复命令
git reset --hard <backup-branch> - 仓库状态检查：执行前验证工作区是否干净
- 只读操作：预览模式完全不修改 Git 历史
工具使用 workalendar 库支持 100+ 个国家和地区的法定节假日识别：
亚洲: CN (中国), JP (日本), KR (韩国), IN (印度), SG (新加坡), TH (泰国), VN (越南), MY (马来西亚), PH (菲律宾), ID (印度尼西亚)
欧洲: GB (英国), DE (德国), FR (法国), IT (意大利), ES (西班牙), NL (荷兰), SE (瑞典), NO (挪威), DK (丹麦), FI (芬兰)
美洲: US (美国), CA (加拿大), BR (巴西), MX (墨西哥), AR (阿根廷), CL (智利), CO (哥伦比亚)
其他: AU (澳大利亚), NZ (新西兰), ZA (南非), RU (俄罗斯)
完整列表请参考: https://github.com/workalendar/workalendar
A: 不会。工具只处理尚未推送到远程仓库的 commits。
A: 工具会自动创建备份分支（如 backup/main-20240115_143022），执行 git reset --hard <backup-branch> 即可恢复。
A: 不会。只修改时间戳（可选修改 message 格式），commit SHA、代码内容、文件变更、顺序都保持原样。
A: 为了安全。用户可以先查看修改计划，确认无误后再使用 --no-dry-run 执行实际修改。
A: 使用 --speed-factor 参数：
0.5= 超快开发者（代码量估时 × 0.5）0.8= 快速开发者（默认）1.0= 正常速度1.5= 保守估计（代码量估时 × 1.5）
A: 支持所有 pytz 时区，常用的如：
Asia/Shanghai(中国)America/New_York(美国东部)Europe/London(英国)Asia/Tokyo(日本)
完整列表: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
A: 提供两种优化方式：
规则优化 (--optimize-message)：
- 首字母大写
- 移除主题行末尾的句号
- 智能添加 conventional commits 前缀（feat:, fix:, docs: 等）
- 确保主题行和正文之间有空行
- 支持中英文关键词识别
AI 优化 (--ai-optimize-message)：
- 使用 Claude AI 分析 commit 内容
- 自动生成规范的 commit message
- 智能推断 commit 类型和描述
- 支持中英文，保持原语言风格
- 需要设置
ANTHROPIC_API_KEY环境变量
A:
- 获取 Anthropic API Key（访问 Anthropic Console）
- 设置环境变量：
export ANTHROPIC_API_KEY="your-api-key" - 使用参数：
git-humanize --ai-optimize-message --dry-run（先预览） - 确认无误后执行：
git-humanize --ai-optimize-message --no-dry-run
A: 不建议。此工具主要用于个人开发分支。在团队共享分支上修改历史会导致协作问题。
解决: 确保在 Git 仓库目录中运行，或使用 --repo-path 指定正确路径。
解决:
- 确认有本地提交尚未推送到远程
- 使用
git log origin/main..HEAD查看未推送的 commits
解决:
- 执行
git status检查未提交的更改 - 提交或暂存更改后再运行工具
解决:
- 检查
--work-hours和--lunch-break设置 - 调整
--speed-factor参数 - 使用
--start-time指定起始时间
解决:
- 确认
--country参数设置正确 - 某些国家可能有地区差异，参考 workalendar 文档
欢迎提交 Issue 和 Pull Request！
⚠️ 此工具仅用于未 push 的提交，已推送的提交不应修改⚠️ 执行前会创建备份分支，但仍建议手动备份重要工作⚠️ 不建议在团队共享分支上使用⚠️ 修改 Git 历史属于高级操作，使用前请充分理解其影响- ✅ 最适合个人开发分支、学习项目或实验性项目
MIT License