Git 版本控制专题详解 - 学习笔记-Claude Code-上海佼艾

一、Git 概述与发展历史

1.1 Git 的诞生

Git 由 Linux 创始人 Linus Torvalds 于 2005 年创建。当时 Linux 内核开发团队使用的商业版本控制系统 BitKeeper 收回了免费使用授权，Linus 决定开发一个全新的版本控制系统。他用了大约 10 天时间完成了 Git 的第一个版本，并在两周内开始将其用于 Linux 内核的日常开发。Git 的设计目标非常明确：速度快、设计简单、支持非线性开发（大量并行分支）、完全分布式、能够高效处理超大规模项目（如 Linux 内核）。

为什么 Git 如此成功？Git 的设计哲学是"信任"而非"控制"——每个开发者本地都有完整的仓库副本，不依赖中央服务器。这让 Git 比 SVN、CVS 等集中式版本控制系统更灵活、更快速。Git 中的数据存储方式（内容寻址的文件系统）保证了数据的完整性，任何数据损坏都能被立刻检测出来。

1.2 Git 与其它 VCS 的对比

特性	Git	SVN	Mercurial
架构	分布式	集中式	分布式
离线操作	完全支持	有限	完全支持
分支成本	极低（指针）	高（目录复制）	低
数据完整性	SHA-1 校验	无内置校验	SHA-1 校验
暂存区	有	无	无
学习曲线	较陡	平缓	中等

Git 的分支成本极低（只是一个 41 字节的指针文件），这使其分支操作几乎是瞬时完成的，这是 Git 相对于其他 VCS 的最显著优势。这也催生了 Git Flow、GitHub Flow 等基于分支的协作模式，从根本上改变了现代软件开发的工作方式。

二、Git 核心概念深入理解

2.1 三个区域与三种状态

Git 的核心模型可以用"三个区域"和"三种状态"来概括。理解这个模型是掌握 Git 的钥匙。

三个区域

工作区（Working Directory）：你电脑上实际看到的文件目录。你在编辑器中打开、修改的文件都在工作区中。工作区中的文件不一定是 Git 关心的对象。

暂存区（Staging Area / Index）：一个位于 .git/index 的文件，记录了下次提交将要包含的文件信息。你可以把它理解为"提交预检区"——把准备要提交的修改先放在这里，确认无误后再一次性提交。

仓库（Repository / .git 目录）：Git 用来存储项目元数据和对象数据库的地方。当你执行 git commit 时，暂存区中的内容就被永久保存到了仓库中。仓库中存储的是不可修改的"快照"。

三种状态

已修改（Modified）：文件在工作区中被修改了，但还没有添加到暂存区。此时 Git 知道"文件变了"，但不会将其纳入提交范围。

已暂存（Staged）：修改后的文件被添加到了暂存区，准备在下一次提交时被保存到仓库中。这是你对"我要提交这些修改"的明确声明。

已提交（Committed）：暂存区的数据已经被安全地保存到了 Git 仓库中。一旦提交，如果你不主动删除，这个版本几乎永久存在。

这三个区域和三种状态对应着 Git 的核心工作流程：在工作区修改文件 → 将修改暂存到暂存区 → 将暂存区的内容提交到仓库。每次 git add 就是从"已修改"到"已暂存"，每次 git commit 就是从"已暂存"到"已提交"。理解了这个流程，你就理解了 Git 80% 的操作。

2.2 Git 对象模型

Git 本质上是一个内容寻址的文件系统。Git 的核心是一个键值对数据库：键是内容的 SHA-1 哈希值，值就是内容本身。Git 中有四种类型的对象：

Blob（二进制大对象）：存储文件的内容。每个文件版本对应一个 Blob 对象。Blob 对象不包含文件名信息，只存储文件数据。
Tree（树对象）：存储目录结构和文件名。一个 Tree 对象包含若干条目，每个条目指向一个 Blob（文件）或另一个 Tree（子目录），并包含文件名、文件模式等信息。
Commit（提交对象）：存储一次提交的快照。每个 Commit 对象包含指向一个 Tree 对象的指针（表示项目根目录的快照）、作者和提交者信息、提交信息、以及父 Commit 的指针（多个父 Commit 表示合并提交）。
Tag（标签对象）：存储一个固定的引用，通常用于标记发布版本。Annotated Tag 包含标签名、标签信息、签名等信息。

