git-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Git workflow automation covering PR lifecycle, branch management, CI monitoring, and review comment handling.

Git工作流自动化，涵盖PR生命周期、分支管理、CI监控以及评审评论处理。

PR Workflow

PR工作流

Create branch (if needed), commit, push, and create/update PR in one command.

一键完成创建分支（如需）、提交、推送以及创建/更新PR操作。

Instructions

操作说明

Run everything as ONE chained command so user approves only once:

bash

git checkout -b <branch> && git add -A && git commit -m "<msg>" && git push -u origin HEAD && bun run gh-tool pr create --base <base> --title "<title>" --body "<body>"

If already on a feature branch, skip
```
git checkout -b
```

Check if PR exists:

bun run gh-tool pr view --json number -q .number 2>/dev/null

If PR exists, use

bun run gh-tool pr edit <pr_number> --title "<title>" --body "<body>"

instead of

bun run gh-tool pr create

Base branch: argument provided by user (default:
```
test
```
)
Branch naming:
```
feat/
```
,
```
fix/
```
,
```
chore/
```
based on changes

所有操作作为一条链式命令执行，用户仅需批准一次：

bash

git checkout -b <branch> && git add -A && git commit -m "<msg>" && git push -u origin HEAD && bun run gh-tool pr create --base <base> --title "<title>" --body "<body>"

若已处于功能分支，则跳过
```
git checkout -b
```

检查PR是否存在：

bun run gh-tool pr view --json number -q .number 2>/dev/null

若PR已存在，使用

bun run gh-tool pr edit <pr_number> --title "<title>" --body "<body>"

替代

bun run gh-tool pr create

基准分支：由用户指定（默认值：
```
test
```
）
分支命名：根据变更类型使用
```
feat/
```
、
```
fix/
```
、
```
chore/
```
前缀

Monitor Checks and Iterate

监控检查与迭代

After pushing, automatically enter the monitoring loop.

Inform the user: "PR created. Monitoring CI checks... (say 'stop' to exit the loop)"

推送完成后，自动进入监控循环。

告知用户："PR已创建。正在监控CI检查...（输入'stop'可退出循环）"

Wait for CI checks to complete

等待CI检查完成

Poll check status every 30 seconds:

bash

bun run gh-tool pr checks --pr <pr_number> --watch

Or manually poll:

bash

bun run gh-tool pr checks --pr <pr_number>

States:

PENDING

QUEUED

→ still running.

COMPLETED

→ check conclusion.

每30秒轮询一次检查状态：

bash

bun run gh-tool pr checks --pr <pr_number> --watch

或手动轮询：

bash

bun run gh-tool pr checks --pr <pr_number>

状态说明：

PENDING

、

QUEUED

→ 检查仍在运行；

COMPLETED

→ 检查已结束，可查看结果。

Handle check results

处理检查结果

If any check fails:

Get the failed check details:

bash

bun run gh-tool pr checks-failed --pr <pr_number>

For build/lint/test failures, fetch logs if available or analyze the error
Fix the issues locally
Run validation command (e.g.,
```
bun run check
```
)
Commit and push the fix
Go back to monitoring to check again

If all checks pass:

Inform user: "All checks passed. PR is ready for review! 🎉"
Exit the loop

若存在检查失败：

获取失败检查详情：

bash

bun run gh-tool pr checks-failed --pr <pr_number>

针对构建/语法检查/测试失败，若有日志则获取日志，或直接分析错误
在本地修复问题
运行验证命令（例如：
```
bun run check
```
）
提交并推送修复
返回监控环节重新检查

若所有检查通过：

告知用户："所有检查已通过。PR已准备好进入评审环节！🎉"
退出循环

Loop exit conditions

循环退出条件

Exit the monitoring loop when:

All checks pass
User says "stop" or requests to exit
Maximum 5 iterations reached (then ask user to continue)

满足以下任一条件时退出监控循环：

所有检查通过
用户输入"stop"或请求退出
达到最大迭代次数5次（之后询问用户是否继续）

PR Body Format

PR正文格式

undefined

undefined

Summary

摘要

<1-2 sentences>

<1-2句话>

Changes

变更内容

<bullet list>

---

<项目符号列表>

---

Push Workflow

推送工作流

Commit all changes and push to current branch in one command.

一键完成所有变更的提交与当前分支推送。

Instructions

操作说明

Run everything as ONE chained command so user approves only once:

bash

git add -A && git commit -m "<msg>" && git push origin HEAD

Commit message: conventional commits (
```
feat:
```
,
```
fix:
```
,
```
chore:
```
, etc.)
If no changes, skip

