QUICKSTART.md

Git Fisher 快速开始 🎣

将 AI 快速生成的 commits 转换为符合人工开发节奏的提交历史

📦 一键安装

# 克隆仓库
git clone https://github.com/andrewhe/git-fisher.git
cd git-fisher

# 安装工具（开发模式）
pip install -e .

# 验证安装
git-humanize --help

🤖 Agent Skill 使用（推荐）

前提条件

• 项目已在 Claude Code 的全局 skills 目录
• skill.json 和 git_fisher_skill.py 在项目根目录

调用方式

方式 1: Slash 命令

/git-fisher

方式 2: 自然语言

帮我预览一下这些 commits 的时间分布

请帮我下班前规划提交

强制今天完成提交，添加摸鱼时间

🚀 命令行使用

基础流程（推荐）

# 1️⃣ 预览模式（默认，不会修改）
git-humanize

# 2️⃣ 确认无误后执行
git-humanize --no-dry-run

# 3️⃣ 查看结果
git log --oneline --date=format:'%Y-%m-%d %H:%M' --pretty=format:'%h %ad %s'

# 4️⃣ 手动 push
git push

常用场景

场景 1: AI 快速生成代码后

# AI 在 20 分钟内生成了 500 行代码
# 调整为看起来像 4 小时的开发过程
git-humanize --speed-factor 0.8 --no-dry-run

场景 2: 添加"摸鱼"时间

# 每 2 小时添加 10-20 分钟休息时间
git-humanize --add-breaks --no-dry-run

场景 3: 自定义工作时间

# 10-19 工作时间，12:00-13:00 午休
git-humanize --work-hours "10-19" --lunch-break "12:00-13:00" --no-dry-run

场景 4: 强制今天完成

# 自动加速，将所有 commits 排进今天
git-humanize --force-fit-today --no-dry-run

⚙️ 全局配置（推荐）

创建 ~/.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
}

📊 核心参数

参数	说明	默认值	示例
--speed-factor	开发速度系数	0.8	--speed-factor 1.2
--work-hours	工作时间范围	"9-18"	--work-hours "10-19"
--lunch-break	午休时间段	"12:00-12:30"	--lunch-break "12:00-13:00"
--add-breaks	添加休息时间	false	--add-breaks
--force-fit-today	强制今天完成	false	--force-fit-today
--dry-run	预览模式	true	--no-dry-run

🛡️ 安全机制

• ✅ 默认预览模式：需明确使用 --no-dry-run 才实际执行
• ✅ 自动备份：执行前自动创建 backup/<branch>-<timestamp> 分支
• ✅ 仅处理未 push：不会修改已推送到远程的提交
• ✅ 一键回滚：git reset --hard <backup-branch>

🔄 回滚方法

如果执行后发现问题：

# 查看备份分支
git branch | grep backup

# 回滚到备份（替换为实际的备份分支名）
git reset --hard backup/main-20240115_143022

⚠️ 注意事项

• ⚠️ 仅用于未 push 的提交
• ⚠️ 不建议在团队共享分支使用
• ⚠️ 修改 Git 历史属于高级操作，使用前请充分理解其影响
• ✅ 最适合个人开发分支、学习项目或实验性项目

📚 更多信息

• 完整文档：查看 README.md
• Skill 使用：查看 SKILL_USAGE.md
• 项目主页：https://github.com/andrewhe/git-fisher