merge-main

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Merge main — sync feature branch with main

Merge main — 将功能分支与main同步

Bring the current feature branch up to date with

origin/main

: commit local work, understand what changed on main, merge, resolve conflicts, validate. Leaves the branch ready for a clean PR.

让当前功能分支与

origin/main

保持同步：提交本地工作、了解main分支的变更内容、合并、解决冲突、验证。完成后分支即可用于创建干净的PR。

Before You Start

开始前准备

```
CLAUDE.md
```
— check for the project's commit-message conventions and any post-merge validation steps.
```
.github/
```
or the project's CI config — identifies what CI expects after a merge (lockfile regen, codegen, ...).
A clean working tree before starting. If there are uncommitted changes, this skill commits them first.

```
CLAUDE.md
```
— 查看项目的提交消息规范以及合并后的任何验证步骤。
```
.github/
```
或项目的CI配置 — 确定合并后CI需要的操作（如重新生成锁文件、代码生成等）。
开始前确保工作区干净。如果存在未提交的更改，此技能会先提交这些更改。

Step 1: commit current work

步骤1：提交当前工作

Uncommitted changes cause merge failures. Commit before fetching:

bash

git status
git diff --stat

If there are uncommitted changes:

bash

git add <specific-files>         # prefer listing files over `git add -A`
git commit -m "type(scope): concise message"

Use the project's commit convention (check

CLAUDE.md

.github/

; common forms:

type(scope): message

, Angular-style, or plain imperative).

未提交的更改会导致合并失败。拉取前先提交：

bash

git status
git diff --stat

如果存在未提交的更改：

bash

git add <specific-files>         # 优先列出具体文件，而非使用`git add -A`
git commit -m "type(scope): concise message"

使用项目的提交规范（查看

CLAUDE.md

或

.github/

；常见格式：

type(scope): message

、Angular风格或简单祈使句）。

Step 2: fetch and measure distance

步骤2：拉取代码并查看分支差距

bash

git fetch origin main
behind=$(git log --oneline HEAD..origin/main | wc -l)
ahead=$(git log --oneline origin/main..HEAD | wc -l)
echo "Branch is $behind commits behind and $ahead ahead of origin/main."

behind

is 0, stop — nothing to merge.

bash

git fetch origin main
behind=$(git log --oneline HEAD..origin/main | wc -l)
ahead=$(git log --oneline origin/main..HEAD | wc -l)
echo "Branch is $behind commits behind and $ahead ahead of origin/main."

如果

behind

为0，则停止操作——无需合并。

Step 3: understand what changed on main

步骤3：了解main分支的变更内容

bash

git log --oneline HEAD..origin/main
git diff --stat HEAD...origin/main

Identify files changed on both main and this branch — these are conflict candidates:

bash

git diff --name-only HEAD...origin/main > /tmp/main_changes.txt
git diff --name-only origin/main...HEAD > /tmp/branch_changes.txt
comm -12 <(sort /tmp/main_changes.txt) <(sort /tmp/branch_changes.txt)

Summarize for the user: how many main commits arrived, which directories they touched, which files overlap with this branch's changes.

bash

git log --oneline HEAD..origin/main
git diff --stat HEAD...origin/main

找出在main分支和当前分支都被修改的文件——这些是潜在的冲突文件：

bash

git diff --name-only HEAD...origin/main > /tmp/main_changes.txt
git diff --name-only origin/main...HEAD > /tmp/branch_changes.txt
comm -12 <(sort /tmp/main_changes.txt) <(sort /tmp/branch_changes.txt)

向用户总结：main分支新增了多少提交、涉及哪些目录、哪些文件与当前分支的变更存在重叠。

Step 4: merge

步骤4：合并

bash

git merge origin/main

Clean merge → step 6. Conflicts → step 5.

bash

git merge origin/main

无冲突合并 → 跳至步骤6。存在冲突 → 步骤5。

Step 5: resolve conflicts

步骤5：解决冲突

bash

git diff --name-only --diff-filter=U

For each conflicted file:

Read the file — understand both sides of the conflict.

Read the main-side history —

git log --oneline -5 origin/main -- <file>

Decide resolution strategy:

Resolve yourself when:

The conflict is in a generated/lock file (
```
package-lock.json
```
,
```
pnpm-lock.yaml
```
,
```
uv.lock
```
,
```
Cargo.lock
```
) — accept one side, then regenerate with the project's tool.
The conflict is purely additive (both sides added different items to a list, import block, or config).
The conflict is in a file you didn't intentionally change (formatting-only, auto-formatter drift).

Ask the user when:

Both sides made substantive changes to the same function or class.
The conflict involves architectural decisions.
Business logic or test assertions are in conflict.

After resolving each file:

bash

git add <resolved-file>

After all conflicts resolved:

bash

git commit                       # use the default merge message; do not amend

bash

git diff --name-only --diff-filter=U

针对每个冲突文件：

阅读文件 — 理解冲突双方的内容。