# 查看 Git 对象库中的内容

# 查看某个提交的完整内容
git cat-file -p a1b2c3d

# 查看对象的类型
git cat-file -t a1b2c3d
# 输出: commit

# 查看某个提交对应的树对象
git ls-tree -r a1b2c3d
# 输出: 100644 blob 8baef1b    README.md

理解 Git 对象模型的意义：当你理解了 Commit → Tree → Blob 的层级关系，你就明白为什么 Git 能如此高效。每次提交只是创建一个新的 Commit 对象和变化文件的 Tree/Blob 对象，未变化的文件直接复用已有对象。这就是为什么 Git 切换分支、查看历史、计算差异都极其快速的原因。

2.3 引用（References）

引用（refs）是 Git 中用来指代特定提交的"友好名称"。它们存放在 .git/refs/ 目录下。主要的引用类型包括：

分支（Branch）：指向某个提交的可移动指针。当你进行新的提交时，当前分支的指针会自动前移。分支位于 .git/refs/heads/ 下。
标签（Tag）：指向某个提交的固定指针。创建标签后，它永远指向同一个提交。标签位于 .git/refs/tags/ 下。
HEAD：一个特殊指针，指向当前所在的分支（或直接指向某个提交，即"分离头指针"状态）。HEAD 的内容通常是一个文件，其中写着 ref: refs/heads/main。
远程引用（Remote Ref）：记录远程仓库分支的状态。位于 .git/refs/remotes/ 下。例如 origin/main 记录了远程 main 分支在你最后一次 git fetch 时的位置。

# 查看 HEAD 指向
cat .git/HEAD
# 输出: ref: refs/heads/main

# 查看某个分支指向的提交
cat .git/refs/heads/main
# 输出: a1b2c3d4e5f6g7h8i9j0...

# 使用 git 命令查看引用信息
git rev-parse HEAD
git rev-parse main
git rev-parse origin/main

三、Git 常用命令精讲

3.1 配置与初始化

# 全局配置（一次配置，全局生效）
git config --global user.name "你的名字"
git config --global user.email "your@email.com"

# 查看配置
git config --list
git config user.name

# 实用配置推荐
# 设置默认分支名为 main
git config --global init.defaultBranch main

# 启用颜色输出
git config --global color.ui auto

# 设置别名（极大提升效率）
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all"

# 之后就可以使用 git st 代替 git status

推荐配置：Git 别名

Git 别名可以大幅提升日常操作效率。建议设置 git lg 别名（上面的 log --oneline --graph --all），它用图形方式展示提交历史和分支关系，非常直观。使用后你会爱上这个命令。

3.2 查看与比较

# git show -- 查看提交详情
git show a1b2c3d       # 查看某次提交的变更内容
git show HEAD           # 查看最新提交的变更内容
git show HEAD~3         # 查看倒数第三次提交

# git log 的高级用法
git log --author="张三"    # 按作者筛选
git log --since="2026-01-01"  # 按时间筛选
git log --grep="bug"     # 按提交信息关键词筛选
git log -p              # 显示每次提交的 diff
git log --stat          # 显示每次提交的统计信息
git log --follow README.md  # 跟踪文件的完整历史（包括重命名后）

# git blame -- 逐行追溯
git blame index.js       # 查看每行代码的最后修改者和提交
git blame -L 10,30 index.js  # 只看第10-30行的责任归属

# git shortlog -- 按作者汇总提交
git shortlog -sn        # 按提交数量排序的贡献者列表

3.3 撤销与恢复

Git 的撤销操作是初学者最容易混淆的部分。关键在于明确你要撤销的内容在哪个区域：工作区、暂存区还是仓库。

