Git 版本控制：开发者完整技术参考手册

Git 是一个分布式版本控制系统（DVCS），它随时间记录项目文件树的快照，允许任意数量的贡献者并行工作而不会覆盖彼此的更改。每位开发者在本地机器上都持有完整的仓库副本——包括完整的提交历史——消除了单点故障并支持完全离线的工作流程。

Git 由 Linus Torvalds 于 2005 年 4 月创建，用于取代 BitKeeper 进行 Linux 内核开发。Git 从基本原则出发，围绕三个不可妥协的需求进行设计：速度、数据完整性以及对非线性分布式工作流的支持。这些设计目标至今仍定义了 Git 与其前身的本质区别，也是它在二十多年后仍是主流 VCS 的原因。

Git 与集中式版本控制的区别

理解 Git 的架构需要与集中式系统进行直接比较，例如 Subversion（SVN）或 CVS，这些系统中单一权威服务器持有规范仓库，开发者检出浅层工作副本。

分布式模型意味着即使 GitHub 等托管平台发生故障，每位开发者的本地克隆也是整个项目历史的完整权威备份。

核心架构：Git 实际存储的内容

Git 不存储差异（diff），它存储快照。每次提交指向一个树对象，代表该时刻所有被跟踪文件的完整状态。如果两次提交之间某个文件未发生变化，Git 会存储指向之前 blob 的指针而不是重复存储——这就是 Git 同时实现完整性和存储效率的方式。

Git 对象存储（.git/objects/）中的四种基本对象类型为：

• Blob——原始文件内容，通过 SHA 哈希寻址
• Tree——目录列表，将文件名映射到 blob 或子树哈希
• Commit——指向一棵树、零个或多个父提交、作者元数据和提交信息的指针
• Tag——指向特定提交的带注释指针，用于发布标记

每个对象都是不可变的，并按内容寻址。修改任何文件中的单个字节都会产生完全不同的 SHA 哈希，这会向上级联到树和提交对象。这就是为什么 Git 的历史具有密码学防篡改性——你无法在不改变所有后续提交哈希的情况下悄悄修改过去的提交。

暂存区（也称为索引，存储于 .git/index）是一个保存拟议下次提交的二进制文件。这种三区模型——工作目录、索引、仓库——是 Git 最容易被误解的架构特性，也是大多数初学者困惑的根源。

安装和配置 Git

在运行任何命令之前，请验证您的安装并配置您的身份。Git 将作者信息嵌入到每个提交对象中，而身份配置错误是共享仓库中提交历史混乱最常见的原因之一。

# Verify installation
git --version

# Set global identity (stored in ~/.gitconfig)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Set default branch name to 'main' (modern convention)
git config --global init.defaultBranch main

# Set preferred editor for commit messages
git config --global core.editor "vim"

# Enable colored output
git config --global color.ui auto

# Verify configuration
git config --list

配置是分层的：--system（所有用户，/etc/gitconfig）、--global（当前用户，~/.gitconfig）和 --local（仓库，.git/config）。更具体的范围会覆盖更广泛的范围。

Git 基本命令：完整参考

初始化和克隆

git init 通过将 .git/ 目录写入当前文件夹来创建新仓库。它不会创建任何提交——仓库从空状态开始。

git init
git init my-project        # Initialize into a new subdirectory
git init --bare repo.git   # Bare repository (no working tree, used for servers)

裸仓库只包含对象存储和引用——没有工作目录。这是多个开发者推送到的远程仓库的正确格式。如果您在 VPS 托管服务器上自托管 Git，请始终将共享仓库初始化为裸仓库。

git clone 创建远程仓库的完整本地副本，包括所有分支、标签和历史。

git clone https://github.com/user/repo.git
git clone git@github.com:user/repo.git          # SSH transport (preferred for auth)
git clone --depth 1 https://github.com/user/repo.git  # Shallow clone (latest commit only)
git clone --branch develop https://github.com/user/repo.git  # Clone specific branch

浅克隆（--depth）适用于只需要最新状态而不需要完整历史的 CI/CD 流水线。它们可以显著减少大型仓库的克隆时间，但会阻止某些依赖历史的操作，如 git bisect。

检查状态

git status 是任何工作流中运行最频繁的命令。它显示仓库的三区状态。

git status
git status -s    # Short format: two-column status codes
git status -sb   # Short format with branch info

git diff 比较各区域或提交之间的内容。

