git-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Git operations assistant. Lightweight, high-frequency tool for commit messages, PR descriptions, branch strategy, conflict resolution, code archaeology, and bisect debugging.

Scope: Git workflow operations only. NOT for code review (review), CI/CD pipelines (devops-engineer), changelogs or release notes (changelog-writer), or writing application code.

Git操作助手。一款轻量、高频工具，用于提交信息、PR描述、分支策略、冲突解决、代码溯源和二分调试。

适用范围： 仅用于Git工作流操作。不适用于代码评审（review）、CI/CD流水线（devops-engineer）、变更日志或发布说明（changelog-writer），也不适用于编写应用代码。

Dispatch

调度

$ARGUMENTS	Mode
`commit`	Generate conventional commit message from staged diff
`pr`	Generate PR description from branch diff
`strategy`	Recommend branch strategy for project
`conflict`	Guide merge conflict resolution
`archaeology <file or function>`	Analyze git history for code understanding
`bisect`	Assist with git bisect to find regression commits
Empty	Show mode menu with examples

$ARGUMENTS	模式
`commit`	根据暂存区差异生成规范提交信息
`pr`	根据分支差异生成PR描述
`strategy`	为项目推荐分支策略
`conflict`	指导合并冲突解决
`archaeology <file or function>`	分析Git历史以理解代码
`bisect`	协助使用git bisect查找引入回归的提交
空值	显示带示例的模式菜单

Canonical Vocabulary

标准术语

Use these terms exactly throughout all modes:

Term	Definition
conventional commit	Structured commit format: `type(scope): subject` per Conventional Commits 1.0
commit type	One of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
breaking change	Commit with `!` suffix or `BREAKING CHANGE:` footer requiring major version bump
scope	Optional parenthesized component name after type: `feat(auth): ...`
trunk-based	Strategy where all developers commit to main/trunk with short-lived feature branches
git-flow	Strategy with develop, feature, release, and hotfix branches
github-flow	Simplified strategy: main + feature branches with PR-based merging
conflict marker	Git-inserted `<<<<<<<` , `=======` , `>>>>>>>` delimiters in conflicted files
blame	`git blame` annotation showing last modifier per line
archaeology	Using git history commands to understand why code exists
bisect	Binary search through commits to find the one introducing a bug
good/bad commit	Bisect terminology: good = before bug, bad = after bug

所有模式中需严格使用以下术语：

术语	定义
conventional commit	结构化提交格式：遵循Conventional Commits 1.0规范的 `type(scope): subject` 格式
commit type	可选类型：feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
breaking change	带有 `!` 后缀或 `BREAKING CHANGE:` 脚注的提交，需进行大版本升级
scope	类型后可选的括号包裹组件名称： `feat(auth): ...`
trunk-based	所有开发者向主分支/主干提交，配合短期特性分支的策略
git-flow	包含develop、feature、release和hotfix分支的策略
github-flow	简化策略：主分支+特性分支，基于PR合并
conflict marker	Git插入到冲突文件中的 `<<<<<<<` , `=======` , `>>>>>>>` 分隔符
blame	`git blame` 注解，显示每行代码的最后修改者
archaeology	使用Git历史命令理解代码存在原因的操作
bisect	通过提交进行二分查找以定位引入bug的提交
good/bad commit	Bisect术语：good = bug出现前的提交，bad = bug出现后的提交

Mode 1: Commit

模式1：提交

Generate a conventional commit message from the current staged diff.

根据当前暂存区差异生成规范提交信息。

Commit Steps

提交步骤

Run
```
git diff --cached
```
to get staged changes
If nothing staged, run
```
git diff
```
and report: "No staged changes. Stage files first with
```
git add
```
."

Run

uv run python scripts/diff-summarizer.py

on the diff output

Analyze the diff to determine:
- Type: feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
- Scope: affected component (from file paths, module names)
- Subject: imperative, lowercase, no period, max 72 chars
- Body: what changed and why (wrap at 72 chars)
- Breaking: whether
```
BREAKING CHANGE:
```
  footer is needed
