Iron rules:Pull the latest source branch → resolve conflicts semi-automatically → when uncertain, always stop and ask. Revertible (git merge --abort / git reset), so a backup branch is not mandatory.
🔴 Hard rules
- Must use the latest remote version of the source branch. Before merge
git fetch, mergeorigin/<源分支>, do not use a stale local copy. - When uncertain about a conflict, always stop and ask. If both sides substantively changed the same logic → 🔴 STOP + AskUserQuestion, do not guess and pick one side on your own.
- Do not push automatically. After the merge completes, keep it local; pushing is up to the user's instruction.
Workflow
1. Get parameters + pre-checks
SRC=<源分支> # 缺省 → 报错要求指定,不猜
CUR=$(git branch --show-current)
git status --porcelain # 必须干净;脏 → 先 git-commit 或 git stash(记下,merge 后 pop)
✅ Completion criteria:SRC is non-empty and git status --porcelain has no output (or dirty changes have been committed/stashed).
2. Pull the latest remote source branch + execute
git fetch origin "$SRC"
git merge "origin/$SRC"
✅ Completion criteria:git fetch exit code 0;git merge has finished running — if there are no conflicts, go directly to step 4; if there are conflicts, go to step 3.
3. Conflict loop (semi-automatic)
Judge each conflicted file according to the table below.Inversion: under merge and rebase, --ours/--theirs points to opposite branches, which is the most error-prone judgment between the two skills; consult the table, do not rely on memory. In merge, --ours=current branch,--theirs=source branch; in rebase the direction is reversed, see git-rebase detailed table。
| Case | Semantics | Command (merge context) |
|---|---|---|
| Only thecurrent branchchanged this file | The current branch takes precedence | git checkout --ours <file> ← ours=current branch |
| Only thesource branchchanged this file | The source branch takes precedence | git checkout --theirs <file> ← theirs=source branch |
| Both sides substantively changedthe same logic | Uncertain | 🔴 STOP, use AskUserQuestion to list the conflicting hunks and let the user decide, do not decide on your own |
Judging "has substantive changes":git log origin/$SRC..HEAD -- <file> check whether the current branch side has commits targeting that file (empty = only the source branch changed it). The direction-agnostic criteria skeleton (pre-checks/substantive-change criteria/conflict loop steps) + -s ours highly dangerous warning + -X usage, for the single source of truth see references/conflict-resolution.md §core。
🔴 The user saying "always take the current branch" ≠ blanket --ours / -X ours: you must still judge file by file. When both sides substantively changed the same file, blindly choosing the current branch willsilently discard the source branch's changes; for such files still STOP and ask the user, do not be induced by a single phrase "take the current branch" to skip the judgment. Even more forbidden is git merge -s ours(discard all changes from the source branch, leaving only a fake merge record).
After resolving one file:
git add <file>
git commit --no-edit # 全部解完后,生成合并提交
git add before git diff --check use <<<<<<< / ======= / >>>>>>> markers.
✅ Completion criteria: all conflicted files have been judged and add, with no residual conflict markers,git commit --no-edit Merge commit has been generated (or it was already fast-forward and no commit was needed).
4. Done
git log --oneline --graph -5 # 确认合并结果
Echo: merge complete + merge commit hash. For rollback methods, see references/recovery.md。
✅ Completion criteria:git log --oneline --graph -5 Shows the expected merge commit (or the latest commit after ff), and the working tree is git status --porcelain clean.
Failure handling (trigger condition → first-line fix → fallback if still failing)
| Trigger condition | First-line fix | Fallback if still failing |
|---|---|---|
| Unsure about a merge conflict | 🔴 STOP + AskUserQuestion list hunks | User is also unsure → git merge --abort restore original state, report "manual intervention required" |
| Want to give up midway | git merge --abort(return to before merge) |
Already committed → git reset --hard HEAD~1(after confirmation) |
| Unexpected fast-forward | Want to keep a merge record → git merge --no-ff redo |
User wants ff → keep default |
| fetch failed (network/permissions) | Retry fetch; confirm the remote name is correct | Cannot fetch → STOP, do not merge with a stale local branch (violates hard rule 1) |
| Source branch does not exist | List remote branches and have the user confirm the name | Name is indeed wrong → STOP and wait for the correct branch name |
add Conflict markers still visible after |
Re-edit to remove <<<</====/>>>> then add |
Unsure which side to keep → STOP and ask the user |
Honest boundaries
- Semi-automatic, not fully automatic: only "one-sided changes" can be machine-determined and checked out; semantic conflicts where both sides changed must be handled manually.
- merge can be rolled back (
--abort/reset), so unlike git-rebase it does not force creation of a backup branch; but resetting an already-pushed merge still affects collaborators. - Does not handle octopus merge (merging multiple branches at once), and does not handle subtree/submodule merge.
- The "substantive change" determination is based on commit history, and may be misjudged in extreme scenarios → fall through to the "unsure" branch and stop to ask.