Git 版本控制与团队协作完全指南 2026：从入门到企业级工作流

# 方式1：Xcode Command Line Tools
xcode-select --install

# 方式2：Homebrew
brew install git

# 下载安装包
# https://git-scm.com/download/win

# 或使用 winget
winget install Git.Git

# 或使用 Scoop
scoop install git

# Debian/Ubuntu
sudo apt install git

# CentOS/RHEL
sudo yum install git

# Arch
sudo pacman -S git

# 设置用户名和邮箱（必须配置）
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# 设置默认编辑器
git config --global core.editor "code --wait"  # VS Code
git config --global core.editor vim             # Vim
git config --global core.editor nano            # Nano

# 设置默认分支名
git config --global init.defaultBranch main

# 设置行尾符处理
# Windows
git config --global core.autocrlf true
# macOS/Linux
git config --global core.autocrlf input

# 设置中文文件名正常显示
git config --global core.quotepath false

# 设置默认拉取策略
git config --global pull.rebase true

# 设置推送默认行为
git config --global push.default current

# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "your@email.com"

# 或使用 RSA（兼容性更好）
ssh-keygen -t rsa -b 4096 -C "your@email.com"

# 启动 SSH Agent
eval "$(ssh-agent -s)"

# 添加密钥
ssh-add ~/.ssh/id_ed25519

# 复制公钥
cat ~/.ssh/id_ed25519.pub
# macOS:
pbcopy < ~/.ssh/id_ed25519.pub
# Windows:
clip < ~/.ssh/id_ed25519.pub

ssh -T git@github.com
# Hi username! You've successfully authenticated...

# ~/.gitconfig

[user]
    name = Your Name
    email = your@email.com

[core]
    editor = code --wait
    autocrlf = input
    quotepath = false
    excludeglobal = ~/.gitignore_global

[init]
    defaultBranch = main

[pull]
    rebase = true

[push]
    default = current
    autoSetupRemote = true

[alias]
    st = status -sb
    co = checkout
    br = branch
    ci = commit
    lg = log --oneline --graph --all --decorate
    last = log -1 HEAD
    unstage = reset HEAD --
    amend = commit --amend --no-edit
    undo = reset --soft HEAD~1
    discard = checkout -- .

[color]
    ui = auto

[diff]
    algorithm = histogram

[merge]
    tool = code
    conflictstyle = zdiff3

[rerere]
    enabled = true

# 初始化新仓库
git init my-project
cd my-project

# 克隆远程仓库
git clone git@github.com:user/repo.git
git clone git@github.com:user/repo.git my-folder  # 指定目录
git clone --depth 1 git@github.com:user/repo.git  # 浅克隆（只取最新提交）

# 克隆特定分支
git clone -b develop git@github.com:user/repo.git

# 1. 查看状态
git status

# 2. 添加文件到暂存区
git add file.txt          # 添加指定文件
git add .                 # 添加所有修改
git add -p                # 交互式添加（按块选择）

# 3. 提交
git commit -m "feat: 添加用户登录功能"
git commit -am "fix: 修复登录bug"  # add + commit（仅已跟踪文件）

# 4. 推送
git push origin main
git push -u origin feature/login  # 首次推送新分支

# 5. 拉取
git pull origin main
git pull --rebase  # 变基拉取（推荐）

# 查看提交历史
git log
git log --oneline              # 简洁模式
git log --oneline --graph      # 图形化
git log --oneline --graph --all --decorate  # 完整图形化

# 查看指定文件的修改历史
git log -- file.txt
git log -p -- file.txt         # 包含 diff
git log --follow -- file.txt   # 跟踪文件重命名

# 查看某人的提交
git log --author="John"

# 查看某段时间的提交
git log --since="2026-01-01" --until="2026-07-01"
git log --since="2 weeks ago"

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

# 查看每次提交的统计信息
git log --stat
git log --shortstat

# 工作区 vs 暂存区
git diff

# 暂存区 vs 最新提交
git diff --cached
git diff --staged  # 同上

# 工作区 vs 最新提交
git diff HEAD

# 两个分支的差异
git diff main..develop

# 两个提交的差异
git diff abc123..def456

# 只看哪些文件变了
git diff --stat

# 只看文件名
git diff --name-only

# 查看分支
git branch                 # 本地分支
git branch -r              # 远程分支
git branch -a              # 所有分支
git branch -vv             # 带跟踪信息

# 创建分支
git branch feature/login
git checkout -b feature/login    # 创建并切换
git switch -c feature/login      # 创建并切换（推荐）
git checkout -b feature/login origin/develop  # 基于远程分支创建

# 切换分支
git checkout main
git switch main            # 推荐
git switch -               # 切回上一个分支

# 删除分支
git branch -d feature/login    # 安全删除（已合并才删）
git branch -D feature/login    # 强制删除

# 重命名分支
git branch -m old-name new-name