查看main分支侧的历史 —

git log --oneline -5 origin/main -- <file>

。

确定解决策略：

可自行解决的情况：

冲突发生在生成文件/锁文件中（
```
package-lock.json
```
、
```
pnpm-lock.yaml
```
、
```
uv.lock
```
、
```
Cargo.lock
```
）——选择其中一方的内容，然后使用项目工具重新生成。
冲突是纯增量式的（双方在列表、导入块或配置中添加了不同内容）。
冲突发生在你无意修改的文件中（仅格式变更、自动格式化工具导致的差异）。

需询问用户的情况：

双方对同一函数或类进行了实质性修改。
冲突涉及架构决策。
业务逻辑或测试断言存在冲突。

解决每个文件后：

bash

git add <resolved-file>

所有冲突解决完成后：

bash

git commit                       # 使用默认的合并提交消息；请勿修改

Step 6: post-merge validation

步骤6：合并后验证

bash

undefined

bash

undefined

Regenerate lockfile if the package manifest changed on main

如果main分支上的包清单发生变更，重新生成锁文件

(pick the one your project uses)

—

pnpm install # if pnpm-lock.yaml was conflicted or package.json changed

—

uv lock # if uv.lock was conflicted

—

cargo check # validates Cargo.toml + Cargo.lock

—

Re-run lint/typecheck to catch merge mistakes

—

(use the project's command from Quick Reference in CLAUDE.md)

—


If the post-merge state needs a commit (lockfile regen, regenerated artifacts):

```bash
git add <regenerated-files>
git commit -m "chore: post-merge regen after syncing with main"

#（选择项目使用的工具）

Step 7: verify

pnpm install # 如果pnpm-lock.yaml存在冲突或package.json发生变更

—

uv lock # 如果uv.lock存在冲突

—

cargo check # 验证Cargo.toml + Cargo.lock

—

重新运行代码检查/类型检查，排查合并错误

Delegate to

review-diff

to check the full branch vs main. This catches merge mistakes where the wrong side was kept or the resolution introduced an inconsistency.

#（使用CLAUDE.md中快速参考里的项目命令）


如果合并后的状态需要提交（如重新生成锁文件、重新生成产物）：

```bash
git add <regenerated-files>
git commit -m "chore: post-merge regen after syncing with main"

Critical Rules

步骤7：验证

Never force-push after merging. The merge commit is permanent.
Do not
git rebase
a branch that's been pushed. This skill does merge. If the project mandates rebase, use a different skill — not this one.
Do not silently drop one side of a conflict. If both sides made real changes, ask the user.
Always commit before merging — uncommitted work gets clobbered.
Use the default merge commit message; don't amend it.

委托

review-diff

技能检查当前分支与main分支的完整差异。这可以排查合并错误，比如保留了错误的内容或解决冲突时引入了不一致性。

Verify

关键规则

bash

undefined

合并后切勿强制推送。 合并提交是永久性的。
不要使用
git rebase
已推送的分支。此技能仅处理合并。如果项目要求使用rebase，请使用其他技能——而非此技能。
不要静默丢弃冲突某一方的内容。 如果双方都进行了实际变更，请询问用户。
合并前务必提交工作——未提交的工作会被覆盖。
使用默认的合并提交消息；请勿修改。

No conflicts remain

验证

git status

bash

undefined

Expected: "nothing to commit, working tree clean" (or only the merge commit)

确保无剩余冲突

Branch is now up to date with origin/main

—

git log --oneline HEAD..origin/main | wc -l

git status

Expected: 0

预期结果："nothing to commit, working tree clean"（或仅存在合并提交）

Lint/typecheck passes (project-specific command from CLAUDE.md)

分支现已与origin/main保持同步

undefined

git log --oneline HEAD..origin/main | wc -l

Common Mistakes

预期结果：0

—

代码检查/类型检查通过（使用CLAUDE.md中的项目特定命令）

Mistake	Correction
Running `git merge` with uncommitted changes	Commit first (step 1). Stashing loses the conventional-commit message.
Accepting one side of a lockfile conflict without regenerating	Accept either side, THEN run the package manager's regen command. Otherwise the lockfile drifts from the manifest.
Resolving a function-body conflict by deleting one side	Never drop real changes silently. If unsure which side's intent wins, ask.
Force-pushing to rewrite the merge commit	Merge commits stay. If the merge was wrong, create a revert commit instead.

undefined

—

常见错误

—

常见错误	修正方法
在存在未提交更改的情况下运行 `git merge`	先提交更改（步骤1）。暂存会丢失符合规范的提交消息。
解决锁文件冲突时仅接受某一方的内容而不重新生成	接受任意一方的内容，然后运行包管理器的重新生成命令。否则锁文件会与清单不一致。
通过删除某一方内容来解决函数体冲突	切勿静默丢弃实际变更。若不确定哪一方的意图应优先，请询问用户。
强制推送以重写合并提交	合并提交应保留。如果合并错误，请创建一个回滚提交。