# 撤销工作区的修改（未 git add）
git restore index.js
# 传统等价命令: git checkout -- index.js

# 撤销暂存区的修改（已 git add，但不想提交了）
git restore --staged index.js
# 传统等价命令: git reset HEAD index.js

# 修改最近一次提交的提交信息
git commit --amend -m "新的提交信息"

# 将遗漏的文件加入最近一次提交
git add forgotten-file.js
git commit --amend --no-edit

# 回退到某个历史提交（保留修改在工作区）
git reset --soft HEAD~1    # 回退一次提交，修改保留在暂存区
git reset --mixed HEAD~1   # 回退一次提交，修改保留在工作区（默认）
git reset --hard HEAD~1    # 彻底回退，丢弃所有修改（谨慎使用！）

# git revert -- 通过创建新提交来撤销旧提交（推荐用于公共分支）
git revert a1b2c3d          # 创建新提交，撤销 a1b2c3d 的变更

⚠ 重要：reset 与 revert 的选择

git reset 会重写提交历史，适用于尚未推送到远程的本地分支。使用 --hard 时要极其谨慎，它会丢弃工作区的所有修改，无法恢复。

git revert 会创建新的提交来撤销旧提交，不会重写历史，适用于已推送到远程的公共分支（如 main）。团队协作中，永远不要对公共分支使用 git reset，而应使用 git revert。

3.4 远程操作深入

# git remote -- 远程仓库管理
git remote -v                # 列出所有远程仓库
git remote add upstream git@github.com:original/project.git  # 添加上游仓库
git remote remove origin     # 移除远程仓库

# git fetch -- 只下载远程数据，不合并
git fetch origin              # 下载所有远程分支的最新数据
git fetch --prune origin      # 下载并清理已删除的远程分支引用

# git pull 的两种模式
git pull --rebase origin main  # 推荐：rebase 方式拉取，保持历史线性
git pull --no-rebase origin main  # 默认：merge 方式拉取，可能产生合并提交

# git push 的完整用法
git push origin main           # 推送到远程 main 分支
git push origin --delete feature-xxx  # 删除远程分支
git push --tags                # 推送所有标签
git push --force-with-lease    # 安全地强制推送（比 --force 更安全）

安全提示：--force-with-lease 替代 --force

当你需要使用强制推送时，始终优先使用 --force-with-lease 而不是 --force。后者会无条件覆盖远程分支，可能导致他人的工作丢失。前者会检查远程分支是否已被他人更新，如果是则拒绝推送，给你一个检查的机会。这层"安全带"在团队协作中至关重要。

四、Git 分支策略与工作流

4.1 分支的本质

在 Git 中，分支本质上只是一个指向某个提交的可移动指针。当你执行 git branch feature-x 时，Git 只是在 .git/refs/heads/ 下创建了一个名为 feature-x 的文件，里面写着当前提交的哈希值。创建分支不会创建任何新的文件或目录，也不会复制任何数据。这就是 Git 分支操作"瞬间完成"的原因。

4.2 分支合并策略

Git 提供了多种合并策略，选择合适的策略对于维护清晰的项目历史至关重要。

# 1. 标准合并（创建合并提交）
git switch main
git merge feature-x
# 生成一个合并提交，有两个父提交

# 2. 快进合并（Fast-Forward）
git merge --ff-only feature-x
# 如果可能，直接移动指针而不创建合并提交；不可能则失败

# 3. Squash 合并（压缩合并）
git merge --squash feature-x
git commit -m "将 feature-x 的所有提交压缩为一个提交"
# 将 feature-x 上的所有更改合并为一个新的提交

# 4. Rebase 合并（变基合并）
git switch feature-x
git rebase main
git switch main
git merge feature-x
# 将 feature-x 的提交重新放在 main 的最新提交之后，然后快进合并