# 将 feature 合并到 main
git switch main
git merge feature/login

# 快进合并（Fast-forward）
# 如果 main 没有新提交，直接移动指针
A---B---C (main)
         \
          D---E (feature)

# 合并后（快进）：
A---B---C---D---E (main, feature)

# 三方合并
# 如果 main 有新提交，创建合并提交
A---B---C---F (main)
         \   /
          D---E (feature)

# 合并后：
A---B---C---F---M (main)
         \       /
          D---E (feature)

# 合并时出现冲突
git merge feature/login
# Auto-merging file.txt
# CONFLICT (content): Merge conflict in file.txt

# 查看冲突文件
git status
git diff

# 冲突标记
<<<<<<< HEAD
这是当前分支的内容
=======
这是被合并分支的内容
>>>>>>> feature/login

# 手动编辑解决冲突后
git add file.txt
git commit -m "merge: 合并 feature/login 分支"

# 放弃合并
git merge --abort

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

# 变基前：
A---B---C---F (main)
         \
          D---E (feature)

# 变基后：
A---B---C---F (main)
              \
               D'---E' (feature)

# 交互式变基（强大！）
git rebase -i HEAD~3  # 修改最近3个提交

# 从其他分支挑选特定提交到当前分支
git cherry-pick abc1234

# 挑选多个提交
git cherry-pick abc1234 def5678

# 挑选一个范围
git cherry-pick A..B  # 不包含A，包含B

# 只应用修改，不提交
git cherry-pick --no-commit abc1234

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

<body>

<footer>

# ❌ 坏的提交
git commit -m "fix"
git commit -m "update"
git commit -m "修改了一些东西"
git commit -m "wip"
git commit -m "fix bug again"

# ✅ 好的提交
git commit -m "fix(auth): 修复 token 过期后无法自动刷新的问题"
git commit -m "feat(api): 添加用户头像上传接口"
git commit -m "perf(list): 使用虚拟滚动优化万级列表渲染"

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

# 把新修改追加到最近一次提交
git add .
git commit --amend --no-edit

# 修改更早的提交（交互式变基）
git rebase -i HEAD~3
# 将要修改的提交从 pick 改为 reword

# 撤销最近一次提交（保留修改）
git reset --soft HEAD~1

# 撤销最近一次提交（丢弃修改）
git reset --hard HEAD~1

# 安全撤销（创建反向提交）
git revert abc1234

# 查看远程仓库
git remote -v

# 添加远程仓库
git remote add origin git@github.com:user/repo.git

# 修改远程仓库地址
git remote set-url origin git@github.com:user/new-repo.git

# 重命名远程仓库
git remote rename origin upstream

# 删除远程仓库
git remote remove origin

# 添加多个远程仓库
git remote add origin git@github.com:user/repo.git
git remote add upstream git@github.com:upstream/repo.git

# 推送
git push origin main
git push -u origin feature/login  # 首次推送并设置跟踪
git push                          # 后续简写
git push --force-with-lease       # 安全的强制推送
git push --tags                   # 推送标签

# 拉取
git pull origin main
git pull                          # 简写
git fetch origin                  # 只下载，不合并
git fetch --all --prune           # 获取所有远程并清理已删除的分支

# fetch vs pull
git fetch  → 只下载远程更新，不修改本地分支
git pull   = git fetch + git merge

# 1. 在 GitHub 上 Fork 项目

# 2. 克隆你的 Fork
git clone git@github.com:your-username/project.git
cd project

# 3. 添加上游仓库
git remote add upstream git@github.com:original-author/project.git

# 4. 创建功能分支
git switch -c fix/typo-in-readme

# 5. 修改并提交
git add README.md
git commit -m "docs: 修复 README 中的拼写错误"

# 6. 同步上游最新代码
git fetch upstream
git rebase upstream/main

# 7. 推送到你的 Fork
git push origin fix/typo-in-readme

# 8. 在 GitHub 上创建 Pull Request

# 查看远程分支
git branch -r

# 创建跟踪远程分支的本地分支
git switch -c feature/login origin/feature/login
# 或简写
git switch feature/login  # 自动跟踪同名远程分支

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

# 清理本地已删除的远程分支引用
git fetch --prune
git remote prune origin

# 暂存当前修改
git stash
git stash push -m "工作到一半的修改"

# 查看暂存列表
git stash list

# 恢复暂存（保留暂存记录）
git stash apply
git stash apply stash@{1}  # 恢复指定暂存

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

# 删除暂存
git stash drop stash@{0}
git stash clear  # 删除所有暂存

# 暂存未跟踪文件
git stash -u
git stash --include-untracked

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

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

# 给历史提交打标签
git tag -a v0.9.0 -m "旧版本" abc1234

# 查看标签
git tag
git tag -l "v1.*"
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 submodule add git@github.com:user/sub-project.git libs/sub-project

# 克隆含子模块的项目
git clone --recurse-submodules git@github.com:user/main-project.git

