Git 常用操作手册
日常开发 Git 工作流总览
1. 分支模型
1.1 分支命名规范
| 分支类型 | 命名格式 | 用途 | 示例 |
|---|---|---|---|
| 主干分支 | master | 稳定发布分支，受保护 | master |
| 版本开发分支 | dev/vX.Y.Z | 版本集成分支，多人协作 | dev/v1.3.0 |
| 特性分支 | feature/<desc> | 个人/小组特性开发，合入到 dev/vX.Y.Z | feature/device_ui |
| 短特性分支 | feat/<desc> | 轻量特性分支（命名更短） | feat/v1.2.0_cmd_audio |
| 修复分支 | fix/<desc> | Bug 修复分支 | fix/crash_on_boot |
| 热修复 | hotfix/vX.Y.Z | 线上紧急修复，基于 master | hotfix/v1.2.2 |
1.2 保护分支
master、dev/vX.Y.Z：禁止直接 push，必须通过 MR 合入- 禁止在保护分支上执行
git push -f
2. 日常开发流程
2.1 初始化仓库
bash
# 克隆仓库
git clone your_repository
cd your_project
# 配置用户信息
git config user.name "yourname"
git config user.email "youremail"
# 建议开启 rerere，自动复用冲突解决
git config rerere.enabled true
2.2 创建特性分支
bash
# 1. 切到目标版本分支并拉取最新代码
git checkout dev/v1.3.0
git pull --rebase origin dev/v1.3.0
# 2. 基于 dev 分支创建特性分支
git checkout -b feature/device_ui
# 3. 推送到远程并关联（首次推送）
git push -u origin feature/device_ui
2.3 日常提交
bash
# 查看变更
git status
git diff # 工作区 vs 暂存区
git diff --cached # 暂存区 vs HEAD
# 添加并提交
git add <file> # 精确添加，避免 git add .
git commit -m "feat(模块): 简要描述"
# 推送
git push
3. 提交规范（Commit Message）
3.1 格式
<type>(<scope>): <subject>
- type（必填）：提交类型
- scope（推荐）：影响模块，使用中文或英文均可，需与项目内现有 scope 保持一致
- subject（必填）：简短描述，≤ 50 字，结尾不加句号
3.2 type 取值
| type | 含义 | 示例 |
|---|---|---|
feat | 新功能 | feat(自定义UI): 新增自定义UI模块开发 |
fix | Bug 修复 | fix(轮询): 修复任务重复触发问题 |
refactor | 重构（非新增也非修复） | refactor(错误码): 重新调整错误码号段顺序 |
docs | 文档变更 | docs(changelog): 新增1.3.0版本changelog |
chore | 构建/工具链/非业务改动 | chore(单元测试): 添加 ENABLE_TESTING 选项 |
test | 测试相关 | test(激活): 补充异常路径用例 |
perf | 性能优化 | perf(日志): 降低空闲时 CPU 占用 |
style | 格式调整（不影响行为） | style: 对齐 include 顺序 |
3.3 修改最近一次提交
bash
# 修改 message
git commit --amend -m "feat(模块): 更准确的描述"
# 把新改动并入最近一次提交（不改 message）
git add <file>
git commit --amend --no-edit
# 已推送则需要 force-with-lease
git push --force-with-lease
4. 同步上游分支
4.1 拉取远端更新
bash
# 仅拉取，不合并
git fetch origin
# 拉取并 rebase（推荐，保持线性历史）
git pull --rebase origin dev/v1.3.0
# 拉取并 merge（会产生 merge commit）
git pull origin dev/v1.3.0
4.2 特性分支同步 dev 最新代码（rebase 方式）
bash
# 当前在 feature/xxx 分支
git fetch origin
git rebase origin/dev/v1.3.0
# 冲突处理
# 1. 查看冲突文件
git status
# 2. 编辑解决冲突后
git add <resolved_file>
git rebase --continue
# 3. 放弃本次 rebase
git rebase --abort
# 推送（必须 force-with-lease）
git push --force-with-lease
4.3 什么时候用 rebase / merge
| 场景 | 选择 | 原因 |
|---|---|---|
| 个人特性分支同步 dev | rebase | 保持线性历史，MR 更清晰 |
| dev → master 发版合入 | merge | 保留版本集成记录，便于回溯 |
| master → dev 同步 hotfix | merge | 多人共享分支，避免改写历史 |
| 已推送并被他人拉取的分支 | merge | 禁止改写已共享的历史 |
5. Merge 操作
5.1 基础 merge
bash
# 将 dev 合入 master（发版）
git checkout master
git pull --rebase origin master
git merge --no-ff dev/v1.3.0 -m "Merge dev/v1.3.0 into master"
git push origin master
--no-ff强制保留 merge commit，便于回溯发版记录。
5.2 解决 merge 冲突
bash
git merge origin/dev/v1.3.0
# 出现冲突
git status # 查看冲突文件
# 手动编辑 <<<<<<< ======= >>>>>>> 标记处
git add <resolved_file>
git commit # 使用默认 merge message
# 放弃合并
git merge --abort
5.3 Cherry-pick（跨分支选择性合入）
bash
# 将某个 commit 合入到当前分支
git cherry-pick <commit_hash>
# 批量（范围）
git cherry-pick <start_hash>^..<end_hash>
# 冲突处理
git cherry-pick --continue
git cherry-pick --abort
git cherry-pick --skip
典型场景：master 的 hotfix 合回 dev，或把 dev 上某个独立修复提到其他版本分支。
6. 回滚操作
6.1 回滚工作区/暂存区（未提交）
bash
# 撤销工作区修改（谨慎：不可恢复）
git restore <file>
git checkout -- <file> # 旧写法
# 撤销暂存区（保留工作区修改）
git restore --staged <file>
git reset HEAD <file> # 旧写法
# 全部丢弃（工作区 + 暂存区）
git checkout .
git clean -fd # 删除未跟踪文件/目录
6.2 回滚最近的提交（本地未推送）
bash
# 撤销最近 1 次 commit，保留改动到暂存区
git reset --soft HEAD~1
# 撤销最近 1 次 commit，改动回到工作区（不保留暂存）
git reset HEAD~1
# 彻底丢弃最近 1 次 commit（改动也丢失，危险）
git reset --hard HEAD~1
6.3 回滚已推送的提交（共享分支）
不要用 reset --hard，会改写共享历史。必须用 revert 生成反向 commit：
bash
# 回滚单个 commit
git revert <commit_hash>
git push
# 回滚 merge commit（需指定主分支 parent）
git revert -m 1 <merge_commit_hash>
git push
# 回滚连续多个 commit（不生成中间 commit）
git revert --no-commit <old_hash>..<new_hash>
git commit -m "revert: 回滚 xxx 特性"
git push
6.4 误操作恢复（reflog 救命）
bash
# 查看所有 HEAD 移动记录（包括已 reset 的 commit）
git reflog
# 恢复到指定状态
git reset --hard HEAD@{3}
# 找回误删分支
git checkout -b <branch_name> <reflog_hash>
6.5 回滚场景速查表
| 场景 | 命令 |
|---|---|
| 改错工作区文件 | git restore <file> |
| 加错了暂存 | git restore --staged <file> |
| 提交信息写错 | git commit --amend |
| 本地多提了 1 个 commit | git reset --soft HEAD~1 |
| 远程已推送，要撤回业务改动 | git revert <hash> && git push |
| 误删分支 | git reflog → git checkout -b |
7. Tag 与发版
7.1 常用命令
bash
# 创建带注解的 Tag（推荐）
git tag -a v1.3.0 -m "Release v1.3.0"
# 基于指定 commit 打 Tag
git tag -a v1.3.0 <commit_hash> -m "Release v1.3.0"
# 推送单个 Tag
git push origin v1.3.0
# 推送全部 Tag
git push origin --tags
# 查看 Tag 信息
git show v1.3.0
# 删除 Tag
git tag -d v1.3.0 # 本地
git push origin :refs/tags/v1.3.0 # 远程
8. Stash 暂存
bash
# 暂存当前改动（带说明）
git stash push -m "wip: 调试上报逻辑"
# 暂存包含未跟踪文件
git stash push -u -m "wip"
# 查看 stash 列表
git stash list
# 恢复最近一次并删除
git stash pop
# 恢复但保留 stash
git stash apply stash@{0}
# 删除指定 stash
git stash drop stash@{0}
# 清空所有 stash
git stash clear
典型场景：rebase / 切分支前有未提交改动。
9. 常用辅助命令
9.1 日志查看
bash
# 简洁单行
git log --oneline -n 20
# 图形化分支
git log --oneline --graph --all -n 30
# 查看某文件历史
git log --follow -p <file>
# 查看某作者提交
git log --author="abc" --oneline
9.2 差异比对
bash
git diff <branch1>..<branch2> # 分支差异
git diff <commit1> <commit2> -- <file> # 文件在两个 commit 之间的差异
git diff --stat # 只看修改统计
9.3 追溯问题
bash
# 查看某行代码是谁改的
git blame <file>
git blame -L 100,120 <file>
# 二分查找引入问题的 commit
git bisect start
git bisect bad # 当前是坏的
git bisect good <old_hash> # 标记一个好的
# 反复 git bisect good / bad 直到定位
git bisect reset
9.4 分支清理
bash
# 列出已合入 dev 的本地分支（可安全删除）
git branch --merged dev/v1.3.0
# 删除本地分支
git branch -d feature/xxx # 安全删（必须已合并）
git branch -D feature/xxx # 强制删
# 删除远程分支
git push origin --delete feature/xxx
# 清理本地对已删远端分支的跟踪
git fetch --prune
11. 最佳实践清单
- ✅ 每次开始开发前先
git fetch+rebase origin/dev/vX.Y.Z - ✅ 推送共享分支永远使用
--force-with-lease，严禁-f - ✅ 提交粒度小而清晰，一个 commit 只做一件事
- ✅ Commit message 遵循
type(scope): desc，scope 与团队约定一致 - ✅ MR 合入前本地必须编译通过，关键模块跑过单测
- ✅ 不在
master/dev/*上直接开发和 push - ✅ 回滚已推送的 commit 用
revert，不用reset - ✅ 切分支 / rebase 前先
stash或commit，保持工作区干净 - ✅ 善用
git reflog，它能救命 - ❌ 禁止提交大二进制、生成物、密钥到仓库（走
.gitignore） - ❌ 禁止
git add .盲加，容易误提交无关文件
💬 评论