git-conflict-resolve

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

目的

Systematically resolve git conflicts (merge, cherry-pick, rebase) with:

Backup of all conflicted files before resolution
Per-file conflict analysis with root cause explanation
Resolution with documented rationale
Comprehensive report generation

系统地解决git冲突（merge、cherry-pick、rebase），包含以下能力：

解决前备份所有冲突文件
针对每个文件做冲突分析并说明根本原因
解决冲突并记录决策依据
生成完整的解决报告

Variables

变量

OPERATION: auto-detect (cherry-pick, merge, rebase) from git state REPORT_PATH:

plans/reports/conflict-resolution-{date}-{operation}-{source}.md

BACKUP_PATH:

.ai/workspace/conflict-backups-{date}/

OPERATION: 从git状态自动检测（cherry-pick、merge、rebase） REPORT_PATH:

plans/reports/conflict-resolution-{date}-{operation}-{source}.md

BACKUP_PATH:

.ai/workspace/conflict-backups-{date}/

Workflow

工作流

Step 1: Detect conflict state

步骤1：检测冲突状态

bash

undefined

bash

undefined

Detect operation type

检测操作类型

git status # Check for "cherry-pick in progress", "merge in progress", etc.

git status # 检查是否存在「cherry-pick进行中」、「merge进行中」等状态

List all conflicted files

列出所有冲突文件

git diff --name-only --diff-filter=U # Unmerged files (both modified) git status --short | grep "^DU|^UD|^UU|^AA|^DD" # All conflict types


Classify each conflict:

- **DU (Deleted by us):** File exists on source but not on target branch
- **UD (Deleted by them):** File exists on target but deleted by source
- **UU (Both modified):** Both branches modified the same file
- **AA (Both added):** Both branches added a file at the same path
- **DD (Both deleted):** Both branches deleted the file

git diff --name-only --diff-filter=U # 未合并文件（双方都做了修改） git status --short | grep "^DU|^UD|^UU|^AA|^DD" # 所有冲突类型


对每个冲突进行分类：

- **DU (我方删除):** 文件存在于源分支，但在目标分支不存在
- **UD (对方删除):** 文件存在于目标分支，但被源分支删除
- **UU (双方修改):** 两个分支都修改了同一个文件
- **AA (双方新增):** 两个分支都在同一路径新增了文件
- **DD (双方删除):** 两个分支都删除了该文件

Step 2: Create backup files

步骤2：创建备份文件

MANDATORY before any resolution.

bash

mkdir -p {BACKUP_PATH}

进行任何解决操作前必须执行。

bash

mkdir -p {BACKUP_PATH}

For each conflicted file, copy WITH conflict markers preserved

为每个冲突文件创建副本，保留冲突标记

cp <conflicted-file> {BACKUP_PATH}/<filename>.conflict


Create a TaskCreate item for each conflicted file PLUS report and review tasks.

cp <conflicted-file> {BACKUP_PATH}/<filename>.conflict


为每个冲突文件创建TaskCreate条目，同时新增报告和审核任务。

Step 3: Analyze each conflict (per file)

步骤3：分析每个冲突（按文件维度）

For each conflicted file, perform this analysis:

针对每个冲突文件，执行以下分析：

3a. Understand the conflict type

3a. 明确冲突类型

DU/UD (deleted by one side): Check if the file was introduced in a commit not present on the target branch. Read the file content from the source commit to understand what it provides.
UU (both modified): Read the conflict markers. Identify what each side changed and why.

DU/UD (被其中一方删除): 检查该文件是否是目标分支中不存在的提交引入的。读取源提交中的文件内容，了解其作用。
UU (双方修改): 读取冲突标记，识别双方分别修改了什么内容以及修改原因。

3b. Read both versions

3b. 读取两个版本的内容

bash

undefined

bash

undefined

For UU conflicts: read the file with conflict markers

针对UU冲突：读取带冲突标记的文件

Look for <<<<<<< HEAD / ======= / >>>>>>> markers

查找 <<<<<<< HEAD / ======= / >>>>>>> 标记