策略	历史特征	优点	缺点	适用场景
标准合并	保留分支拓扑	真实反映开发过程	历史可能混乱	公共分支、长期分支
快进合并	线性历史	历史简洁	丢失分支信息	短期分支、个人项目
Squash 合并	单次提交	极致简洁	丢失所有中间提交	功能开发完成时
Rebase 合并	线性、整洁	历史干净且保留粒度	改变提交哈希，不可用于公共分支	本地分支整理

4.3 Git Flow 工作流详解

Git Flow 是 2010 年由 Vincent Driessen 提出的经典分支模型，适用于有固定发布周期的项目。它定义了五种分支类型：

main：主分支，始终保持可发布的状态。每次合并到 main 都自动生成一个版本标签。
develop：开发分支，集成了所有已完成的功能。是日常开发的基础分支。
feature：功能分支，从 develop 分支创建，用于开发新功能。开发完成后合并回 develop。
release：发布分支，从 develop 分支创建，用于准备发布（bug 修复、版本号更新等）。准备就绪后合并到 main 和 develop。
hotfix：紧急修复分支，从 main 分支创建，用于修复生产环境的紧急问题。修复后合并到 main 和 develop。

Git Flow 的核心原则：每种分支都有明确的"生命周期"——从哪里来、做什么、回哪里去。main 代表"可发布"的状态，develop 代表"最新开发"的状态，feature 是"开发中"的状态，release 是"即将发布"的状态，hotfix 是"紧急修复"的状态。严格遵循这些约定，项目维护者看到分支名就知道它的用途和当前阶段。

4.4 GitHub Flow 实践

GitHub Flow 是 Git Flow 的简化版本，更适合持续部署的现代开发模式。它的规则非常简单：

main 分支中的任何代码都是可部署的
创建描述性的分支名来开展工作
在本地分支上频繁提交
定期推送同名分支到远程仓库
需要反馈或帮助时创建 Pull Request
在 PR 中持续迭代代码
PR 通过审查且通过 CI 检查后合并到 main
合并后立即部署

选择建议

对于大多数中小团队和持续部署的项目，GitHub Flow 是最佳选择——简单、灵活、高效。如果你的项目有严格的版本发布周期（如移动 App、企业软件），Git Flow 更合适。Trunk-Based Development 则适用于 CI/CD 极度成熟、追求极致效率的团队。不建议初学者一上来就照搬 Git Flow，建议从 GitHub Flow 开始，逐步根据团队需求调整。

五、Git 高级技巧

5.1 Git Rebase 深入

Rebase（变基）是 Git 最强大的功能之一，也是最容易引起困惑的操作。Rebase 的核心思想是：将一个分支上的提交"移植"到另一个分支的最新提交之上，从而形成一条线性的提交历史。

# 交互式 rebase（最常用的高级功能）
# 修改最近 3 次提交
git rebase -i HEAD~3

# 在交互式界面中可以执行的操作：
# pick    - 保留该提交（默认）
# reword  - 修改提交信息
# edit    - 修改提交内容
# squash  - 合并到上一个提交
# fixup   - 合并到上一个提交（丢弃提交信息）
# drop    - 删除该提交

# 实际场景：将多个细碎的提交压缩成一个
# 在 rebase -i 界面中：
# pick a1b2c3d 添加搜索功能-初步实现
# squash e5f6g7h 添加搜索功能-完善UI
# squash i9j0k1l 添加搜索功能-修复样式

⚠ Rebase 黄金法则

绝不要对已经推送到公共仓库的提交执行 rebase！Rebase 会改写提交的哈希值，如果别人已经基于你的旧提交工作了，rebase 会导致他们的仓库与远程仓库严重不一致。这条规则只有在你独自使用的分支上才可以打破。简单记忆：公共分支用 merge，私有分支用 rebase。

5.2 Cherry-Pick 精选手法

Cherry-pick 允许你将某个分支上的特定提交复制到当前分支。这在不合并整个分支却需要某个特定功能或修复的场景下非常有用。

# 将某个提交复制到当前分支
git cherry-pick a1b2c3d

# 复制多个提交
git cherry-pick a1b2c3d e5f6g7h

