git 使用指南

这是一份“命令优先、可快速检索”的 Git 速用指南。
如果你在找 log，直接跳到 ## 1. command > ### 1.2 log。

# 0. 核心概念（精简）

# 0.1 三区模型

工作区（Working Directory）：你正在改的文件
暂存区（Staging Area）：准备提交的变更
仓库（Repository）：提交历史

Untracked -> git add -> Staged -> git commit -> Committed

# 0.2 HEAD 与引用

HEAD：当前分支或当前提交指针
HEAD~1：上一个提交
HEAD^2：合并提交的第二父提交

# 0.3 第一父路径（first-parent）

first-parent 表示：遇到 merge commit 时，只沿着“当前主线分支”的父提交继续回溯。
它适合查看主分支的演进，不被功能分支内部提交干扰。

# 只看主线提交历史
git log --first-parent --oneline

# 只看主线上的合并点
git log --first-parent --merges --oneline

# 统计主线提交数量
git rev-list --first-parent --count main

1
2
3
4
5
6
7
8

# 1. command

# 1.1 common

# 1.1.1 状态与差异（status / diff / show）

# 当前状态（推荐先看这个）
git status
git status -s

# 差异查看
git diff                    # 工作区 vs 暂存区
git diff --staged           # 暂存区 vs 最新提交
git diff --name-only
git diff --stat

# 查看提交详情
git show
git show <commit>

1
2
3
4
5
6
7
8
9
10
11
12
13

使用场景：

不确定改了什么：git status -s && git diff --stat
提交前做最后检查：git diff --staged

# 1.1.2 暂存与提交（add / commit / restore）

# 暂存
git add <file>
git add .
git add -A

# 提交
git commit -m "feat(scope): message"

# 撤销工作区修改
git restore <file>

# 取消暂存
git restore --staged <file>

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1.1.3 分支操作（branch / switch / checkout）

# 创建与切换
git switch -c feature/demo
git switch main
git switch -

# 查看分支
git branch
git branch -vv
git branch -a

# 删除分支
git branch -d feature/demo
git branch -D feature/demo

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1.1.4 远程同步（fetch / pull / push / remote）

git remote -v
git fetch origin
git pull origin main
git push origin main
git push -u origin feature/demo

1
2
3
4
5

pull 默认是 fetch + merge。
想先看变更再合并，优先 fetch。

# 1.1.5 补充常用命令（tag / cherry-pick / stash / revert-reset）

# tag
git tag
git tag -a v1.2.0 -m "release v1.2.0"
git push origin --tags

# cherry-pick
git cherry-pick <commit-hash>
git cherry-pick --continue
git cherry-pick --abort

# stash
git stash push -m "wip"
git stash list
git stash pop

# reset / revert（按是否改历史选择）
git reset --soft HEAD~1
git revert <commit-hash>

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

# 1.2 log

# 1.2.1 基础查看

git log --help
git log --oneline
git log --graph --oneline --all --decorate
git log -n 20 --oneline

1
2
3
4

# 1.2.2 场景化检索（最常用）

# 按时间
git log --since="2026-01-01" --until="2026-12-31" --oneline

# 按作者
git log --author="jacky" --oneline

# 按提交信息关键字
git log --grep="fix" --oneline

# 按代码内容变化（非常常用）
#   --source: 显示改动来自哪个分支
#   --all: 所有本地分支 + 远程跟踪分支
git log -S "function_name" --source --all

# 按文件追踪
git log -- <file-path>
git log --follow -- <file-path>    # 文件重命名后继续追踪

# 只看新增/删除文件相关提交
git log --diff-filter=A --summary
git log --diff-filter=D --summary

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

# 1.2.3 排障与审查场景

# 找“谁在什么时候改了什么”
git log --oneline --decorate -- <file-path>

# 看某个功能分支与 main 的差异历史
git log main..feature --oneline
git diff main...feature

1
2
3
4
5
6

# 1.3 rev-list

rev-list 适合脚本和统计；log 适合人读。

# 1.3.1 双点 / 三点 / 计数

# 在 feature 但不在 main
git rev-list main..feature

