Git 基础教程:原理、常见操作与企业实践规范
Git 是目前最主流的分布式版本控制系统,几乎所有软件团队都在用。但很多人停留在 add / commit / push 三板斧,遇到冲突或误操作就不知道怎么处理。这篇从原理出发,把常见操作和企业实践规范串起来。
Git 的三个区域和分布式原理
工作区、暂存区、本地仓库
Git 把文件状态分成三个区域,理解这个是所有操作的基础:
1 | 工作区(Working Directory) |
- 工作区:你实际编辑文件的目录
- 暂存区:
git add后文件进入这里,是一个”预提交缓冲区”,可以精确控制这次 commit 包含哪些改动 - 本地仓库:
git commit后改动被永久记录,存在.git/objects/目录 - 远程仓库:
git push后同步到 GitHub/GitLab 等远端
暂存区是很多人忽略的设计:它让你可以把一个大改动拆分成多个有意义的 commit,而不是把所有修改塞进一个 commit。
分布式的含义
Git 是分布式的,每个开发者本地都有完整的仓库历史,不依赖中央服务器就能查历史、切分支、提交。这和 SVN 等集中式系统不同——SVN 断网就不能提交。
git clone 会把远端的完整历史都拉下来,所以 git log 是本地操作,不需要网络。
Git 对象模型
Git 内部用四种对象存储所有内容,每个对象用其 SHA-1 哈希值唯一标识:
| 对象类型 | 存储内容 |
|---|---|
| blob | 文件内容(不含文件名) |
| tree | 目录结构(文件名 + blob 引用) |
| commit | 提交信息 + tree 引用 + parent commit 引用 |
| tag | 附注标签(指向 commit) |
一个 commit 对象大概长这样:
1 | tree 8f3b2a... # 指向这次提交的目录快照 |
branch 和 HEAD 是什么:branch 只是一个指向某个 commit 的指针(存在 .git/refs/heads/ 里),HEAD 是当前所在分支的指针。切换分支不是”复制文件”,只是移动指针,速度极快。
常见操作速查
初始化和克隆
1 | # 初始化新仓库 |
查看状态和差异
1 | # 查看工作区和暂存区的状态 |
git diff 只会比较已经被 git 跟踪的文件:它按暂存区里登记的文件清单,逐个去看工作区里对应的文件有没有变化。新建的文件在 git add 之前不在暂存区里,git status 里显示为 ??(未跟踪),git diff 不会输出它,哪怕它就在工作区里。想在 git diff 里看到新文件,有两种办法:
1 | git add -N 新文件 |
还有一种办法不用碰暂存区:git diff --no-index 直接比较磁盘上的两个文件,拿 /dev/null(空文件)当旧版本,新文件就整个显示成新增。
1 | git diff --no-index /dev/null 新文件 |
不过这个办法实用性有限:只看单个新文件,不如直接打开它;想一次看完所有未跟踪文件,又得敲一长串:
1 | git ls-files --others --exclude-standard -z | xargs -0 -n1 git diff --no-index -- /dev/null |
经常需要这样看的话,可以设成别名,已跟踪文件的改动和未跟踪的新文件一次显示:
1 | git config --global alias.diffall '!git diff; git ls-files --others --exclude-standard -z | xargs -0 -n1 git diff --no-index -- /dev/null || true' |
查看历史与追溯:谁改的、什么时候改的
排查”这段代码为什么长这样”时的三件套——看文件的修改历史、看某一行是谁改的、看某次提交到底改了什么:
1 | # 查看某个文件的历史修改记录 |
三个命令正好串成一条排查链:git log 文件 找到相关提交 → git blame 定位到具体某一行是哪次提交改的 → git show 看那次提交的完整改动和说明。
更进一步——想看某个函数或某段代码块(而不是整个文件)的完整历史,用
git log -L,踩坑细节见:Git: 查看指定代码块的历史记录
add 和 commit
1 | # 把指定文件加入暂存区 |
git add -p 是个容易被忽视的功能:当一个文件有多处修改,但只想把其中一部分提交时,用它可以逐块选择。
分支操作
1 | # 查看本地分支 |
切分支为什么用 switch:checkout 的歧义
git checkout 是个身兼多职的老命令:既能切换分支,又能把文件恢复成暂存区的版本(丢弃改动)。参数只写一个名字时,Git 得自己判断这个名字指的是分支还是路径。大多数时候没有歧义,一旦两者重名就会卡住。
一个真实遇到的例子:仓库根目录下有个 test/ 目录,本地还没有 test 分支,只有远端的 origin/test:
1 | git checkout test |
Git 2.23(2019 年 8 月)起把 checkout 拆成了两个各管一件事的命令:switch 只管分支,restore 只管恢复文件。日常写法的对应关系:
| 想做的事 | 旧写法 | 新写法 |
|---|---|---|
| 切换到已有分支 | git checkout main |
git switch main |
| 新建并切换 | git checkout -b feature/login |
git switch -c feature/login |
| 回到上一个分支 | git checkout - |
git switch - |
| 丢弃文件的改动 | git checkout -- a.go |
git restore a.go |
checkout 没有被废弃,老教程和老脚本里的写法照样能用。自己在本机手动切分支,优先用 switch;如果命令要写进脚本,或者要在版本可能低于 2.23 的机器上运行(老的 CI 镜像、服务器),继续用 checkout,遇到重名时按报错提示加上 --。
合并和变基
1 | # 合并分支(在 main 分支上执行,把 feature/login 合并进来) |
merge vs rebase 的区别:
merge保留完整历史,会生成一个 merge commit,清楚地记录”这两条线在这里合并了”rebase重写 feature 分支的提交历史,让它看起来像是在最新的 main 上线性开发的,历史更干净,但会改变 commit 的 SHA
已推送到远端的分支不要 rebase,rebase 会改变提交历史,会和别人的本地仓库产生冲突。
远端操作
1 | # 查看远端仓库配置 |
git pull 提示 divergent branches:merge、rebase、ff-only 怎么选
git pull 其实是两个动作:先 git fetch 把远端的新提交下载下来,再把它们整合进当前分支。第二步会遇到三种情形:
- 只有远端有新提交:直接快进,输出里会看到
Fast-forward,没有选择余地。 - 只有本地有新提交:没有东西可拉,输出
Already up to date.。 - 本地和远端各自都有对方没有的提交:这叫分叉(diverged)。Git 不替你决定怎么整合,直接报错:
1 | hint: You have divergent branches and need to specify how to reconcile them. |
Git 2.27 起,没设置过整合方式的 git pull 会先给警告,后来的版本改成了直接报错。本节命令在 Git 2.49 下实测。报错时下载已经完成(origin/main 已更新),但本地分支没有被改动,可以放心重新选一种方式再拉。
分叉长这样:init 之后,远端有同事推送的 A1、A2,本地有你还没推送的 B1、B2。
graph LR
I["init"] --> A1["A1(远端)"] --> A2["A2(origin/main)"]
I --> B1["B1(本地)"] --> B2["B2(main)"]
git status 也会显示这个状态:Your branch and 'origin/main' have diverged, and have 2 and 2 different commits each, respectively.
选方式之前,可以先看清两边各多了什么:
1 | git fetch origin |
merge:保留两条线,生成一个合并提交
1 | git pull --no-rebase origin main |
执行后输出 Merge made by the 'ort' strategy.,git log --graph --oneline 的结果:
1 | * 33ce922 Merge branch 'main' of github.com:example/library-api |
两条线都原样保留,A1、A2、B1、B2 的 SHA 都没变,只多出一个有两个父提交的 merge commit。好处是不改写任何历史,随时能看出“这两条线在哪里合并”;代价是经常 pull 的话,历史里会堆满合并提交,提交图变成一团交叉的线。
rebase:把本地提交接到远端最新提交后面,历史是一条直线
1 | git pull --rebase origin main |
执行前本地是 B2(44f8efe)、B1(69cb85c),执行后:
1 | * 185daa3 B2: add sort |
历史是一条直线,没有合并提交。内容没变,但 B1、B2 的 SHA 变了(69cb85c 变成 4e91513),因为它们的父提交换成了 A2。被重写的只有你本地独有、别人还没拿到的提交。
rebase 是一个提交一个提交地重放,所以冲突可能每个提交都要解决一次,不是只解决一次。
--rebase 还有两个取值:
--rebase=merges:默认的 rebase 会把本地的合并提交拍平。例如本地用git merge --no-ff feat合并过一个分支,普通 rebase 之后那个Merge feat提交就消失了,feat里的提交直接接进直线历史。改用merges后会保留这个合并提交。--rebase=interactive:变基前先打开待办列表,和git rebase -i一样,可以顺手调整顺序、压缩提交,使用前要清楚后果。
ff-only:只在能快进时才拉,分叉就拒绝
1 | git pull --ff-only origin main |
分叉时的结果:
1 | hint: Diverging branches can't be fast-forwarded, you need to either: |
本地提交原封不动,既不生成合并提交,也不改写历史。分叉时你得自己决定下一步是 git merge 还是 git rebase。只有本地落后、可以快进时,--ff-only 和普通 git pull 一样正常拉取。
三种方式放在一起对比:
| merge | rebase | ff-only | |
|---|---|---|---|
| 参数 | --no-rebase |
--rebase |
--ff-only |
| 分叉时 | 生成一个合并提交 | 本地提交重放到远端之后 | 报错退出 |
| 本地提交的 SHA | 不变 | 改变 | 不变 |
| 历史形状 | 有分叉和汇合 | 一条直线 | 一条直线(只在能快进时) |
| 冲突 | 解决一次 | 每个冲突的提交解决一次 | 不会冲突,也不会整合 |
设成默认值,不用每次敲参数
1 | git config pull.rebase true |
几个容易搞混的点:
- 命令行参数的优先级最高。已经设了
pull.rebase true,临时执行git pull --no-rebase照样走 merge,只对这一次生效。 - 只给某个分支设置,用
branch.<分支名>.rebase,例如git config branch.main.rebase true。它的优先级高于pull.rebase。 pull.ff false不是“用 merge 整合”的开关。它的含义是“即使能快进,也生成一个合并提交”,只落后不分叉时也会多出合并提交。想选 merge,设的是pull.rebase false。
工作区有未提交改动时
- merge:只要未提交改动的文件和远端改动的文件没有重叠,照常拉取。有重叠就中止,不会动你的文件:
1 | error: Your local changes to the following files would be overwritten by merge: |
- rebase:只要有未提交的改动就拒绝,不管文件有没有重叠:
1 | error: cannot pull with rebase: You have unstaged changes. |
rebase 的情况可以让 Git 自动 stash:
1 | git pull --rebase --autostash origin main |
自动取出时,未提交的改动可能和变基后的代码冲突。这时 Git 会提示 Applying autostash resulted in conflicts. Your changes are safe in the stash.,改动还留在 stash 里,不会丢,手动处理冲突后再 git stash drop。
冲突时怎么收场
- merge 冲突:解决冲突,
git add之后git commit;想放弃就git merge --abort,回到 pull 之前。冲突标记怎么处理见解决合并冲突。 - rebase 冲突:解决冲突,
git add之后git rebase --continue,继续重放下一个提交;git rebase --skip丢弃当前这个提交;git rebase --abort回到 pull 之前。变基进行中 HEAD 会暂时脱离分支,git status -sb第一行显示HEAD (no branch),完成或中止后回到原来的分支。 - ff-only:不会产生冲突,因为它在分叉时根本不动手。
怎么选
- 本地提交还没推送过,比如在自己的 feature 分支上开发:用 rebase。历史干净,被重写的又都是只在本地的提交,没有人受影响。
- 团队规范要求保留合并记录:用 merge,不改写任何已有提交。
- 本地提交已经推送到别处时慎用 rebase。例如 feature 分支已经推送到
origin/feature,再用git pull --rebase origin main同步 main,提交的 SHA 变了,之后git push会被拒绝(non-fast-forward),只能用git push --force-with-lease强推;如果有同事基于这个分支开发,强推会让他们的本地历史对不上。这和前面“已推送到远端的分支不要 rebase”是同一个道理。 - 想保证 pull 不会自己改历史、也不会自己生成合并提交:用
--ff-only,分叉时报错,由你决定下一步。
暂存工作区:stash
git stash 把当前工作区和暂存区的改动临时存起来,让工作区恢复干净状态,适合”临时切换分支处理紧急 bug”的场景。
1 | # 把当前改动暂存起来 |
回滚操作
1 | # 撤销工作区的修改(恢复到上次 commit 的状态,改动丢失) |
reset --hard 会直接丢弃工作区改动,执行前确认好。已经 push 的提交用 revert 更安全,它不改历史,而是新增一个撤销的 commit。
restore -p 单独展开讲一下,它解决的是一个很常见的场景:一个文件里混着有效修改和无效修改——比如改了几行逻辑,编辑器顺手又格式化出一堆空格变动、删掉的空行,git diff 一看满屏噪音。整个文件 restore 会把有效修改一起丢掉,手动改回去又太费劲。-p(patch)模式会把文件的改动拆成一个个块(hunk),逐块展示 diff 并询问怎么处理:
1 | git restore -p src/main.go |
遇到”空格、空行这类无效修改混在有效修改里”的情况,逐块 y/n 过一遍,噪音全清掉、有效改动一行不丢。同样的 -p 参数在 git add -p 上也能用,方向反过来——从混杂的改动里挑出想提交的部分。
分支策略:Git Flow 与 GitHub Flow
多人协作时,如果每个人随意创建分支、随意往 main 合并,很快就会出现以下问题:main 上有未测试的代码导致线上崩溃;不知道哪个分支是”当前最新”的;hotfix 合到了错误的地方,修复没生效。
分支策略就是团队约定好”什么分支做什么事、从哪切出、合到哪里去”,把协作流程标准化,避免上面这些混乱。不同规模和发布节奏的团队适合不同的策略,没有统一答案,但必须有一套。
Git Flow
Git Flow 是经典的企业分支模型,有两条长期分支和三类临时分支:
长期分支:
main(或master):只存放生产环境的稳定代码,每次更新都打 tagdevelop:集成分支,所有功能开发完成后先合并到这里
临时分支(用完即删):
feature/xxx:从 develop 切出,功能开发完合回 developrelease/x.x.x:从 develop 切出,做最终测试和 bug 修复,完成后合并到 main 和 develophotfix/xxx:从 main 切出,紧急修复生产 bug,完成后合并到 main 和 develop
适合场景:有明确版本节奏的项目(比如定期发版的 App、SDK)。
缺点:分支多、流程重,小团队或持续交付场景下嫌麻烦。
GitHub Flow
GitHub Flow 更轻量,只有一条规则:main 随时可部署,所有改动通过 PR 合并。
1 | main(始终可部署) |
流程:
- 从 main 创建 feature 分支
- 在 feature 分支开发、提交
- 发起 PR,Code Review
- CI 通过后合并到 main
- 立即部署
适合场景:持续交付、小团队、Web 服务(随时上线)。
怎么选
| 场景 | 推荐 |
|---|---|
| 有固定发版周期(App、SDK) | Git Flow |
| 持续部署、随时上线 | GitHub Flow |
| 小团队、快速迭代 | GitHub Flow |
| 需要维护多个版本 | Git Flow |
企业实践规范
commit message 规范:Conventional Commits
混乱的 commit message 让 git log 毫无意义,也没法自动生成 changelog。Conventional Commits 是目前最主流的规范:
1 | <type>(<scope>): <subject> |
常用 type:
| type | 含义 |
|---|---|
feat |
新功能 |
fix |
Bug 修复 |
docs |
文档改动 |
refactor |
重构(不影响功能) |
test |
测试相关 |
chore |
构建、依赖、CI 等杂项 |
perf |
性能优化 |
revert |
撤销某次提交 |
示例:
1 | feat(auth): add Google OAuth login |
实践建议:
- subject 用英文或中文均可,保持团队统一就行
- subject 不超过 72 个字符
- 用祈使句(”add”,不是”added”或”adding”)
- 破坏性改动在 footer 加
BREAKING CHANGE: 说明
可以用 commitlint 在 git hook 里强制校验格式。
分支命名规范
1 | feature/issue-42-user-login # 新功能(关联 issue 号) |
关联 issue 号的好处:在 GitHub/GitLab 上可以直接从分支名跳转到对应 issue,review 时方便查背景。
保护主分支
在 GitHub/GitLab 上给 main 开启 branch protection:
- 禁止直接 push,所有改动必须通过 PR
- PR 合并前必须通过 CI(单测、lint、构建)
- 至少一个 Code Review 通过才能合并
- 禁止 force push
这几条规则能防止 90% 的低级事故。
PR/MR 规范
一个好的 PR 应该:
- 只做一件事:一个 PR 只解决一个问题,越小越容易 review
- 有清晰的描述:说明改了什么、为什么改、怎么测试
- 关联 issue:在描述里加
Closes #42,合并后自动关闭 issue - 自己先 review 一遍:提交前 diff 看一眼,去掉调试代码和无关改动
.gitignore 配置
.gitignore 要在项目初始化时就配好,不要等到不该提交的文件已经进了仓库再处理。
常见需要忽略的内容:
1 | # 依赖 |
gitignore.io 可以按语言和框架自动生成。
常见问题处理
误操作恢复:git reflog
git reflog 记录了 HEAD 的所有移动历史,包括 reset --hard 这类”危险操作”之后的状态。只要没有 git gc,几乎所有误操作都能恢复。
1 | # 查看 HEAD 的操作历史 |
reset --hard 把工作区搞没了?先跑 git reflog,找到那个 commit 的哈希,reset --hard 回去就行。
解决合并冲突
冲突发生时 Git 会在文件里标记冲突区域:
1 | <<<<<<< HEAD |
处理步骤:
- 用编辑器打开冲突文件,选择保留哪一方或手动合并
- 删除所有
<<<<<<<、=======、>>>>>>>标记 git add标记冲突已解决git commit完成合并
1 | # 查看哪些文件有冲突 |
如果冲突太复杂,可以用 git mergetool 调出可视化合并工具(需要先配置)。
改到一半发现冲突超出预期、想放弃这次合并重新来过,不用手动去删那些冲突标记——直接取消合并,回到合并前的状态:
1 | git merge --abort |
注意前提:合并前的工作区应该是干净的(没有未提交的改动)——这也是为什么合并前先 commit 或 stash 是个好习惯,否则 --abort 恢复现场时可能没法完整还原你未提交的那部分内容。
修改最近一次 commit
1 | # 修改最近一次 commit 的 message |
--amend 会重写最近一次 commit,产生新的 SHA。已推送到远端的 commit 不要 amend,否则需要 force push,会影响其他人。
修改指定 commit:git rebase -i
--amend 只能改最近一次 commit,修改更早的提交要用交互式 rebase。
1 | # 修改最近 3 个 commit(打开交互式编辑界面) |
弹出的编辑器里每行是一个 commit,把要修改的那行前面的 pick 改成对应指令:
| 指令 | 含义 |
|---|---|
pick |
保留这个 commit(默认) |
reword |
只修改 commit message |
edit |
暂停在这个 commit,可以修改内容 |
squash |
把这个 commit 合并到上一个 commit |
drop |
删除这个 commit |
以修改 message 为例,把 pick 改成 reword,保存退出,Git 会再弹出编辑器让你改 message。
以修改内容为例,把 pick 改成 edit,保存退出后 Git 会暂停在那个 commit:
1 | # Git 提示你现在在指定 commit,可以修改文件 |
同样:已推送到远端的 commit 不要用 rebase -i 修改,会改写历史,影响所有人。
cherry-pick:把某个 commit 单独移植
1 | # 把 abc1234 这个 commit 的改动应用到当前分支 |
场景:hotfix 在 main 分支修复了一个 bug,需要把这个修复也应用到正在维护的 release 分支,用 cherry-pick 比重新写一遍高效。
提交里带了构建产物:git show 和提交预览变得很卡
在 Neovim 里翻 Git Log 时的具体表现和原因见:从零开始用 Neovim:LazyVim 让配置不再是障碍“Git Log 预览卡顿”一节。
git show、git log -p,或者编辑器、lazygit 里的提交预览,遇到个别提交突然变得很慢,多半是这个提交把构建产物也提交了(比如 dist/ 下压缩后的 JS)。压缩后的文件单行能有几百 KB,文件名还带内容哈希、每次构建都换名,git 眼里就是”删掉整个旧文件、新增整个新文件”,一个提交的 diff 动辄 2~3MB,真正的代码改动却只有十几 KB。
让 git 不再展开这类文件的 diff,在仓库的 .git/info/attributes 里加一行:
1 | web/dist/** -diff |
这个文件在 .git/ 目录里,不属于任何提交,只影响本机,不会被推送,也不改动仓库里存的内容;同一个提交里其他文件的 diff 照常显示。想撤销,删掉那一行即可。
中文文件名在 git status 里变成八进制转义:core.quotePath
仓库里有带中文的文件名时,git status 不会直接显示中文,而是显示成带引号的一串转义:
1 | M "posts/\345\200\237\351\230\205\346\225\231\347\250\213.md" |
这是 Git 的默认行为。UTF-8 里一个汉字占 3 个字节,Git 把每个字节写成一个八进制转义,上面三组 \345\200\237 合起来就是“借”字。不只是 git status,git diff --name-only、git ls-files、git diff --stat、git log --name-status 以及 diff 头部的文件名,都会这样输出。
肉眼看不方便还是小事。编辑器、Git 图形客户端、AI 编程工具这类程序读取 Git 的输出、再按路径去找文件时,拿到的是转义后的路径,对不上磁盘上真正的文件名,就可能出问题。Claude 桌面端的 Code 标签页就遇到过:修改一个中文文件名的文件后,输入框上方的改动统计(+193 -1)正常,右侧 diff 面板却提示 Diff content unavailable for 1 file.。把转义关掉后,diff 面板恢复正常。官方文档没有解释这条提示的成因,所以原因只是推测:很可能是工具没有把转义后的路径还原,找不到对应的文件。
先确认是不是转义在作怪,看两样东西:git status 里的路径是不是带引号的 \345 这种写法,以及这个配置项的值:
1 | git config core.quotePath |
这条命令没有输出,容易误以为“没开启”。实际含义正好相反:没有输出表示这一项从来没设置过,退出码是 1,此时 Git 用的是默认值 true,也就是开启转义。想看到真正生效的值,补上默认值(--default 需要 Git 2.18 及以上):
1 | git config --type=bool --default true --get core.quotePath |
关掉转义:
1 | git config core.quotePath false |
设置之后,git status 直接显示原来的中文路径:
1 | M posts/借阅教程.md |
只想临时看一眼,不想改配置,可以用 -c 只在这一条命令里覆盖:
1 | git -c core.quotePath=false status --short |
这个开关管什么:官方文档的说法是,路径里“不寻常”的字符会被加上双引号,并按 C 语言的写法转义,大于 0x80 的字节(中文就在其中)也算“不寻常”。设成 false 之后,大于 0x80 的字节不再算特殊,所以中文原样输出。这个名字容易想反:quotePath 是“给路径加引号并转义”这件事的开关,false 是关闭它。
关掉转义只改变 Git 命令输出的样子,不影响文件内容,也不影响提交历史:实测设置前后,同一个提交的 tree 哈希完全一样。双引号、反斜杠和制表符这类控制字符不受这个开关影响,设成 false 之后照样会被转义。另外,带 -z 参数的命令(如 git ls-files -z)本来就不转义,用它写脚本时不必关心这个配置。