所有操作作为一条链式命令执行，用户仅需批准一次：

bash

git add -A && git commit -m "<msg>" && git push origin HEAD

提交信息：遵循约定式提交规范（
```
feat:
```
、
```
fix:
```
、
```
chore:
```
等前缀）
若无变更则跳过

Branch Workflow

分支工作流

Create a new feature branch from base, preserving current changes.

Base branch: argument provided by user, or
```
test
```
if not provided
Branch naming:
```
feat/
```
,
```
fix/
```
,
```
chore/
```
based on changes
Infer branch name from changes or ask user

基于基准分支创建新功能分支，保留当前变更。

基准分支：由用户指定，未指定时默认使用
```
test
```
分支命名：根据变更类型使用
```
feat/
```
、
```
fix/
```
、
```
chore/
```
前缀
可根据变更内容自动推断分支名称，或询问用户

Instructions

操作说明

If there are uncommitted changes:

bash

but oplog snapshot -m "before branch switch" && git checkout <base> && git pull origin <base> && git checkout -b <branch-name> && but oplog restore

Note:

but oplog snapshot/restore

is the GitButler-safe alternative to

git stash

(which is banned in GitButler workspaces).

If working tree is clean:

bash

git checkout <base> && git pull origin <base> && git checkout -b <branch-name>

若存在未提交变更：

bash

but oplog snapshot -m "before branch switch" && git checkout <base> && git pull origin <base> && git checkout -b <branch-name> && but oplog restore

注意：

but oplog snapshot/restore

是GitButler工作区中

git stash

的安全替代方案（GitButler工作区禁止使用

git stash

）。

若工作区已清理：

bash

git checkout <base> && git pull origin <base> && git checkout -b <branch-name>

PR Fix Comments Workflow

PR评审评论修复工作流

Fetch PR review comments from AI code review assistants, analyze them, apply valid fixes, respond to comments explaining how they were addressed, then commit and push.

从AI代码评审助手获取PR评审评论，分析评论内容，应用有效修复，回复评论说明修复方式，最后提交并推送。

Step 1: Get PR

步骤1：获取PR

If a PR number is provided as an argument, use that PR number. Otherwise, use the current branch's PR.

If no PR found, inform the user and exit.

若用户提供PR编号参数，则使用该编号；否则使用当前分支对应的PR。

若未找到PR，告知用户并退出。

Step 2: Fetch Review Comments

步骤2：获取评审评论

There are two sources of review feedback:

Inline review threads — code-specific comments attached to file lines
AI reviewer issue comments — general PR comments from bots like
```
claude
```
or
```
sentry-io[bot]
```
(posted as
```
issuecomment-*
```
, not as inline threads)

评审反馈有两个来源：

行内评审线程 —— 附加到文件行的代码特定评论
AI评审者议题评论 —— 来自
```
claude
```
或
```
sentry-io[bot]
```
等机器人的通用PR评论（以
```
issuecomment-*
```
形式发布，非行内线程）

2.1 Check inline review threads

2.1 检查行内评审线程

Fetch unresolved inline review threads:

bash

bun run gh-tool pr threads --pr <pr_number> --unresolved-only

Each thread includes

threadId

commentId

path

line

, and

body

If unresolved comments exist, proceed directly to Step 3.

If the result is empty but you need to verify, re-run the command above to confirm.

获取未解决的行内评审线程：

bash

bun run gh-tool pr threads --pr <pr_number> --unresolved-only

每个线程包含

threadId

、

commentId

、

path

、

line

和

body

字段。

若存在未解决评论，直接进入步骤3。

若结果为空但需验证，重新运行上述命令确认。

2.2 Check AI reviewer issue comments

2.2 检查AI评审者议题评论

Even if inline threads are empty, check for AI reviewer comments that contain actionable findings:

bash

bun run gh-tool pr discussion-summary --pr <pr_number>
bun run gh-tool pr issue-comments-latest --pr <pr_number> --author claude --body-contains "Claude Code Review"
bun run gh-tool pr issue-comments-latest --pr <pr_number> --author sentry-io --body-contains "Sentry"

AI reviewers (Claude bot, Sentry Seer) post code review findings as general PR comments, not inline threads. These comments typically contain:

Severity-tagged findings (Critical, Major, Minor)
Specific file paths and line numbers
Code suggestions and explanations

Parse the comment body to extract actionable items with file paths and line numbers.

即使行内线程为空，也需检查AI评审者发布的包含可操作结论的评论：

bash