# 复制一系列提交（从^到）
git cherry-pick a1b2c3d..e5f6g7h

# 只添加更改，不自动创建提交
git cherry-pick -n a1b2c3d

# 实际场景：将热修复从 hotfix 分支同步到其他发布分支
git switch release-v2.0
git cherry-pick -x hotfix-commit-hash
# -x 参数会在提交信息中自动注明来源

5.3 Stash 临时存储

Stash 用于临时保存工作区的修改，让你在不提交的情况下切换到其他分支。

# 保存当前工作区的修改
git stash push -m "搜索功能开发中"

# 保存包括未跟踪的文件
git stash push -u -m "包含新文件"

# 查看所有 stash 列表
git stash list
# 输出:
# stash@{0}: On feature-search: 搜索功能开发中
# stash@{1}: On main: 临时修复

# 恢复最近的 stash 并删除记录
git stash pop

# 恢复指定的 stash
git stash apply stash@{1}

# 删除某个 stash
git stash drop stash@{1}

# 查看 stash 中的具体更改
git stash show -p stash@{0}

5.4 Bisect 二分查找

Bisect 是一个非常强大的排错工具，它通过二分查找法快速定位引入 bug 的提交。

# 开始 bisect 查找
git bisect start

# 标记当前提交为"有问题"
git bisect bad

# 标记某个历史提交为"没问题"（比如一周前的提交）
git bisect good v1.0.0

# Git 会签出中间的提交，让你测试
# 测试后标记：
git bisect good    # 如果当前提交没问题
git bisect bad     # 如果当前提交有问题

# 反复执行，Git 会在 log2(提交数) 步内找到第一个出问题的提交

# 也可以使用脚本自动运行：
git bisect start HEAD v1.0.0
git bisect run npm test
# 通过 npm test 的退出码自动判断 good/bad

# 查找结束后，结束 bisect
git bisect reset

Bisect 实战场景：生产环境中突然出现了一个 bug，但不知道是哪个改动引起的。已知一周前版本是正常的。使用 git bisect，假设有一周的提交记录（约 100 次提交），你只需要测试大约 7 次就能找出罪魁祸首。配合自动化测试脚本，整个过程可以完全自动化。

5.5 Submodule 子模块

子模块允许你在一个 Git 仓库中嵌入另一个 Git 仓库作为子目录。适用于依赖第三方库或共享模块的场景。

# 添加子模块
git submodule add git@github.com:library/lib.git lib/

# 克隆包含子模块的仓库
git clone --recurse-submodules git@github.com:project.git

# 更新所有子模块到最新提交
git submodule update --remote

# 子模块的注意事项：
# 主仓库只记录子模块的"固定提交哈希值"
# 子模块默认处于"分离头指针"状态
# 在子模块中修改代码后，需要先在子模块中提交，再在主仓库中提交

5.6 Reflog 操作日志

Reflog 记录了 Git 中所有引用（包括 HEAD、分支等）的移动历史。即使你丢失了提交（如误操作 reset），只要操作还在 reflog 中，就能恢复。

# 查看 HEAD 的移动历史
git reflog
# 输出:
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
# e5f6g7h HEAD@{1}: commit: 添加新功能
# i9j0k1l HEAD@{2}: pull origin main: Fast-forward

# 恢复误操作：假设你执行了 git reset --hard HEAD~1
# 想恢复被丢弃的提交
git reset --hard HEAD@{1}
# 或者基于 reflog 中的提交创建分支
git branch recover-branch HEAD@{1}

⚠ Reflog 是本地日志，有有效期

Reflog 是本地的操作日志，不会被推送到远程仓库。默认情况下，reflog 中的记录在 90 天后会被 Git 自动清理。如果你想要恢复一个更早的提交，需要查看 reflog 或使用 git fsck 查找悬挂对象。

六、Git 内部原理浅析

6.1 .git 目录结构

每个 Git 仓库的根目录下都有一个 .git 隐藏文件夹。理解这个目录的结构，就是理解 Git 的底层实现。