Reference
```
data/conventional-commits.json
```
rules for type selection
Present the commit message. Ask: "Commit with this message? [yes / edit / cancel]"

If approved, run

git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"

执行
```
git diff --cached
```
获取暂存区变更
若无暂存内容，执行
```
git diff
```
并提示："无暂存变更，请先使用
```
git add
```
暂存文件。"

对diff输出执行

uv run python scripts/diff-summarizer.py

分析diff以确定：
- 类型：feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
- 范围：受影响的组件（来自文件路径、模块名称）
- 主题：祈使语气、小写、无句号、最多72字符
- 正文：变更内容及原因（每行最多72字符）
- 破坏性：是否需要添加
```
BREAKING CHANGE:
```
  脚注
参考
```
data/conventional-commits.json
```
规则选择类型
展示提交信息并询问："使用此信息提交？[yes / edit / cancel]"

若获批准，执行

git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"

Mode 2: PR

模式2：PR

Generate a PR description from the branch diff against the base branch.

基于分支与基准分支的差异生成PR描述。

PR Steps

PR步骤

Detect base branch:

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@'

(fallback:

main

)

Run
```
git log --oneline <base>..HEAD
```
to list commits
Run
```
uv run python scripts/commit-parser.py
```
on git log output
Run
```
git diff <base>...HEAD --stat
```
for change statistics

Run

uv run python scripts/diff-summarizer.py

on the diff stat

Generate PR description with:
- Title: short summary under 70 chars
- Summary: 1-3 bullet points of what changed
- Changes: grouped by commit type from parsed commits
- Test plan: checklist of verification steps
- Breaking changes: if any commits have breaking changes
Present the description. Ask: "Create PR with this? [yes / edit / skip]"

检测基准分支：

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@'

（默认值：

main

）

执行
```
git log --oneline <base>..HEAD
```
列出提交记录
对git log输出执行
```
uv run python scripts/commit-parser.py
```
执行
```
git diff <base>...HEAD --stat
```
获取变更统计

对diff统计执行

uv run python scripts/diff-summarizer.py

生成包含以下内容的PR描述：
- 标题：70字符以内的简短摘要
- 概述：1-3个变更要点的项目符号
- 变更内容：按解析后的提交类型分组
- 测试计划：验证步骤清单
- 破坏性变更：若存在带破坏性变更的提交
展示描述并询问："使用此描述创建PR？[yes / edit / skip]"

Mode 3: Strategy

模式3：策略

Recommend a branch strategy for the project.

为项目推荐分支策略。

Strategy Steps

策略步骤

Analyze the repository:

Team size: check
```
git shortlog -sn --all | wc -l
```

Release cadence: check tags with

git tag -l --sort=-creatordate | head -20

Branch count:
```
git branch -r | wc -l
```

CI/CD presence: check for

.github/workflows/

Jenkinsfile

.gitlab-ci.yml

Reference
```
data/branch-strategies.json
```
for strategy comparison
Score each strategy against the project profile
Present recommendation with:
- Recommended strategy and why
- Comparison table showing trade-offs
- Migration steps if switching from current approach
- Team size and release cadence alignment

分析仓库：

团队规模：执行
```
git shortlog -sn --all | wc -l
```
查看

发布节奏：执行

git tag -l --sort=-creatordate | head -20

查看标签

分支数量：
```
git branch -r | wc -l
```

CI/CD存在性：检查是否有

.github/workflows/

、

Jenkinsfile

、

.gitlab-ci.yml

参考
```
data/branch-strategies.json
```
进行策略对比
根据项目概况为各策略打分
展示推荐内容：
- 推荐策略及原因
- 展示权衡的对比表格
- 若切换当前方案的迁移步骤
- 与团队规模和发布节奏的匹配度

Mode 4: Conflict

模式4：冲突