git diff                    # Working directory vs. index (unstaged changes)
git diff --staged           # Index vs. last commit (what will be committed)
git diff HEAD               # Working directory vs. last commit (all changes)
git diff main..feature      # Compare tips of two branches
git diff abc123..def456     # Compare two specific commits
git diff --stat             # Show changed files and line counts only

git log 遍历提交图。其过滤选项是 Git 最强大但最少被使用的功能之一。

git log
git log --oneline --graph --decorate --all   # Visual branch graph
git log -p                                   # Show patch (diff) for each commit
git log --author="Jane"                      # Filter by author
git log --since="2 weeks ago"               # Filter by date
git log --grep="fix:"                        # Filter by commit message pattern
git log -- path/to/file                      # History of a specific file
git log --follow -- path/to/file             # Follow renames

--graph --oneline --decorate --all 组合非常普遍实用，大多数工程师会为其创建别名：

git config --global alias.lg "log --oneline --graph --decorate --all"

暂存和提交

git add filename.py          # Stage a specific file
git add src/                 # Stage an entire directory
git add .                    # Stage all changes in current directory
git add -p                   # Interactive patch staging (stage hunks, not whole files)
git add -u                   # Stage modifications and deletions, but not new files

交互式暂存（git add -p）是 Git 最强大但最少被使用的功能之一。它允许您审查并选择性地暂存文件中的单个代码块，即使工作目录包含多个不相关的更改，也能实现精确的原子提交。

git commit -m "feat: add OAuth2 token refresh logic"
git commit --amend           # Modify the most recent commit (message or content)
git commit --amend --no-edit # Amend content without changing the message
git commit -v                # Open editor showing full diff of staged changes

关键规则：永远不要修改已经推送到共享远程的提交。修改会重写提交哈希，迫使协作者对其本地分支进行 rebase 或重置。

推送和拉取

git push origin main
git push origin feature/auth     # Push a specific branch
git push -u origin feature/auth  # Push and set upstream tracking
git push --force-with-lease      # Safer force push (fails if remote has new commits)
git push origin --delete old-branch  # Delete a remote branch
git push --tags                  # Push all local tags

当必须重写远程历史时，优先使用 --force-with-lease 而非 --force。它会检查自上次 fetch 以来是否有其他人推送过，防止意外数据丢失。

git pull origin main
git pull --rebase origin main    # Fetch and rebase instead of merge
git pull --ff-only               # Only fast-forward; abort if a merge commit would be created

git fetch 下载远程更改而不影响您的工作目录或当前分支。这是在集成上游更改之前检查它们的安全方式。

git fetch origin
git fetch --all          # Fetch from all remotes
git fetch --prune        # Remove remote-tracking branches that no longer exist upstream

分支和合并：核心工作流

Git 的分支模型是其最具架构意义的特性。分支只是一个命名指针（.git/refs/heads/ 中的一个 41 字节文件），指向一个提交哈希。无论仓库大小，创建分支都是即时的。

分支管理

git branch                        # List local branches
git branch -a                     # List all branches (local and remote-tracking)
git branch -v                     # List branches with last commit info
git branch feature/user-auth      # Create a new branch
git branch -d feature/user-auth   # Delete merged branch
git branch -D feature/user-auth   # Force delete (even if unmerged)
git branch -m old-name new-name   # Rename a branch

切换分支

现代 Git（2.23+）将 git checkout 的功能分离为两个专用命令：

git switch main                   # Switch to existing branch
git switch -c feature/payments    # Create and switch in one step
git restore filename.py           # Discard working directory changes to a file
git restore --staged filename.py  # Unstage a file (remove from index)

git checkout 对所有这些操作仍然有效，但 git switch 和 git restore 具有更清晰、更明确的语义，在现代工作流中应优先使用。

合并策略

git merge feature/user-auth           # Standard merge (creates merge commit if needed)
git merge --no-ff feature/user-auth   # Always create merge commit (preserves branch topology)
git merge --squash feature/user-auth  # Squash all branch commits into one staged change
git merge --abort                     # Abort an in-progress conflicted merge

快进合并发生在目标分支与源分支没有分叉时——Git 只是将指针向前移动。不会创建合并提交。--no-ff 即使在这种情况下也会强制创建合并提交，从而在 git log --graph 中保留功能分支的可视历史。