For DU conflicts: get the source version

针对DU冲突：获取源分支版本

git show <source-commit>:<file-path>

Optionally extract clean versions

可选：提取双方的干净版本

git show HEAD:<file-path> > {BACKUP_PATH}/<filename>.ours git show <source-commit>:<file-path> > {BACKUP_PATH}/<filename>.theirs

undefined

git show HEAD:<file-path> > {BACKUP_PATH}/<filename>.ours git show <source-commit>:<file-path> > {BACKUP_PATH}/<filename>.theirs

undefined

3c. Analyze dependencies

3c. 分析依赖

Check callers: Do other files reference methods/classes in this file? Are caller names compatible?
Check constructor/DI: Does the resolution require new dependencies?
Check cross-file consistency: Will the resolution break other files?

检查调用方: 其他文件是否引用了该文件中的方法/类？调用方名称是否兼容？
检查构造函数/DI: 冲突解决是否需要新增依赖？
检查跨文件一致性: 冲突解决是否会影响其他文件？

3d. Determine resolution strategy

3d. 确定解决策略

Conflict Pattern	Resolution Strategy
DU: File needed by feature	Accept theirs (add the file)
DU: File not needed	Keep ours (skip the file)
UU: Non-overlapping changes	Merge both (keep all changes)
UU: Overlapping, source modifies methods not on target	Keep ours if methods don't exist on target
UU: Overlapping, both modify same method	Manual merge with careful analysis
UU: Schema/snapshot files	Accept theirs for new entities, merge for modified

冲突场景	解决策略
DU：功能需要用到该文件	接受对方版本（新增文件）
DU：不需要该文件	保留我方版本（忽略该文件）
UU：修改内容无重叠	合并双方内容（保留所有修改）
UU：修改有重叠，源分支修改了目标分支不存在的方法	如果目标分支不存在对应方法则保留我方版本
UU：修改有重叠，双方都修改了同一个方法	仔细分析后手动合并
UU：Schema/快照文件	新增实体接受对方版本，修改内容合并双方

Step 4: Resolve each conflict

步骤4：解决每个冲突

Apply the determined strategy:

bash

undefined

执行确定的解决策略：

bash

undefined

Accept theirs (source version)

接受对方版本（源分支版本）

git checkout --theirs <file> && git add <file>

Keep ours (target version)

保留我方版本（目标分支版本）

git checkout --ours <file> && git add <file>

Manual merge: Edit the file to remove conflict markers, then:

手动合并：编辑文件移除冲突标记后执行：

git add <file>


For manual merges:

1. Remove `<<<<<<< HEAD`, `=======`, `>>>>>>> <commit>` markers
2. Keep the correct content from each side
3. Verify no leftover conflict markers: `git diff --check`

git add <file>


手动合并注意事项：

1. 移除`<<<<<<< HEAD`、`=======`、`>>>>>>> <commit>`标记
2. 保留双方的正确内容
3. 验证没有残留的冲突标记：`git diff --check`

Step 5: Verify resolution

步骤5：验证解决结果

bash

undefined

bash

undefined

Check no unmerged files remain

检查是否还有未合并的文件

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

Check no leftover conflict markers

检查是否有残留的冲突标记

git diff --check

Review overall status

查看整体状态

git status

undefined

git status

undefined

Step 6: Complete the operation

步骤6：完成操作

bash

undefined

bash

undefined

For cherry-pick

处理cherry-pick场景

git cherry-pick --continue --no-edit

For merge

处理merge场景

git commit # (merge commit is auto-prepared)

git commit # （合并提交已自动生成）

For rebase

处理rebase场景

git rebase --continue

undefined

git rebase --continue

undefined

Step 7: Generate report

步骤7：生成报告

Create a comprehensive report at

{REPORT_PATH}

with:

Header: Date, source commit/branch, target branch, result commit
Summary: Total conflicts, categories, overall risk
Per-file details:
- File path
- Conflict type (DU/UU/etc.)
- Root cause (why the conflict occurred)
- Resolution chosen (accept theirs/keep ours/manual merge)
- Rationale (why this resolution was chosen)
- Risk level (Low/Medium/High)
Summary table: All files with conflict type, resolution, risk
Root cause analysis: Common patterns across conflicts
Recommendations: Follow-up actions, build verification, etc.