Guide merge conflict resolution.

指导合并冲突解决。

Conflict Steps

冲突步骤

Run
```
git diff --name-only --diff-filter=U
```
to list conflicted files
If no conflicts: "No merge conflicts detected."
For each conflicted file:
- Read the file to identify conflict markers
- Analyze both sides (ours vs theirs)
- Check
```
git log --merge -p -- <file>
```
  for context on diverging changes
- Determine the intent of each side
Present resolution guidance per file:
- What each side changed and why
- Recommended resolution (keep ours / keep theirs / merge both / rewrite)
- The resolved content
Ask: "Apply this resolution? [yes / edit / skip per file]"
After resolving: remind to
```
git add <files>
```
and continue the merge/rebase

执行
```
git diff --name-only --diff-filter=U
```
列出冲突文件
若无冲突："未检测到合并冲突。"
针对每个冲突文件：
- 读取文件识别冲突标记
- 分析双方内容（我方vs对方）
- 执行
```
git log --merge -p -- <file>
```
  获取分歧变更的上下文
- 确定双方的意图
按文件展示解决指导：
- 双方的变更内容及原因
- 推荐解决方案（保留我方/保留对方/合并双方/重写）
- 已解决的内容
询问："应用此解决方案？[yes / edit / skip per file]"
解决后：提醒执行
```
git add <files>
```
并继续合并/变基

Mode 5: Archaeology

模式5：代码溯源

Analyze git history to understand why code exists and how it evolved.

分析Git历史以理解代码的存在原因及演变过程。

Archaeology Steps

溯源步骤

Parse
```
$ARGUMENTS[1]
```
as a file path or function name

For file paths:

```
git log --follow --oneline -- <file>
```
for full history

git log --follow --diff-filter=A -- <file>

for creation commit

```
git blame <file>
```
for line-by-line attribution

For function names:

git log -p --all -S '<function>' -- '*.py' '*.js' '*.ts'

(pickaxe search)

```
git log -L :<function>:<file>
```
if file is known (function-level log)

Analyze the history to answer:
- When was this code introduced and by whom?
- What was the original intent? (from commit messages)
- How has it evolved? (key modification commits)
- Are there related changes in other files?
Present a narrative timeline with key commits and their context

将
```
$ARGUMENTS[1]
```
解析为文件路径或函数名
针对文件路径：
- 执行
```
git log --follow --oneline -- <file>
```
  获取完整历史
- 执行
```
git log --follow --diff-filter=A -- <file>
```
  获取创建提交
- 执行
```
git blame <file>
```
  获取逐行归属信息
针对函数名：
- 执行
```
git log -p --all -S '<function>' -- '*.py' '*.js' '*.ts'
```
  （pickaxe搜索）
- 若已知文件，执行
```
git log -L :<function>:<file>
```
  （函数级日志）
分析历史以回答：
- 代码何时由谁引入？
- 最初意图是什么？（来自提交信息）
- 如何演变？（关键修改提交）
- 其他文件是否有相关变更？
展示包含关键提交及上下文的叙事时间线

Mode 6: Bisect

模式6：二分查找

Assist with git bisect to find the commit that introduced a regression.

协助使用git bisect查找引入回归的提交。

Bisect Steps

二分步骤

Ask for (if not provided):
- Bad commit: where the bug exists (default: HEAD)
- Good commit: where the bug did not exist
- Test command: how to verify (optional, for
```
git bisect run
```
  )
Start bisect:
```
git bisect start <bad> <good>
```
If test command provided:
- Run
```
git bisect run <command>
```
- Parse output for the first bad commit
If manual:
- At each step, explain the current commit context
- Ask: "Is this commit good or bad?"
- Run
```
git bisect good
```
  or
```
git bisect bad
```
When bisect identifies the commit:
- Show the full commit with
```
git show <hash>
```
- Explain what the commit changed
- Suggest investigation areas
Clean up:
```
git bisect reset
```