压缩合并将功能分支的所有提交折叠成一个暂存更改，然后手动提交。这会在 main 上产生干净的线性历史，但会丢弃功能分支的细粒度提交历史。

变基（Rebase）

git rebase 将一个分支的提交重放到另一个分支之上，重写其哈希以创建线性历史。

git rebase main                  # Rebase current branch onto main
git rebase -i HEAD~5             # Interactive rebase: edit last 5 commits
git rebase --onto main server client  # Transplant client branch onto main, excluding server
git rebase --abort               # Abort a rebase in progress
git rebase --continue            # Continue after resolving a conflict

交互式变基（-i）是专业人员的提交整理工具。它允许您在共享提交之前重新排序、压缩、编辑、删除或拆分提交。常见用例：在开启 pull request 之前整理混乱的功能分支。

变基的黄金法则：永远不要对存在于公共共享分支上的提交进行变基。变基会重写提交哈希。如果团队成员已经基于这些提交开展工作，他们的历史将会分叉，并将面临痛苦的协调过程。

解决合并冲突

当两个分支修改同一文件的同一区域时会发生冲突。Git 使用标准冲突标记在文件中标记冲突：

<<<<<<< HEAD
const timeout = 30000;
=======
const timeout = 60000;
>>>>>>> feature/increase-timeout

解决工作流：

# After a conflicted merge or rebase
git status                    # Identify conflicted files (marked as "both modified")
# Edit each conflicted file, remove markers, keep correct content
git add resolved-file.js      # Mark as resolved
git commit                    # Complete the merge (message is pre-populated)

对于复杂冲突，三路合并工具提供更清晰的视图：

git mergetool                 # Launch configured merge tool (vimdiff, meld, etc.)
git config --global merge.tool vimdiff

撤销更改：决策矩阵

选择错误的撤销命令是开发者丢失工作或破坏共享历史最常见的方式之一。正确的选择取决于两个变量：更改所在的位置以及是否已经推送。

git reset --soft HEAD~1      # Undo commit, keep changes in index
git reset HEAD~1             # Undo commit, keep changes in working dir
git reset --hard HEAD~1      # Undo commit, discard all changes permanently

git revert abc1234           # Create new commit that inverts abc1234
git revert HEAD~3..HEAD      # Revert last 3 commits (creates 3 revert commits)
git revert -n HEAD~3..HEAD   # Stage the reversals without committing (batch revert)

git reset --hard 通过普通 Git 命令是不可逆的。如果您意外运行了它，唯一的恢复途径是 git reflog，它记录了 HEAD 在大约 90 天内指向的每个位置。

git reflog                   # Show HEAD movement history with hashes
git checkout -b recovery abc1234  # Recover by creating a branch at the lost commit

生产工作流的高级命令

git stash

git stash 将当前工作目录和索引状态保存到堆栈中，为您提供干净的工作树以切换上下文。

git stash                        # Stash tracked changes
git stash -u                     # Include untracked files
git stash push -m "WIP: auth refactor"  # Stash with a descriptive name
git stash list                   # List all stash entries
git stash pop                    # Apply most recent stash and remove it from stack
git stash apply stash@{2}        # Apply specific stash without removing it
git stash drop stash@{2}         # Delete a specific stash entry
git stash branch feature/wip     # Create a new branch from a stash

git cherry-pick

git cherry-pick abc1234                    # Apply a single commit to current branch
git cherry-pick abc1234 def5678            # Apply multiple commits
git cherry-pick abc1234 --no-commit        # Apply changes without committing
git cherry-pick main~3..main              # Apply a range of commits

Cherry-pick 是将错误修复向后移植到维护分支的标准机制。如果您在 main 上修复了一个关键安全漏洞，您可以将该提交 cherry-pick 到 v2.1-stable 和 v2.0-stable，而无需合并不相关的功能。

git bisect

git bisect 通过对提交历史进行二分搜索来找到引入 bug 的确切提交。它是 Git 最强大但最鲜为人知的调试工具之一。

git bisect start
git bisect bad                   # Mark current commit as broken
git bisect good v2.3.0           # Mark a known-good commit or tag
# Git checks out the midpoint commit automatically
# Test your code, then:
git bisect good                  # If this commit is fine
git bisect bad                   # If this commit is broken
# Repeat until Git identifies the first bad commit
git bisect reset                 # Return to original HEAD when done

