Git on heyaohua's Blog

Git 使用手册 · 终极篇：工程化、安全与团队规范

Sat, 22 Aug 2026 23:24:00 +0800

这是 Git 手册系列的最后一篇。前三篇解决了"会用 → 用得对 → 懂原理"，本篇解决最后一件事：让 Git 在团队和工程体系里成为可靠的基础设施，并在灾难发生时救得回来。

Monorepo vs Polyrepo：仓库拓扑决策

	Monorepo（一个仓库存所有项目）	Polyrepo（每项目一个仓库）
跨项目改动	一次提交原子完成	要发版、升依赖、多 PR 联动
代码共享	直接 import	发包 / submodule
CI	需要增量构建，配置复杂	简单直接
权限边界	靠 CODEOWNERS，粒度粗	天然隔离
克隆体积	大（可用 sparse checkout 缓解）	小
代表	Google、Meta、Vue、React 生态	多数中小团队

决策建议：

项目间强耦合、频繁联动发布（如前端组件库 + 应用）→ monorepo
团队/项目独立、发布节奏不同、需要强权限边界 → polyrepo
不确定就先 polyrepo；拆容易，合回去很难

monorepo 配套工具：Nx、Turborepo、Bazel（构建缓存与增量）、changesets（多包版本管理）。

大型仓库的性能优化

仓库几万提交、几百 MB 之后，这些手段能救体验：

# 浅克隆：只拿最近的历史（CI 必备）
git clone --depth 1 

# 部分克隆：不下载全部 blob，按需懒加载（本地开发大仓库神器）
git clone --filter=blob:none 

# 稀疏检出：只 checkout 需要的目录
git sparse-checkout init --cone
git sparse-checkout set apps/web packages/ui

# 让 status / diff 在大仓库里更快
git config core.fsmonitor true
git config core.untrackedCache true
git maintenance start        # 后台自动做 gc、打包、提交图等维护

提交图（commit-graph）单独提一句：它让 git log --graph、合并基计算在大仓库里快一个数量级，git maintenance start 会自动开启。

提交规范：Conventional Commits

格式：

():

常用 type：

type	含义	影响版本
`feat`	新功能	次版本 +1
`fix`	修 bug	修订号 +1
`perf`	性能优化	修订号 +1
`refactor`	重构（不改行为）	不升
`docs` / `style` / `test` / `chore` / `ci` / `build`	文档 / 格式 / 测试 / 杂务	不升
带 `!` 或 footer 写 `BREAKING CHANGE:`	破坏性变更	主版本 +1

示例：

feat(auth): 支持手机号验证码登录

- 新增 /auth/sms/send 与 /auth/sms/verify 接口
- 验证码 5 分钟有效，限频 1 条/分钟

Closes #128

为什么值得推行：版本号和 CHANGELOG 可以全自动生成。配套工具链：

# commitizen：交互式生成规范提交信息
pnpm add -D commitizen cz-conventional-changelog

# commitlint + husky：不合规的提交直接拒绝
pnpm add -D @commitlint/cli @commitlint/config-conventional
echo "npx commitlint --edit \$1" > .husky/commit-msg

# semantic-release / release-please：按提交记录自动升版本、发 CHANGELOG

签名提交与提交者验证

Git 的 user.name / user.email 可以随便填——git commit --author="Linus " 就能伪装任何人。要证明"这个提交真的是我提交的"，用签名：

SSH 签名（推荐，零门槛复用现有密钥）

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true      # 之后每次提交自动签名

GitHub 设置里把同一个公钥添加为 Signing Key，你的提交就会显示 Verified 徽章。

验证别人的提交

git log --show-signature         # 查看签名验证结果
git merge --verify-signatures main

为什么这很重要

供应链安全：防止有人伪装核心维护者提交恶意代码
审计合规：金融、政企场景要求提交可追溯真人
配合分支保护规则"要求签名提交"，从平台侧强制

密钥防护：从预防到泄漏处置

密钥进仓库是最高频的安全事故。三层防御：

第一层：本地预防

# gitleaks：提交/推送前扫描
brew install gitleaks
gitleaks git --pre-commit --staged --verbose   # 接入 husky pre-commit

.gitignore 里永远有：.env、*.pem、*.key、credentials*。

第二层：服务端拦截

GitHub：开启 Push Protection（推送时扫描，疑似密钥直接拒绝）
GitLab：开启 Secret Detection
自建：pre-receive hook 跑 gitleaks

第三层：泄漏后的处置 SOP

