第23章版本控制与协作

学习目标

深入理解版本控制的核心原理与分布式架构设计
掌握 Git 内部对象模型与底层机制
熟练运用分支策略与合并策略解决复杂协作场景
理解并实践主流 Git 工作流模型
掌握代码审查流程与协作规范
了解 CI/CD 集成与自动化质量保障体系

23.1 版本控制基础理论

23.1.1 版本控制的演进

版本控制系统（Version Control System, VCS）经历了三个主要阶段的演进：

阶段	代表工具	架构	核心特征
本地式	RCS	单机	仅本地文件差异记录
集中式	SVN、Perforce	C/S	单一中央服务器，需网络连接
分布式	Git、Mercurial	P2P	每个副本包含完整历史

分布式版本控制的核心优势在于：

离线工作：每个开发者拥有完整的仓库副本，包括全部历史记录
数据完整性：通过 SHA-1 哈希校验确保数据不可篡改
高性能：绝大多数操作在本地完成，无需网络通信
灵活的分支模型：分支创建与切换几乎零开销

23.1.2 Git 内部对象模型

Git 本质上是一个内容寻址文件系统（Content-addressable File System），其核心由四种对象类型构成：

┌─────────────────────────────────────────────────────┐
│                   Git 对象模型                        │
├─────────────┬───────────────────────────────────────┤
│   Blob      │  文件内容快照（不包含文件名）            │
│   Tree      │  目录结构映射（文件名 → Blob/Tree）     │
│   Commit    │  项目快照元数据（Tree + 父提交 + 信息） │
│   Tag       │  指向特定提交的命名引用                  │
└─────────────┴───────────────────────────────────────┘

理解对象模型对于掌握 Git 高级操作至关重要：

git cat-file -p HEAD
git cat-file -p HEAD^{tree}
git cat-file -p HEAD:src/main.py

echo "Hello, Git" | git hash-object --stdin
echo "Hello, Git" | git hash-object -w --stdin

Git 的引用（Reference）机制：

┌──────────────────────────────────────────────────┐
│  .git/refs/                                       │
│  ├── heads/        # 分支引用                     │
│  │   ├── main      # → commit SHA                │
│  │   └── develop   # → commit SHA                │
│  ├── tags/         # 标签引用                     │
│  │   └── v1.0      # → tag object / commit SHA   │
│  └── remotes/      # 远程引用                     │
│      └── origin/                                 │
│          ├── main                                │
│          └── develop                             │
└──────────────────────────────────────────────────┘

23.1.3 工作区域模型

Git 将文件管理划分为四个逻辑区域：

工作目录 (Working Directory)
    │  git add
    ▼
暂存区 (Staging Area / Index)
    │  git commit
    ▼
本地仓库 (Local Repository)
    │  git push
    ▼
远程仓库 (Remote Repository)

深入理解暂存区（Index）：

git ls-files -s
git diff
git diff --cached
git diff HEAD

23.2 Git 核心操作

23.2.1 仓库初始化与配置

git init
git init --bare
git clone https://github.com/user/repo.git
git clone --depth 1 https://github.com/user/repo.git
git clone --recursive https://github.com/user/repo.git
git clone --single-branch --branch develop https://github.com/user/repo.git

项目级配置最佳实践：

git config user.name "Your Name"
git config user.email "your.email@example.com"
git config core.autocrlf input
git config core.whitespace trailing-space,space-before-tab
git config init.defaultBranch main
git config pull.rebase true
git config fetch.prune true
git config diff.algorithm histogram
git config merge.conflictstyle diff3

23.2.2 提交与历史

git add -p
git commit -m "feat(auth): add JWT token refresh mechanism"
git commit --amend
git commit --fixup=<commit>
git commit --squash=<commit>

git log --oneline --graph --all --decorate
git log --format="%h %ad | %s%d [%an]" --graph --date=short
git log -L :function_name:file.py
git log --all --diff-filter=D -- "**/*.py"
git log -S "deprecated_function" --all
git log --author="Alice" --since="2025-01-01" --until="2025-12-31"
git shortlog -sn --no-merges

Conventional Commits 规范：

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

<body>

<footer>

类型定义：

