w wyl123ly 的博客
MD

工具-01-Git版本控制

45 KB 2026.10.11 原文件

工具-01-Git版本控制

这篇笔记讲什么

Git 是目前使用最广的分布式版本控制系统(distributed version control system, DVCS)。这篇笔记从「没有版本控制会怎样」讲起,讲清 Git 的快照模型与三个工作区域,再用可直接执行的命令覆盖日常提交、历史查看、撤销、分支、合并、变基、远程协作与灾难恢复,最后给出仓库体积治理与常见工作流的选型建议。

读完你应该能够:独立完成一个仓库从 git init 到推送到远程的全流程;在误操作后把代码救回来;解释「为什么不能对已推送的公共分支变基」。

是什么

Git 是一个分布式版本控制系统(distributed version control system)。它把项目的全部历史(每一条提交、每一个分支、每一个标签)完整地保存在每个克隆(clone)出来的本地仓库里,而不是只保存在一台中心服务器上。

从数据角度看,Git 本质上是一个内容寻址(content-addressable)的文件系统:它把文件内容做哈希运算得到一个 40 位十六进制(SHA-1)或 64 位(SHA-256)的键,用这个键存储内容。所谓「提交」,只是往这个键值库里写入一个描述目录树和父提交的小对象。

工作区 (Working Directory)     暂存区 (Staging Area / Index)     本地仓库 (Repository, .git)
       │                                    │                              │
       │  git add                           │  git commit                  │
       ├───────────────────────────────────►├─────────────────────────────►│
       │                                    │                              │
       │◄───────────────────────────────────┴──────────────────────────────┤
       │              git restore / git reset --hard / git checkout        │

为什么需要它

先看一份没有版本控制的项目目录长什么样:

论文/
├── 论文.doc
├── 论文_修改版.doc
├── 论文_最终版.doc
├── 论文_最终版_真的最终.doc
├── 最终版_v2_真的最终.zip
├── 最终版_v2_真的最终_导师改过.zip
└── 最终版_v2_真的最终_导师改过_这个才是最新的(1).zip

这段惨状暴露了四个真实问题:

  1. 无法回答「改了什么」:两个 zip 之间到底差在哪几段?只能靠人工对比。
  2. 无法回答「为什么改」:三个月后没人记得为什么删掉了那一章。
  3. 无法回答「谁改的」:多人协作时互相覆盖,谁覆盖了谁无从追查。
  4. 无法回退:改坏了只能重来,因为旧版本已经被覆盖掉了。

版本控制系统要解决的正是这四件事:

问题版本控制给出的答案
改了什么差异(diff)与提交(commit)记录
为什么改提交信息(commit message)
谁改的、什么时候作者、邮箱、时间戳,git blame 可逐行追溯
改坏了怎么办任意回退到历史提交;分支上试错不影响主线
多人同时改怎么办分支 + 合并,冲突显式暴露而不是静默覆盖
谁可以发布、发的是哪版标签(tag)+ 远程仓库 + 权限控制

集中式与分布式版本控制的区别

维度集中式(CVS/SVN)分布式(Git/Mercurial)
历史存放位置只有中心服务器有完整历史每个克隆都是完整仓库
提交是否需要联网需要不需要,本地提交后择机推送
单点故障服务器磁盘坏了历史就没了任一克隆都能恢复全部历史
分支成本高(通常直接操作目录)极低(只是一个 41 字节的指针文件)
权限粒度可按目录精细控制通常按仓库控制
典型工作方式检出(checkout)后直接改克隆(clone)后在本地提交再推(push)

一句话记住分布式

在 Git 里,你的电脑上本来就有一份完整的历史备份。远程仓库(origin)只是「大家约定同步的那一份」,它不是唯一的一份。

Git 的核心理念

1. 快照(snapshot),而不是差异(delta)

很多人以为 Git 存的是「每次改了哪几行」。实际上每执行一次 git commit,Git 都会记录当时所有文件的完整快照,并为这个快照建一个指向它的引用。没有变化的文件不重复存储,而是复用上一版的对象(Git 用内容哈希天然去重)。

差异(diff)是需要时才现算的,不是存储形式。这解释了为什么 Git 切换分支极快:切换分支就是换一套指针,把工作区文件按目标快照重写一遍,既不需要「回放」也不需要考虑新旧分支的先后顺序。

2. 近乎全能的本地操作

除了 fetch/pull/push,几乎所有 Git 操作都是纯本地的:看历史、比较版本、切分支、合并、变基、打标签、查责任。这意味着你可以在飞机上完整地开发一整个功能,落地后一次性推送。

3. 完整性校验

Git 在存储任何对象前都会先算哈希,用哈希值当作对象的唯一名字。取回对象时会重新计算哈希并比对,内容被改过一个字节就会被发现。历史记录因此天然防篡改:你不可能悄悄改掉一条老提交的内容而不改变它以及它之后所有提交的哈希值。

早期 Git 使用 SHA-1,从 Git 2.29 起支持 SHA-256 仓库格式(git init --object-format=sha256),但目前绝大多数仓库仍是 SHA-1 格式。日常使用无需关心这一点。

