本文以 Nebula 项目的日常开发为场景，介绍团队 Git 工作流、分支规范、Commit 规范和常见操作，帮助开发者快速融入团队协作节奏。

---

目录

• 一、分支规范
• 二、日常开发流程
• 三、Commit 提交规范
• 四、合并与 Rebase
• 五、冲突解决
• 六、常用命令速查
• 七、高频场景处理

---

一、分支规范

Nebula 各子项目采用统一的分支命名规范：

分支	说明	谁能直接推
main / master	生产代码，只通过 MR 合并	禁止直接推送
dev	开发主干，日常联调合并目标	禁止直接推送（通过 MR）
feature/xxx	功能开发分支	开发者自己
fix/xxx	Bug 修复分支	开发者自己
hotfix/xxx	紧急线上修复，从 main 切出	开发者自己
release/x.x.x	版本发布分支	发布负责人

命名示例：

feature/idgen-rule-crud        # 功能：发号器规则 CRUD
fix/login-captcha-expire       # 修复：验证码过期判断问题
hotfix/tenant-data-leak        # 紧急修复：租户数据泄露

---

二、日常开发流程

标准开发流程

1. 从 dev 切出功能分支
       ↓
2. 本地开发、提交（多次 commit）
       ↓
3. 推送到远端，发起 Merge Request（MR）
       ↓
4. 等待 Code Review，修改意见处理完毕
       ↓
5. 合并到 dev（Squash 或 Merge）
       ↓
6. 删除功能分支

具体操作

# 1. 确保本地 dev 是最新的
git checkout dev
git pull origin dev

# 2. 从 dev 切出功能分支
git checkout -b feature/user-role-crud

# 3. 开发过程中多次提交
git add .
git commit -m "feat(system): 新增用户角色关联 CRUD 接口"

# 4. 开发完毕，推送到远端
git push origin feature/user-role-crud

# 5. 在 GitLab / GitHub 上发起 MR，目标分支为 dev

# 6. MR 合并后，删除本地分支
git branch -d feature/user-role-crud
git remote prune origin   # 清理已删除的远端分支引用

---

三、Commit 提交规范

Nebula 项目遵循 Conventional Commits 规范，便于自动生成 CHANGELOG 和代码追溯。

格式

<type>(<scope>): <subject>

[可选 body]

[可选 footer]

type 类型

type	说明
feat	新功能
fix	Bug 修复
refactor	重构（不新增功能，不修复 Bug）
perf	性能优化
docs	文档更新
test	测试相关
chore	构建工具、依赖更新等杂项
style	代码格式（不影响逻辑）

scope（影响范围）

scope 填模块或业务域名称，如：system、auth、tenant、idgen、build、deps

示例

# 新功能
git commit -m "feat(system): 新增发号器规则的分页查询和 CRUD 接口"

# Bug 修复
git commit -m "fix(auth): 修复验证码过期后登录不提示的问题"

# 依赖更新
git commit -m "chore(deps): 升级 nebula-boot 至 1.2.3"

# 重构
git commit -m "refactor(tenant): 将数据源路由逻辑抽取为独立 Strategy"

# 带 body 的 commit（说明为什么这样改）
git commit -m "fix(mybatis): 修复 @Select 注解 SQL 缺少 tenant_id 过滤

使用 LambdaQueryWrapper 替代 @Select，确保多租户拦截器生效。
原写法在多租户场景下会查询到其他租户的数据，存在安全风险。"

不好的 commit 写法

# ❌ 太模糊，看不出改了什么
git commit -m "fix bug"
git commit -m "update"
git commit -m "修改"

# ❌ 一次提交包含太多不相关的改动（应该拆分）
git commit -m "feat: 新增用户管理接口 + 修复登录 bug + 重构字典模块"

---

四、合并与 Rebase

推荐用 Rebase 保持分支整洁

在合并 MR 之前，先把 dev 的最新变更同步到自己的分支，避免 MR 中产生大量无关的合并提交：

# 在功能分支上，将 dev 的最新变更 rebase 进来
git checkout feature/user-role-crud
git fetch origin
git rebase origin/dev

# 如果有冲突，解决后继续
git add .
git rebase --continue