类型	用途	语义化版本影响
`feat`	新功能	MINOR
`fix`	修复缺陷	PATCH
`docs`	文档变更	-
`style`	代码格式（不影响逻辑）	-
`refactor`	重构（非新功能/非修复）	-
`perf`	性能优化	PATCH
`test`	测试相关	-
`build`	构建系统或依赖	-
`ci`	CI 配置	-
`chore`	其他杂项	-
`revert`	回退提交	依原提交而定

23.2.3 差异与比较

git diff
git diff --staged
git diff HEAD~3..HEAD
git diff branch1...branch2
git diff --stat
git diff --word-diff
git diff --check
git diff --diff-filter=MRC
git difftool -d HEAD~1

23.3 分支管理

23.3.1 分支操作

git branch
git branch -v
git branch -a
git branch --merged main
git branch --no-merged main

git branch feature/login
git checkout -b feature/login
git switch -c feature/login
git checkout -b feature/login origin/feature/login

git branch -d feature/login
git branch -D feature/login
git push origin --delete feature/login

23.3.2 合并策略

Git 提供三种合并策略，各有适用场景：

Fast-forward 合并：

Before:  A---B---C  (main)
              \
               D---E  (feature)

After:   A---B---C---D---E  (main, feature)

1	git merge --ff-only feature

Non-fast-forward 合并（Merge Commit）：

Before:  A---B---C  (main)
              \
               D---E  (feature)

After:   A---B---C---F  (main)
              \     /
               D---E  (feature)

1	git merge --no-ff feature -m "Merge branch 'feature'"

Squash 合并：

1 2	git merge --squash feature git commit -m "feat(scope): implement feature X"

策略选择指南：

策略	适用场景	优点	缺点
`--ff-only`	同步远程变更	历史线性	仅适用于无分叉场景
`--no-ff`	功能分支合并	保留分支拓扑	增加合并提交
`--squash`	整合零碎提交	历史简洁	丢失细粒度变更记录

23.3.3 变基（Rebase）

变基的本质是将一系列提交”移植”到新的基底之上：

Before:  A---B---C  (main)
              \
               D---E  (feature)

After:   A---B---C---D'---E'  (feature)

git rebase main
git rebase -i HEAD~5
git rebase --onto main feature/base feature/topic
git rebase --abort
git rebase --continue
git rebase --skip

交互式变基操作：

pick a1b2c3d feat: initial implementation
reword e4f5g6h fix: correct edge case
squash i7j8k9l chore: minor cleanup
fixup m0n1o2p fix: typo
drop q3r4s5t wip: experimental approach
edit t6u7v8w feat: add validation

变基的黄金法则：永远不要变基已经推送到远程仓库的提交。

23.3.4 冲突解决

git merge feature
git status
git diff --name-only --diff-filter=U

git mergetool
git checkout --ours path/to/file
git checkout --theirs path/to/file
git add path/to/file
git merge --continue

git rerere
git config rerere.enabled true

冲突标记格式（diff3 风格）：

<<<<<<< ours
当前分支的内容
=======
基础版本的内容（便于理解双方修改）
>>>>>>> theirs
对方分支的内容

23.4 远程协作

23.4.1 远程仓库管理

git remote -v
git remote add origin https://github.com/user/repo.git
git remote add upstream https://github.com/original/repo.git
git remote set-url origin git@github.com:user/repo.git
git remote prune origin

git fetch origin
git fetch --all --prune
git pull --rebase origin main
git push origin main
git push -u origin feature/login
git push --force-with-lease origin main

23.4.2 Fork 与 Pull Request 工作流

┌──────────────┐    fork     ┌──────────────┐
│  上游仓库     │────────────►│  个人 Fork    │
│  (upstream)  │             │  (origin)    │
└──────┬───────┘             └──────┬───────┘
       │                            │
       │  PR                        │ push
       │◄───────────────────────────┤
       │                            │
       │  sync                      │ pull
       │───────────────────────────►│

git clone https://github.com/yourname/repo.git
cd repo
git remote add upstream https://github.com/original/repo.git

git checkout -b feature/new-feature

git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

23.4.3 SSH 密钥配置

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

cat ~/.ssh/id_ed25519.pub

~/.ssh/config 配置多账户：

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes

23.5 Git 工作流模型