在好坏节点之间有 1,000 个提交的仓库中，git bisect 最多只需 10 步即可找到罪魁祸首。

git tag

标签将特定提交标记为重要节点——通常是发布版本。

git tag v1.4.2                          # Lightweight tag (just a pointer)
git tag -a v1.4.2 -m "Release 1.4.2"   # Annotated tag (recommended; stores metadata)
git tag -a v1.4.2 abc1234              # Tag a specific past commit
git push origin v1.4.2                 # Push a specific tag
git push origin --tags                 # Push all tags
git tag -d v1.4.2                      # Delete local tag
git push origin --delete v1.4.2        # Delete remote tag

发布时始终使用带注释的标签。它们存储标记者的姓名、电子邮件、日期和消息，并且可以用 GPG 签名。轻量标签仅适用于临时本地书签。

git worktree

git worktree 允许同时从同一仓库检出多个工作目录——每个目录位于不同的分支上。这消除了在需要切换到热修复时暂存或提交进行中工作的需要。

git worktree add ../hotfix-branch hotfix/critical-auth-bug
git worktree list
git worktree remove ../hotfix-branch

这在运行 CI/CD 流水线的独立服务器上特别有价值，多个构建任务需要同时访问同一仓库的不同分支而互不干扰。

团队 Git 工作流

正确的分支策略取决于您的发布节奏和团队规模。存在三种主流模型：

功能分支工作流

每个功能或修复都在其自己的分支上进行。开发者开启 pull request 合并到 main。简单，对大多数团队有效。

Gitflow

定义长期存在的 main 和 develop 分支，以及具有严格合并规则的短期 feature/、release/ 和 hotfix/ 分支。适用于具有明确版本发布的软件（库、打包应用程序）。

基于主干的开发

开发者直接提交到 main（或使用在一天内合并的极短期分支）。严重依赖功能标志来隐藏未完成的工作。受高速团队和持续部署实践的青睐。

托管 Git 仓库：自托管与托管平台

对于需要数据主权、合规性或私有基础设施的团队，自托管 Git 服务器是一个可行且通常必要的选择。选项包括 Gitea（轻量级，基于 Go）、GitLab CE（完整 DevOps 平台）和 Forgejo（具有社区治理的 Gitea 分支）。

一个最小化的自托管 Gitea 实例可以在配备 2 vCPU 和 2 GB RAM 的 VPS 托管方案上舒适运行。对于较大的团队或带有 CI 运行器的 GitLab CE，4–8 GB RAM 是实际最低要求。

自托管时，请通过以下方式保护您的 Git 服务器：

• SSH 密钥认证（完全禁用密码认证）
• 使用有效证书的 HTTPS——SSL 证书对于保护传输中的凭据至关重要
• 限制 Git 端口暴露的防火墙规则（22 或自定义 SSH 端口，HTTPS 使用 443）
• 定期自动备份 .git 裸仓库目录
• CI/CD 集成的 Webhook 密钥

对于使用基于 Git 的部署流水线同时管理 Web 基础设施的团队，将自托管 Git 服务器与 带 cPanel 的 VPS 配合使用，可以在熟悉的托管管理工具旁边获得集成的部署钩子。

Git 钩子：自动化质量门控

Git 钩子是在 Git 生命周期特定节点自动执行的脚本。它们存放在 .git/hooks/ 中，默认不提交到仓库（使用 pre-commit 或 husky 等工具来共享它们）。

生产工作流的关键钩子：

# Example pre-commit hook: reject commits with debug print statements
#!/bin/bash
if git diff --cached | grep -E '^+.*(console.log|debugger|print("DEBUG)'; then
  echo "ERROR: Debug statement detected. Remove before committing."
  exit 1
fi

裸服务器仓库上的 post-receive 钩子是简单 Git 部署的基础：推送到服务器，钩子将新的 HEAD 检出到 Web 根目录，运行构建步骤并重启服务——无需外部 CI 平台。

.gitignore：保持仓库整洁

.gitignore 文件告诉 Git 哪些文件和模式不需要跟踪。它应该提交到仓库并仔细维护。

# Dependencies
node_modules/
vendor/

# Build artifacts
dist/
build/
*.o
*.pyc
__pycache__/

# Environment and secrets — NEVER commit these
.env
.env.local
*.pem
*.key
config/secrets.yml

# IDE files
.idea/
.vscode/
*.swp

# OS files
.DS_Store
Thumbs.db

