文档

常用Git规范及命令

# 常用Git规范及命令

# COMMIT 规范

主流社区（GitHub 开源、Conventional Commits、部分阿里/腾讯项目）普遍采用 类型 + 简短描述 的格式，便于自动生成 Changelog 和语义化版本。

# 标准格式（Conventional Commits）

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

[optional body]

[optional footer]

1
2
3
4
5

type（必填）：提交类型，见下表。
scope（可选）：影响范围，如模块名、包名，如 feat(auth):。
subject（必填）：简短说明，约 50 字以内，句末不加句号；使用祈使句，如「添加」「修复」。
body（可选）：详细说明动机、改动内容。
footer（可选）：关联 Issue（如 Closes #123）、标注破坏性变更（BREAKING CHANGE: 或 type 后加 !）。

# type 类型说明

type	说明	Changelog
`feat`	新功能	✅ 通常纳入
`fix`	修复 BUG	✅ 通常纳入
`docs`	文档/注释	按需
`style`	代码格式、风格，不改变逻辑	一般不纳入
`refactor`	重构	按需
`perf`	性能优化	建议纳入
`test`	测试相关	一般不纳入
`chore`	构建/依赖/工具/配置	一般不纳入
`ci`	持续集成	一般不纳入
`revert`	撤销某次提交	按需
`workflow`	工作流改进	按需
`types`	类型定义变更	按需
`wip`	开发中（可仅本地使用）	不纳入

# 书写要求

subject：简洁、用中文或英文统一；说明「做了什么」而非「做了啥功能」。
一行一事：一次 commit 只做一类改动，便于回滚和追溯。
禁止：无意义说明（如「更新」「fix」「修改代码」）、直接粘贴大段代码说明。

# 示例

feat(auth): 增加登录超时配置项
fix(api): 修复列表分页在空数据时报错
docs: 更新 README 安装步骤
refactor(utils): 抽离日期格式化函数

1
2
3
4

# 其他规范参考

腾讯部分项目（如 StreamPark）：[ISSUE-XXXX][Feature|Bug|Refactor|...] 标题，强调用 Issue 号驱动。
部分阿里/内部项目：在 type 基础上要求关联 Redmine/禅道单号。
参与具体开源项目时，以该仓库的 CONTRIBUTING.md 或 PR 模板为准。

# PR 规范

适用于 GitHub / Gitee 等平台的 Pull Request（合并请求），便于代码评审和合并。

# PR 标题

与 commit 风格一致更佳，如：feat(auth): 增加登录超时配置。
写清「做了什么」或「修复了哪类问题」，可带 Issue 号，例如：修复用户登录超时异常（#127）。
避免笼统标题，如「问题修复」「更新代码」。

# PR 描述建议

项	说明
修改背景	解决什么问题、关联的 Issue 链接
实现方案	采用的做法、关键设计决策
影响范围	涉及模块、是否兼容旧逻辑
测试说明	如何验证、是否通过单测/联调

可补充：替代方案与取舍、需要 Reviewer 重点看的文件、截图或操作步骤。

# 分支与提交要求

分支命名：feature/功能简述、fix/问题简述、docs/xxx 等，与团队约定一致。
一个 PR 一事：一个 PR 只做一类改动，便于回滚和 Code Review。
控制规模：单 PR 改动量不宜过大（如建议不超过约 800 行），可拆成多个 PR。
提交前：在目标分支上先 pull/rebase 一次，减少冲突；通过 CI 后再提 PR。

# 常用命令

# git 配置

# 全局配置（首次使用建议设置）
git config --global user.name "<用户名>"
git config --global user.email "<电子邮件>"

# 查看配置
git config --list

# 其他常用配置
git config color.ui true          # 彩色输出
git config format.pretty oneline  # 历史记录单行显示

1
2
3
4
5
6
7
8
9
10

# 项目初始化

git init                          # 在当前目录创建新仓库
git clone <git地址>                # 克隆远端仓库到本地
git clone /path/to/repository     # 从本地路径检出

1
2
3

# 个人开发

# 查看状态与差异
git status                        # 查看工作区/暂存区状态
git diff                          # 工作区 vs 暂存区
git diff HEAD                     # 工作区 vs 最近一次 commit
git log                           # 查看提交历史
git show [commit]                 # 查看某次提交内容

# 暂存与提交
git add <file>                    # 将文件加入暂存区（A → B）
git add .                         # 暂存所有修改
git add -i                        # 交互式选择要暂存的文件
git commit -m "<提交说明>"         # 提交到本地（B → C）
git commit -am "<提交说明>"        # 暂存已跟踪文件并提交（-a 含修改与增删）
git commit --amend                # 与上一次 commit 合并，可修改说明（*B → C）

# 撤销操作
git reset <file>                  # 将某文件从暂存区撤出，C → B
git reset                         # 暂存区回滚到最近一次提交，C → B
git reset --hard                  # 暂存区+工作区都回滚，C → B → A
git reset HEAD~1                  # 撤销最近一次本地 commit（保留修改）
git checkout -- <file>            # 工作区从暂存区恢复，B → A
git checkout HEAD -- <file>       # 工作区从最近一次提交恢复，C → A

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 多分支开发

# 分支列表与创建
git branch                        # 列出本地分支
git branch -r                     # 列出远端分支
git branch -a                     # 列出所有分支
git branch <分支名>                # 新建分支
git checkout -b <分支名>           # 新建并切换到该分支
git checkout -b <本地分支> origin/<远端分支>  # 新建本地分支并跟踪远端