# 两边差异计数（左边/右边）
git rev-list --left-right --count main...feature

# 提交数量统计
git rev-list --count HEAD
git rev-list --count main..feature

1
2
3
4
5
6
7
8
9

# 1.3.2 first-parent 与 ancestry-path

# 主分支演进统计（忽略被合入分支细节）
git rev-list --first-parent --count main

# 只看祖先路径
git rev-list <commit>..main --ancestry-path

1
2
3
4
5

# 1.3.3 查“某提交何时被合并”

commit_hash="abc1234"
git rev-list "$commit_hash"..main --ancestry-path --merges --reverse | head -1

1
2

# 1.4 blame

# 1.4.1 定位某行是谁改的

git blame <file>
git blame -L 10,40 <file>

1
2

# 1.4.2 与 log 联动追溯

# 先用 blame 找到提交 hash，再看该提交详情
git show <commit-hash>

# 追踪文件历史
git log --follow -- <file>

1
2
3
4
5

使用建议：

先 blame -L 锁定行范围
再 show 看提交上下文
最后 log --follow 看文件演进

# 2. workflow（工作流与规范）

# 2.1 常规协作流程

# 1) 基于主分支拉新分支
git switch main
git pull origin main
git switch -c feature/xxx

# 2) 开发提交
git add .
git commit -m "feat(module): add xxx"

# 3) 同步主分支
git fetch origin
git rebase origin/main

# 4) 推送并发起 PR
git push -u origin feature/xxx

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

# 2.2 提交规范（Conventional Commits）

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

常见 type：

feat 新功能
fix 修复问题
docs 文档更新
refactor 重构
test 测试
chore 杂项

示例：

fix(auth): 修复 token 刷新失败

# 2.3 分支命名建议

feature/user-auth
fix/login-error
hotfix/critical-bug
release/v1.2.0

1
2
3
4

# 3. troubleshoot（故障排除）

# 3.1 推送被拒绝（non-fast-forward）

git pull --rebase origin main
git push origin main

1
2

# 3.2 提交到错误分支

git reset --soft HEAD~1
git switch correct-branch
git commit -m "fix: move commit to correct branch"

1
2
3

# 3.3 忘记把文件放进上次提交

git add <forgotten-file>
git commit --amend --no-edit

1
2

# 3.4 撤销合并

# 未推送
git reset --hard HEAD~1

# 已推送（推荐）
git revert -m 1 <merge-commit-hash>

1
2
3
4
5

# 3.5 误删分支恢复

git reflog
git switch -c recovered-branch <commit-hash>

1
2

# 3.6 冲突处理

git status
git diff

# 解决后
git add <resolved-file>
git commit -m "fix: resolve merge conflict"

1
2
3
4
5
6

# 3.7 大文件清理（历史已污染）

# 推荐 git-filter-repo
git filter-repo --path large-file --invert-paths

1
2

该操作会改写历史，执行前先备份仓库。

# 3.8 提交了敏感信息（先止血）

# 先从当前跟踪中移除（保留本地文件）
git rm --cached sensitive-file
git commit -m "chore: remove sensitive file from tracking"

# 之后再做历史清理（会改写历史）
# git filter-repo --path sensitive-file --invert-paths

1
2
3
4
5
6

# 4. quick-reference（速查清单）

# 4.1 我想看最近提交

git log --oneline -n 20

# 4.2 我想找“谁改了这一行”

git blame -L 120,160 src/foo.ts

# 4.3 我想查某个函数在哪次提交里变了

git log -S "myFunction" --source --all

# 4.4 我想比较两个分支谁领先多少提交

git rev-list --left-right --count main...feature

# 4.5 我想撤销本地未提交改动

git restore <file>
git restore .

1
2

# 4.6 我想取消已暂存但不丢改动

git restore --staged <file>

# 4.7 我想查看某次修改何时合并到主分支

commit_hash="abc1234"
git rev-list "$commit_hash"..main --ancestry-path --merges --reverse | head -1

1
2

# 5. 资源

#git #tool #tutorial

上次更新: 2026/03/27, 17:34:59