密钥一旦进过任何一次提交，就视为已泄漏，即使后来的提交删了它：

立即吊销 / 轮换密钥（这是唯一有效的补救，改历史只是清理痕迹）
用 git filter-repo 从全历史删除该文件（见高级篇）
全员重新克隆
排查密钥使用日志，评估影响面
复盘：为什么绕过了第一层和第二层

CI/CD 中的 Git 技巧

浅克隆 + 按需加深

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # 需要 tag / 全历史（如算版本号）时才用 0，否则保持默认 1

只跑受影响范围的测试

# 与合并基比较，得到改动文件列表
git diff --name-only origin/main...HEAD | grep -q '^apps/web/' && run_web_tests

版本号来自 Git

git describe --tags --always --dirty
# v1.2.0-5-ga1b2c3d  → 距 v1.2.0 之后第 5 个提交，哈希 a1b2c3d

这是给构建产物打版本标识的零维护方案，前端塞进 __VERSION__、后端塞进 /healthz 返回值。

自动打 tag / 生成 CHANGELOG

release-please 或 semantic-release 会读取 Conventional Commits，自动算出版本号、生成 CHANGELOG、创建 release PR 和 tag。从此"发版"不是一个手工动作。

保护分支 + 必需检查

平台侧配置（GitHub Branch Protection / GitLab Protected Branches）：

禁止直接 push main，必须走 PR
必须 ≥1 人 approve
必须通过 CI 检查
禁止 force push 和删除

灾难恢复 SOP

场景 1：误删了远程分支

# 任何拉过该分支的人本地都有完整历史
git switch -c feature/xxx <已知的最新提交id 或 reflog 里找>
git push -u origin feature/xxx

场景 2：对 main 执行了 force push，覆盖掉别人的提交

# 找到被覆盖前的 main 位置（任何同事本地、CI 缓存、或平台 Events API）
git reflog show main           # 在还没 pull 的机器上
git push --force origin <旧提交id>:main

教训：在平台设置里禁掉 main 的 force push，从制度上消灭这个场景。

场景 3：仓库本地损坏（对象丢失、索引损坏）

git fsck --full                # 诊断
git clone  rescue  # 最省事：远程还在就直接重克隆
# 远程也没了但同事机器上有：任何人的 clone 都是完整备份

场景 4：rebase / amend 错了，想回到操作前

git reflog                     # 找到 rebase 之前的 HEAD 位置
git reset --hard HEAD@{5}

场景 5：整个 .git 目录被删了

未推送的提交彻底丢失——这就是为什么"每天至少 push 一次"写进了初级篇。能做的只有从远程重新克隆，工作区文件还在的话手动对比恢复。

通用原则：Git 里 99% 的"丢失"都能用 git reflog + git fsck 找回；剩下 1% 是"从未 commit / 从未 push"，只能靠备份习惯预防。

一套可直接落地的团队 Git 规范

以下是本篇的浓缩，可以直接贴进团队 Wiki：

分支

main 永远可发布，受保护，禁止直推、禁止 force push
功能分支命名：/<简述>，如 feat/sms-login、fix/pay-timeout
功能分支活不过 3 天，合并后删除

提交

遵循 Conventional Commits，commitlint 强制
一次提交做一件事；wip、tmp 类提交合并前必须 squash
开启 SSH 提交签名

同步

每天开工先 git rebase origin/main（功能分支上）
每天至少 push 一次
公共分支只用 merge，功能分支同步用 rebase，永不 rebase 公共历史

评审

一切代码经 PR 合入 main，CI 通过 + 至少 1 人 approve
PR 保持小：≤400 行变更为佳，大了拆

发布