23.5.1 Git Flow

Git Flow 由 Vincent Driessen 提出，适合有计划性发布周期的项目：

main:      A─────────────────────H─────M─────R
           │                     │     │     │
develop:   A──B──C──D──E──F──G──H──I──J──M──N──R
               │         │          │
feature/1:     B──C──D──E│          │
                        │          │
feature/2:              F──G──H    │
                                   │
release/1.0:                       J──K──L
                                        │
hotfix/1.0.1:                           ──K──L──M

分支类型：

分支	命名规范	生命周期	合并目标
`main`	`main`	永久	-
`develop`	`develop`	永久	-
`feature`	`feature/<name>`	临时	`develop`
`release`	`release/<version>`	临时	`main` + `develop`
`hotfix`	`hotfix/<version>`	临时	`main` + `develop`

git flow init
git flow feature start user-authentication
git flow feature finish user-authentication
git flow release start 1.0.0
git flow release finish 1.0.0
git flow hotfix start 1.0.1
git flow hotfix finish 1.0.1

23.5.2 GitHub Flow

GitHub Flow 更为简洁，适合持续部署的项目：

main:  A──B──C──D──E──F──G
           │        │
feature:   B──C──D  │
                    │
feature:            E──F──G

核心原则：

main 分支始终可部署
所有开发在功能分支上进行
通过 Pull Request 进行代码审查
审查通过后合并并立即部署

23.5.3 Trunk-Based Development

主干开发模式强调频繁集成：

main:  A─B─C─D─E─F─G─H─I─J─K─L─M
          │  │     │  │     │
short:    B─C│     │  │     │
             │     │  │     │
short:       D─E─F │  │     │
                    │  │     │
short:              G─H│     │
                       │     │
short:                 I─J─K │
                              │
release:                     L─M─N (release branch, cherry-pick)

适用场景：拥有成熟 CI/CD 基础设施和特性开关（Feature Flag）系统的团队。

23.5.4 工作流选择指南

维度	Git Flow	GitHub Flow	Trunk-Based
发布周期	计划性发布	持续部署	持续集成
团队规模	中大型	中小型	任意
CI/CD 成熟度	中等	高	极高
学习曲线	陡峭	平缓	中等
适用项目	库/框架	Web应用	微服务/SaaS

23.6 Git 高级技巧

23.6.1 暂存与恢复

git stash push -m "work in progress on auth module"
git stash push -u -m "including untracked files"
git stash push -p
git stash list
git stash pop
git stash apply stash@{0}
git stash drop stash@{0}
git stash clear
git stash branch feature/from-stash stash@{0}

23.6.2 提交修改

git commit --amend -m "feat: correct commit message"
git rebase -i HEAD~3
git reflog
git reset --soft HEAD~1
git reset --mixed HEAD~1
git reset --hard HEAD~1
git revert HEAD
git revert -m 1 HEAD
git cherry-pick abc123
git cherry-pick abc123..def456

reset 三种模式对比：

模式	工作目录	暂存区	提交历史	安全性
`--soft`	不变	不变	回退	安全
`--mixed`	不变	回退	回退	安全
`--hard`	回退	回退	回退	危险

23.6.3 二分查找与问题定位

git bisect start
git bisect bad
git bisect good v1.0.0
git bisect run python -m pytest tests/
git bisect reset

23.6.4 子模块与子树

git submodule add https://github.com/user/lib.git vendor/lib
git submodule update --init --recursive
git submodule foreach git pull origin main

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

23.6.5 大文件管理

git lfs install
git lfs track "*.psd"
git lfs track "datasets/**"
git lfs track "models/*.pth"
git lfs ls-files
git lfs pull

23.7 代码审查与协作规范

23.7.1 Pull Request 最佳实践

提交者规范：

标题：遵循 Conventional Commits 格式
描述模板：

## 变更类型
- [ ] feat: 新功能
- [ ] fix: 修复缺陷
- [ ] refactor: 重构
- [ ] docs: 文档
- [ ] test: 测试

## 变更说明
<!-- 描述本次变更的内容和原因 -->

## 关联 Issue
Closes #

## 测试方案
<!-- 描述如何验证本次变更 -->

