git-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Workflow

Git工作流

PR lifecycle automation. Create PR → watch → fix → address → push → repeat until green.

PR生命周期自动化。创建PR → 监控 → 修复 → 处理反馈 → 推送 → 重复操作直到全绿。

PR Workflow

PR工作流

Trigger: user says "pr"

The entire PR lifecycle runs as one continuous aggressive loop. There is no separate "fix comments" step — it's all one workflow.

触发条件：用户说出"pr"

整个PR生命周期以一个连续的主动循环运行，没有单独的“修复评论”步骤——所有操作都属于同一个工作流。

Phase 1: Create or Update PR

阶段1：创建或更新PR

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 && agent-tools-gh pr create --base <base> --title "<title>" --body "<body>"

If already on a feature branch, skip
```
git checkout -b
```
Check if PR exists:
```
agent-tools-gh pr status
```
(auto-detects PR for current branch or GitButler workspace)

If PR exists, use

agent-tools-gh pr edit --pr <pr_number> --title "<title>" --body "<body>"

instead of

agent-tools-gh 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 && agent-tools-gh pr create --base <base> --title "<title>" --body "<body>"

若已处于功能分支，则跳过
```
git checkout -b
```
检查PR是否存在：
```
agent-tools-gh pr status
```
（自动检测当前分支或GitButler工作区对应的PR）

若PR已存在，使用

agent-tools-gh pr edit --pr <pr_number> --title "<title>" --body "<body>"

替代

agent-tools-gh pr create

基础分支：由用户提供参数（默认值：
```
test
```
）
分支命名：根据变更类型使用
```
feat/
```
、
```
fix/
```
、
```
chore/
```
前缀

PR Body Format

PR正文格式

undefined

undefined

Summary

摘要

<1-2 sentences>

<1-2句话>

Changes

变更内容

<bullet list>

undefined

<项目符号列表>

undefined

Commit Message Standard

提交消息规范

Every commit MUST use proper conventional commits describing the actual change, not meta-descriptions like "address review feedback" or "fix CI".

Format:

<type>(<scope>): <what actually changed>

```
type
```
:
```
fix
```
,
```
feat
```
,
```
refactor
```
,
```
perf
```
,
```
style
```
,
```
chore
```
, etc.
```
scope
```
: the module/area affected (e.g.,
```
auth
```
,
```
db
```
,
```
ui
```
,
```
api
```
)
```
message
```
: describe the concrete change, not why you're committing

Good examples:

fix(auth): add null check for session token before redirect

refactor(api): extract validation logic into shared middleware

fix(db): correct JOIN condition in user query

perf(search): add index on created_at for faster lookups

style(ui): align spacing in sidebar navigation

Bad examples (NEVER use these):

~~fix: address review feedback~~
~~fix: resolve CI check failures~~
~~fix: address Claude PR feedback~~
~~chore: fix issues~~

If a single commit addresses multiple review comments across different scopes, make separate commits per scope rather than one catch-all.

每次提交必须使用规范的conventional commits格式，描述实际的变更内容，而非像“处理审核反馈”或“修复CI”这类元描述。

格式：

<type>(<scope>): <实际变更内容>

```
type
```
：
```
fix
```
（修复）、
```
feat
```
（新功能）、
```
refactor
```
（重构）、
```
perf
```
（性能优化）、
```
style
```
（格式调整）、
```
chore
```
（杂项）等
```
scope
```
：受影响的模块/区域（例如：
```
auth
```
、
```
db
```
、
```
ui
```
、
```
api
```
）
```
message
```
：描述具体的变更，而非提交的原因

优秀示例：

fix(auth): add null check for session token before redirect

refactor(api): extract validation logic into shared middleware

fix(db): correct JOIN condition in user query

perf(search): add index on created_at for faster lookups

style(ui): align spacing in sidebar navigation

错误示例（禁止使用）：

~~fix: address review feedback~~
~~fix: resolve CI check failures~~
~~fix: address Claude PR feedback~~
~~chore: fix issues~~

若单次提交需处理不同模块的多个审核评论，请按模块拆分提交，而非使用一个笼统的提交。

Phase 2: Active Watch Loop

阶段2：主动监控循环

