Git — 分布式版本控制系统完全指南

# 方式一：安装 Xcode 命令行工具（自带 Git）
xcode-select --install

# 方式二：Homebrew 安装最新版（推荐）
brew install git

# 验证安装
git --version

# Ubuntu / Debian
sudo apt update && sudo apt install git

# CentOS / RHEL / Fedora
sudo dnf install git

# Arch Linux
sudo pacman -S git

# 验证安装
git --version

winget install Git.Git

# 必须配置：用户名和邮箱
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

# 推荐配置
git config --global init.defaultBranch main          # 默认分支名
git config --global core.autocrlf input              # 换行符处理（macOS/Linux）
git config --global core.autocrlf true               # 换行符处理（Windows）
git config --global pull.rebase true                  # pull 时使用 rebase
git config --global core.editor "code --wait"         # 使用 VS Code 作为编辑器
git config --global merge.conflictstyle diff3         # 三方合并冲突样式
git config --global diff.algorithm histogram          # 更优的 diff 算法

# 查看所有配置
git config --global --list

# 1. 生成 SSH 密钥对（推荐 Ed25519）
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 2. 启动 ssh-agent
eval "$(ssh-agent -s)"

# 3. 添加私钥
ssh-add ~/.ssh/id_ed25519

# 4. 复制公钥（添加到 GitHub/GitLab 设置中）
cat ~/.ssh/id_ed25519.pub

# 5. 测试连接
ssh -T git@github.com

# 在当前目录创建新仓库
git init

# 在指定目录创建新仓库
git init my-project

# 克隆远程仓库
git clone https://github.com/user/repo.git

# 克隆并指定目录名
git clone https://github.com/user/repo.git my-folder

# 浅克隆（只获取最近 1 次提交，适合大仓库）
git clone --depth 1 https://github.com/user/repo.git

# 暂存单个文件
git add file.txt

# 暂存多个文件
git add file1.txt file2.txt

# 暂存当前目录所有变更
git add .

# 暂存所有已追踪文件的变更（不含新文件）
git add -u

# 交互式暂存（按补丁块选择）
git add -p

# 提交暂存区的内容
git commit -m "feat: 添加用户登录功能"

# 跳过暂存直接提交所有已追踪文件的变更
git commit -am "fix: 修复空指针异常"

# 修改上一次提交（补充文件或修改信息）
git commit --amend -m "feat: 添加用户登录和注册功能"

# 空提交（触发 CI/CD）
git commit --allow-empty -m "chore: trigger CI"

# 推送当前分支到远程
git push

# 首次推送并设置上游追踪
git push -u origin main

# 推送所有分支
git push --all origin

# 推送标签
git push origin v1.0.0
git push --tags

# 强制推送（危险！仅在必要时使用）
git push --force-with-lease

# 拉取并合并远程更新
git pull

# 拉取并使用 rebase（推荐，保持线性历史）
git pull --rebase

# 仅获取远程更新（不合并）
git fetch

# 获取所有远程的更新
git fetch --all

# 获取并清理已删除的远程分支引用
git fetch --prune

# 查看工作区和暂存区状态
git status

# 简洁输出
git status -s

# 显示分支信息
git status -sb

# 查看提交历史
git log

# 简洁的单行模式
git log --oneline

# 图形化显示分支关系
git log --oneline --graph --all

# 查看某个文件的修改历史
git log --follow -p file.txt

# 按作者过滤
git log --author="张三"

# 按时间范围过滤
git log --since="2024-01-01" --until="2024-12-31"

# 搜索提交信息
git log --grep="bug fix"

# 查看工作区与暂存区的差异
git diff

# 查看暂存区与上次提交的差异
git diff --staged

# 比较两个分支
git diff main..feature

# 比较两个提交
git diff abc1234..def5678

# 仅显示变更的文件名
git diff --name-only

# 显示统计信息
git diff --stat