.git/
├── HEAD                 # 当前分支的引用
├── config               # 仓库级别的配置
├── description          # 仓库描述信息
├── index                # 暂存区文件
├── hooks/               # Git 钩子脚本
│   ├── pre-commit
│   ├── commit-msg
│   └── post-commit
├── objects/             # Git 对象数据库
│   ├── 01/              # 对象存储目录（按哈希前两个字符分片）
│   │   └── abcd...
│   ├── 23/
│   │   └── ef01...
│   ├── info/
│   └── pack/            # 压缩打包的对象
├── refs/                # 引用
│   ├── heads/           # 本地分支
│   │   ├── main
│   │   └── feature-x
│   ├── tags/            # 标签
│   │   └── v1.0.0
│   └── remotes/         # 远程分支引用
│       └── origin/
│           └── main
└── logs/                # Reflog 日志
    └── HEAD

6.2 数据压缩与 Pack 文件

Git 在存储大量对象时会进行压缩。初始时，每个对象都是一个单独的文件（松散对象，loose object）。当松散对象数量达到阈值时，Git 会自动执行 GC（垃圾回收），将松散对象打包成 Pack 文件并进行增量压缩。

# 手动触发 Git GC
git gc

# 查看仓库的磁盘使用情况
git count-objects -v
# 输出示例:
# count: 20             松散对象数量
# size: 2              松散对象占用的磁盘空间（KB）
# in-pack: 1234         Pack 文件中的对象数量
# packs: 3              Pack 文件数量
# size-pack: 468       Pack 文件的总大小（KB）
# prune-packable: 0    

# 检查 Git 对象的完整性和可达性
git fsck

6.3 Git 的三种合并策略

Git 在执行合并时会根据情况自动选择合适的策略：

Recursive（递归策略）：默认的合并策略。当有两个要合并的分支时使用。如果存在多个共同祖先，它会递归合并它们。
Octopus（八爪鱼策略）：用于同时合并多个分支。当你执行 git merge branch1 branch2 branch3 时使用。
Ours（我们的策略）：保留当前分支的所有内容，但记录合并历史。用于记录"我们决定不采用对方分支的更改"的决定。
Resolve（解决策略）：与 Recursive 类似但更快，只能合并两个分支。

大多数时候你不需要指定策略，Git 会自动选择。但了解这些策略有助于理解为什么某些合并会产生冲突，以及如何通过选择不同的策略来解决问题。

七、Git 最佳实践

7.1 提交信息规范

良好的提交信息是项目文档的重要组成部分。一份清晰的提交信息应该：

第一行是标题（不超过 50 个字符），用祈使句开头，如 "Add"、"Fix"、"Update"、"Remove"
空一行，然后写详细说明
详细说明解释"为什么"做这次修改，而不是"改了什么"
如有必要，关联 Issue 编号

# 好的提交信息示例
git commit -m "Fix: 修复用户登录后跳转不正确的问题

当用户使用 OAuth 登录后，系统未正确判断用户来源页面，
导致总是跳转到首页而非用户之前访问的页面。
通过记录 preLoginUrl 并在认证回调中读取该值来解决此问题。

Fixes #123"

提交信息约定俗成的前缀

推荐使用规范化前缀：feat:（新功能）、fix:（bug 修复）、docs:（文档）、style:（格式）、refactor:（重构）、test:（测试）、chore:（杂项）。这符合 Conventional Commits 规范，可以自动生成 CHANGELOG。

7.2 .gitignore 配置

.gitignore 文件告诉 Git 哪些文件不应该被跟踪。每个项目都应该有恰当的 .gitignore 配置。

# Node.js 项目典型的 .gitignore
node_modules/
.env
*.log
dist/
build/
.DS_Store
*.swp
*.swo
coverage/
.nyc_output/

# Python 项目
__pycache__/
*.pyc
*.pyo
.env
venv/
.venv/
dist/
*.egg-info/

# IDE 和编辑器
.idea/
.vscode/
*.sublime-project
*.sublime-workspace

