git-merge-to-main

Git 合并到 Main

概述

将当前分支合并到 main，然后在本地删除源分支，因为它现在已完全合并；如果源分支受保护，则保留。安全是此流程的设计原则——绝不使用 --force，绝不使用 -D（只使用 -d），绝不自动解决冲突，绝不自动推送。

开始时宣告：“我将使用 git-merge-to-main 技能把 <source-branch> 合并到 main，并在源分支未受保护时将其删除。”

受保护的源分支

以下源分支名称受保护，合并后必须在本地保留：

main、master、dev、develop、development、stg、stage、staging、root

如果 src 是受保护的源分支，仍要显示合并计划，并在确认后继续，但跳过本地删除步骤。不要对受保护的分支运行 git branch -d "$src"，也不要建议删除它们的远程分支。

前置条件

执行任何操作前先运行这些检查。任何一项不符合都应采取失败关闭策略——报告问题并停止。

#	检查	命令	失败时
1	位于 Git 仓库中	git rev-parse --is-inside-work-tree	中止：“这不是 Git 仓库。”
2	HEAD 已关联到分支（未分离）	git symbolic-ref -q HEAD	中止：“HEAD 处于分离状态；请先检出一个分支。”
3	当前分支不是 main	[ "$(git branch --show-current)" != "main" ]	中止：“已在 main 上；无需合并。”
4	工作区干净	[ -z "$(git status --porcelain)" ]	中止：“工作区有未提交的更改；请先提交或暂存。”
5	本地存在 main 分支	git rev-parse --verify main	中止：“本地未找到 main 分支；请创建该分支或使用 git-merge-to-dev。”

工作流程

第 1 步：捕获状态

src=$(git branch --show-current)
echo "Source branch: $src"
git log --oneline "main..$src" | head -20      # what will be merged

如果 main..$src 为空 → 告知用户“$src 没有超出 main 的新提交；无需合并”，然后停止。

显示计划前，确定源分支是否受保护：

protected=(main master dev develop development stg stage staging root)
delete_src=1
case " ${protected[*]} " in
  *" $src "*) delete_src=0 ;;
esac

第 2 步：显示计划并确认

Plan:
  1. git checkout main
  2. git merge $src
  3. git branch -d $src     (safe delete; refuses if not fully merged)
  4. (you stay on main; push manually when ready)

N commits will be merged. Proceed? (y/N)

如果 delete_src=0，则将第 3 步替换为：

  3. skip the local delete for protected source branch $src

等待明确确认。默认选择为否。

第 3 步（可选）：获取并检查分歧（仅提供信息）

git fetch origin main 2>/dev/null || true
behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo 0)
if [ "$behind" -gt 0 ]; then
  echo "Heads up: local main is $behind commits behind origin/main."
  echo "After merge, you'll want to: git pull --rebase (or reconcile manually) before pushing."
fi

不要自动拉取。何时同步由用户决定。

第 4 步：切换到 main 并合并

git checkout main
git merge "$src"

使用普通的 git merge——可能时快进，否则创建合并提交。除非用户要求，否则不要使用 --no-ff。不要使用 --ff-only（历史分歧时该命令会报错；让 merge 处理即可）。

如果合并产生冲突：

1. **停止。**不要尝试自动解决。
2. 报告冲突路径。
3. 告知用户解决冲突后运行 git commit（完成合并），或运行 git merge --abort（回滚）。
4. 不要删除源分支。

第 5 步：删除或保留源分支

合并成功且工作区干净后：

if [ "$delete_src" -eq 0 ]; then
  echo "Source branch $src is a protected source branch; skip the local delete."
else
  git branch -d "$src"
fi

对于不受保护的源分支，使用 -d（小写）。如果分支尚未完全合并，Git 会拒绝删除——这是安全保障。此处绝不使用 -D（强制）。如果 -d 拒绝删除：

• 最可能的原因是合并实际上未包含 $src 的所有提交（例如，用户选择了 --ff-only，导致操作未产生变更，或者钩子改写了合并）。请报告问题并停止；不要升级为使用 -D。

第 6 步：摘要

git log --oneline -5
git branch --show-current
if [ "$delete_src" -eq 0 ]; then
  echo "Merged $src into main and kept protected source branch $src locally. Push when ready: git push"
else
  echo "Merged $src into main and deleted $src locally. Push when ready: git push"
fi

如果存在远程跟踪分支 origin/$src 且 src 未受保护，提及该分支，但不要自动删除：

Note: origin/$src still exists. Delete the remote branch with:
  git push origin --delete $src

对于受保护的源分支，不要建议删除远程分支。

示例

User: 이 브랜치를 main에 머지해줘

Step 1:
  src = feature/oauth-login
  git log --oneline main..feature/oauth-login →
    a1b2c3d feat(auth): add OAuth login flow
    e4f5g6h test(auth): add OAuth login tests

Step 2 (plan):
  → checkout main, merge feature/oauth-login, delete feature/oauth-login
  User confirms.

Step 3 (divergence): origin/main is 0 commits ahead. ✓

Step 4: git checkout main && git merge feature/oauth-login → fast-forward.

Step 5: git branch -d feature/oauth-login → "Deleted branch feature/oauth-login (was a1b2c3d)."

Step 6: Show git log -5; remind user to push.

受保护的源分支示例：

User: dev를 main에 머지해줘

Source: dev (protected)
Plan:
  1. git checkout main
  2. git merge dev
  3. skip the local delete for protected source branch dev

User confirms.
→ checkout main, merge succeeds, keep dev locally.
→ Remind user to push main when ready.

危险信号

绝不：

• 使用 git branch -D（强制删除）——使用 -d 并遵守安全检查
• 自动解决合并冲突——停止并让用户解决
• 合并后自动推送——用户准备好后自行推送
• 未经用户明确同意运行 git pull / git pull --rebase
• 未经用户明确同意删除远程分支（git push origin --delete）
• 删除受保护的源分支：main、master、dev、develop、development、stg、stage、staging、root
• 在任何地方使用 --force
• 在工作树不干净时进行操作

始终：

• 合并前展示计划并等待确认
• 报告冲突并停止，不要自动修复
• 删除未受保护的源分支时使用安全的 git branch -d
• 识别受保护的源分支并跳过本地删除
• 合并后运行 git status --short，确认工作树状态

常见错误

当 -d 拒绝删除时改用强制删除

• **问题：**提示“branch was not fully merged”后，就想改用 -D
• **解决方法：**调查合并未完成的原因；绝不要自动升级为使用 -D

发布合并后删除长期存在的分支

• **问题：**将 dev / staging / master 合并到 main 后，又像删除功能分支一样将其删除
• **解决方法：**将受保护的源分支视为合并后保留的分支；跳过本地删除

合并后自动推送

• **问题：**这会让用户措手不及；如果 main 落后，还可能破坏协作者的工作流
• **解决方法：**合并后停止；告知用户手动推送

未经许可拉取 main

• 问题：git pull 可能会变基或合并意料之外的提交
• **解决方法：**仅运行 git fetch origin main（用于获取信息）；由用户处理同步

集成

配合使用：

• git-commit / git-commit-push — 先提交工作树中的更改，再进行合并
• git-branch-cleanup — 批量删除已合并到 main 的其他分支
• git-merge-to-dev — 相同模式，目标为 dev（或 develop）

**调用方式：**仅由用户手动调用。绝不要在其他技能的工作流中自动运行。