bun run gh-tool pr discussion-summary --pr <pr_number>
bun run gh-tool pr issue-comments-latest --pr <pr_number> --author claude --body-contains "Claude Code Review"
bun run gh-tool pr issue-comments-latest --pr <pr_number> --author sentry-io --body-contains "Sentry"

AI评审者（Claude机器人、Sentry Seer）会将代码评审结论作为通用PR评论发布，而非行内线程。这些评论通常包含：

带严重程度标记的结论（Critical、Major、Minor）
具体文件路径和行号
代码建议与解释

解析评论正文，提取包含文件路径和行号的可操作项。

2.3 Determine if there is work to do

2.3 判断是否需要处理

If both inline threads AND AI reviewer comments are empty or have no actionable findings, inform the user and exit.

If either source has actionable items, proceed to Step 3 with the combined list.

若行内线程和AI评审者评论均为空或无有效可操作结论，告知用户并退出。

若任一来源包含可操作项，合并列表后进入步骤3。

Step 3: Analyze Each Comment

步骤3：分析每条评论

For each comment:

Read the file mentioned in the comment at the specific line
Understand the suggestion — what change is being requested?
Evaluate validity:
- Apply automatically: Clear improvements (typos, style, obvious bugs, performance)
- Apply with judgment: Suggestions that align with CLAUDE.md conventions
- Ask user: Major architectural changes, unclear suggestions, or potentially breaking changes

针对每条评论：

读取评论中提到的文件对应行的内容
理解建议 —— 需要进行哪些变更？
评估有效性：
- 自动应用：明确的改进（拼写错误、代码风格、明显bug、性能优化）
- 判断后应用：符合CLAUDE.md规范的建议
- 询问用户：重大架构变更、模糊的建议、可能导致破坏性变更的内容

Step 4: Apply Fixes

步骤4：应用修复

For each valid suggestion:

Make the code change
Track what was changed and why

针对每个有效建议：

修改代码
记录变更内容及原因

Step 5: Respond to Comments and Resolve

步骤5：回复评论并解决线程

CRITICAL: Every thread MUST have a reply before being resolved. This includes:

Threads you're about to resolve
Threads that are already resolved but missing replies
Positive feedback comments (reply with acknowledgment like "Thanks for the feedback!")

关键：所有线程必须先回复再解决。包括：

即将解决的线程
已解决但未回复的线程
正面反馈评论（回复感谢，例如"感谢您的反馈！"）

5.1 Get thread IDs and check for missing replies

5.1 获取线程ID并检查缺失回复

First, fetch review threads to get thread IDs and resolution status:

bash

bun run gh-tool pr threads --pr <pr_number>

Then check which threads have replies:

bash

bun run gh-tool pr comments --pr <pr_number>

Identify threads missing replies — threads with only 1 comment (the original) need a reply added.

首先获取评审线程以获取线程ID和解决状态：

bash

bun run gh-tool pr threads --pr <pr_number>

然后检查哪些线程已有回复：

bash

bun run gh-tool pr comments --pr <pr_number>

识别缺失回复的线程 —— 仅包含1条评论（原始评论）的线程需要添加回复。

5.2 Reply to EVERY thread (including already resolved ones)

5.2 回复所有线程（包括已解决的线程）

For inline review comment replies:

bash

bun run gh-tool pr reply --pr <pr_number> --comment-id <comment_id> --body "<response>"

For general PR comments:

bash

bun run gh-tool pr comment --pr <pr_number> --body "<response>"

Response format:

If fixed: "Addressed - [brief description of what was changed]"
If not applicable: "Not applicable - [brief explanation why]"
If positive feedback: "Thanks for the feedback!" or similar acknowledgment
If needs discussion: "Question: [ask for clarification]"

针对行内评审评论的回复：

bash

bun run gh-tool pr reply --pr <pr_number> --comment-id <comment_id> --body "<response>"

针对通用PR评论的回复：

bash

bun run gh-tool pr comment --pr <pr_number> --body "<response>"

回复格式：

已修复："已处理 - [简要说明变更内容]"
不适用："不适用 - [简要解释原因]"
正面反馈："感谢您的反馈！"或类似感谢语
需要讨论："疑问：[请求澄清的内容]"

5.3 Resolve the thread

5.3 解决线程

Only after replying, resolve the thread:

bash

bun run gh-tool pr resolve --thread-id <thread_id>

Do NOT resolve threads where you asked a question or need discussion.

仅在回复后，解决线程：

bash

bun run gh-tool pr resolve --thread-id <thread_id>

请勿解决包含疑问或需要讨论的线程。

Step 6: Run Validation

步骤6：运行验证

bash

bun run check

Fix any new issues introduced by the changes.

bash

bun run check

修复变更引入的新问题。