核心内容

一、三个工作区域与文件的四种状态

这是理解 Git 所有命令的唯一钥匙。请务必把下面这张表记牢。

区域英文物理位置存的是什么
工作区Working Directory你能直接看到的项目目录你正在编辑的文件
暂存区Staging Area / Index.git/index 文件下次提交要包含的快照清单
本地仓库Repository.git/objects 等所有历史提交
远程仓库Remote服务器(如 GitLab/GitHub)共享的提交历史

文件在 Git 眼中有四种状态:

状态含义位于何处
未跟踪 Untracked新文件,Git 完全不管工作区
已修改 Modified已跟踪文件被改动,尚未暂存工作区
已暂存 Staged改动被记录进暂存区,等下次提交暂存区
未修改 Unmodified与最近一次提交一致工作区 = 仓库

git status 是最好的老师

每次不确定自己在哪一步,先敲 git status。它会明确告诉你「哪些改动还没暂存、哪些已暂存待提交」。

二、初始化与配置

git config 有三级作用域,优先级从高到低:

作用域参数配置文件位置影响范围
系统级--systemWindows: C:\Program Files\Git\etc\gitconfig;Linux: /etc/gitconfig本机所有用户
全局级--global~/.gitconfig(Windows 为 C:\Users\你\.gitconfig)当前用户的全部仓库
仓库级--local(默认).git/config仅当前仓库

同一个键在多个作用域出现时,粒度越细的优先:仓库级 > 全局级 > 系统级。

三、基础工作流

Git 的日常就是这三步的循环:

暂存区的价值在于让你把一次提交裁剪成逻辑完整的最小单元。改了 5 个文件的 bug 修复、顺手格式化了 3 个文件、还加了一个新功能——这三件事应该分成三条提交,而不是一锅粥。

四、撤销操作全景(最容易混淆的部分)

先把结论浓缩成一张表,后面再逐个解释。「三个区域」列表示该命令改变了哪些区域的内容。

命令作用对象影响的区域是否改写历史什么时候用
git restore <file>工作区工作区否丢弃还没暂存的修改,回到暂存区/HEAD 的样子
git restore --staged <file>暂存区暂存区否把文件移出暂存区(add 的反操作),工作区不动
git restore --source=HEAD --staged --worktree <file>两者暂存区 + 工作区否彻底丢弃某文件的所有未提交改动
git reset --soft <commit>指针只移动 HEAD 分支指针是(本地)撤销提交,改动保留在暂存区(想重新提交)
git reset --mixed <commit>指针 + 暂存区HEAD 指针 + 暂存区是(本地)撤销提交,改动保留在工作区(默认模式)
git reset --hard <commit>全部HEAD + 暂存区 + 工作区是(本地)彻底丢弃,未提交的数据会永久丢失
git revert <commit>新增反向提交三个区域都不动,追加新提交否(历史只增不改)撤销已经推送的提交
git commit --amend最近一条提交本地仓库是(本地)改提交信息,或补上漏掉的文件
git switch / git checkoutHEAD 指针工作区 + 暂存区跟着变否切换分支 / 检出某个提交

三种 reset 的区别可以用一句话概括:--soft 只动指针,--mixed 动指针和暂存区,--hard 三个区域全动。

                HEAD 分支指针      暂存区        工作区
--soft             ✔ 重置          —            —
--mixed (默认)     ✔ 重置          ✔ 重置        —
--hard             ✔ 重置          ✔ 重置        ✔ 重置(危险!)

五、分支的本质

分支不是目录的副本,只是一个指向某条提交的指针。 在 .git/refs/heads/ 下就是一个内容为 40 位哈希的普通文本文件。创建分支因此是 操作,这也是 Git 鼓励「多开分支」的根本原因。

HEAD 是一个特殊指针,通常指向当前分支(如 refs/heads/main)。这就是「分离头指针(detached HEAD)」状态的来源:HEAD 不再指向某个分支,而是直接指向一条提交。

六、合并的两种方式

方式触发条件结果历史形态
快进合并 Fast-forward目标分支是当前分支的直接后继直接把指针前移,不产生新提交线性
三方合并 Three-way merge两边都有对方没有的提交产生一个合并提交(两个父提交)有分叉

三方合并的三个输入是:两个分支的末端提交,以及它们的共同祖先(merge base)。

七、变基的原理与铁律

git rebase 的做法是:找到两条分支的共同祖先,把当前分支独有的提交逐个「摘下来」并在目标分支末端重新应用一遍,生成一批全新的提交(哈希值全变了)。

变基铁律

不要对已经推送到公共分支的提交做变基。 因为变基会生成哈希完全不同的新提交,别人本地基于旧提交的工作会与你的新历史彻底分叉,一推就冲突,越推越乱。判断标准很简单:这条提交别人可能已经拉取过吗? 是,就只用 merge,不用 rebase。

八、其他常用能力总览

