Git 合并未合并分支完整教程

背景

在 GitHub / DevOps 工作流中，功能开发通常在独立分支上进行，完成后需要合并到 main。如果分支中存在未合并的 commit，CI/CD 流水线或代码审查系统会提示：

复制代码

Branch `gh-sdd/210163` still has 1 unmerged commit (`#208595 [AIGC] 新增 protobuf V1 集成核心`).
Please merge it to `main` first, then re-check.

本文详细讲解如何安全地将未合并分支合并到 main。

当前状态

项目	详情
当前分支	`main`
待合并分支	`gh-sdd/210163`
未合并 commit 数	1 个
commit 信息	`#208595 [AIGC] 新增 protobuf V1 集成核心：契约、编解码、映射、协调器与 40 项单元测试`
涉及文件	13 个文件，+2050 行

分支关系图

复制代码

origin/main ──●──●──●──●──●──●──●──● (远程 main)
                          \
 main (本地) ──●──●─────────● (本地 main, 领先1个commit: 大文件清理)
                          \
 gh-sdd/210163 ────────────● (9d94ff9, 待合并)

第一步：确认当前状态

1.1 查看当前所在分支

bash 复制代码

git branch

意图： 确认当前在 main 分支上操作，避免误操作其他分支。

复制代码

* main
  gh-sdd/210163

1.2 查看待合并分支有哪些未合并的 commit

bash 复制代码

git log main..gh-sdd/210163 --oneline

意图： A..B 语法表示"B 中有但 A 中没有的 commit"。这条命令列出 gh-sdd/210163 上尚未合并到 main 的所有 commit。

复制代码

9d94ff9 #208595 [AIGC] 新增 protobuf V1 集成核心：契约、编解码、映射、协调器与 40 项单元测试

1.3 查看待合并 commit 的详细信息

bash 复制代码

git log gh-sdd/210163 -1 --format="%H %an %ae %ad"

意图： 查看 commit 的完整哈希、作者、邮箱、时间，确认是正确的提交。

复制代码

9d94ff966e31f80c2a2680993f490f87a263759f maokaiyin maokaiyin@jly.cn Tue Aug 18 11:38:30 2026 +0800

1.4 查看待合并的文件变更

bash 复制代码

git diff main..gh-sdd/210163 --stat

意图： 预览合并后会影响哪些文件，评估变更范围和冲突风险。

复制代码

 backend/app/integration/__init__.py                |  24 +
 backend/app/integration/coordinator.py             | 391 ++++++++++++++
 backend/app/integration/domain_mapper.py           | 197 +++++++
 backend/app/integration/generated/__init__.py      |   1 +
 .../generated/simulation_integration_v1_pb2.py     | 450 ++++++++++++++++
 backend/app/integration/protobuf_codec.py          | 150 ++++++
 backend/app/schemas.py                             |  14 +
 backend/app/services/planner.py                    |   5 +-
 backend/app/services/store.py                      |  20 +-
 backend/data/tables/simulation_mappings.json       |  70 +++
 backend/proto/simulation_integration_v1.proto      | 161 ++++++
 backend/requirements.txt                           |   1 +
 backend/tests/test_protobuf_integration_core.py    | 568 +++++++++++++++++++++
 13 files changed, 2050 insertions(+), 2 deletions(-)

第二步：合并分支

2.1 确保当前在 main 分支

bash 复制代码

git checkout main
# 或
git switch main

意图： 合并操作的目标分支。必须先切到接收合并的分支上。

2.2 拉取远程 main 最新代码（如有需要）

bash 复制代码

git pull origin main

意图： 如果有其他协作者已经向远程 main 推送了新 commit，先同步到本地，避免合并后产生不必要的冲突。

2.3 执行合并

bash 复制代码

git merge gh-sdd/210163

意图： 将 gh-sdd/210163 的所有未合并 commit 合并到当前分支（main）。

Git 会尝试自动合并。可能出现两种结果：

情况 A：自动合并成功

复制代码

Updating 2dfd04e..9d94ff9
Fast-forward
 13 files changed, 2050 insertions(+), 2 deletions(-)

Fast-forward 表示 main 是 gh-sdd/210163 的直接祖先，Git 只需将指针前移，无需创建合并 commit。

情况 B：出现冲突

复制代码

Auto-merging backend/app/services/planner.py
CONFLICT (content): Merge conflict in backend/app/services/planner.py
Automatic merge failed; fix conflicts and then commit the result.

如果出现冲突，进入第三步；否则跳到第四步。

第三步：解决冲突（仅在出现冲突时执行）