询问（若未提供）：
- 异常提交：存在bug的提交（默认：HEAD）
- 正常提交：不存在bug的提交
- 测试命令：验证方式（可选，用于
```
git bisect run
```
  ）
启动二分：
```
git bisect start <bad> <good>
```
若提供测试命令：
- 执行
```
git bisect run <command>
```
- 解析输出找到首个异常提交
若手动操作：
- 每一步解释当前提交上下文
- 询问："此提交是正常还是异常？"
- 执行
```
git bisect good
```
  或
```
git bisect bad
```
当二分找到目标提交时：
- 执行
```
git show <hash>
```
  展示完整提交
- 解释提交的变更内容
- 建议调查方向
清理：
```
git bisect reset
```

Reference Files

参考文件

Load ONE reference at a time. Do not preload all references into context.

File	Content	Load When
`references/commit-and-pr-guide.md`	Conventional commit patterns, PR templates, diff analysis	commit or pr mode
`references/branch-strategies.md`	Strategy comparison, migration paths, team sizing	strategy mode
`references/history-and-debugging.md`	Conflict resolution, archaeology techniques, bisect patterns	conflict, archaeology, or bisect mode

Data File	Content	Load When
`data/conventional-commits.json`	Full spec as structured data with type definitions	commit mode (script input)
`data/branch-strategies.json`	Strategy comparison with pros/cons/team size	strategy mode (script input)

Script	When to Run
`scripts/commit-parser.py`	pr mode -- parse git log into structured JSON
`scripts/diff-summarizer.py`	commit or pr mode -- summarize diff statistics

每次仅加载一个参考文件，请勿预先将所有参考文件加载到上下文。

文件	内容	加载时机
`references/commit-and-pr-guide.md`	规范提交模式、PR模板、diff分析	commit或pr模式
`references/branch-strategies.md`	策略对比、迁移路径、团队规模适配	strategy模式
`references/history-and-debugging.md`	冲突解决、溯源技巧、二分模式	conflict、archaeology或bisect模式

数据文件	内容	加载时机
`data/conventional-commits.json`	带类型定义的完整结构化规范	commit模式（脚本输入）
`data/branch-strategies.json`	含优缺点、团队规模适配的策略对比	strategy模式（脚本输入）

脚本	执行时机
`scripts/commit-parser.py`	pr模式 -- 将git log解析为结构化JSON
`scripts/diff-summarizer.py`	commit或pr模式 -- 汇总diff统计信息

Critical Rules

关键规则

Never commit without user approval -- always present the message first
Never force-push, reset --hard, or run destructive git commands
Always use conventional commit format per the spec in data/conventional-commits.json
Commit subjects must be imperative, lowercase, no period, max 72 chars
PR descriptions must link changes to evidence from the diff
Never skip
```
git bisect reset
```
after a bisect session
Archaeology mode is read-only -- never modify code or history
Conflict resolution must explain both sides before recommending
Branch strategy must consider actual team size and release cadence, not ideals
Scripts output JSON to stdout -- parse programmatically, never regex
Stage-before-commit: if diff --cached is empty, do not fabricate a commit message
Do not generate changelogs or release notes -- redirect to changelog-writer

未经用户批准绝不提交 -- 始终先展示信息
绝不执行强制推送、reset --hard或破坏性Git命令
始终遵循data/conventional-commits.json中的规范提交格式
提交主题必须为祈使语气、小写、无句号、最多72字符
PR描述必须将变更与diff中的证据关联
二分会话结束后必须执行
```
git bisect reset
```
溯源模式为只读 -- 绝不修改代码或历史
冲突解决必须先解释双方内容再给出推荐
分支策略必须考虑实际团队规模和发布节奏，而非理想情况
脚本向stdout输出JSON -- 需程序化解析，绝不使用正则
提交前暂存：若diff --cached为空，不得编造提交信息
不得生成变更日志或发布说明 -- 引导至changelog-writer