能力命令典型场景
摘取单个提交git cherry-pick <commit>把 hotfix 从 dev 搬到 main
临时存放git stash改到一半被叫去修紧急 bug
打标签git tag -a v1.0.0 -m "..."发布版本
二分定位git bisect找「哪个提交引入了 bug」
查责任git blame看某行是谁在哪个提交里写的
找回丢失提交git reflog误 reset --hard 之后
多工作区git worktree add同一仓库同时检出两个分支
子模块git submodule仓库里嵌另一个仓库

怎么用

以下命令全部可直接执行。默认在 Windows 的 Git Bash / PowerShell / Linux 终端中运行;<...> 表示需要你替换的占位符。

1. 安装与首次配置

# 确认已安装(Windows 可从 https://git-scm.com/downloads 下载安装包)
git --version

预期输出:形如 git version 2.4x.x.windows.1。若提示「不是内部或外部命令」,说明安装时没勾选加入 PATH。

# 必做:身份配置。提交记录里的作者信息就来自这里
git config --global user.name "张三"
git config --global user.email "zhangsan@example.com"

# 推荐:把默认分支名设为 main(Git 2.28+ 支持)
git config --global init.defaultBranch main

# 推荐:让 Git 在 pull 时用 rebase 而不是 merge,历史更线性(见后文取舍)
git config --global pull.rebase true

# 查看当前所有生效配置及其来源文件
git config --list --show-origin

预期输出:--list --show-origin 会逐行打印 file:C:/Users/你/.gitconfig user.name=张三 这样的内容,能一眼看出每个配置来自哪一级。

# 换行符处理(Windows 上最重要的一项配置)
# true  = 检出时 LF 转 CRLF,提交时 CRLF 转 LF(Windows 推荐)
git config --global core.autocrlf true

# Linux/macOS 上则推荐 input:提交时 CRLF 转 LF,检出时不转换
# git config --global core.autocrlf input

core.autocrlf 是 Windows 上最常见的「整个文件都变了」元凶

如果仓库里有人用 Windows(autocrlf=true)、有人用 Linux(autocrlf=input)、有人没配,同一份文件会在 LF 与 CRLF 之间反复翻转,git status 显示「整个文件都改了」,git diff 却几乎看不到内容差异——因为差异只在行尾。

正确的做法是在仓库根目录放一个 .gitattributes 文件,把规则写进仓库,这样所有人一致:

```gitattributes

* text=auto

*.sh text eol=lf

*.bat text eol=crlf

*.png binary

```

2. .gitignore 的写法规则

# 以 # 开头是注释
# 空行被忽略

# 忽略任意目录下名为 node_modules 的目录
node_modules/

# 忽略根目录下的 build 目录(前导斜杠表示只在仓库根)
/build/

# 忽略所有 .log 文件
*.log

# 但不要忽略 important.log(! 表示取反)
!important.log

# 忽略 doc 下的 .pdf,但不忽略 doc/server 下的
doc/*.pdf

# ** 可以跨目录匹配
logs/**/*.tmp

# 忽略任意目录下的 .env,包括子目录
.env

常用模板(Python 项目):

__pycache__/
*.py[cod]
.venv/
venv/
*.egg-info/
.pytest_cache/
.mypy_cache/
.ruff_cache/
dist/
build/
.env
.idea/
.vscode/

常用模板(Node.js 项目):

node_modules/
dist/
build/
coverage/
*.log
.env
.env.local
.DS_Store

.gitignore 只对尚未被跟踪的文件生效

已经 git add 过(即已被跟踪)的文件,即使后来写进了 .gitignore 也依然会被继续跟踪。要让它真正失效,必须先取消跟踪:

```bash

git rm --cached path/to/file # 只从索引移除,本地文件保留

git rm -r --cached node_modules # 目录版

```

3. 创建仓库并完成第一次提交

mkdir my-project && cd my-project
git init

预期输出:Initialized empty Git repository in D:/.../my-project/.git/

# 创建一个文件
printf 'hello git\n' > README.md

git status

预期输出(节选):

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        README.md

nothing added to commit but untracked files present (use "git add" to track)
git add README.md     # 或 git add .  添加当前目录下全部改动
git status

预期输出:Changes to be committed: 下面出现 new file: README.md。

git commit -m "docs: 添加 README"

预期输出:[main (root-commit) 1a2b3c4] docs: 添加 README 与 1 file changed, 1 insertion(+)。

提交信息怎么写

推荐约定式提交(Conventional Commits)风格:类型(范围): 描述,例如 fix(login): 修复验证码过期后未刷新。类型常用 feat/fix/docs/refactor/test/chore。第一行不超过 50 字符,需要解释动机时空一行再写正文。

4. 分块暂存与修补提交

# 交互式分块暂存:Git 会把改动拆成若干 hunk 逐个问你
git add -p

预期输出:逐个 hunk 显示并询问:

@@ -1,3 +1,4 @@
 line one
+line two added
 line three
(1/1) Stage this hunk [y,n,q,a,d,j,J,g,/,s,e,?]?