## 自检清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的测试
- [ ] 所有测试通过
- [ ] 已更新相关文档
- [ ] 无安全风险引入

审查者规范：

审查维度	关注点
正确性	逻辑是否正确，边界条件是否处理
可读性	命名是否清晰，结构是否合理
可维护性	是否易于修改和扩展
性能	是否存在性能瓶颈
安全性	是否存在安全漏洞
测试	测试覆盖是否充分

23.7.2 代码所有权与 CODEOWNERS

# .github/CODEOWNERS

# 全局默认审查者
*       @team-lead

# 按目录分配
/src/core/       @core-team
/src/api/        @api-team
/src/web/        @frontend-team

# 按文件类型分配
*.py             @python-team
*.tsx            @frontend-team
Dockerfile       @devops-team

# 按关键文件分配
/pyproject.toml  @tech-lead @devops-team
/CHANGELOG.md    @release-manager

23.7.3 提交信息规范与工具

使用 commitizen 强制规范提交信息：

1
2
3

pip install commitizen
cz init
cz commit

pyproject.toml 配置：

[tool.commitizen]
name = "cz_conventional_commits"
version = "1.0.0"
version_files = [
    "src/myproject/__init__.py:__version__",
    "pyproject.toml:version",
]
changelog_file = "CHANGELOG.md"
update_changelog_on_bump = true

自动生成变更日志：

1 2	cz changelog cz bump --changelog

23.8 Python 项目的 .gitignore

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# IDE
.idea/
.vscode/
*.swp
*.swo
*~
.project
.classpath
.settings/
*.sublime-project
*.sublime-workspace

# Type checkers
.mypy_cache/
.dmypy.json
dmypy.json
.pyre/
.pytype/

# Profiling
*.prof

# Database
*.db
*.sqlite3

# OS
.DS_Store
Thumbs.db

# Secrets (NEVER commit these)
*.pem
*.key
credentials.json
secrets.yaml

23.9 CI/CD 集成

23.9.1 GitHub Actions

name: CI

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

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install ruff black mypy
      - name: Run Ruff
        run: ruff check .
      - name: Run Black check
        run: black --check .
      - name: Run MyPy
        run: mypy src/

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
      - name: Run tests
        run: |
          pytest --cov=src --cov-report=xml --cov-report=term-missing
      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.xml

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Run safety check
        run: |
          pip install safety
          safety check --full-report
      - name: Run Bandit
        run: |
          pip install bandit
          bandit -r src/ -f json -o bandit-report.json

  build:
    needs: [lint, test, security]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Build package
        run: |
          pip install build
          python -m build
      - name: Publish to PyPI
        if: github.ref == 'refs/heads/main'
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

23.9.2 Git Hooks 自动化

使用 pre-commit 框架管理 Git Hooks：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-json
      - id: check-merge-conflict
      - id: check-added-large-files
        args: ['--maxkb=500']
      - id: detect-private-key
      - id: no-commit-to-branch
        args: ['--branch', 'main']

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
        args: ['--fix']
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]

  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.27.0
    hooks:
      - id: commitizen

pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg
pre-commit run --all-files
pre-commit autoupdate

23.9.3 分支保护规则

推荐的分支保护配置：

main 分支保护规则：
├── ✅ Require a pull request before merging
│   ├── Required approving reviews: 2
│   ├── Dismiss stale reviews on new pushes
│   └── Require review from Code Owners
├── ✅ Require status checks to pass
│   ├── lint
│   ├── test (3.10)
│   ├── test (3.11)
│   ├── test (3.12)
│   └── security
├── ✅ Require conversation resolution
├── ✅ Require signed commits
├── ✅ Require linear history
├── ❌ Allow force pushes
└── ❌ Allow deletions

23.10 团队协作工具链

23.10.1 Git 钩子自动化工作流

import subprocess
import sys
from pathlib import Path


def run_command(cmd: list[str]) -> int:
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        print(result.stderr)
    return result.returncode