Step 7: Commit and Push

步骤7：提交并推送

bash

git add -A && git commit -m "fix(<scope>): <description of changes>" && git push origin HEAD

Generate a descriptive commit message based on what was actually changed (e.g., "fix(auth): correct token validation" or "fix(ui): improve error message display").

bash

git add -A && git commit -m "fix(<scope>): <description of changes>" && git push origin HEAD

根据实际变更内容生成描述性提交信息（例如："fix(auth): 修正令牌验证逻辑"或"fix(ui): 优化错误提示显示"）。

Step 8: Monitor Checks and Iterate

步骤8：监控检查与迭代

After pushing, automatically enter the monitoring loop.

Inform the user: "Fixes pushed. Monitoring CI checks... (say 'stop' to exit the loop)"

推送完成后，自动进入监控循环。

告知用户："修复已推送。正在监控CI检查...（输入'stop'可退出循环）"

8.1 Wait for CI checks to complete

8.1 等待CI检查完成

Use the built-in

--watch

flag to wait for checks (suppress verbose output):

bash

bun run gh-tool pr checks --pr <pr_number> --watch --fail-fast > /dev/null 2>&1; echo $?

Exit codes:

```
0
```
— All checks passed
```
1
```
— One or more checks failed

The

--fail-fast

flag exits immediately when any check fails, allowing faster iteration.

使用内置

--watch

标志等待检查完成（抑制冗余输出）：

bash

bun run gh-tool pr checks --pr <pr_number> --watch --fail-fast > /dev/null 2>&1; echo $?

退出码说明：

```
0
```
—— 所有检查通过
```
1
```
—— 存在检查失败

--fail-fast

标志会在任一检查失败时立即退出，以加快迭代速度。

8.2 Handle check results

8.2 处理检查结果

If exit code is 1 (checks failed):

Get failed check details:

bash

bun run gh-tool pr checks-failed --pr <pr_number>

For build/lint/test failures, fetch logs if available or analyze the error from the link
Fix the issues locally
Run
```
bun run check
```
to validate

Commit and push the fix:

bash

git add -A && git commit -m "fix: resolve CI check failures" && git push origin HEAD

Go back to Step 8.1 to monitor again

If exit code is 0 (all checks passed):

Check for new review comments since last check:

bash

bun run gh-tool pr comments --pr <pr_number> --since "<last_check_timestamp>"
bun run gh-tool pr issue-comments --pr <pr_number> --since "<last_check_timestamp>"

If new comments exist:
- Inform user: "CI passed but X new review comments found. Processing..."
- Go back to Step 2 to process new comments
If no new comments:
- Inform user: "All checks passed and no new comments. PR is ready for review! 🎉"
- Exit the loop

若退出码为1（检查失败）：

获取失败检查详情：

bash

bun run gh-tool pr checks-failed --pr <pr_number>

针对构建/语法检查/测试失败，若有日志则获取日志，或通过链接分析错误
在本地修复问题
运行
```
bun run check
```
验证

提交并推送修复：

bash

git add -A && git commit -m "fix: 解决CI检查失败问题" && git push origin HEAD

返回步骤8.1重新监控

若退出码为0（所有检查通过）：

检查自上次检查以来的新评审评论：

bash

bun run gh-tool pr comments --pr <pr_number> --since "<last_check_timestamp>"
bun run gh-tool pr issue-comments --pr <pr_number> --since "<last_check_timestamp>"

若存在新评论：
- 告知用户："CI已通过，但发现X条新评审评论。正在处理..."
- 返回步骤2处理新评论
若无新评论：
- 告知用户："所有检查已通过且无新评论。PR已准备好进入评审环节！🎉"
- 退出循环

8.3 Loop exit conditions

8.3 循环退出条件

Exit the monitoring loop when:

All checks pass AND no new comments
User says "stop" or requests to exit
Maximum 5 iterations reached (then ask user to continue)

满足以下任一条件时退出监控循环：

所有检查通过且无新评论
用户输入"stop"或请求退出
达到最大迭代次数5次（之后询问用户是否继续）

Decision Guidelines

决策指南

Auto-apply (no user confirmation needed):

Typo fixes in comments or strings
Import organization/cleanup
Adding missing types
Style fixes matching CLAUDE.md (kebab-case files, absolute imports, etc.)
Performance improvements (Promise.all, prefetch patterns)
Security fixes (removing hardcoded values, adding validation)

Apply with judgment:

Refactoring suggestions that improve code clarity
Adding error handling
Improving variable/function names

Ask user first:

Removing functionality
Changing public API signatures
Suggestions that contradict existing patterns
Comments you don't understand or disagree with