# 查看所有分支
git branch          # 本地分支
git branch -a       # 包含远程分支

# 创建新分支
git branch feature-login

# 切换分支
git checkout feature-login
git switch feature-login       # Git 2.23+ 推荐

# 创建并切换（一步完成）
git checkout -b feature-login
git switch -c feature-login    # Git 2.23+ 推荐

# 从指定提交创建分支
git checkout -b hotfix abc1234

# 删除已合并的分支
git branch -d feature-login

# 强制删除未合并的分支
git branch -D feature-login

# 删除远程分支
git push origin --delete feature-login

# 切换到目标分支
git switch main

# 合并 feature 分支
git merge feature-login

# 使用 --no-ff 强制创建合并提交（推荐）
git merge --no-ff feature-login -m "merge: 合并登录功能"

# 放弃正在进行的合并
git merge --abort

# 查看已合并/未合并的分支
git branch --merged
git branch --no-merged

# 将 feature 分支变基到 main 的最新提交
git switch feature-login
git rebase main

# 发生冲突时
# 1. 解决冲突文件
# 2. git add 已解决的文件
# 3. 继续变基
git rebase --continue

# 跳过当前冲突的提交
git rebase --skip

# 取消变基
git rebase --abort

# 摘取单个提交
git cherry-pick abc1234

# 摘取多个提交
git cherry-pick abc1234 def5678

# 摘取一个范围的提交（不含起始提交）
git cherry-pick abc1234..def5678

# 只应用变更不自动提交
git cherry-pick --no-commit abc1234

# 发生冲突时
git cherry-pick --continue   # 解决后继续
git cherry-pick --abort      # 放弃