常用按键:y 暂存本块、n 跳过、s 把本块拆得更小、q 退出、? 查看全部帮助。

# 补上漏掉的文件 / 改写提交信息(仅限尚未推送的最近一次提交)
git add forgotten-file.txt
git commit --amend --no-edit        # --no-edit 表示提交信息不变

git commit --amend 的使用边界

--amend 不是修改原提交,而是丢弃原提交并创建一个新提交。所以:

- 只能用于尚未推送的提交;

- 已经推送的提交被 amend 后,本地与远程历史分叉,必须 git push --force-with-lease 才能推上去,而强制推送会覆盖别人的工作;

- 已合并到其他分支的提交不要 amend。

5. 查看状态与差异

git status                 # 完整状态
git status -s              # 精简状态,XY 两列分别代表暂存区/工作区状态
git diff                   # 工作区 vs 暂存区(还没 add 的改动)
git diff --staged          # 暂存区 vs 最近提交(这次 commit 会提交什么)
git diff HEAD              # 工作区 + 暂存区 vs 最近提交(全部未提交改动)
git diff main..feature     # 两个分支之间的差异
git diff --stat            # 只看统计,不打印具体内容

预期输出:git status -s 形如

 M README.md      # 第二列 M:工作区已改,未暂存
M  src/a.py       # 第一列 M:已暂存
?? new.txt        # ??:未跟踪

6. 查看历史

git log --oneline --graph --decorate --all

预期输出:

* 3f2a1b0 (HEAD -> main) feat: 添加登录接口
*   9c8d7e6 (tag: v1.0.0) Merge branch 'feature/pay'
|\
| * 5b4a3c2 (feature/pay) feat: 支付回调
|/
* 1a2b3c4 docs: 添加 README

参数含义:--oneline 一条一行、--graph 画 ASCII 分叉图、--decorate 显示分支与标签名、--all 包含所有分支。

git log --author="张三" --since="2 weeks ago" --oneline
git log -p README.md                 # 只看某个文件的改动历史(含 diff)
git log -S "def login" --oneline     # 搜索「新增/删除了这段字符串」的提交(pickaxe)
git show 3f2a1b0                     # 查看某次提交的元信息 + 完整 diff
git show v1.0.0:README.md            # 查看某个版本里某文件的内容
git blame README.md                  # 逐行标注最后修改它的提交与作者

git blame 的局限

git blame 只能告诉你「这行最后一次被谁在哪个提交里改动」。如果那次提交做的是全文件格式化或者纯移动代码,责任信息就失真了。它适合定位线索,不适合直接用来追责。配合 git log -S(按内容变化搜索)和 git log -L(按行范围搜索)更可靠。

# 二分定位:找出引入 bug 的那次提交
git bisect start
git bisect bad                  # 当前版本是坏的
git bisect good v1.0.0          # 这个标签对应的版本是好的
# Git 会自动检出中间那次提交,你测试后告诉它结果
git bisect good     # 或 git bisect bad
# 重复若干次后 Git 打印出「第一个坏提交」
git bisect reset                # 结束后回到原来的分支

预期输出:每次回答后 Git 打印 Bisecting: 3 revisions left to test after this (roughly 2 steps),最终打印 <hash> is the first bad commit。

二分可以自动化

如果能写出一条「坏则返回非 0」的脚本(例如 pytest tests/test_login.py),可以用 git bisect run pytest tests/test_login.py 全自动完成二分, 次提交只需约 次执行。

7. 撤销操作实战

# ① 工作区改了想丢掉(未暂存)
git restore README.md
git restore .                      # 丢弃当前目录全部未暂存改动

# ② add 错了想撤出暂存区(保留工作区改动)
git restore --staged README.md

# ③ 彻底丢弃某文件的所有未提交改动
git restore --source=HEAD --staged --worktree README.md

# ④ 提交了但想重新组织:撤销提交,改动回到暂存区
git reset --soft HEAD~1

# ⑤ 撤销提交,改动回到工作区(未暂存)
git reset HEAD~1                   # 等价于 git reset --mixed HEAD~1

# ⑥ 撤销已经推送的提交:生成一条反向提交,历史只增不改
git revert 3f2a1b0
git revert --no-commit 3f2a1b0     # 只改工作区,不自动提交,可与其他改动一起提交

预期输出:git reset --soft HEAD~1 后 git status 会显示原来的改动全部处于 Changes to be committed:;而 git reset HEAD~1 后同一批改动位于 Changes not staged for commit:。

git reset --hard 会永久丢弃未提交的改动

```bash

git reset --hard HEAD~3 # 回退 3 个提交,工作区和暂存区的相关改动全部消失

git checkout -- . # 老写法,同样会丢弃全部未暂存改动

git clean -fd # 删除所有未跟踪的文件和目录,新建但没 add 的文件直接没了

```

执行前请先 git status 确认,或先 git stash 保存一份。已经提交过的内容还能靠 git reflog 救回,从未提交过的内容救不回来。

怎么选?一句话决策表:

我想……用
丢掉某文件还没 add 的改动git restore <file>
把文件从暂存区拿出来但保留改动git restore --staged <file>
撤销最近提交,改动想重新提交git reset --soft HEAD~1
撤销最近提交,改动想重新整理git reset HEAD~1
撤销最近提交并彻底丢弃改动git reset --hard HEAD~1(危险)
撤销已推送的提交git revert <commit>
改最近一条提交的信息或内容git commit --amend(未推送时)

8. 分支、合并与冲突

git branch                       # 列出本地分支,* 表示当前分支
git branch -a                    # 含远程分支
git switch -c feature/login      # 新建并切换到该分支(等价于 git checkout -b)
git switch main                  # 切回 main
git merge feature/login          # 把 feature/login 合并进当前分支
git branch -d feature/login      # 删除已合并的分支
git branch -D feature/login      # 强制删除(未合并也删,慎用)

预期输出:git merge 在快进时打印

Updating 1a2b3c4..5b4a3c2
Fast-forward
 src/login.py | 42 ++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

在需要三方合并时则提示 Merge made by the 'ort' strategy.。

冲突的产生与解决。 当两个分支改了同一文件的同一区域时,Git 无法自动决定保留哪个,于是把两边的内容都写进文件并标记出来:

<<<<<<< HEAD
本次要合并进的当前分支(ours)的内容
=======
被合并进来的分支(theirs)的内容
>>>>>>> feature/login

解决步骤:

git merge feature/login
# 预期输出:CONFLICT (content): Merge conflict in src/login.py
#          Automatic merge failed; fix conflicts and then commit the result.

git status                 # 冲突文件会列在 "Unmerged paths" 下
# 1) 手动编辑文件,删掉 <<<<<<<、=======、>>>>>>> 三行标记,保留你想要的最终内容
# 2) 标记为已解决
git add src/login.py
# 3) 完成合并提交
git commit                 # Git 会预填好合并提交信息

# 中途反悔:放弃这次合并,回到合并前
git merge --abort

冲突解决辅助工具

git checkout --ours <file> 表示整份文件采用当前分支的版本,--theirs 采用对方的版本;git mergetool 可打开图形化三方对比工具。注意:在 rebase 过程中 ours/theirs 的含义是反的(因为 rebase 是把你放到对方基底上重放)。

9. 变基与交互式变基

git switch feature/login
git rebase main

预期输出:Successfully rebased and updated refs/heads/feature/login.;若中途冲突,Git 会停下并提示你解决后再 git rebase --continue,想放弃则 git rebase --abort。

# 交互式变基:整理最近 4 条提交
git rebase -i HEAD~4

预期输出(编辑器打开):

pick 1a2b3c4 feat: 添加登录接口
pick 5b4a3c2 fix: 修正拼写
pick 9c8d7e6 wip
pick 3f2a1b0 feat: 添加登出接口

把第一列的动作词改掉即可:

动作缩写含义
pickp保留该提交
rewordr保留改动,但重新编辑提交信息
edite停下来,允许你修改提交内容后再继续
squashs合并进上一条提交,并合并两条提交信息
fixupf合并进上一条提交,丢弃本条提交信息
dropd删除该提交(也可直接删掉整行)
execx执行一条 shell 命令(例如跑测试)

例如把上面 4 条整理成 2 条干净的提交:

pick 1a2b3c4 feat: 添加登录接口
fixup 5b4a3c2 fix: 修正拼写
fixup 9c8d7e6 wip
pick 3f2a1b0 feat: 添加登出接口

变基与 push --force 的组合是团队协作事故高发区

变基后本地哈希与远程不一致,普通 git push 会被拒绝,很多人于是用:

```bash

git push --force # 危险:无条件覆盖远程分支,会抹掉同事刚推的提交

```

正确做法是用带保护的强制推送,它在覆盖前会检查远程是否被别人改动过:

```bash

git push --force-with-lease

```

更好的做法是:公共分支永远不 force push,只在个人特性分支上使用。

10. cherry-pick 与 stash

# 把某一条提交「复制」到当前分支(生成新哈希的新提交)
git cherry-pick 5b4a3c2
git cherry-pick 5b4a3c2 9c8d7e6           # 一次摘取多条
git cherry-pick 5b4a3c2..9c8d7e6          # 一个区间(不含起点)
git cherry-pick --abort                   # 冲突时放弃

典型场景:修复了 main 上一个紧急 bug,想把这条修复也搬到 release/1.0 分支上。

# 临时保存当前改动
git stash push -m "登录页调试到一半"
git stash -u                              # -u 连未跟踪文件一起存(默认不含)
git stash list

预期输出:

stash@{0}: On feature/login: 登录页调试到一半
git stash pop        # 恢复并【从栈里删除】这条 stash
git stash apply      # 恢复但【保留】栈里的这条 stash
git stash pop stash@{1}
git stash drop stash@{0}     # 手动删除某条
git stash clear              # 清空整个栈(无法恢复,慎用)
命令恢复改动保留 stash 记录何时用
git stash pop是否最常用,恢复后不再需要这条记录
git stash apply是是想在多个分支上应用同一份改动