# 已克隆的项目初始化子模块
git submodule update --init --recursive

# 更新子模块
git submodule update --remote

# 修改子模块代码后提交
cd libs/sub-project
git add .
git commit -m "update submodule"
git push
cd ../..
git add libs/sub-project
git commit -m "chore: 更新子模块"

# 当你不知道哪个提交引入了 Bug
git bisect start
git bisect bad          # 标记当前版本有 Bug
git bisect good v1.0.0  # 标记 v1.0.0 版本正常

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

# 重复直到找到引入 Bug 的提交
# Git 会告诉你哪个提交有问题

# 结束二分查找
git bisect reset

# 查看所有操作记录（包括已删除的提交）
git reflog

# 恢复误删的提交
git reset --hard HEAD@{2}

# 恢复误删的分支
git switch -c recovered-branch abc1234

# 在不同目录同时检出多个分支
git worktree add ../project-hotfix hotfix/urgent
git worktree add ../project-feature feature/new-api

# 查看工作树
git worktree list

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

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

# 2. 开发并提交
git add .
git commit -m "feat: 添加用户个人资料页面"

# 3. 推送
git push -u origin feature/user-profile

# 4. 在 GitHub/GitLab 上创建 Pull Request
#    目标分支：develop 或 main

# 5. 代码审查
#    - 至少1-2人审核
#    - 讨论修改建议
#    - 根据反馈修改

# 6. 根据审查意见修改
git add .
git commit -m "fix: 根据代码审查意见修改"
git push

# 7. 审核通过，合并
#    - Squash and Merge（推荐）
#    - Rebase and Merge
#    - Create a Merge Commit

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'pnpm'
      
      - name: Install pnpm
        run: npm install -g pnpm
      
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      
      - name: Lint
        run: pnpm lint
      
      - name: Type check
        run: pnpm type-check
      
      - name: Test
        run: pnpm test -- --coverage
      
      - name: Build
        run: pnpm build
      
      - name: Upload coverage
        uses: codecov/codecov-action@v4

# 安装 Husky
pnpm add -D husky lint-staged

# 初始化 Husky
pnpm husky init

// package.json
{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml}": ["prettier --write"]
  }
}

# 创建 pre-commit hook
echo 'pnpm lint-staged' > .husky/pre-commit

# 创建 commit-msg hook（检查提交信息规范）
cat > .husky/commit-msg << 'EOF'
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# 检查提交信息是否符合约定式提交规范
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?: .{1,100}$
error_msg="提交信息不符合规范！格式：type(scope): subject"

if ! grep -qE "$commit_regex" "$1"; then
    echo "$error_msg"
    exit 1
fi
EOF

# 从暂存区移除（保留本地文件）
git rm --cached secret.txt
echo "secret.txt" >> .gitignore
git add .gitignore
git commit -m "chore: 移除误提交的文件并添加到 .gitignore"

# 如果已经推送到远程，需要从历史中彻底删除
# 使用 git-filter-repo（推荐）
pip install git-filter-repo
git filter-repo --path secret.txt --invert-paths

# 或使用 BFG Repo-Cleaner
java -jar bfg.jar --delete-files secret.txt
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force

# 放弃合并
git merge --abort

# 使用合并工具
git mergetool

# 查看冲突文件列表
git diff --name-only --diff-filter=U

# 一次性添加所有已解决的文件
git add $(git diff --name-only --diff-filter=U)

# 方法1：创建反向提交（推荐，安全）
git revert abc1234
git push

# 方法2：强制推送（危险！只在个人分支用）
git reset --hard HEAD~1
git push --force-with-lease

# ⚠️ 永远不要对 main/develop 等公共分支使用强制推送

# 合并最近3次提交
git rebase -i HEAD~3

# 在编辑器中：
pick abc123 feat: 添加功能A
squash def456 feat: 添加功能B
squash ghi789 fix: 修复功能A的bug

# 保存后会让你编辑合并后的提交信息

# 浅克隆（只取最新提交）
git clone --depth 1 git@github.com:user/repo.git

# 克隆指定分支
git clone --branch main --single-branch --depth 1 git@github.com:user/repo.git

# 后续需要完整历史时
git fetch --unshallow

# 查看文件每行的最后修改者
git blame file.txt

# 查看指定行范围
git blame -L 10,20 file.txt

# 忽略空白修改
git blame -w file.txt

# 在 VS Code 中：
# 右键 → Open Timeline / GitLens: Toggle Line Blame

# lazygit — 终端 GUI
brew install lazygit

# delta — 美化 diff 输出
brew install git-delta
# 在 .gitconfig 中配置：
# [core]
#     pager = delta
# [interactive]
#     diffFilter = delta --color-only

# tig — 文本模式仓库浏览器
brew install tig

# gh — GitHub CLI
brew install gh
gh auth login
gh pr create --fill
gh pr checkout 123