2.1 git config：先把身份和偏好配好#

第一次装完 Git，最先应该设置的是提交身份。

1
git config --global user.name "Your Name"
2
git config --global user.email "you@example.com"

Git 配置有作用域，后面的值会覆盖前面的同名值。

常用查询和修改：

1
git config --list --show-origin
2
git config --get user.name
3
git config --get-all alias.lg
4
git config --global --edit
5
git config --unset user.name
6
git config --unset-all alias.lg
7
git config --add alias.st status
8
git config --replace-all core.autocrlf input

常见而实用的配置：

1
git config --global alias.lg "log --oneline --graph --decorate --all"
2
git config --global alias.st status
3
git config --global alias.co checkout

提示： 配置优先级通常是 system < global < local。如果同一个键在多个地方都存在，仓库级最优先。

2.2 git init：把目录变成仓库#

1
git init
2
git init -b main

git init 会创建 .git 目录，里面保存对象、引用和配置。-b 可以直接指定初始分支名。

2.3 git clone：从远程复制仓库#

1
git clone <repository-url>
2
git clone <repository-url> my-project
3
git clone --depth 1 <repository-url>
4
git clone --branch feature/login --single-branch <repository-url>
5
git clone --recurse-submodules <repository-url>

注意： 浅克隆会让 git log、git bisect、复杂回溯变得受限，不适合长期开发。

3.1 路径参数怎么用#

Git 里很多命令后面跟的是 pathspec，不只是“单个文件名”。

提示： . 不是“全仓库”的魔法开关，它只是当前目录。你在仓库根目录运行时，看起来才像“全仓库”。

3.2 git status：先看状态再动手#

1
git status
2
git status -s
3
git status -sb

-s 是精简状态，-b 会额外显示当前分支。

3.3 git add：把本次想提交的内容放进暂存区#

1
git add file.txt
2
git add src/
3
git add .
4
git add -A
5
git add -u
6
git add -p

git add -p 很适合把一次大改拆成多个更干净的提交。每个 hunk 是一段连续改动，你可以按块决定要不要进暂存区。

提示： -A 更像“整个仓库都按当前状态入暂存区”，-u 更像“只刷新已跟踪文件的修改和删除”，add . 则受当前目录影响。

3.4 git commit：把暂存区写进历史#

1
git commit -m "feat: support dark mode"
2
git commit -a -m "fix: tracked file changes"
3
git commit --amend
4
git commit --amend --no-edit

-a 只会自动加入已跟踪文件的修改，不会把新文件自动加进来。

--amend 的作用是改写最近一次提交。常见场景：

注意： 一旦别人已经拿这笔提交作为新分支起点，amend 就会改掉提交 SHA。你的分支和对方分支会从同一个祖先变成分叉历史，后续要额外 rebase 才能对齐。

3.5 git rm、git mv、git clean#

1
git rm file.txt
2
git rm -r dir/
3
git rm --cached file.txt
4
git mv old.md new.md
5
git clean -n
6
git clean -fd

注意： git clean 只针对未跟踪文件，执行前最好先 -n 预览。

4.1 .gitignore、.git/info/exclude、全局 ignore 的区别#

docs/tmp.md 这种只想本地忽略的草稿，理论上更适合 .git/info/exclude；如果要所有协作者都忽略，才写进 .gitignore。

4.2 精准控制 .gitignore#

常见技巧：

1
*.log
2
!important.log
3