11. 标签与版本发布

# 轻量标签:只是一个指向提交的指针,不含额外信息
git tag v1.0.0

# 附注标签:是一个完整的对象,含作者、日期、说明,可被 GPG 签名
git tag -a v1.0.1 -m "修复登录超时问题"

git tag                        # 列出所有标签
git tag -l "v1.*"              # 按模式过滤
git show v1.0.1                # 查看标签详情(轻量标签只显示提交)
git push origin v1.0.1         # 推送单个标签
git push origin --tags         # 推送所有标签
git tag -d v1.0.0              # 删除本地标签
git push origin :refs/tags/v1.0.0   # 删除远程标签
类型命令存储内容适用
轻量标签 lightweightgit tag v1.0.0仅指向提交临时标记、本地用途
附注标签 annotatedgit tag -a v1.0.0 -m "..."独立对象,含作者/日期/说明/可签名正式发布一律用这个

语义化版本(Semantic Versioning, SemVer) 形如 MAJOR.MINOR.PATCH:

位何时递增例子
MAJOR有不兼容的破坏性变更1.4.2 → 2.0.0
MINOR向后兼容地新增功能1.4.2 → 1.5.0
PATCH向后兼容地修 bug1.4.2 → 1.4.3

预发布版本写成 1.0.0-alpha.1、1.0.0-rc.1,其优先级低于对应的正式版。详见 工具-03-包管理器。

12. 远程仓库与跟踪分支

git remote -v                                        # 查看已配置的远程
git remote add origin https://example.com/team/repo.git
git remote set-url origin git@example.com:team/repo.git   # 换成 SSH 方式
git clone https://example.com/team/repo.git          # 克隆
git push -u origin main                              # 首次推送并建立跟踪关系
git push                                             # 之后直接推
git push origin feature/login                        # 推送指定分支
git push origin --delete feature/old                 # 删除远程分支

-u(--set-upstream)的作用是把本地分支与远程分支建立跟踪关系(tracking branch)。建立之后,git status 会告诉你「领先/落后远程几个提交」,git push / git pull 也能省略参数。

git branch -vv          # 查看本地分支与上游分支的对应关系

预期输出:* main 3f2a1b0 [origin/main: ahead 2, behind 1] feat: ...

git fetch origin              # 只下载远程更新,【不】改动你的工作区
git fetch --prune             # 同时清理已在远程删除的远程跟踪分支
git pull                      # = git fetch + git merge
git pull --rebase             # = git fetch + git rebase
git pull --ff-only            # 只允许快进,否则报错(最安全)
命令是否改动工作区是否产生合并提交历史形态
git fetch否否不变
git pull是本地有分叉时会产生有分叉
git pull --rebase是否线性
git pull --ff-only是(仅快进)否线性,且不可能出现意外合并

pull --rebase 的取舍

优点:本地历史保持线性,git log 好读,不会出现一堆「Merge branch 'main' of ...」噪音。

代价:本地未推送的提交会被改写哈希。如果这些提交已经推给别人看,就不要用。

折中做法:git config --global pull.rebase true 加上 git config --global rebase.autoStash true,让未提交的改动自动暂存再恢复。团队公共分支上则更推荐 git pull --ff-only,把合并动作交给显式的 merge 或 PR。

13. 找回丢失的提交(reflog)

git reflog 记录的是 HEAD 和分支指针的每一次移动,包括提交、切换分支、重置、合并。默认保留 90 天(不可达对象 30 天)。

误 reset --hard 之后的完整救援步骤

```bash

# 第 1 步:查看指针移动历史,找到被 reset 掉的那个提交

git reflog

# 预期输出(注意时间顺序,越在上面越新):

# 3f2a1b0 (HEAD -> main) HEAD@{0}: reset: moving to HEAD~3

# 9c8d7e6 HEAD@{1}: commit: feat: 添加登出接口

# 5b4a3c2 HEAD@{2}: commit: feat: 添加登录接口

# 1a2b3c4 HEAD@{3}: commit (initial): docs: 添加 README

# 第 2 步:确认 9c8d7e6 就是你丢的那条(先看一眼内容再动)

git show 9c8d7e6 --stat

# 第 3 步:三种救法,按需选择

git reset --hard 9c8d7e6 # 直接把 main 指回丢失前的位置

git branch rescue 9c8d7e6 # 更安全:新开一个分支指向它,慢慢挑

git cherry-pick 9c8d7e6 # 只把这一条捡回当前分支

```

如果连 reflog 都找不到(例如对象已被 gc 回收),可查 git fsck --lost-found 列出悬挂对象(dangling commit)再尝试恢复。从未提交过的改动无法用 reflog 找回。

14. 子模块与 worktree

# 子模块:在一个仓库里引用另一个仓库的某个提交
git submodule add https://example.com/libs/common.git libs/common
git submodule update --init --recursive     # 克隆后初始化子模块
git clone --recurse-submodules <url>        # 一步到位
git submodule status                        # 查看各子模块当前提交