3.1 查看冲突文件列表

bash 复制代码

git status

意图： 找出所有标记为 both modified 的冲突文件。

复制代码

Unmerged paths:
  both modified:   backend/app/services/planner.py

3.2 手动编辑冲突文件

打开冲突文件，找到冲突标记并解决：

复制代码

<<<<<<< HEAD
这是 main 分支上的内容
=======
这是 gh-sdd/210163 分支上的内容
>>>>>>> gh-sdd/210163

冲突标记含义：

标记	含义
`<<<<<<< HEAD`	当前分支（main）的内容开始
`=======`	分隔线
`>>>>>>> gh-sdd/210163`	合并分支的内容结束

手动选择保留哪部分代码，删除冲突标记。

3.3 标记冲突已解决

bash 复制代码

git add backend/app/services/planner.py

意图： 告诉 Git 该文件的冲突已手动解决，加入暂存区。

3.4 提交合并

bash 复制代码

git commit -m "merge: 合并 gh-sdd/210163 protobuf V1 集成核心"

意图： 完成合并 commit，记录这次合并操作。

第四步：验证合并结果

4.1 确认分支已合并

bash 复制代码

git log main..gh-sdd/210163 --oneline

意图： 再次检查是否还有未合并的 commit。如果输出为空，说明全部已合并。

复制代码

（无输出 = 合并完成）

4.2 查看合并后的 commit 历史

bash 复制代码

git log --oneline -5

意图： 确认 commit 历史符合预期。

复制代码

9d94ff9 #208595 [AIGC] 新增 protobuf V1 集成核心：契约、编解码、映射、协调器与 40 项单元测试
2dfd04e feat: Docker 离线部署、CORS 配置、前端同源化、测试补充（不含二进制大文件）
41598c4 更改基础镜像
d893797 前端打包
2cc5877 feat: add production deployment and equipment reconstruction

4.3 验证文件内容正确

bash 复制代码

git diff HEAD~1..HEAD --stat

意图： 确认最新 commit（合并进来的）包含预期的文件变更。

第五步：推送合并结果到远程

5.1 推送 main 分支

bash 复制代码

git push origin main

意图： 将合并后的 main 推送到远程仓库，使 CI/CD 系统识别到分支已合并。

5.2 （可选）清理已合并的远程分支

bash 复制代码

git push origin --delete gh-sdd/210163

意图： 分支合并后通常不再需要，删除远程分支保持仓库整洁。

注意： 此操作不可逆，确保分支确实已合并后再执行。

5.3 （可选）删除本地已合并分支

bash 复制代码

git branch -d gh-sdd/210163

意图： 清理本地分支列表。-d 参数只删除已合并的分支（安全模式）。

如果分支未合并但想强制删除：

bash 复制代码

git branch -D gh-sdd/210163

完整操作速查

bash 复制代码

# === 检查阶段 ===
git branch                                          # 确认在 main
git log main..gh-sdd/210163 --oneline               # 查看待合并 commit
git diff main..gh-sdd/210163 --stat                 # 预览变更范围

# === 合并阶段 ===
git checkout main                                   # 切到 main
git pull origin main                                # 同步远程最新
git merge gh-sdd/210163                             # 执行合并

# === 冲突解决（如有） ===
# 手动编辑冲突文件 → 删除冲突标记 → 选择保留内容
git add <冲突文件>                                   # 标记已解决
git commit -m "merge: 合并说明"                      # 提交合并

# === 验证阶段 ===
git log main..gh-sdd/210163 --oneline               # 确认无未合并 commit
git log --oneline -5                                # 查看历史

# === 推送与清理 ===
git push origin main                                # 推送到远程
git push origin --delete gh-sdd/210163              # 删除远程分支（可选）
git branch -d gh-sdd/210163                         # 删除本地分支（可选）

注意事项

合并前确保工作区干净 。运行 git status 确认没有未提交的修改，否则合并可能产生意外冲突。
合并前检查大文件 。确保待合并分支不包含不应入库的大文件（参考 Git 移除大文件教程）。
Fast-forward vs 合并 commit。
- 如果 main 在分支创建后没有新 commit，Git 会执行 Fast-forward（快进），不会创建额外的合并 commit。
- 如果 main 有新 commit，Git 会创建一个合并 commit 保留分支历史。
不要在公共分支上 rebase 。如果分支已推送到远程且有其他人在使用，应使用 merge 而非 rebase，避免改写历史导致协作者冲突。
合并后运行测试。确认合并后的代码能正常编译、测试通过，再推送到远程。