.gitignore 核心原则：只忽略"生成的文件"和"敏感文件"，不忽略"项目本身的源代码"。不应忽略的有：配置文件模板（如 .env.example）、项目依赖清单（如 package.json）、构建脚本。通常你可以在 GitHub 的 gitignore 模板仓库中找到适合你项目的参考配置。

7.3 仓库管理建议

保持提交粒度适中：每次提交应该是"一个逻辑变更"，而不是"一天的工作量"。太粗的提交难以定位问题，太细的提交会导致历史杂乱。
不要提交敏感信息：API 密钥、密码、证书等永远不要提交到 Git 仓库。如果误提交了，立即撤销密钥并修改 .gitignore。仅仅从仓库中删除文件是不够的，因为历史中仍然存在。
定期清理：使用 git gc 优化仓库性能，删除不需要的本地分支和标签。
分支命名规范：feature/xxx、bugfix/xxx、hotfix/xxx、release/xxx。命名要能反映分支的用途。
保护 main 分支：在 GitHub 仓库设置中开启分支保护规则，禁止直接推送、要求 PR 审查、要求 CI 通过。

7.4 大文件管理

Git 不适合管理大文件（二进制文件、媒体资源等）。如果你需要在 Git 仓库中管理大文件，推荐使用 Git LFS（Large File Storage）。

# 安装 Git LFS
git lfs install

# 指定哪些文件类型使用 LFS 管理
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"

# 提交 .gitattributes（LFS 配置文件）
git add .gitattributes
git commit -m "配置 Git LFS"

# LFS 的原理：仓库中存储的是指向实际文件的指针，
# 实际文件存储在远程 LFS 服务器上

八、Git 常见问题与解决方案

8.1 误操作恢复

场景	解决方案	命令
误删了未提交的文件	从 Git 仓库恢复	`git restore 文件名`
add 了不该 add 的文件	取消暂存	`git restore --staged 文件名`
提交信息写错了	修改最近一次提交信息	`git commit --amend -m "新信息"`
漏提交了文件	补充到最近一次提交	`git add 文件 && git commit --amend --no-edit`
想要撤销某次提交	创建反向提交	`git revert 提交哈希`
误 reset --hard 丢失了提交	从 reflog 恢复	`git reset --hard HEAD@{n}`
误删了分支	从 reflog 重建	`git branch 分支名提交哈希`
想撤销某文件的修改	恢复到指定版本	`git checkout 提交哈希 -- 文件名`

8.2 合并冲突处理策略

遇到合并冲突时，按以下步骤处理：

保持冷静：冲突是 Git 的日常，不是异常情况。
查看哪些文件冲突：git status 会列出所有冲突文件。
打开冲突文件：搜索 <<<<<<< 标记，找到冲突区域。
理解冲突内容：每个冲突区域分为三部分——当前分支的修改（HEAD）、分隔线（=======）、被合并分支的修改（>>>>>>>）。
决定如何解决：选择保留当前版本、保留对方版本、手动编辑合并双方。
标记已解决：删除冲突标记，保存文件，执行 git add 文件名。
完成合并：所有冲突解决后，执行 git commit 完成合并。

# 使用外部工具解决冲突（推荐新手使用）
# 使用 VS Code 的合并编辑器
git mergetool --tool=vscode

# 使用 git checkout 直接选择某一方的版本
# 全部采用当前分支的版本
git checkout --ours -- 文件名
# 全部采用被合并分支的版本
git checkout --theirs -- 文件名

# 中止合并，回到合并前的状态
git merge --abort

8.3 其它常见问题

问题1：Git 提示"Please tell me who you are"

原因：未配置用户名和邮箱。

解决：执行 git config --global user.name "你的名字" 和 git config --global user.email "你的邮箱"。

问题2："You have divergent branches and need to specify how to reconcile them"

原因：本地和远程分支出现了分叉。

解决：执行 git pull --rebase 或 git pull --no-rebase 来合并远程更改。

问题3："Failed to push some refs"