关键陷阱：如果文件在添加到 .gitignore 之前已经被跟踪，Git 将继续跟踪它。您必须显式取消跟踪它：

git rm --cached path/to/sensitive-file
git commit -m "chore: stop tracking secrets file"

永远不要将凭据、API 密钥或私钥提交到仓库——即使是私有仓库也不行。使用环境变量、密钥管理器（HashiCorp Vault、AWS Secrets Manager）或已被 .gitignore 的 .env 文件。

大型仓库的性能调优

标准 Git 在拥有数百万文件或数 GB 二进制资产的仓库上性能会下降。缓解策略：

• Git LFS（大文件存储）：将仓库中的大型二进制文件替换为指针文件，并将实际内容存储在单独的 LFS 服务器上。对于包含媒体、ML 模型权重或编译二进制文件的仓库至关重要。
• 部分克隆：git clone --filter=blob:none 下载提交和树，但按需获取 blob。显著减少大型 monorepo 的初始克隆大小。
• 稀疏检出：git sparse-checkout set path/to/subdir 只检出工作树的一个子集。在开发者只在一个服务目录中工作的 monorepo 中很有用。
• 提交图文件：git commit-graph write --reachable 预计算提交图，加速大型历史上的 git log --graph 等操作和可达性查询。
• git maintenance start：调度后台维护任务（松散对象打包、提交图更新、fetch 预取），随时间保持仓库操作的高效性。

技术关键要点清单

在认为您的 Git 设置已准备好投入生产之前，请验证以下每一项：

• 已配置身份：在适当的配置范围内正确设置 user.name 和 user.email
• 使用 SSH 密钥：远程密码认证已替换为 SSH 密钥对或基于令牌的 HTTPS
• 已提交 .gitignore：在第一次提交之前排除密钥、构建产物和操作系统文件
• 默认分支命名为 main：全局设置 init.defaultBranch 以避免遗留的 master 命名
• 提交信息遵循约定：通过 commit-msg 钩子强制执行约定式提交（feat:、fix:、chore:）或团队约定格式
• 公共历史使用 git revert：git reset --hard 仅用于本地未推送的提交
• 使用 --force-with-lease 而非 --force：防止意外覆盖队友的推送
• 发布使用带注释的标签：带消息的 git tag -a，而非轻量标签
• 通过 pre-commit 或 husky 共享钩子：在团队中一致执行质量门控
• 已配置 Git LFS（如果仓库包含超过 1 MB 的二进制资产）
• 服务器上使用裸仓库：自托管远程使用 git init --bare 初始化
• 定期执行 git fetch --prune：保持远程跟踪分支与实际远程状态同步

常见问题解答

git fetch 和 git pull 有什么区别？

git fetch 将远程的提交、分支和标签下载到本地远程跟踪引用（例如 origin/main）中，而不影响您的工作目录或当前分支。git pull 是 git fetch 后立即执行 git merge（或如果已配置则执行 git rebase）。当您想在集成上游更改之前检查它们时，请使用 git fetch。

什么时候应该使用 git rebase 而不是 git merge？

在开启 pull request 之前使用 rebase 来线性化您的本地功能分支，保持项目历史的可读性。永远不要对其他开发者已经克隆或基于其开展工作的分支进行变基——重写已发布的提交哈希会迫使其他人手动协调分叉的历史。

如何永久删除意外提交的敏感文件？

使用 git filter-repo（git filter-branch 的现代替代品）：git filter-repo --path secrets.env --invert-paths。这会重写整个仓库历史，从每个提交中删除该文件。重写后，强制推送所有分支和标签，然后立即轮换暴露的凭据——无论您行动多快，都应假设它们已被泄露。

什么是 HEAD 分离状态，如何从中恢复？

HEAD 分离状态意味着您的 HEAD 指针直接引用特定的提交哈希而不是分支名称。您所做的任何提交都不会属于任何分支，在您切换离开后将变得不可达。恢复方法：git switch -c new-branch-name 将提交附加到新分支，或 git switch main 丢弃它们。

Git 如何处理二进制文件与文本文件的不同之处？

Git 将二进制文件存储为不透明的 blob——它无法计算有意义的行级差异或对其执行自动合并。二进制文件中的冲突必须通过完全选择一个版本来解决。对于拥有大量二进制资产的仓库，配置 Git LFS 将二进制文件存储在外部，保持仓库本身精简高效。