Git 分支管理与代码合并规范（master/dev 分支场景）
Git 分支管理与代码合并规范（master/dev 分支场景）
本文整理了 Git 日常开发中涉及 master（主分支）和 dev（开发分支）的核心操作流程，包含仓库初始化、分支开发、代码合并、冲突处理、代码回退等关键场景。
一、初始化仓库（首次使用）
场景1：直接克隆远程仓库（推荐，避免关联问题）
# 克隆远程仓库到本地（自动创建本地仓库并关联远程）git clone 远程仓库地址 # 示例：git clone https://github.com/用户名/仓库名.git# 进入仓库目录cd 仓库名 场景2：本地先建仓库，再关联远程
# 本地初始化仓库git init # 添加文件并首次提交gitadd.# 暂存所有文件git commit -m "首次提交：初始化项目"# 关联远程仓库（远程仓库需提前在平台创建）git remote add origin 远程仓库地址 # 首次拉取远程历史（若远程有内容，必须执行，否则推送报错）git pull origin master --allow-unrelated-histories # 仅首次需要# 推送本地仓库到远程（-u 绑定上游分支，后续可直接 git push）git push -u origin master 二、日常开发核心流程（dev 分支开发）
1. 分支准备（确保基础分支最新）
# 切换到本地 master 分支git checkout master # 拉取远程 master 最新代码git pull origin master # 切换到本地 dev 分支（若无则创建：git checkout -b dev）git checkout dev # 合并远程 master 到本地 dev（同步主分支更新）git fetch origin master git merge origin/master 2. 本地开发与提交
# 查看文件状态（确认修改/新增文件）git status # 暂存修改（单个文件/所有文件）gitadd 文件名 # 暂存单个文件gitadd.# 暂存所有修改（推荐）# 提交到本地仓库（备注需清晰，仅包含单个功能点）git commit -m "功能：完成dev分支XX模块开发"3. 推送本地 dev 到远程 dev
# 首次推送 dev 分支到远程（-u 绑定上游）git push -u origin dev # 后续修改后推送（已绑定上游，直接推送）git push 4. 定期同步主分支更新（减少冲突）
# 在 dev 分支中拉取并合并远程 master 最新代码git pull origin master # 若出现冲突（终端提示 "Automatic merge failed"）：# 1. 打开冲突文件，删除冲突标记（<<<<<<< HEAD、=======、>>>>>>> origin/master）# 2. 保留需要的内容，保存文件# 3. 标记冲突已解决并提交gitadd.# 标记所有冲突文件已解决git commit -m "合并master到dev，解决XX模块冲突"git push # 推送到远程 dev 分支三、代码合并（dev → master）
场景1：合并 dev 分支指定提交到 master
适用于仅需合并 dev 分支中某一个提交（而非整个分支）的场景：
# 1. 切换到 master 分支并检查工作区git checkout master git status # 2. 暂存 master 分支未提交的修改（若有）git stash # 3. 拉取远程 master 最新代码git pull origin master # 4. 查找 dev 分支中需要合并的提交哈希值git checkout dev git log --oneline -n 10# 查看最近10条提交，复制目标哈希值（如 23919c9）# 5. 切回 master 分支，执行 cherry-pick 合并指定提交git checkout master git cherry-pick 23919c9 # 6. 若 cherry-pick 出现冲突，解决后提交gitadd.git commit -m "cherry-pick：合并dev分支23919c9提交到master"# 7. 推送合并后的 master 到远程git push origin master # 8. 恢复 master 分支暂存的修改（若有）git stash pop # 9. 验证提交结果（确认指定提交已合并）git log # 查看提交历史场景2：合并整个 dev 分支到 master
适用于 dev 分支功能开发完成，需整体合并到主分支的场景：
# 1. 切换到 master 分支并拉取最新git checkout master git pull origin master # 2. 合并远程 dev 分支到本地 mastergit merge origin/dev # 3. 若出现冲突，解决后提交gitadd.# 标记冲突已解决git commit -m "合并dev分支到master，解决XX模块冲突"# 4. 推送 master 到远程（可测试完成后推送）git push origin master # 5. 验证合并结果git log # 查看提交历史，确认dev分支代码已合并场景3：合并后清理（可选）
若 dev 分支功能已完全合并到 master 且无需保留，可清理分支：
# 删除本地 dev 分支git branch -d dev # 删除远程 dev 分支（确认不再需要时执行）git push origin --delete dev 四、代码回退操作
需将本地指定文件回退到历史提交版本，并重新提交推送的场景：
# 1. 回退指定文件到历史提交版本（替换哈希值和文件路径）git restore --source=054f3b -- backend/app/api/v1/module_visualization/service.py # 2. 暂存回退后的文件gitadd backend/app/api/v1/module_visualization/service.py # 3. 提交回退操作git commit -m "回退：将XX文件恢复到054f3b版本"# 4. 拉取远程最新代码（避免推送冲突）git pull origin dev # 若操作的是dev分支# 5. 推送回退后的代码到远程git push origin dev 五、关键注意事项
1. 推送前必拉取
无论推送到 master 还是 dev 分支，推送前必须执行 git pull origin 分支名，确保本地与远程同步，避免推送被拒绝（rejected 错误）。
2. 分支规范
- 主分支（master）：保持可运行状态，不直接修改；
- 开发分支（dev）：从 master 创建，用于日常功能开发；
- 功能分支（可选）：feature/功能名（从 dev 创建，开发独立功能）；
- 修复分支（可选）：bugfix/问题名（从 dev 创建，修复开发分支问题）。
3. 提交与合并规范
- 提交粒度：每次提交仅包含一个功能点（如“修复dev分支登录按钮样式”），避免大量无关修改；
- 冲突处理：必须删除冲突标记（<<<<<<< / ======= / >>>>>>>），不确定保留内容时及时沟通；
- 合并后提交：冲突解决后必须先
git commit标记状态，推送可延后（如测试完成后）。
4. 数据安全
- 定期备份：dev 分支开发到关键节点（如完成子模块），立即推送到远程 dev 分支；
- 暂存恢复：使用
git stash暂存未提交修改，合并完成后通过git stash pop恢复。
六、冲突处理专项
1. 冲突标记识别
冲突文件中会出现以下标记，需全部删除：
<<<<<<< HEAD （本地分支的代码） ======= （远程分支的代码） >>>>>>> origin/master 2. 冲突处理流程
- 打开冲突文件，删除上述标记；
- 保留正确的代码内容（可与团队确认）；
- 执行
git add .标记冲突已解决； - 执行
git commit提交（备注需说明“解决XX冲突”）； - 推送当前分支到远程（如 dev → 远程 dev，master → 远程 master）。
总结
- 核心流程：dev 分支开发 → 定期同步 master 更新 → 合并（指定提交/整分支）到 master → 推送验证；
- 冲突关键：推送前必拉取、删除冲突标记、解决后先提交再推送；
- 分支原则：master 保持稳定不直接开发，dev 分支承接日常开发，提交粒度小且备注清晰。