# 分支模型
main        ── 生产环境代码，只接受合并
develop     ── 开发主线，功能分支从这里分出
feature/*   ── 功能分支，完成后合并回 develop
release/*   ── 发布分支，用于发布前的最终修复
hotfix/*    ── 热修复分支，从 main 分出，修复后同时合并回 main 和 develop

# 使用 git-flow 工具
git flow init
git flow feature start login
git flow feature finish login
git flow release start v1.0.0
git flow release finish v1.0.0
git flow hotfix start fix-crash
git flow hotfix finish fix-crash

# 核心原则
1. 只有一个长期分支（main/trunk）
2. 功能分支生命周期极短（1-2 天内合并）
3. 使用 Feature Flag 控制未完成功能的可见性
4. 频繁集成，每天至少合并一次

# 冲突标记格式
<<<<<<< HEAD
你在当前分支的修改
=======
来自另一个分支的修改
>>>>>>> feature-branch

# 解决步骤
1. 编辑冲突文件，保留正确的内容
2. 删除冲突标记（<<<, ===, >>>）
3. git add 已解决的文件
4. git commit（合并）或 git rebase --continue（变基）

# 使用可视化工具解决冲突
git mergetool

# 常用配置
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait --merge $REMOTE $LOCAL $BASE $MERGED'

# 暂存当前修改
git stash

# 暂存并添加描述
git stash push -m "正在开发登录功能"

# 包含未追踪文件
git stash -u

# 查看暂存列表
git stash list

# 恢复最近的暂存（保留暂存记录）
git stash apply

# 恢复并删除暂存记录
git stash pop

# 恢复指定的暂存
git stash apply stash@{2}

# 删除所有暂存
git stash clear

# 创建轻量标签
git tag v1.0.0

# 创建附注标签（推荐）
git tag -a v1.0.0 -m "正式发布 1.0.0 版本"

# 为历史提交打标签
git tag -a v0.9.0 abc1234 -m "补打 0.9.0 标签"

# 查看所有标签
git tag -l

# 查看标签详情
git show v1.0.0

# 推送标签到远程
git push origin v1.0.0
git push origin --tags

# 删除本地标签
git tag -d v1.0.0

# 删除远程标签
git push origin --delete v1.0.0

# 创建新的工作树
git worktree add ../hotfix-branch hotfix/fix-crash

# 列出所有工作树
git worktree list

# 删除工作树
git worktree remove ../hotfix-branch

# 开始二分查找
git bisect start

# 标记当前版本有 bug
git bisect bad

# 标记某个已知正常的版本
git bisect good v1.0.0

# Git 会自动切换到中间提交，测试后标记
git bisect good   # 或 git bisect bad

# 找到问题提交后结束
git bisect reset

# 自动化二分查找（使用测试脚本）
git bisect start HEAD v1.0.0
git bisect run ./test.sh

# 交互式变基最近 5 个提交
git rebase -i HEAD~5

pick abc1234 feat: 添加用户模型
pick def5678 fix: 修复拼写错误
pick ghi9012 feat: 添加登录页面
pick jkl3456 fix: 修复样式
pick mno7890 feat: 添加验证逻辑

# 查看 HEAD 的 reflog
git reflog

# 查看特定分支的 reflog
git reflog show main

# 恢复到 reflog 中的某个状态
git reset --hard HEAD@{3}

# 找回已删除的分支
git reflog
# 找到删除前的提交哈希
git checkout -b recovered-branch abc1234

# 找回 rebase 前的状态
git reflog
git reset --hard HEAD@{5}  # 回到 rebase 之前

# 添加子模块
git submodule add https://github.com/user/lib.git libs/lib

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

# 已克隆的仓库初始化子模块
git submodule init
git submodule update

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

# 删除子模块
git submodule deinit libs/lib
git rm libs/lib
rm -rf .git/modules/libs/lib

# 克隆时启用稀疏检出
git clone --filter=blob:none --sparse https://github.com/user/monorepo.git
cd monorepo

# 设置要检出的目录
git sparse-checkout set packages/my-app packages/shared

# 添加更多目录
git sparse-checkout add docs

# 查看当前稀疏检出配置
git sparse-checkout list

# 禁用稀疏检出（检出所有文件）
git sparse-checkout disable

# 钩子文件位于 .git/hooks/ 目录
# 常用客户端钩子：
pre-commit      # 提交前运行（代码检查、格式化）
commit-msg      # 验证提交信息格式
pre-push        # 推送前运行（运行测试）
post-merge      # 合并后运行（安装依赖）

# .git/hooks/pre-commit
#!/bin/sh
npm run lint
if [ $? -ne 0 ]; then
  echo "Lint 检查未通过，请修复后再提交"
  exit 1
fi

# 1. 从 main 创建功能分支
git switch -c feature/user-auth main

# 2. 开发并提交
git add .
git commit -m "feat: 实现用户认证模块"

# 3. 推送到远程
git push -u origin feature/user-auth

# 4. 在 GitHub/GitLab 上创建 Pull Request

# 5. 代码评审通过后合并

# 6. 清理已合并的分支
git switch main
git pull
git branch -d feature/user-auth

# 拉取他人的 PR 到本地测试
git fetch origin pull/123/head:pr-123
git switch pr-123

# 使用 GitHub CLI
gh pr checkout 123

# 查看 PR 的差异
git diff main...pr-123

# .gitignore 常见配置

# 依赖目录
node_modules/
vendor/
__pycache__/
venv/

# 构建产物
dist/
build/
*.o
*.pyc

# 环境与配置文件
.env
.env.local
*.secret

# IDE 和编辑器
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db

# 日志
*.log
logs/

# 已追踪的文件加入 .gitignore 后不会自动停止追踪
# 需要先从 Git 缓存中移除
git rm --cached .env
git rm --cached -r node_modules/

# 全局 .gitignore（适用于所有仓库）
git config --global core.excludesfile ~/.gitignore_global

# Monorepo 目录结构示例
my-monorepo/
├── packages/
│   ├── web-app/
│   ├── api-server/
│   ├── shared-utils/
│   └── ui-components/
├── package.json
└── turbo.json