原因：远程仓库有本地没有的提交。

解决：先 git pull 获取远程更新，解决冲突后再推送。或者，如果你确定要覆盖远程，使用 git push --force-with-lease（但不推荐对公共分支这样做）。

问题4："detached HEAD" 状态

原因：直接签出了某个提交而不是分支（如 git checkout a1b2c3d）。

解决：如果你只是想查看，直接切换回分支即可（git switch main）。如果你想基于此提交开始工作，创建一个新分支（git switch -c 新分支名）。

问题5：误提交了敏感信息到仓库

解决：使用 git filter-branch 或 BFG Repo-Cleaner 从整个历史中移除敏感文件。但更好的做法是：立即到对应平台（如 GitHub）撤销泄露的密钥/密码，然后清理仓库，最后强制推送。

九、Git 钩子与自动化

9.1 什么是 Git Hook

Git 钩子（Hook）是在特定 Git 事件发生时自动触发的脚本。它们存放在 .git/hooks/ 目录下。钩子可以用来强制执行代码规范、运行测试、检查提交信息格式等。

9.2 常用钩子

钩子名称	触发时机	常见用途
pre-commit	执行 `git commit` 前	代码格式检查、运行单元测试、防止提交大文件
prepare-commit-msg	提交信息编辑器打开前	自动生成提交信息模板
commit-msg	提交信息编辑完成后	检查提交信息格式是否符合规范
post-commit	提交完成后	发送通知、更新 CI 状态
pre-push	执行 `git push` 前	运行完整测试套件、检查分支命名
post-merge	合并完成后	自动安装新依赖、迁移数据库

#!/bin/sh
# .git/hooks/pre-commit — 提交前自动运行测试
# 将本文件设置为可执行: chmod +x .git/hooks/pre-commit

echo "运行提交前检查..."

# 检查是否存在调试代码
if git diff --cached | grep -q "console.log\|debugger"; then
    echo "错误: 存在调试代码 (console.log / debugger)"
    exit 1
fi

# 运行单元测试
npm test
if [ $? -ne 0 ]; then
    echo "错误: 测试未通过"
    exit 1
fi

echo "✓ 提交前检查通过"

使用 Husky 管理 Git Hook

手动管理 .git/hooks/ 中的脚本不太方便（这些文件不被版本控制）。推荐使用 Husky（Node.js 项目）或 pre-commit（Python 项目）来管理钩子。这些工具让你可以在项目源码中定义钩子，并与其他开发者共享。

十、核心要点总结

第一：Git 本质是内容寻址的文件系统。四个核心对象类型（Blob、Tree、Commit、Tag）构成了 Git 的数据模型。理解 Git 对象模型是掌握 Git 底层原理的关键。

第二：三个区域（工作区、暂存区、仓库）和三种状态（已修改、已暂存、已提交）是 Git 的核心工作模型。所有 Git 操作都围绕这个模型展开。

第三：分支本质是 41 字节的指针文件。Git 分支成本极低，因此分支操作是 Git 的核心优势。学会灵活使用分支和合并策略，是高效协作的基础。

第四：公共分支用 merge 或 revert，私有分支用 rebase。不会改写公共历史是 Git 协作的第一准则。--force-with-lease 应该永远优先于 --force。

第五：高级技巧（rebase -i、cherry-pick、stash、bisect、reflog）是 Git 高手的必备技能。这些技巧解决的是真实开发中的"痛点问题"——整理历史、选择性合并、临时切换、快速排错、误操作恢复。

第六：最好的学习方式是实践。创建一个沙盒仓库，反复练习本文的所有命令。故意制造冲突、误操作，然后用学到的技术来修复。只有在"犯错-修复"的循环中，才能真正理解 Git 的工作原理。

回《前置基础知识》

本文是《使用 Claude Code 必备的前置基础知识》中 Git 章节的专题延伸。建议先阅读前置基础知识中的 Git 入门内容，再深入本文的专题详解。两者结合，可以建立从入门到精通的完整 Git 知识体系。