def main() -> int:
    staged_python_files = subprocess.run(
        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM", "--", "*.py"],
        capture_output=True,
        text=True,
    ).stdout.strip().split("\n")

    staged_python_files = [f for f in staged_python_files if f]

    if not staged_python_files:
        return 0

    errors = 0

    if run_command(["ruff", "check", "--fix"] + staged_python_files) != 0:
        errors += 1

    if run_command(["black", "--quiet"] + staged_python_files) != 0:
        errors += 1

    if run_command(["mypy"] + staged_python_files) != 0:
        errors += 1

    if errors > 0:
        print(f"\n❌ {errors} check(s) failed. Please fix before committing.")
        return 1

    run_command(["git", "add"] + staged_python_files)
    print("✅ All checks passed!")
    return 0


if __name__ == "__main__":
    sys.exit(main())

23.10.2 变更日志自动生成

from __future__ import annotations

import re
import subprocess
from dataclasses import dataclass, field
from enum import Enum


class ChangeType(Enum):
    FEAT = "feat"
    FIX = "fix"
    REFACTOR = "refactor"
    PERF = "perf"
    DOCS = "docs"
    TEST = "test"
    BUILD = "build"
    CI = "ci"
    CHORE = "chore"


@dataclass
class CommitInfo:
    hash: str
    type: ChangeType
    scope: str
    subject: str
    breaking: bool = False


SECTION_ORDER = [
    ChangeType.FEAT,
    ChangeType.FIX,
    ChangeType.REFACTOR,
    ChangeType.PERF,
    ChangeType.DOCS,
    ChangeType.TEST,
    ChangeType.BUILD,
    ChangeType.CI,
    ChangeType.CHORE,
]

SECTION_TITLES = {
    ChangeType.FEAT: "🚀 New Features",
    ChangeType.FIX: "🐛 Bug Fixes",
    ChangeType.REFACTOR: "♻️ Code Refactoring",
    ChangeType.PERF: "⚡ Performance Improvements",
    ChangeType.DOCS: "📝 Documentation",
    ChangeType.TEST: "✅ Tests",
    ChangeType.BUILD: "📦 Build",
    ChangeType.CI: "👷 CI",
    ChangeType.CHORE: "🔧 Chore",
}


def parse_commit(line: str) -> CommitInfo | None:
    pattern = r"^([0-9a-f]+)\s+(\w+)(?:\(([^)]+)\))?(!)?:\s+(.+)$"
    match = re.match(pattern, line)
    if not match:
        return None

    hash_val, type_str, scope, breaking, subject = match.groups()
    try:
        change_type = ChangeType(type_str)
    except ValueError:
        return None

    return CommitInfo(
        hash=hash_val[:7],
        type=change_type,
        scope=scope or "",
        subject=subject,
        breaking=breaking == "!",
    )


def generate_changelog(from_tag: str, to_ref: str = "HEAD") -> str:
    result = subprocess.run(
        ["git", "log", "--oneline", f"{from_tag}..{to_ref}"],
        capture_output=True,
        text=True,
    )

    commits_by_type: dict[ChangeType, list[CommitInfo]] = {}
    breaking_changes: list[CommitInfo] = []

    for line in result.stdout.strip().split("\n"):
        commit = parse_commit(line)
        if commit is None:
            continue
        commits_by_type.setdefault(commit.type, []).append(commit)
        if commit.breaking:
            breaking_changes.append(commit)

    sections: list[str] = []

    if breaking_changes:
        sections.append("💥 BREAKING CHANGES\n")
        for commit in breaking_changes:
            scope = f"**{commit.scope}**: " if commit.scope else ""
            sections.append(f"- {scope}{commit.subject} ({commit.hash})")
        sections.append("")

    for change_type in SECTION_ORDER:
        commits = commits_by_type.get(change_type, [])
        if not commits:
            continue
        sections.append(f"### {SECTION_TITLES[change_type]}\n")
        for commit in commits:
            scope = f"**{commit.scope}**: " if commit.scope else ""
            sections.append(f"- {scope}{commit.subject} ({commit.hash})")
        sections.append("")

    return "\n".join(sections)


if __name__ == "__main__":
    import sys

    from_tag = sys.argv[1] if len(sys.argv) > 1 else "v0.0.0"
    to_ref = sys.argv[2] if len(sys.argv) > 2 else "HEAD"
    print(generate_changelog(from_tag, to_ref))

23.11 前沿技术动态

23.11.1 现代Git工作流