# 完成后强制推送（rebase 改变了提交历史）
git push --force-with-lease origin feature/user-role-crud

为什么用 --force-with-lease 而不是 --force？
--force-with-lease 在强制推送前会检查远端是否有别人推的新提交，如果有则推送失败（防止误覆盖他人代码）。

Squash 合并（保持 dev 历史整洁）

MR 合并时，建议选择 Squash and Merge，将功能分支的多次 commit 压缩为 1 个。这样 dev 分支的历史是"每个功能一个 commit"，非常清晰。

---

五、冲突解决

在 IDEA 中解决冲突

IDEA 提供了三窗格合并工具，比命令行更直观：

1. Git → Pull 或 Rebase 操作后，提示有冲突
2. 打开 Git 面板 → Changes → 右键冲突文件 → Resolve Conflicts
3. 三窗格界面：左侧是本地修改，右侧是远端修改，中间是合并结果
4. 逐块点击 >> / << 接受对应修改，或直接在中间编辑
5. 保存后，git add 标记已解决，git rebase --continue 继续

冲突预防技巧

• 小步提交、频繁 push：每完成一个小功能就提交，分支存活时间越短，越不容易冲突
• 功能分支不超过 2 天：分支存活太久，与 dev 分叉越来越深，合并时冲突越多
• 沟通并行修改：如果知道同事也在改同一个文件，提前沟通，错峰修改

---

六、常用命令速查

分支操作

git branch                        # 查看本地所有分支
git branch -a                     # 查看所有分支（含远端）
git checkout -b feature/xxx       # 创建并切换到新分支
git branch -d feature/xxx         # 删除本地分支（已合并）
git branch -D feature/xxx         # 强制删除本地分支（未合并）
git push origin --delete feature/xxx  # 删除远端分支

暂存与恢复

git stash                         # 暂存当前工作区（临时切分支时用）
git stash pop                     # 恢复最近一次暂存
git stash list                    # 查看所有暂存记录
git stash drop stash@{0}          # 删除指定暂存

撤销操作

git restore <file>                # 撤销工作区的修改（未 add）
git restore --staged <file>       # 撤销 add（保留工作区修改）
git reset --soft HEAD~1           # 撤销最近一次 commit（保留代码修改）
git reset --hard HEAD~1           # 撤销最近一次 commit（同时丢弃代码修改，慎用）

查看历史

git log --oneline --graph         # 简洁图形化查看提交历史
git log --author="张三"            # 查看某人的提交
git diff HEAD~1 HEAD              # 对比最近两次提交的差异
git blame <file>                  # 查看文件每行的最后修改人

远端操作

git fetch origin                  # 拉取远端最新信息（不 merge）
git pull --rebase origin dev      # 拉取并 rebase（推荐替代 git pull）
git remote prune origin           # 清理本地已删除的远端分支引用

---

七、高频场景处理

场景 1：不小心在 dev 上直接提交了

# 1. 把刚提交的内容撤回到工作区
git reset --soft HEAD~1

# 2. 切到正确的功能分支
git checkout -b feature/xxx

# 3. 在功能分支上重新提交
git add .
git commit -m "feat: ..."

场景 2：要临时处理一个紧急 Bug，但当前功能开发到一半

# 1. 暂存当前开发中的代码
git stash

# 2. 切到 dev，拉最新代码，切 hotfix 分支
git checkout dev && git pull
git checkout -b hotfix/xxx

# 3. 修复，提交，MR 合并

# 4. 回到功能分支，恢复之前的代码
git checkout feature/xxx
git stash pop

场景 3：提交了包含密码/密钥的文件

# 立刻修改密码/密钥（这步不能省）！

# 从最近 commit 中移除敏感文件（未推送时）
git reset --soft HEAD~1
git restore --staged secret.yaml
echo "secret.yaml" >> .gitignore
git add .
git commit -m "chore: remove secret file"

# 如果已经推送，需要联系仓库管理员强制清除历史
# 同时立即轮转所有泄露的密钥

场景 4：合并时提示 "refusing to merge unrelated histories"

通常出现在新建远端仓库后，本地也初始化了 git：

git pull origin dev --allow-unrelated-histories