子模块的坑在于:父仓库记录的是子模块的某个具体提交哈希,而不是分支。子模块一旦更新,父仓库必须提交这次指针变化。团队里若有人忘记 --init,就会遇到「目录是空的」的困惑。多数场景下,改用包管理器(见 工具-03-包管理器)或 monorepo 会更省心。

# worktree:同一个仓库同时检出多个分支到不同目录
git worktree add ../hotfix hotfix/urgent    # 在 ../hotfix 目录检出 hotfix/urgent 分支
git worktree list
git worktree remove ../hotfix

用途:正在写新功能时线上出紧急 bug,不必 stash 就能在另一个目录里切到 hotfix 分支干活。

15. .git 目录里都有什么

路径作用
.git/HEAD当前 HEAD 指向哪(通常是一行 ref: refs/heads/main)
.git/config仓库级配置
.git/index暂存区(二进制文件)
.git/objects/所有对象:blob(文件内容)、tree(目录)、commit(提交)、tag(附注标签)
.git/refs/heads/本地分支,每个文件一行提交哈希
.git/refs/tags/标签
.git/refs/remotes/远程跟踪分支
.git/logs/reflog 记录
.git/hooks/客户端钩子脚本(pre-commit、commit-msg 等)
git cat-file -t 3f2a1b0      # 查看对象类型,输出 commit / tree / blob / tag
git cat-file -p 3f2a1b0      # 查看对象内容
git count-objects -vH        # 查看仓库对象数量与占用体积

16. 大文件与仓库体积治理

Git 对文本极其高效,但对二进制文件很糟糕:一张图片改一个像素,Git 也要存下一整份新副本(因为它存的是快照,且二进制无法做有意义的差异压缩)。一旦提交过大文件,它会永久留在历史里,克隆时所有人都会被拖累。

# 找出历史上占体积最大的对象
git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '/^blob/ {print $3, $4}' | sort -rn | head -20

.gitignore 补救不了已提交的文件

.gitignore 只影响「哪些未跟踪文件不出现在 git status 里」。一个 200MB 的视频一旦被 git add 并 commit,它会作为对象永久存在于 .git/objects 中,即使你后来 git rm 删掉文件,历史里的那份副本依然在,git clone 依然要下载它。要缩小体积必须重写历史。

历史重写工具:

工具说明
git filter-repo目前推荐的官方方向工具(需单独安装),速度快、用法清晰
git filter-branch老工具,极慢,官方已不推荐,仅在无法安装 filter-repo 时使用
BFG Repo-CleanerJava 实现,专注删除大文件与敏感信息,配置简单
# 用 filter-repo 从全部历史中删除某个大文件(示例,务必先备份仓库!)
git clone --mirror https://example.com/team/repo.git repo-backup.git
cd repo-backup.git
git filter-repo --path path/to/big-video.mp4 --invert-paths

历史重写会改写所有提交的哈希,属于不可逆的破坏性操作

执行前必须:① 完整备份(git clone --mirror);② 通知所有协作者;③ 重写后所有人必须重新克隆,本地旧克隆直接推送会把脏历史带回来。

团队协作场景请先与负责人确认,并选择低峰期执行。日常更省事的做法是:从一开始就用 Git LFS 管理大文件,或干脆把二进制产物放在对象存储而不是 Git 里。

17. 常见工作流简介