# 切换与删除
git checkout <分支名>              # 切换分支
git branch -d <分支名>             # 删除已合并分支
git branch -D <分支名>             # 强制删除分支

# 合并与衍合
git merge <分支名>                 # 将指定分支合并到当前分支
git rebase <分支名>                # 将当前分支衍合到指定分支（线性历史）
git cherry-pick <commit-id>       # 将指定 commit 应用到当前分支

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 团队开发

# 远端管理
git remote -v                     # 列出远端（含地址）
git remote add <别名> <git地址>    # 添加远端
git remote show <别名>            # 查看远端详情
git remote rename <旧名> <新名>    # 重命名远端
git remote rm <别名>              # 删除远端
git remote update [<别名>]         # 更新远端分支列表

# 同步与推送
git fetch [<远端>]                # 抓取远端更新（不合并），D → C
git pull [<远端>] [<分支>]         # 抓取并合并，相当于 fetch + merge
git push [<远端>] [<分支>]         # 推送到远端，C → D
git push -f [<远端>] [<分支>]      # 强制推送（慎用）
git push origin <分支名>           # 推送指定分支到 origin

# 冲突处理
git diff <源分支> <目标分支>       # 查看两分支差异
# 冲突时：编辑文件解决冲突 → git add <file> 标记已解决 → git commit 完成合并

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 开发实际场景

# 撤销最近一次 commit（未 push）

仅撤销「最近一次提交」，不改动工作区与暂存区内容，相当于「摘掉最后一次 commit，改动仍保留」。

git reset --soft HEAD~1    # 撤销 commit，改动保留在暂存区（可重新 commit）
git reset HEAD~1           # 撤销 commit，改动保留在工作区（默认 --mixed）

1
2

若已 push，不要直接在本机 reset 后强制推送共享分支，应改用下面的「撤销已 push」或「回滚到某一提交」。

# 撤销已 push 的提交

方式一：revert（推荐，用于共享分支如 main）

不改写历史，新增一个「反向提交」抵消指定提交的改动，适合多人协作分支。

git revert <commit-id>     # 撤销某一次提交，生成新的 revert 提交
git revert HEAD            # 撤销最近一次
git revert --no-commit <commit-id>   # 只改工作区/暂存区，不自动 commit
git push origin <分支>

1
2
3
4

方式二：reset + 强制推送（仅适合个人分支或确定无人基于该提交开发）

会改写历史，其他人若已拉取该分支需要重新同步。

git fetch origin
git reset --hard <commit-id>       # 或 git reset --hard HEAD~N
git push --force-with-lease origin <分支>

1
2
3

优先使用 --force-with-lease 而非 -f：若远端已被他人更新则拒绝推送，避免覆盖他人提交。

# 回滚到某一提交记录

仅本地未 push：git reset --hard <commit-id> 即可。
已 push 的共享分支：
- 用 revert 逐条或一次性 revert 到目标状态（推荐）；
- 或在该分支上 git reset --hard <commit-id> 后 git push --force-with-lease（仅当该分支为个人或团队同意重写历史时）。

查看要回滚到的 commit-id：

git log --oneline
git reflog    # 包含已“消失”的 commit，便于找回

1
2

# 冲突处理（merge / pull 时）

执行 git pull 或 git merge <分支> 后提示冲突。
打开冲突文件，按提示处理 <<<<<<<、=======、>>>>>>> 之间的内容，保留或合并正确逻辑。

标记已解决并完成合并：

git add <已解决冲突的文件>
git commit   # 或 git merge --continue（若为 merge）

1
2

若想放弃本次合并：git merge --abort。

对比两分支差异（辅助判断冲突范围）：

git diff <源分支> <目标分支>

# 开源贡献：多 commit 合并为单 commit 再提 PR

很多开源仓库要求「一个 PR 对应一个清晰的 commit」，需要把本地多个 commit 合并成一个再推送。

方法一：交互式 rebase（本地合并后推送）

# 合并当前分支上最近 N 个 commit 为 1 个
git rebase -i HEAD~N

# 在编辑器中：保留第一个 commit 为 pick，其余改为 squash（或 s），保存
# 再在随后弹出的编辑器中填写合并后的 commit message，保存
# 若该分支已 push 过，需强制推送（仅在自己的 fork 分支上做）
git push --force-with-lease origin <你的分支>

1
2
3
4
5
6
7

方法二：GitHub 后台 Squash and Merge

若仓库允许，在 PR 合并时选择 Squash and merge，由 GitHub 将 PR 内所有 commit 压成一条后合并到目标分支，无需本地改历史。

方法三：本地先 squash 再提 PR

在本地把功能分支上的多次提交合并成一次，再推送到你的 fork 后提 PR。

git checkout main && git pull origin main    # 或从 upstream 拉取
git merge --squash <你的功能分支>
git commit -m "feat(xxx): 功能简述"
git push origin <你的推送分支>                # 推送到 fork 后到 GitHub 提 PR

1
2
3
4

日常推荐：在自己的 fork 分支上用 方法一 整理成单 commit，再提 PR；若项目开启 Squash and merge，也可直接多 commit 提 PR，由维护者合并时 squash。

# 其他实用命令

gitk                              # 打开图形化 Git 界面
git add -i                        # 交互式添加文件到暂存区

1
2

# Git 工作区示意

命令说明中的 A（工作区）→ B（暂存区）→ C（本地仓库）→ D（远端） 对应关系可参考下图：

Git 工作区

帮助我改善此页面

上次更新: 2026/03/04, 10:23:59

← 10分钟快速搭建个人博客