在

{REPORT_PATH}

路径生成完整报告，包含以下内容：

头部: 日期、源提交/分支、目标分支、结果提交
摘要: 总冲突数、分类、整体风险
单文件详情:
- 文件路径
- 冲突类型（DU/UU等）
- 根本原因（冲突发生的原因）
- 选择的解决方案（接受对方/保留我方/手动合并）
- 决策依据（为什么选择该方案）
- 风险等级（低/中/高）
汇总表: 所有文件的冲突类型、解决方案、风险
根本原因分析: 冲突的共性规律
建议: 后续行动、构建验证等

Step 8: Final review

步骤8：最终审核

Verify report is complete and accurate
Check that all backup files exist
Confirm build passes (if applicable)
Flag any Medium/High risk resolutions for user attention

验证报告完整准确
检查所有备份文件都已存在
确认构建通过（如适用）
标记所有中/高风险的解决操作，提醒用户注意

Resolution Decision Framework

解决决策框架

When to "Accept Theirs" (source version)

何时选择「接受对方版本」（源分支版本）

File is NEW (DU) and required by the feature being cherry-picked/merged
File contains schema/config additions needed by new entities
Source has strictly more content (e.g., empty class → populated class)

文件是新增的（DU），且是当前cherry-pick/merge的功能必需的
文件包含新实体需要的Schema/配置新增内容
源分支的内容明显更完整（例如：空类 → 填充了内容的类）

When to "Keep Ours" (target version)

何时选择「保留我方版本」（目标分支版本）

Source modifies methods that don't exist on target (added by uncommitted prerequisite)
Source renames methods/types that target callers still reference by old names
Changes are not required for the feature being brought in

源分支修改的方法在目标分支不存在（来自未合入的前置提交）
源分支重命名了目标分支调用方仍在使用旧名称的方法/类型
修改内容不是当前引入功能的必需部分

When to "Manual Merge"

何时选择「手动合并」

Both sides have legitimate changes that need to coexist
Schema files where both add new entries (keep both)
Config files where both add new sections

双方的修改都合理，需要共存
Schema文件中双方都新增了条目（保留两边）
配置文件中双方都新增了配置段

Risk Assessment

风险评估

Risk	Criteria	Action
Low	New file, no existing code affected	Proceed
Medium	Method changes, caller compatibility uncertain	Flag in report, recommend build verification
High	Breaking changes, cross-service impact	Require user confirmation before proceeding

风险等级	判断标准	处理动作
低	新增文件，不影响现有代码	直接执行
中	方法变更，调用方兼容性不确定	在报告中标记，建议进行构建验证
高	破坏性变更，跨服务影响	执行前需要用户确认

Notes

注意事项

Always create backup files BEFORE any resolution
Never force-resolve without understanding the root cause
For complex conflicts (>3 conflict regions in one file), extract both clean versions for side-by-side analysis
Check for prerequisite commits: if a cherry-pick modifies files from prior commits not on target, note this in the report
Use
```
git diff <commit>^..<commit> -- <file>
```
to see the actual diff of a specific commit (not the full file state)

IMPORTANT Task Planning Notes (MUST FOLLOW)

Always plan and break work into many small todo tasks
Always add a final review todo task to verify work quality and identify fixes/enhancements

解决冲突前务必先创建备份文件
未理解根本原因前不要强制解决冲突
复杂冲突（单个文件超过3个冲突区域）：提取双方的干净版本进行对照分析
检查前置提交：如果cherry-pick修改的文件来自目标分支不存在的前置提交，在报告中注明
使用
```
git diff <commit>^..<commit> -- <file>
```
查看特定提交的实际diff（而非完整文件状态）

重要任务规划注意事项（必须遵守）

始终将工作拆分为多个小的todo任务
始终添加最终审核的todo任务，验证工作质量，识别需要修复/优化的内容