# Git 2.38+ 新特性
git switch -c feature/new-feature
git restore --staged .
git sparse-checkout set src/

# Git LFS 大文件管理
git lfs track "*.psd"
git lfs track "*.zip"
git add .gitattributes

23.11.2 GitHub CLI自动化

# 使用gh命令行工具
gh repo create my-project --private
gh pr create --title "Add feature" --body "Description"
gh pr merge --squash
gh issue create --title "Bug report" --body "Details"

23.11.3 现代CI/CD实践

# GitHub Actions 现代化配置
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest --cov

23.11.4 代码质量自动化

# pre-commit 配置
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.7.0
    hooks:
      - id: mypy

23.12 本章小结

本章系统阐述了版本控制与协作的核心知识体系：

理论基础：从 VCS 演进到 Git 对象模型，理解分布式版本控制的底层原理
核心操作：掌握提交、差异比较、历史查询等日常高频操作
分支管理：深入理解合并策略（ff/noff/squash）与变基机制
远程协作：Fork/PR 工作流、SSH 配置、多账户管理
工作流模型：Git Flow、GitHub Flow、Trunk-Based Development 的选择与应用
高级技巧：暂存、提交修改、二分查找、子模块、大文件管理
协作规范：代码审查流程、CODEOWNERS、提交信息规范
CI/CD 集成：GitHub Actions、pre-commit 框架、分支保护
工具链：自动化钩子、变更日志生成

23.13 习题与项目练习

基础练习

仓库操作：创建一个 Python 项目仓库，配置 .gitignore，完成首次提交并推送到 GitHub。
分支实践：创建功能分支开发一个新特性，完成后分别使用 --ff-only、--no-ff、--squash 三种策略合并，观察历史记录差异。
冲突解决：在两个分支中修改同一文件的不同位置和相同位置，练习冲突解决流程。

进阶练习

交互式变基：使用 git rebase -i 整理一个包含 5 个提交的功能分支，实践 reword、squash、fixup、reorder 操作。
Git Flow 实战：使用 Git Flow 模型管理一个项目，完成从功能开发到版本发布的完整流程。
CI/CD 配置：为一个 Python 项目配置 GitHub Actions，包含 lint、测试、安全检查和自动发布。

项目练习

协作模拟项目：组建 3-4 人小组，模拟完整的协作流程：
- Fork 仓库并创建功能分支
- 提交 Pull Request 并进行代码审查
- 解决冲突并合并
- 配置 CI/CD 自动化流水线
- 使用 Conventional Commits 和自动变更日志
Git Hooks 工具：编写一套完整的 Git Hooks 脚本，实现：
- pre-commit：自动运行 ruff、black、mypy
- commit-msg：验证提交信息格式
- pre-push：运行完整测试套件

思考题

在什么场景下应该选择 merge 而非 rebase？反之呢？请从历史可追溯性、协作安全性、回滚便利性三个维度分析。
如何设计一个适合 50 人以上团队的 Git 工作流？需要考虑哪些因素（代码所有权、审查效率、集成频率、发布策略）？

23.14 延伸阅读

23.14.1 Git官方资源

Pro Git (https://git-scm.com/book/zh/v2) — Git权威指南（中文版）
Git官方文档 (https://git-scm.com/docs) — 命令参考手册
GitHub文档 (https://docs.github.com/) — GitHub协作指南

23.14.2 工作流与协作

Git Flow (https://nvie.com/posts/a-successful-git-branching-model/) — 经典分支模型
GitHub Flow (https://docs.github.com/en/get-started/quickstart/github-flow) — 简化工作流
Trunk Based Development (https://trunkbaseddevelopment.com/) — 主干开发模式

23.14.3 工具与规范

Conventional Commits (https://www.conventionalcommits.org/) — 提交信息规范
pre-commit (https://pre-commit.com/) — Git钩子框架
commitizen (https://commitizen-tools.github.io/commitizen/) — 提交工具

23.14.4 CI/CD平台

GitHub Actions (https://docs.github.com/en/actions) — GitHub CI/CD
GitLab CI/CD (https://docs.gitlab.com/ee/ci/) — GitLab持续集成
CircleCI (https://circleci.com/docs/) — 云端CI平台

下一章：第24章项目结构与规范

第23章 版本控制与协作