tag 遵循 semver，由 release-please 自动生成
线上 bug 走 hotfix/* 分支，修完同时回合 main

安全

pre-commit 跑 gitleaks，服务端开 Push Protection
密钥泄漏 = 立即轮换，其次才是清历史

终极速查表

场景	方案
大仓库克隆	`--filter=blob:none` + sparse-checkout
提交规范	Conventional Commits + commitlint
自动发版	release-please / semantic-release
构建版本号	`git describe --tags --always --dirty`
提交防伪	SSH 签名 + 平台 Verified
密钥扫描	gitleaks（本地）+ Push Protection（服务端）
密钥泄漏	轮换密钥 → filter-repo 清历史 → 全员重克隆
误删/覆盖找回	`git reflog` → `reset --hard` / 强推恢复
仓库损坏	`git fsck` 诊断，重新克隆
协作红线	保护 main、禁 force push、一切走 PR

系列回顾

初级篇：四个区域、三板斧、远程同步——能用
中级篇：分支模型、merge/rebase、reflog——用得对
高级篇：对象模型、bisect、worktree、submodule、LFS——懂原理
终极篇：工程化、安全、SOP、团队规范——成体系

Git 的学习曲线不在命令数量，而在心智模型。四篇读完，剩下的就是每天在真实项目里踩坑、翻 reflog、读 graph——祝你的每一次 git push 都心安理得。

Git 使用手册 · 高级篇：原理、调试与仓库工程

Sat, 22 Aug 2026 23:23:00 +0800

这是 Git 手册系列的第三篇。前两篇讲"怎么用"，本篇讲"为什么"：理解了 Git 的内部模型，所有命令都会变成推理题而非背诵题；再配上一批工程化工具，解决"什么时候出的 bug"、“仓库太大”、“多仓库依赖"这类真实难题。

Git 对象模型：blob、tree、commit、tag
引用：分支、HEAD、tag 都只是指针
彻底理解 merge / rebase / cherry-pick
bisect：二分查找"哪次提交引入了 bug”
worktree：一个仓库多个工作区
submodule 与 subtree：仓库套仓库
hooks：在关键时刻自动执行脚本
Git LFS 与大文件
仓库瘦身：清理历史中的大文件
高级调试与诊断

Git 对象模型：blob、tree、commit、tag

Git 本质是一个内容寻址的文件系统 + 一个版本控制外壳。.git/objects/ 下只有四种对象：

对象	内容	类比
blob	文件的内容（不含文件名）	文件快照
tree	一个目录：文件名 → blob/tree 的指针列表	文件夹快照
commit	指向一个 tree + 父 commit 指针 + 作者/时间/信息	一次版本
tag（附注）	指向一个 commit + 标签信息	里程碑

所有对象用内容算 SHA-1（新版支持 SHA-256）哈希作为 id：内容相同 → id 相同，这就是 Git 去重和完整性校验的原理。

一次提交的结构示意：

commit a1b2c3d
├── tree     e4f5g6h          ← 项目根目录快照
│   ├── src/        → tree ...
│   ├── README.md   → blob ...
│   └── package.json→ blob ...
├── parent   9i0j1k2          ← 上一次提交
├── author   heyaohua <...> 1700000000 +0800
└── message  修复登录页按钮错位

自己动手看一眼（plumbing 命令）：

git cat-file -t a1b2c3d    # 对象类型：commit
git cat-file -p a1b2c3d    # 打印内容
git cat-file -p HEAD^{tree} # 当前提交的根 tree

关键推论：

“快照"其实很省空间：没改的文件，新 tree 直接复用旧 blob 指针。
commit 是不可变的：任何修改历史（amend/rebase）都是生成新对象，旧的靠 reflog 留着。

引用：分支、HEAD、tag 都只是指针

.git/refs/ 和 .git/HEAD 揭开了分支的全部秘密：

分支：一个文件，内容就是某个 commit 的哈希。git switch -c foo 就是写了一个 41 字节的文件——所以 Git 开分支快到零成本。
HEAD：一个文件，内容是"当前指向哪个分支”（如 ref: refs/heads/main）。
detached HEAD：HEAD 直接指向 commit 而不是分支（如 git switch a1b2c3d）。此时提交的改动没有分支名挂着，切走后会变成"孤儿"，解法是立刻 git switch -c rescue 给它安个分支名。
远程跟踪分支 origin/main：也是本地的一个指针，记录"上次和远程同步时远程在哪"，只有 fetch/pull/push 时才更新。

合并提交 = 有两个 parent 的 commit。fast-forward 合并 = 只是把分支指针往前挪，不产生新 commit。

git log --oneline --graph --all    # 现在你应该能完全读懂这张图了
git rev-parse HEAD main origin/main  # 看各引用实际指向的哈希

彻底理解 merge / rebase / cherry-pick

有了对象模型，三者的区别一句话说清：

merge：新建一个双 parent 的 commit，tree 取三方合并（base、我方、对方）的结果。
rebase：把每条提交的 diff 依次"重放"到新 base 上，生成一串新 commit（旧提交还在，靠 reflog 可见）。
cherry-pick：等价于对单条提交做一次 rebase——算出它的 diff，重放到当前 HEAD。

所以"rebase 会改历史"的准确说法是：commit id（哈希）会变，因为 parent 变了 → 内容变了 → 哈希变了。这也是为什么不能 rebase 公共分支：别人手里还是旧 id，你们的对象图从此分叉。

bisect：二分查找"哪次提交引入了 bug"

场景：线上报 bug，上次发版还是好的，中间隔了 200 条提交，不知道哪次改坏了。人肉翻要半天，bisect 用二分查找只要约 8 步（log₂200 ≈ 7.6）。

git bisect start
git bisect bad                 # 当前版本是坏的
git bisect good v1.2.0         # 上次发版是好的

# Git 自动 checkout 到中间的提交，你测试后回答：
git bisect good   # 或 git bisect bad
# …重复几轮…

git bisect reset   # 结束后回到原分支

最后 Git 会告诉你：a1b2c3d is the first bad commit。

自动化 bisect——有现成测试脚本时全程不用动手：

git bisect start HEAD v1.2.0
git bisect run npm test        # 退出码非 0 即 bad
git bisect reset

worktree：一个仓库多个工作区

场景：正在 feature 分支开发到一半（一堆未提交改动），需要紧急在 main 上验证一个问题。stash 来回倒腾很烦，worktree 直接给仓库开第二个目录：

git worktree add ../my-project-hotfix main   # 在旁边目录开一个 main 的工作区
cd ../my-project-hotfix                      # 独立目录，独立工作区，共享 .git
# …修 bug、提交、push…

cd ../my-project
git worktree remove ../my-project-hotfix     # 用完删掉
git worktree list

注意：同一分支不能同时被两个 worktree 检出。这也是 Code Review 时快速跑别人 PR 的利器。

submodule 与 subtree：仓库套仓库

submodule：嵌一个独立仓库的固定版本

git submodule add https://github.com/org/shared-lib.git vendor/shared-lib
git commit -m "引入 shared-lib 子模块"

主仓库存的只是"子模块的仓库地址 + commit id"。克隆含子模块的项目：

git clone --recurse-submodules 
# 或事后补：
git submodule update --init --recursive

更新子模块：

cd vendor/shared-lib && git pull origin main && cd -
git add vendor/shared-lib && git commit -m "升级 shared-lib"

痛点：每个协作者都要记得 --recurse-submodules，子模块内部的修改提交流程也绕。适合：外部依赖、发布节奏完全独立的组件。

subtree：把另一个仓库的内容直接并入

git subtree add --prefix vendor/shared-lib https://github.com/org/shared-lib.git main --squash
git subtree pull --prefix vendor/shared-lib https://github.com/org/shared-lib.git main --squash

对协作者完全透明（就是一个普通目录），但拉取更新稍慢、命令冗长。适合：想 vendoring 一份代码且偶尔同步上游。

选择建议：依赖关系强、需要锁版本 → submodule；只想拷一份进来偶尔同步 → subtree；能走包管理器（npm/pip/go mod）的一律别用这两个。

hooks：在关键时刻自动执行脚本

.git/hooks/ 里的可执行脚本会在对应时机触发。常用：

hook	时机	典型用途
`pre-commit`	提交前	lint、格式化、跑单测
`commit-msg`	提交信息生成后	校验 message 格式（conventional commits）
`pre-push`	推送前	跑完整测试套件
`post-merge`	合并后	检测 package.json 变了就提醒装依赖

示例 pre-commit：

#!/bin/sh
npm run lint-staged || exit 1

实践中不要手写裸 hook，用 husky（Node 项目）或 pre-commit 框架（Python/多语言）管理，它们把 hooks 纳入版本库、团队共享：

pnpm add -D husky lint-staged
npx husky init
echo "pnpm lint-staged" > .husky/pre-commit

Git LFS 与大文件

Git 对二进制的差量存储很差，一个 100MB 的 PSD 改 10 次，仓库就胖 1GB。Git LFS（Large File Storage）把大文件内容存到专门服务器，仓库里只留指针：

git lfs install
git lfs track "*.psd" "*.zip" "assets/videos/**"
git add .gitattributes        # 必须提交，团队才会共享规则
git add design.psd && git commit -m "添加设计稿"

注意：LFS 只对新提交生效；历史里已有的大家伙要用下节的方法清理。另外 LFS 服务器（GitHub 等）有流量配额，重度使用前先算账。

仓库瘦身：清理历史中的大文件

场景：早期误提交了构建产物 / 视频，仓库 clone 要 10 分钟。目标是改写全部历史，把大文件从每个 commit 里抠掉。

推荐工具 git-filter-repo（官方推荐的第三方工具，替代已废弃的 filter-branch）：

pip install git-filter-repo

# 按路径删除（历史上所有提交）
git filter-repo --path dist/ --invert-paths

# 按大小：干掉所有超过 50M 的 blob
git filter-repo --strip-blobs-bigger-than 50M

⚠️ 这是破坏性重写历史：

操作前全量备份（cp -r 或推一个备份 remote）。
所有协作者必须重新克隆，旧本地仓库作废。
推送用 git push --force 全分支全标签。
如果只是为了去掉误提交的密钥，改完历史后密钥照样要换——它可能已经泄露。

查一下仓库里最占空间的历史对象：

git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '/^blob/ {print substr($0,6)}' | sort -k2 -n | tail -20

高级调试与诊断

# 仓库统计与磁盘占用
git count-objects -vH

# 某行代码的演化史：谁在什么时候为什么改的
git log -L 10,20:src/app.js        # 跟踪文件第 10-20 行的变更历史
git log -S "functionName"           # 找"某段字符串被增删"的提交（pickaxe）
git log -G "regex"                  # 按正则找 diff 内容变化的提交

# 分支拓扑
git log --graph --oneline --all --decorate
git branch --contains       # 哪些分支包含这个提交（修没修进发布版？）
git branch --no-merged main         # 还没合并进 main 的分支

# 比较
git diff main...feature/xxx         # 三点：feature 从 main 分叉后引入的改动
git range-diff main..old main..new  # 比较 rebase 前后两个提交序列的差异

# 数据完整性
git fsck                            # 检查对象库损坏 / 悬空对象

-S（pickaxe）是排查"这行代码什么时候没的"的终极武器，配合 --reverse 还能看一段逻辑从出生到现在的完整演化。

本篇速查表

目的	命令
看对象内容	`git cat-file -p`
看引用指向	`git rev-parse`
二分排错	`git bisect start/bad/good/run`
多工作区	`git worktree add`
子模块	`git submodule update --init --recursive`
并入外部仓库	`git subtree pull --prefix=... --squash`
提交前自动化	husky / pre-commit 框架
大文件	`git lfs track "*.bin"`
历史瘦身	`git filter-repo --invert-paths --path ...`
找代码何时被删	`git log -S "..."`
检查仓库健康	`git fsck` / `git count-objects -vH`

到这里，Git 对你已经没有黑盒了。下一篇《终极篇》转向工程之巅：monorepo 策略、安全合规（签名提交、密钥扫描）、CI/CD 中的 Git 技巧、灾难恢复 SOP，以及一套可以直接落地的团队 Git 规范。

Git 使用手册 · 中级篇：分支协作、冲突与历史修改

Sat, 22 Aug 2026 23:22:00 +0800

这是 Git 手册系列的第二篇。初级篇解决了"能用"，本篇解决"用得对"：多人协作不打架、冲突不慌、历史能改得干净。

分支模型：选一个然后坚持

个人 / 小团队：Trunk-Based（主干开发）

main 是唯一长期分支，随时可发布
功能分支从 main 切出，活 1~3 天，合并后立即删除
配合 PR/MR 做代码评审

git switch -c feature/xxx main
# 开发、提交
git push -u origin feature/xxx   # 提 PR，评审通过后合并
git switch main && git pull
git branch -d feature/xxx

需要同时维护多个发布版本：Git Flow

main：线上版本；develop：集成分支
feature/*、release/*、hotfix/* 各司其职
重，只有确实需要多版本并行（如 SaaS + 私有化部署）才用

结论：90% 的团队用 Trunk-Based 就够了。分支模型越简单，协作成本越低。

merge 与 rebase：到底用哪个

两者都用来"把 B 分支的改动合进 A 分支"，区别在于历史形态：

merge（保留真实历史，产生合并提交）：
main:   A---B-------M
              \   /
feature:       C---D

rebase（把 feature 的提交"搬家"到 main 最新处，历史成一条直线）：
main:   A---B
feature:         C'--D'   （C、D 被重放为新提交）

经验法则：

公共分支（main、develop）上用 merge，保留协作痕迹。
自己的功能分支同步 main 最新代码时用 rebase，保持历史干净：

git switch feature/xxx
git fetch origin
git rebase origin/main      # 解决冲突后 git rebase --continue

⚠️ 黄金规则：永远不要 rebase 已经 push 且别人在用的分支。rebase 会改写提交 id，别人的本地历史会对不上。

冲突的正确解法

冲突的本质：同一文件的同一区域，两边都改了，Git 不知道该听谁的。

git merge feature/xxx
# CONFLICT (content): Merge conflict in src/app.js

处理流程：

git status                 # 1. 看哪些文件冲突

打开冲突文件，会看到标记：

<<<<<<< HEAD
const timeout = 3000;
=======
const timeout = 5000;
>>>>>>> feature/xxx

<<<<<<< HEAD 到 ======= 是当前分支的内容，======= 到 >>>>>>> 是合入方的内容。手动编辑成正确结果，删掉标记：

const timeout = 5000;

然后：

git add src/app.js         # 2. 标记为已解决
git commit                 # 3. 完成合并提交

中途想放弃：git merge --abort（rebase 对应 git rebase --abort），一切回到合并前。

降低冲突概率的三个习惯：

功能分支短命，尽快合并
开始干活前先 git pull / git rebase origin/main
公共文件（配置文件、路由表）的改动尽早沟通

reset 的三种模式（soft / mixed / hard）

git reset 把 HEAD 移动到某个提交，三种模式决定"工作区和暂存区怎么办"：

模式	提交历史	暂存区	工作区
`--soft`	回退	保留	保留
`--mixed`（默认）	回退	清空	保留
`--hard`	回退	清空	清空

git reset --soft HEAD~1      # 撤销上次提交，改动还在暂存区（改提交内容用）
git reset HEAD~1             # 撤销上次提交，改动回到工作区（重新组织提交用）
git reset --hard HEAD~1      # 撤销上次提交，改动全部丢弃（危险！）

HEAD~1 表示"上一条提交"，HEAD~3 表示往前数 3 条。

安全准则：--hard 之前先 git stash 或确认改动有备份；只 reset 还没 push 的提交。

stash：临时收摊子

场景：正在 feature 分支改一半，线上突然有 bug 要你切分支修。

git stash                    # 把未提交的改动收起来，工作区变干净
git switch hotfix/urgent     # 去修 bug
# …修完、提交…
git switch feature/xxx       # 回来
git stash pop                # 恢复刚才收起的改动

常用操作：

git stash list               # 看有几个 stash
git stash show -p            # 看最近一次 stash 的内容
git stash push -m "登录页改了一半"   # 带备注存
git stash apply stash@{1}    # 恢复指定的（pop 会删掉，apply 保留）
git stash drop stash@{0}     # 删除

cherry-pick：挑一个提交带走

场景：在 develop 上修的一个 bug，main 上也需要，但不想合并整个 develop。

git log --oneline develop        # 找到那个提交的 id，比如 a1b2c3d
git switch main
git cherry-pick a1b2c3d          # 把它复制过来（生成新提交 id）

可以连续挑多个：git cherry-pick A B C，或挑一个区间 git cherry-pick A..B（不含 A）。

修改历史：amend 与交互式 rebase

amend：修补最近一次提交

# 刚提交完发现漏了个文件 / 提交信息写错了
git add forgotten.js
git commit --amend               # 编辑器里顺便改 message
git commit --amend --no-edit     # 只补内容不改 message

交互式 rebase：整理最近 N 条提交

git rebase -i HEAD~4

编辑器里列出最近 4 条提交，把每行开头的 pick 改成：

指令	作用
`pick`	保留这条提交
`reword`	保留，但改提交信息
`squash`	合并进上一条（保留两条的信息供编辑）
`fixup`	合并进上一条（丢弃本条信息）
`drop`	删除这条提交

典型场景：PR 之前把 修复 typo、再改一下、真的改好了 这类碎提交压成一条干净的。

⚠️ 同样的黄金规则：只改写未 push 的历史。如果已 push 且确认只有自己在用，改写后需要 git push --force-with-lease（比 --force 安全：远程有别人新提交时会拒绝）。

reflog：你的后悔药

几乎所有"我完了"的瞬间，git reflog 都能救：

git reflog

a1b2c3d HEAD@{0}: reset: moving to HEAD~1      ← 手滑的操作
e4f5g6h HEAD@{1}: commit: 重要的提交            ← 以为丢了的提交

reflog 记录 HEAD 的每一次移动（commit、reset、rebase、切换分支……），保留约 90 天。找回方式：

git reset --hard e4f5g6h     # 直接回到那个状态
# 或
git branch rescue e4f5g6h    # 开个分支把那个提交捞回来

只要不是 git clean 删掉的未跟踪新文件，Git 里几乎没有真正丢失的提交。

tag 与发布

git tag v1.2.0                   # 轻量标签
git tag -a v1.2.0 -m "发布 1.2.0：新增支付模块"   # 附注标签（推荐）
git push origin v1.2.0           # 推送单个标签
git push --tags                  # 推送所有标签
git tag -d v1.2.0                # 删本地
git push origin :v1.2.0          # 删远程

版本号遵循语义化版本 主.次.修（semver）：破坏性变更升主版本，新功能升次版本，修 bug 升修订号。

中级常见错误

1. 在公共分支上 rebase / amend 了已 push 的提交 队友 pull 时会历史错乱。解：公共分支只用 merge；改写前先确认没有别人基于它工作。

2. 解决冲突时直接用"接受我方/接受对方"整文件覆盖 可能把别人无关的改动一起吞掉。逐块（hunk）检查。

3. git reset --hard 之后发现误删了改动 先别慌，git reflog 找回。养成 hard 之前 git stash 的习惯。

4. stash 堆成山从来不清理 git stash list 定期看一眼，用完就 pop/drop。

5. cherry-pick 之后又 merge 原分支，出现重复改动 偶尔会发生，合并时 Git 通常能识别；冲突了耐心解一次即可。

本篇速查表

目的	命令
同步 main 到功能分支	`git rebase origin/main`
放弃合并	`git merge --abort`
撤销提交保留改动	`git reset --soft/--mixed HEAD~1`
彻底回退（危险）	`git reset --hard`
暂存半成品	`git stash` / `git stash pop`
复制单个提交	`git cherry-pick`
改最近提交	`git commit --amend`
整理历史	`git rebase -i HEAD~n`
找回丢失提交	`git reflog`
安全强推	`git push --force-with-lease`
打标签	`git tag -a v1.0.0 -m "..."`

到这一层，你已经能应付团队协作的全部日常。下一篇《高级篇》进入 Git 的内部世界：对象模型、引用、HEAD 的本质、bisect 二分排错、worktree、submodule/subtree 与钩子——理解了"为什么"，命令就再也背不丢。

Git 使用手册 · 初级篇：从第一次提交开始

Sat, 22 Aug 2026 23:21:00 +0800

这是 Git 手册系列的第一篇。目标只有一个：让你今天就能用 Git 管好自己的代码，并且知道每条命令在干什么。不理解原理没关系，先把工作流跑通。

Git 是什么，解决什么问题
安装与初始配置
四个区域：工作区、暂存区、本地仓库、远程仓库
第一次提交
日常三板斧：status / add / commit
查看历史
撤销与回退（安全版）
连接远程仓库（GitHub / GitLab）
分支是什么（先会用最基础的）
初级常见错误

Git 是什么，解决什么问题

没有 Git 的时候，你是这样管理代码的：

project/
project-final/
project-final-v2/
project-final-v2-真的最终版/

Git 做的事：把项目的每一次修改记录成"快照"（commit），你可以随时查看任何历史版本、回到任何历史版本、同时维护多条并行的修改线（分支），并和别人协作而互不覆盖。

安装与初始配置

# macOS
brew install git

# Ubuntu / Debian
sudo apt install git

# Windows：安装 Git for Windows（自带 Git Bash）

第一次使用必须先配置身份，否则提交会带上机器默认的匿名信息：

git config --global user.name "你的名字"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

验证：

git config --list

四个区域：工作区、暂存区、本地仓库、远程仓库

这是理解 Git 所有命令的钥匙：

工作区          暂存区          本地仓库          远程仓库
(working dir)   (staging)      (repository)     (remote)
    |               |               |                |
    |  git add  →   |  git commit → |  git push  →   |
    |               |               |                |
    |  ← checkout   |  ← reset      |  ← git pull    |

工作区：你正在编辑的文件
暂存区：下一次提交要包含的内容（一个"待打包区"）
本地仓库：已经提交的历史快照
远程仓库：GitHub / GitLab / 自建服务器上的副本

为什么要多一个暂存区？因为你可以改 10 个文件，但只把其中 3 个相关的改动打成一次干净的提交。

第一次提交

# 在项目目录初始化仓库
cd my-project
git init

# 查看状态（最重要的命令，有事没事敲一下）
git status

# 把文件放进暂存区
git add README.md        # 单个文件
git add .                # 所有变更（初级可以先这样用）

# 提交到本地仓库
git commit -m "初始化项目：添加 README"

提交信息（commit message）的约定：一句话说清"做了什么"，用动词开头。例如 修复登录页按钮错位、新增用户注册接口。不要写 update、fix、123。

.gitignore：告诉 Git 别管某些文件

# 依赖与构建产物
node_modules/
dist/
*.log

# 环境与密钥（永远不要提交）
.env
*.pem

# 系统文件
.DS_Store

新建仓库第一件事就是写 .gitignore。如果已经把 node_modules 提交了，用 git rm -r --cached node_modules 把它移出版本库再提交。

日常三板斧：status / add / commit

你的日常循环就是：

git status                    # 现在有哪些改动？哪些已暂存？
git add                 # 挑选改动放入暂存区
git commit -m "做了什么"      # 打包成一次快照

辅助命令：

git diff                      # 工作区 vs 暂存区：还没 add 的改动细节
git diff --staged             # 暂存区 vs 上次提交：这次将要提交什么

提交频率建议：完成一个"说得清的小目标"就提交一次。一天 3~10 次提交很正常；一周一次提交等于没用 Git。

查看历史

git log                       # 完整历史
git log --oneline             # 一行一条，最常用
git log --oneline --graph     # 带分支图形
git show           # 看某次提交的具体改动
git blame               # 文件每一行是谁在哪次提交写的

每次提交有一个 40 位的哈希 id，平时用前 7 位即可指代（如 a1b2c3d）。

撤销与回退（安全版）

初级只需要记住三句，按"还没提交到哪一步"选：

# 1. 改了文件但还没 add：丢弃工作区修改
git restore 

# 2. 已经 add 但还没 commit：退回暂存区（改动保留在工作区）
git restore --staged 

# 3. 已经 commit：再提交一次"反向提交"来撤销，不改历史，最安全
git revert

⚠️ git reset --hard 和 git push --force 会永久丢数据或改写共享历史，初级阶段先别碰，等中级篇再学。

连接远程仓库（GitHub / GitLab）

情形 A：本地已有项目，推到新建的远程仓库

在 GitHub 上创建一个空仓库（不要勾选初始化 README），然后：

git remote add origin git@github.com:yourname/my-project.git
git branch -M main
git push -u origin main

情形 B：从远程克隆一个已有项目

git clone git@github.com:someone/some-project.git
cd some-project

日常同步

git pull        # 拉取远程最新提交并合并到本地
git push        # 推送本地提交到远程

认证推荐配置 SSH key（ssh-keygen 生成后把公钥贴到 GitHub 设置里），一次配置永久免密。

分支是什么（先会用最基础的）

分支 = 一条独立的修改线，互不影响。默认分支是 main。

git branch                      # 列出本地分支
git switch -c feature-login     # 新建并切换到新分支
git switch main                 # 切回 main

典型用法：

git switch -c fix-button        # 开分支做修复
# …改代码、add、commit…
git switch main                 # 回主线
git merge fix-button            # 把修复合并进来
git branch -d fix-button        # 删掉用完的分支
git push                        # 同步到远程

初级记住一个原则：永远别直接在 main 上干活，做任何改动都先开分支。合并冲突暂时不用怕，中级篇会专门讲。

初级常见错误

1. 提交信息写 “update” 一个月后你自己都不知道这次提交干了什么。写具体点。

2. 把 .env、密钥提交了 先 git rm --cached .env 移除并写进 .gitignore。注意：历史里还有，密钥必须立即更换。

3. 在错误的目录 git init 比如在家目录 ~ 下执行了 init。删掉误建的 .git 目录即可：rm -rf ~/.git（确认路径后再执行）。

4. pull 下来一堆冲突，慌了 冲突不是错误，是 Git 在问你"两边都改了，听谁的"。先 git status 看哪些文件冲突，打开文件找 <<<<<<< 标记，手动改对后 add + commit。

5. 半年不 push 本地仓库丢了硬盘就没了。每天至少 push 一次。

本篇速查表

目的	命令
初始化	`git init`
看状态	`git status`
暂存	`git add`
提交	`git commit -m "..."`
看历史	`git log --oneline`
撤销未暂存修改	`git restore`
撤销已暂存	`git restore --staged`
安全撤销某次提交	`git revert`
克隆	`git clone`
拉取 / 推送	`git pull` / `git push`
开分支	`git switch -c`
合并	`git merge`

掌握这些，你已经覆盖了个人项目 90% 的场景。下一篇《中级篇》讲分支协作模型、合并冲突的正确解法、stash、reset 的三种模式和 rebase 入门——也就是从"会用"到"用得对"。