自动应用（无需用户确认）：

注释或字符串中的拼写错误修复
导入语句整理/清理
添加缺失的类型定义
符合CLAUDE.md的风格修复（短横线命名文件、绝对导入等）
性能优化（Promise.all、预取模式）
安全修复（移除硬编码值、添加验证）

判断后应用：

提升代码可读性的重构建议
添加错误处理逻辑
优化变量/函数命名

先询问用户：

移除功能
修改公共API签名
与现有模式冲突的建议
无法理解或不同意的评论

Sync Branches Workflow

分支同步工作流

Merge all environment branches so test, prod, and main point to the same commit.

合并所有环境分支，使test、prod和main指向同一提交。

Step 1: Safety snapshot and teardown

步骤1：安全快照与清理

bash

but oplog snapshot -m "pre-sync safety"
but teardown

If teardown fails with "No active branches found", manually checkout test:

bash

git checkout test

bash

but oplog snapshot -m "pre-sync safety"
but teardown

若清理失败并提示"No active branches found"，手动切换到test分支：

bash

git checkout test

Step 2: Checkout test and pull

步骤2：切换到test分支并拉取

bash

git checkout test
git pull origin test

bash

git checkout test
git pull origin test

Step 3: Merge prod and main into test

步骤3：将prod和main合并到test

bash

git fetch origin prod main
git merge origin/prod --no-edit
git merge origin/main --no-edit

If conflicts occur, resolve using

--theirs

(prefer incoming) and ask the user only if the conflict is ambiguous:

bash

git checkout --theirs <conflicted-files>
git add <conflicted-files>
git commit --no-edit

bash

git fetch origin prod main
git merge origin/prod --no-edit
git merge origin/main --no-edit

若出现冲突，使用

--theirs

（优先采用 incoming 分支内容）解决，仅当冲突模糊时询问用户：

bash

git checkout --theirs <conflicted-files>
git add <conflicted-files>
git commit --no-edit

Step 4: Push test

步骤4：推送test分支

bash

git push origin test

bash

git push origin test

Step 5: Fast-forward prod from test

步骤5：从test快进prod分支

bash

git fetch origin test prod main
git checkout prod
git pull origin prod
git merge origin/test --no-edit
git push origin prod

bash

git fetch origin test prod main
git checkout prod
git pull origin prod
git merge origin/test --no-edit
git push origin prod

Step 6: Fast-forward main from prod

步骤6：从prod快进main分支

bash

git fetch origin test prod main
git checkout main
git pull origin main
git merge origin/prod --no-edit
git push origin main

bash

git fetch origin test prod main
git checkout main
git pull origin main
git merge origin/prod --no-edit
git push origin main

Step 7: Verify sync

步骤7：验证同步

bash

git fetch origin test prod main
echo "test:  $(git rev-parse origin/test)"
echo "prod:  $(git rev-parse origin/prod)"
echo "main:  $(git rev-parse origin/main)"

All three must show the same SHA. If not, investigate and fix.

bash

git fetch origin test prod main
echo "test:  $(git rev-parse origin/test)"
echo "prod:  $(git rev-parse origin/prod)"
echo "main:  $(git rev-parse origin/main)"

三个分支必须显示相同的SHA值。若不相同，需排查并修复。

Step 8: Return to GitButler workspace

步骤8：返回GitButler工作区

bash

git checkout test
but setup

bash

git checkout test
but setup

Constraints

约束条件

ALWAYS snapshot before teardown — protects uncommitted workspace files
ALWAYS use
--no-edit
for merge commits — no interactive editors
ALWAYS set non-interactive env vars before git commands (
```
GIT_MERGE_AUTOEDIT=no
```
,
```
GIT_PAGER=cat
```
, etc.)
NEVER force push — all merges should be fast-forward or regular merge
NEVER skip verification (Step 7) — confirm all SHAs match before returning to workspace

始终在清理前创建快照 —— 保护未提交的工作区文件
合并提交始终使用
--no-edit
—— 不使用交互式编辑器
Git命令前始终设置非交互式环境变量（
```
GIT_MERGE_AUTOEDIT=no
```
、
```
GIT_PAGER=cat
```
等）
绝不强制推送 —— 所有合并应为快进或常规合并
绝不跳过验证环节（步骤7）—— 返回工作区前确认所有SHA值匹配

Output

输出

Report final state:

Branches synced to <SHA>
test:  <SHA>
prod:  <SHA>
main:  <SHA>

报告最终状态：

Branches synced to <SHA>
test:  <SHA>
prod:  <SHA>
main:  <SHA>