Immediately after PR creation/update, enter the active watch loop. No pause, no waiting for user input.

Inform user: "PR created/updated. Entering active watch loop — monitoring CI and reviews. (say 'stop' to exit)"

PR创建/更新完成后立即进入主动监控循环，无需暂停或等待用户输入。

告知用户：“PR已创建/更新。进入主动监控循环——正在监控CI与审核。（输入‘stop’可退出）”

LOOP START

循环开始

Step 1: Watch CI checks

步骤1：监控CI检查

Wait for all CI checks to complete:

bash

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

Exit codes:

= all passed,

= failure detected.

The

--fail-fast

flag exits immediately on first failure for faster iteration.

等待所有CI检查完成：

bash

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

退出码：

= 全部通过，

= 检测到失败。

--fail-fast

标志会在首次失败时立即退出，以加快迭代速度。

Step 2: Handle CI results

步骤2：处理CI结果

If checks failed (exit code 1):

Get failed check details immediately:

bash

agent-tools-gh pr checks-failed --pr <pr_number>

For deeper CI log analysis, fetch clean parsed logs for the failed job:

bash

agent-tools-gh workflow job-logs --run <run_id> --job "<job_name>" --failed-steps-only

Analyze the error from the logs
Fix the issues locally — do not ask, just fix
Run validation:
bash
```
bun run check
```

Commit and push:

bash

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

If the failure seems flaky (e.g., timeout, network issue), consider rerunning instead of fixing:
bash
```
agent-tools-gh pr rerun-checks --pr <pr_number> --failed-only
```
→ Go back to LOOP START

If checks passed (exit code 0): proceed to Step 3.

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

立即获取失败检查的详细信息：

bash

agent-tools-gh pr checks-failed --pr <pr_number>

如需深入分析CI日志，获取失败任务的清晰解析日志：

bash

agent-tools-gh workflow job-logs --run <run_id> --job "<job_name>" --failed-steps-only

分析日志中的错误
在本地立即修复问题——无需询问，直接修复
运行验证：
bash
```
bun run check
```

提交并推送：

bash

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

若失败看起来是偶发问题（例如超时、网络问题），可考虑重新运行而非修复：
bash
```
agent-tools-gh pr rerun-checks --pr <pr_number> --failed-only
```
→ 返回循环开始

若检查通过（退出码0）： 继续步骤3。

Step 3: Check for reviews and comments

步骤3：检查审核与评论

Run a full triage immediately:

bash

agent-tools-gh pr review-triage --pr <pr_number>

Then check each source of feedback:

3.1 Inline review threads:

bash

agent-tools-gh pr threads --pr <pr_number> --unresolved-only

Each thread includes

threadId

commentId

path

line

, and

body

3.2 AI reviewer issue comments (Claude bot, Sentry Seer, etc.):

bash

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

AI reviewers post findings as general PR comments with severity-tagged items (Critical, Major, Minor), specific file paths and line numbers, and code suggestions.

Parse the comment body to extract actionable items.

3.3 Decision:

If NO unresolved threads AND NO actionable AI comments → PR is clean. → Go to LOOP EXIT
If ANY feedback found → proceed to Step 4

立即运行完整的分类处理：

bash

agent-tools-gh pr review-triage --pr <pr_number>

然后检查各来源的反馈：

3.1 内联审核线程：

bash

agent-tools-gh pr threads --pr <pr_number> --unresolved-only

每个线程包含

threadId

、

commentId

、

path

、

line

和

body

。

3.2 AI审核者的问题评论（Claude机器人、Sentry Seer等）：

bash

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

AI审核者会将检查结果作为PR的通用评论发布，包含带严重程度标签的项（Critical、Major、Minor）、具体的文件路径和行号，以及代码建议。

解析评论内容以提取可操作的任务项。

3.3 决策：

若无未解决线程且无可操作的AI评论 → PR已清理完成。→ 进入循环退出
若发现任何反馈 → 继续步骤4

Step 4: Address every comment immediately

步骤4：立即处理每条评论

For each comment/finding:

Read the file at the specific line mentioned
Understand the suggestion — what change is being requested?
Evaluate and act:
- Auto-apply (no confirmation): typos, style fixes, missing types, import cleanup, obvious bugs, performance improvements, security fixes matching CLAUDE.md conventions
- Apply with judgment: refactoring suggestions that improve clarity, error handling, naming improvements
- Ask user first: removing functionality, changing public API signatures, contradicting existing patterns, unclear suggestions
Make the fix immediately — track what was changed and why

针对每条评论/检查结果：

读取提及的特定行对应的文件
理解建议——请求的变更内容是什么？
评估并执行：
- 自动应用（无需确认）：拼写错误、格式修复、缺失类型、导入清理、明显的bug、性能优化、符合CLAUDE.md规范的安全修复
- 根据判断应用：提升代码清晰度的重构建议、错误处理改进、命名优化
- 先询问用户：移除功能、修改公共API签名、与现有模式冲突、模糊不清的建议
立即修复问题——记录变更内容及原因

Step 5: Reply to comments and resolve threads

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

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

First, identify all threads needing replies:

bash

agent-tools-gh pr threads --pr <pr_number>
agent-tools-gh pr comments --pr <pr_number>

Threads with only 1 comment (the original) need a reply added.

Reply to EVERY thread (including already resolved ones missing replies):

For inline threads — use the shortcut to reply and resolve in one step:

bash

agent-tools-gh pr reply-and-resolve --pr <pr_number> --comment-id <comment_id> --thread-id <thread_id> --body "<response>"

Or reply separately then resolve:

bash

agent-tools-gh pr reply --pr <pr_number> --comment-id <comment_id> --body "<response>"
agent-tools-gh pr resolve --thread-id <thread_id>

For general PR comments:

bash

agent-tools-gh 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]"

If reply fails with "pending review" error: Submit the pending review first, then retry:

bash

agent-tools-gh pr submit-review --pr <pr_number>

Do NOT resolve threads where you asked a question.

关键要求：每个线程在解决前必须有回复。

首先，识别所有需要回复的线程：

bash

agent-tools-gh pr threads --pr <pr_number>
agent-tools-gh pr comments --pr <pr_number>

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

回复所有线程（包括已解决但缺少回复的线程）：

对于内联线程——使用快捷命令一步完成回复与解决：

bash

agent-tools-gh pr reply-and-resolve --pr <pr_number> --comment-id <comment_id> --thread-id <thread_id> --body "<response>"

或分开回复再解决：

bash

agent-tools-gh pr reply --pr <pr_number> --comment-id <comment_id> --body "<response>"
agent-tools-gh pr resolve --thread-id <thread_id>

对于PR通用评论：

bash

agent-tools-gh pr comment --pr <pr_number> --body "<response>"

回复格式：

若已修复：“已处理 - [简要描述变更内容]”
若不适用：“不适用 - [简要解释原因]”
若为正面反馈：“感谢您的反馈！”或类似致谢语
若需讨论：“问题：[请求澄清]”

若回复时出现“pending review”错误：先提交待审核的回复，然后重试：

bash

agent-tools-gh pr submit-review --pr <pr_number>

请勿解决你提出问题的线程。

Step 6: Validate and push

步骤6：验证并推送

bash

bun run check

Fix any new issues. Then commit and push:

bash

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

→ Go back to LOOP START

bash

bun run check

修复任何新出现的问题。然后提交并推送：

bash

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

→ 返回循环开始

LOOP EXIT

循环退出

When reaching here (all checks pass + no unresolved comments):

Inform user: "All CI checks passed. All review comments addressed. PR is ready for review! 🎉"

当到达此步骤（所有检查通过 + 无未解决评论）：

告知用户：“所有CI检查已通过。所有审核评论已处理。PR已准备好进行最终审核！🎉”

Loop exit conditions

循环退出条件

Exit the watch loop when:

All checks pass AND no unresolved feedback — natural exit
User says "stop" or requests to exit
Maximum 10 iterations reached — ask user if they want to continue

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

所有检查通过且无未解决反馈——自然退出
**用户说“stop”**或请求退出
达到最大10次迭代——询问用户是否继续

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

提交消息：使用conventional commits格式（
```
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>

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：将prod分支快速同步到test分支

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：将main分支快速同步到prod分支

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>