4
build/*
5
!build/.gitkeep
6

7
*.env
8
!.env.example

提示： 规则生效后，最实用的排查命令是 git check-ignore -v <path>，它会告诉你到底是哪个规则命中的。

这里的 build/* 比 build/ 更适合配合 !build/.gitkeep。如果直接忽略整个目录，Git 会停止继续进入这个目录匹配后续规则，取消忽略里面的文件就容易失效。

如果你确实想把一个被忽略的文件强制纳入版本控制，可以用：

1
git add -f docs/tmp.md

4.3 已经被跟踪的文件怎么停掉#

1
git rm --cached file.txt
2
git commit -m "chore: stop tracking generated file"

.gitignore 只能阻止新文件被跟踪，已经进过仓库的文件要先从索引里移除。

4.4 当你只想本地临时忽略#

如果是你自己临时写的笔记、调试文件、导出文件，优先考虑：

1
git check-ignore -v docs/tmp.md

然后把规则写进 .git/info/exclude 或你的全局 ignore，而不是污染仓库级规则。

5.1 创建、查看、切换、删除分支#

1
git branch
2
git branch -a
3
git branch -vv
4
git branch feature/login
5
git branch -m old-name new-name
6
git branch -d feature/login
7
git branch -D feature/login
8
git switch main
9
git switch -c feature/login
10
git switch --track origin/feature/login

5.2 常见合并/整合方式对照#

1
例子：feature 上有 C 和 D，main 上有 A 和 B
2

3
快进合并（FF）:
4
A--B--C--D
5

6
非快进合并（no-FF）:
7
A--B------M
8
      \   /
9
       C--D
10

11
压缩合并（squash）:
12
A--B--S
13

14
变基（rebase）:
15
A--B--C'--D'
16

17
挑拣提交（cherry-pick）:
18
A--B--C'

提示： 上面几个方式最大的区别，就是“是否保留原始分支结构”和“是否改写已有提交 SHA”。

更准确地说，cherry-pick 会复制指定提交的改动并在当前分支上生成新提交，原来的提交不会被改写；rebase 才会把当前分支上的既有提交复制成新的提交，因此提交 SHA 会变化。

5.3 git merge：把一条开发线并回主线#

1
git switch main
2
git merge feature/login
3
git merge --no-ff feature/login
4
git merge --squash feature/login
5
git merge --ff-only feature/login

git merge 会找共同祖先，尝试把两边的改动合在一起。

5.4 git rebase：重放提交，整理历史#

1
git switch feature/login
2
git rebase main
3
git rebase -i HEAD~4
4
git rebase --onto main release/1.0 feature/login

rebase 的核心是：把当前分支的提交拿下来，重新放到另一个基底后面。

-i 里常见指令：

注意： rebase 会改写提交 SHA，公共分支上要非常谨慎。它最适合你的私有分支，或者团队约定好的整理阶段。

5.5 git cherry-pick：只搬一笔或几笔提交#

1
git cherry-pick <commit-id>
2
git cherry-pick -x <commit-id>
3
git cherry-pick --no-commit <commit-id>
4
git cherry-pick <id1> <id2> <id3>
5
git cherry-pick A^..B

cherry-pick 常用于热修复回补到维护分支，或者把主分支上的某个修复单独带到发布分支。

6.1 什么时候会冲突#

• merge
• rebase
• cherry-pick
• revert
• stash apply / stash pop
• pull --rebase

6.2 怎么查看冲突#

1
git status
2
git diff --name-only --diff-filter=U
3
git ls-files -u

git ls-files -u 的三阶段含义：

如果你想快速选择一边，可以用：

1
git restore --ours path/to/file
2
git restore --theirs path/to/file
3
git add path/to/file

注意： ours / theirs 在 merge 里比较直观；但在 rebase 时会更绕。rebase 是把你的提交重放到新基底上，ours 往往指新基底一侧，theirs 才是正在被重放的提交一侧。冲突复杂时，先打开文件看内容，比直接套命令更稳。

6.3 冲突文件里到底是什么#

1
<<<<<<< HEAD
2
当前分支的内容
3
=======
4
另一边的内容
5
>>>>>>> feature/login

你可以用任意文本编辑器在工作区直接修改冲突文件。常见做法是：

1. 打开冲突文件
2. 选择保留哪一边，或者手动合并两边内容
3. 删除 <<<<<<<、=======、>>>>>>> 这些标记
4. 保存文件
5. git add 这个文件，告诉 Git “我已经解决了”

6.4 冲突时各区状态#

git add 在这里的意义不是“新增文件”，而是把你手工整理后的版本写回索引，让 Git 认为这个路径已经解决。

6.5 不同操作的收尾命令#

如果发现方向不对，可以中止当前操作：

--abort 是回到操作前；--skip 是放弃当前这一个提交，继续处理后面的提交。--skip 常见于 rebase 或 cherry-pick 队列中某个提交已经不需要了。

提示： 如果你想让冲突更容易看清，可以把 merge.conflictstyle 设成 zdiff3，它会把共同祖先上下文也展示出来。

7.1 远程地址、别名和查询#

远程地址里的 origin、upstream、fork 这些名字只是别名，不是特殊语法。

1
git remote -v
2
git remote show origin
3
git remote get-url origin
4
git remote get-url --push origin
5
git branch -r
6
git branch -vv

7.2 远程地址的增删改查#

1
git remote add origin <url>
2
git remote rename origin upstream
3
git remote set-url origin <new-url>
4
git remote set-url --push origin <push-url>
5
git remote remove origin

7.3 本地分支和远程分支的对应关系#

1
git push -u origin feature/login
2
git branch --set-upstream-to=origin/main main
3
git branch --unset-upstream
4
git fetch --prune
5
git push origin --delete feature/login

7.4 git fetch 和 git pull 的区别#

1
fetch: 只把远程变化下载到本地远程跟踪分支，不动工作区和当前分支
2
pull : fetch + merge/rebase，把当前分支和它的上游整合起来

git fetch 默认会按远程的 fetch refspec 更新匹配到的远程跟踪分支，通常是 origin/*。它不会改你当前分支。

git pull 不是“把所有分支都合到当前分支”，它只会把当前分支对应的上游整合进来。别的远程分支如果也被下载了，只是更新了本地跟踪引用，不会自动合并进当前分支。

1
git fetch origin
2
git pull origin main
3
git pull --rebase origin main
4
git pull --ff-only
5
git pull --rebase --autostash origin main

7.5 git push 和两个 force 参数#

1
git push
2
git push -u origin feature/login
3
git push --force origin main
4
git push --force-with-lease origin main

--force-with-lease 适合“我确认自己在重写历史，但希望先检查远程有没有被别人更新过”的场景。

8.1 git log：先看历史图#

1
git log
2
git log --oneline
3
git log --oneline --graph --decorate --all
4
git log --author="Alice"
5
git log --since="2026-06-01"
6
git log -- path/to/file.md
7
git log --follow -- path/to/file.md

8.2 怎么拿到提交 ID#

1
git log --oneline
2
git rev-parse HEAD
3
git rev-parse --short HEAD
4
git reflog

8.3 HEAD~1、HEAD^ 这些表达式到底是什么#

它们不是宏，而是 Git 的 revision 语法。

8.4 git diff：比较差异#

1
git diff
2
git diff --cached
3
git diff HEAD
4
git diff 分支一 分支二
5
git diff 分支一...分支二
6
git diff --name-only 分支一 分支二
7
git diff --stat 分支一 分支二
8
git diff --word-diff 分支一 分支二
9
git diff --check

提示： git diff main..feature/login 这种写法容易让人联想到“范围”语法。教学和日常里更建议写成 git diff main feature/login，如果想看 merge-base 再用 git diff main...feature/login。

8.5 git show 和 git blame#

1
git show <commit-id>
2
git show <commit-id> -- path/to/file
3
git blame path/to/file
4
git blame -L 20,40 path/to/file

git show 适合看一笔提交的完整内容；git blame 适合看某一行是谁引入的。

git blame 常用参数：

提示： blame 更像“查上下文”，不是“找人背锅”。通常是先用 blame 找到提交，再用 show 看这个提交为什么这么改。

9.1 git restore：处理工作区和暂存区#

1
git restore file.txt
2
git restore --staged file.txt
3
git restore --source=HEAD~1 file.txt
4
git restore --source=HEAD~1 --staged --worktree file.txt

git restore 不会移动 HEAD，所以它适合“只想撤文件，不想动历史”。

换句话说，git restore --staged file.txt 不是把内容“搬回工作区”，而是取消这次暂存。文件在工作区里仍然保持你修改后的样子，只是不再属于下一次提交。

9.2 git reset：移动分支指针#

1
git reset --soft <commit-id>
2
git reset --mixed <commit-id>
3
git reset --hard <commit-id>

1
--soft  只动 HEAD
2
--mixed 动 HEAD 和暂存区
3
--hard  动 HEAD、暂存区、工作区

注意： reset --hard 会直接丢工作区内容。只在你确定不要这些改动时使用。

9.3 git revert：用一笔新提交抵消旧提交#

1
git revert <commit-id>
2
git revert -n <commit-id>
3
git revert -m 1 <merge-commit-id>
4
git revert --continue
5
git revert --abort

revert 不改历史，而是追加一个“反向提交”。这就是为什么它特别适合公共分支。

撤销合并提交时，-m 是 mainline 的意思，也就是告诉 Git “以哪个父提交作为主线”。一个 merge commit 至少有两个父提交：

常见主分支上撤销功能分支合并，一般是 git revert -m 1 <merge-commit-id>，因为第一个父提交通常是主分支原来的历史。这个操作会留下“这个功能分支的改动已经被反向抵消”的历史痕迹；未来如果再合并同一个分支，Git 可能认为那些提交已经合并过。更稳的做法通常是从新分支重新提交需要恢复的改动。

9.4 git stash：临时收起当前工作#

1
git stash push -m "wip: temp notes"
2
git stash push -p
3
git stash push -u
4
git stash push -a
5
git stash push --keep-index
6
git stash list
7
git stash show -p stash@{0}
8
git stash apply stash@{0}
9
git stash pop
10
git stash drop stash@{0}
11
git stash clear
12
git stash branch temp-work stash@{0}

stash 很适合和 switch、pull、rebase 配合：

• 先 stash
• 切分支或同步上游
• 再 pop 或 apply

如果恢复时冲突，处理方式和 merge 类似：解决文件、git add、再继续后续步骤。

默认 git stash push 只会收起已跟踪文件的改动，不会收未跟踪文件。临时新建的文件也要收起来时，用 -u；连 .gitignore 忽略的产物都要收起来时，用 -a，但这个很少需要。

--keep-index 的一个典型用法是：你已经用 git add -p 暂存了准备提交的干净部分，但工作区里还有别的半成品。此时可以 git stash push --keep-index，先只测试和提交暂存区里的内容，之后再 git stash pop 把半成品拿回来。

9.5 git reflog：最后的后悔药#

1
git reflog
2
git reset --hard HEAD@{1}

reflog 记录的是 HEAD 和分支引用移动过的历史。你就算把分支删了、reset 过头了，通常还是能从里面把引用找回来。

提示： 如果你做了危险操作，先去看 reflog，再决定要不要 reset 回去，比盲猜安全得多。

10.1 git tag：给版本打标签#

1
git tag
2
git tag -l "v1.*"
3
git tag v1.0.0
4
git tag -a v1.0.0 -m "Release v1.0.0"
5
git show v1.0.0
6
git tag -d v1.0.0
7
git push origin v1.0.0
8
git push origin --tags
9
git push origin --delete v1.0.0
10
git fetch --tags

轻量 tag 只是一个名字；annotated tag 会保存作者、时间和说明。发布版本更推荐 annotated tag。

注意： tag 一般当作“版本刻度”使用，最好不要随便改名改内容。要改时通常是删掉重建。

10.2 git submodule：把另一个仓库挂进来#

1
git submodule add <repository-url> vendor/lib
2
git submodule status
3
git submodule update --init --recursive
4
git submodule foreach git pull --ff-only
5
git submodule deinit -f vendor/lib
6
git rm -f vendor/lib

子模块会在父仓库里记录一个固定提交 SHA。它的常见流程是：

1. 在子模块仓库里更新并提交
2. 回到父仓库，把子模块指针更新到新的 SHA
3. 提交父仓库的指针变化

这和普通目录不一样，父仓库不会自动跟着子仓库的最新分支跑。

10.3 git bisect：二分法找出引入 Bug 的提交#

1
git bisect start
2
git bisect bad
3
git bisect good <good-commit>
4
git bisect skip
5
git bisect reset
6
git bisect run pnpm test

git bisect run 脚本里，通常 0 表示好，1 表示坏，125 表示跳过当前提交。

10.4 Git Hooks：把检查前置到提交前#

常见 hook：

hooks 默认放在 .git/hooks，但那里的脚本通常不会被仓库版本化。团队如果要共享 hooks，常见做法是设置 core.hooksPath 指向一个可提交目录。

10.5 git worktree：同一个仓库同时开多个工作区#

worktree 很适合“当前分支写到一半，又要马上切去修另一个 bug”的情况。它不会强迫你 stash 当前工作，而是在同一个仓库历史上额外挂一个工作目录。

1
git worktree list
2
git worktree add ../repo-hotfix main
3
git worktree add -b hotfix/login ../repo-hotfix origin/main
4
git worktree remove ../repo-hotfix
5
git worktree prune

和 stash 的区别：

注意： 同一个本地分支通常不能被两个 worktree 同时检出。需要并行开发时，给另一个 worktree 新建分支更清楚。

10.6 git rerere：记住你解决过的冲突#

rerere 是 reuse recorded resolution 的缩写。它会记录你怎么解决过某类冲突，下次遇到相同冲突时自动套用之前的解决结果。

1
git config --global rerere.enabled true
2
git rerere status
3
git rerere diff
4
git rerere forget path/to/file
5
git rerere gc

它特别适合长期功能分支反复 rebase、或者维护多个发布分支时重复解决同一类冲突。第一次还是要你手动解决，后续才会复用。

10.7 git grep：在仓库里查内容#

git grep 只查 Git 认识的文件，速度快，也不会默认扫进 node_modules、构建产物这类噪音。

1
git grep "TODO"
2
git grep -n "useEffect"
3
git grep -i "login"
4
git grep -l "fetchUser"
5
git grep "oldName" -- "*.ts" "*.tsx"
6
git grep "api" HEAD~3

如果只是查当前仓库代码，git grep 经常比普通 grep 更少噪音；如果要查未跟踪文件，还是用编辑器搜索或 rg 更合适。

10.8 git commit --fixup 和 git rebase --autosquash#

当你在 code review 后要修前面某个提交，fixup 比“新建一个 fix typo 提交，最后手动 squash”更顺。

1
git log --oneline
2
git commit --fixup <commit-id>
3
git rebase -i --autosquash <base>

流程是：

1. 找到要修正的目标提交 ID
2. 修改代码并 git add
3. git commit --fixup <commit-id>
4. git rebase -i --autosquash <base>
5. Git 会自动把 fixup 提交排到目标提交后面，并标成 fixup

常见例子：

1
git commit --fixup abc1234
2
git rebase -i --autosquash origin/main

提示： 这个功能适合整理个人分支提交。和普通 rebase 一样，如果分支已经被别人依赖，要先沟通再改写历史。

10.9 git range-diff：比较两组提交#

range-diff 很适合看“我 rebase 前后的提交系列到底变了什么”。普通 diff 更关注最终文件差异，range-diff 更关注提交序列之间的对应关系。

1
git range-diff origin/main..feature-old origin/main..feature-new
2
git range-diff main@{1}..feature main..feature

它的输出会按提交配对，告诉你哪些提交相同、哪些被重写、哪些新增或删除。写复杂 PR 时，这个命令比单纯看最终 diff 更能发现“整理历史时漏了提交”的问题。

10.10 git describe：从 tag 推导版本号#

describe 会从当前提交往回找最近的 tag，并生成一个可读版本描述。

1
git describe --tags
2
git describe --tags --always
3
git describe --tags --dirty

输出可能像这样：

1
v1.2.0-5-gabc1234

含义是：当前提交距离 v1.2.0 这个 tag 之后有 5 个提交，当前短 SHA 是 abc1234。

这个命令很适合放进构建脚本里生成版本号，比如 CLI 的 --version、前端页面的构建信息、后端服务的启动日志。

10.11 git sparse-checkout：大仓库只检出一部分#

大仓库里你只需要某几个目录时，可以用 sparse checkout 减少工作区体积。

1
git clone --filter=blob:none --sparse <repository-url>
2
cd repo
3
git sparse-checkout set frontend docs
4
git sparse-checkout list
5
git sparse-checkout add scripts
6
git sparse-checkout disable

它适合 monorepo 或超大项目。注意它改变的是工作区可见文件，不代表仓库历史不存在；需要和构建脚本、IDE 配置配合好。

10.12 git archive：导出干净源码包#

archive 可以从某个提交、分支或 tag 导出一份不带 .git 目录的源码包。

1
git archive --format=zip --output=release.zip HEAD
2
git archive --format=tar --prefix=myapp/ v1.0.0 > myapp.tar

它适合发源码包、交作业、给别人一份干净快照。它不会包含未提交文件，也不会包含 .git 历史。

11.1 常见任务对应的命令#

11.2 如果你只记三件事#

1. 先看 git status，再决定下一步。
2. 区分 restore、reset、revert：文件级恢复、历史回退、历史反向提交不是一回事。
3. 公共分支上不要随便改写历史，rebase、amend、force push 都要先想清楚别人是否已经依赖这笔提交。

如果把这篇文章串起来看，Git 的主线其实很简单：先配置好，再用 status -> add -> commit 形成日常闭环，遇到分支就用 switch/merge/rebase/cherry-pick，遇到远程就用 fetch/pull/push，出问题再用 restore/reset/revert/stash/reflog 收尾。