工作流分支结构优点缺点适合团队规模
集中式 Centralized只有 main,大家直接提交最简单,无合并互相阻塞,代码随时可能坏1–3 人 / 个人项目
功能分支 Feature Branchmain + 每人一个短生命周期特性分支隔离好,配合 PR 可审查需要纪律维护分支寿命3–30 人,最主流
Git Flowmain + develop + feature/ + release/ + hotfix/*发布节奏严格、职责清晰分支多、流程重、合并开销大有明确版本发布周期的大团队
Trunk-based只有 main(主干),改动小步快跑频繁合并集成早、冲突小、天然适配 CI/CD依赖完善的自动化测试与开关30 人以上或高频发布团队

Git Flow 的长期分支 develop 在持续交付的团队里往往是负担;trunk-based 的前提是必须有可靠的自动化测试与功能开关(feature flag),否则主干会长期处于不可发布状态。相关实践(Pull Request、Code Review、分支保护)见 工具-05-GitHub与GitLab协作,流水线部分见 工具-08-CICD入门。

常见坑

坑 1:把 git commit 当成 git add 的替代

git commit -a 会跳过暂存区直接提交所有已跟踪文件,新文件依然不会被包含。它看起来省事,代价是失去了用暂存区裁剪提交的能力。建议老老实实 add + commit,需要细分时用 git add -p。

坑 2:在分离头指针状态下提交

git checkout 3f2a1b0(直接用哈希检出一个提交)之后,HEAD 处于分离状态。此时提交的内容不属于任何分支,一旦切走就可能「消失」。git status 会明确提示 HEAD detached at 3f2a1b0。若已经提交了想保留,立刻 git switch -c 新分支名。

坑 3:.gitignore 不生效

三种常见原因:① 目标文件已被跟踪(见上文,需要 git rm --cached);② 规则写错,比如写了 node_modules(会匹配同名文件)而本意是 node_modules/(只匹配目录);③ 规则被父目录的 ! 取反规则覆盖,或位于更浅的 .gitignore 而优先级更低。

坑 4:误把敏感信息提交进仓库

密码、密钥(.env、*.pem、id_rsa)一旦提交并推送,必须视为已泄露:先立刻在服务端轮换(rotate)这把密钥,然后用 git filter-repo 清理历史。仅删除文件再提交是无效的——历史里还在。预防手段:写好 .gitignore、用 git secrets / gitleaks 之类的 pre-commit 钩子。

坑 5:git pull 触发意外的合并提交

git pull 默认是 fetch + merge。当本地有未推送提交且远程也有新提交时,它会自动创建一个合并提交,把历史弄乱,甚至弹出编辑器让你写合并信息而把人卡住。规避方式:git config --global pull.rebase true,或团队统一用 git pull --ff-only 让它直接报错,再手动决定 merge 还是 rebase。

坑 6:文件权限/换行符导致的「整个文件都改了」

除了 core.autocrlf,core.fileMode 也会造成类似现象(Windows 与其他系统混用时)。用 .gitattributes 把规则提交到仓库,让所有人行为一致,是唯一可靠的解法。

练习题

练习 1:撤销操作辨析

你刚刚执行了 git add . 并 git commit -m "temp",现在发现这次提交混进了两个不该提交的调试文件,且你还没推送。请给出两种修正方案,并说明它们对暂存区和工作区的不同影响。

练习 2:手写 .gitignore

为一个 Python 项目写一份 .gitignore,要求:忽略 __pycache__、所有虚拟环境目录、.env 文件、dist/ 和 build/;但保留 docs/ 下的所有 .pdf 文件,同时忽略 docs/tmp/ 下的全部内容。

练习 3:模拟冲突并解决

创建仓库,在 main 上把 README.md 第一行改成 A 并提交;切出 feature 分支,把同一行改成 B 并提交;切回 main 再改成 C 并提交。现在 git merge feature 会冲突。请写出完整的解决步骤,并解释冲突标记里 HEAD 与分支名分别代表哪一边。

练习 4:整理提交历史

你的 feature/cart 分支上有 6 条提交,其中 3 条是 wip。请用交互式变基把它们整理成 2 条语义清晰的提交,再把这个分支变基到最新的 main 上。写出完整命令序列,并说明为什么这之后不能用普通的 git push。

练习 5:灾难恢复

你执行了 git reset --hard HEAD~5,丢掉了 5 条提交。请写出用 git reflog 找回它们的完整步骤;如果你在 reset 之前还修改了一个文件但从未 add 过,这个文件能找回吗?为什么?

FAQ

Q1:git fetch 和 git pull 到底差在哪?

git fetch 只把远程的新对象下载到本地并更新远程跟踪分支(origin/main),完全不碰你的工作区和本地分支,是绝对安全的。git pull 等于 git fetch 再加一次 git merge(或 git rebase),会实际改动工作区,因此可能产生冲突或意外的合并提交。想安全地看一眼远程有什么变化,永远先用 git fetch + git log HEAD..origin/main --oneline。

Q2:不小心提交了一个 1GB 的文件,删掉再提交为什么仓库还是很大?

因为 Git 的历史是不可变的追加式结构。删除文件只是新增一条「删除」提交,旧提交里的那个对象依然被引用着,git clone 依然要传输它。必须重写历史(git filter-repo)才能真正移除,而且重写后所有协作者都要重新克隆。这也是「第一次提交前就把 .gitignore 写好」如此重要的原因。

Q3:可以同时用多个远程仓库吗?

可以。常见做法是 fork 工作流:origin 指向自己的 fork,upstream 指向原项目。

```bash

git remote add upstream https://example.com/original/repo.git

git fetch upstream

git switch main && git merge upstream/main

```

另外 git remote set-url --add --push origin <url> 还能实现「一次 push 同步到多个远程」。

Q4:提交信息写错了但已经推送了,怎么办?

如果仓库是团队共享的,不要用 --amend + push --force,那会改写公共历史。正确做法是接受它,或者用 git revert 生成一条反向提交(对代码而言),并在后续沟通中说明。只有在个人分支、且确认没人拉取过时,才考虑 git push --force-with-lease 修正。

相关笔记

  • 工具-05-GitHub与GitLab协作 —— 分支策略、Pull Request、Code Review、Issue 管理,与本文的 Git 本地操作用法互补
  • 工具-02-命令行与Shell —— Git 命令全部在终端里执行,Shell 基础不牢会拖累 Git 学习
  • 工具-08-CICD入门 —— 持续集成如何在每次推送后自动跑构建与测试
  • 工具-07-调试技巧 —— git bisect 是「二分定位 bug」在版本维度上的应用
  • 工具-03-包管理器 —— 语义化版本、锁文件与依赖管理,与本文的标签/版本发布直接关联

参考来源