第23章 版本控制与协作

学习目标

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

23.1 版本控制基础理论

23.1.1 版本控制的演进

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

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

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

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

23.1.2 Git 内部对象模型

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

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

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

1
2
3
4
5
6
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）机制：

1
2
3
4
5
6
7
8
9
10
11
12
┌──────────────────────────────────────────────────┐
│  .git/refs/                                       │
│  ├── heads/        # 分支引用                     │
│  │   ├── main      # → commit SHA                │
│  │   └── develop   # → commit SHA                │
│  ├── tags/         # 标签引用                     │
│  │   └── v1.0      # → tag object / commit SHA   │
│  └── remotes/      # 远程引用                     │
│      └── origin/                                 │
│          ├── main                                │
│          └── develop                             │
└──────────────────────────────────────────────────┘

23.1.3 工作区域模型

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

1
2
3
4
5
6
7
8
9
10
工作目录 (Working Directory)
    │  git add
    ▼
暂存区 (Staging Area / Index)
    │  git commit
    ▼
本地仓库 (Local Repository)
    │  git push
    ▼
远程仓库 (Remote Repository)

深入理解暂存区（Index）：

1
2
3
4
git ls-files -s
git diff
git diff --cached
git diff HEAD

23.2 Git 核心操作

23.2.1 仓库初始化与配置

1
2
3
4
5
6
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

项目级配置最佳实践：

1
2
3
4
5
6
7
8
9
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 提交与历史

1
2
3
4
5
6
7
8
9
10
11
12
13
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 规范：

1
2
3
4
5
<type>(<scope>): <subject>

<body>

<footer>

类型定义：

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

23.2.3 差异与比较

1
2
3
4
5
6
7
8
9
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 分支操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 合并：

1
2
3
4
5
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）：

1
2
3
4
5
6
7
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）

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

1
2
3
4
5
Before:  A---B---C  (main)
              \
               D---E  (feature)

After:   A---B---C---D'---E'  (feature)
1
2
3
4
5
6
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

交互式变基操作：

1
2
3
4
5
6
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 冲突解决

1
2
3
4
5
6
7
8
9
10
11
12
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 风格）：

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

23.4 远程协作

23.4.1 远程仓库管理

1
2
3
4
5
6
7
8
9
10
11
12
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 工作流

1
2
3
4
5
6
7
8
9
10
┌──────────────┐    fork     ┌──────────────┐
│  上游仓库     │────────────►│  个人 Fork    │
│  (upstream)  │             │  (origin)    │
└──────┬───────┘             └──────┬───────┘
       │                            │
       │  PR                        │ push
       │◄───────────────────────────┤
       │                            │
       │  sync                      │ pull
       │───────────────────────────►│
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 密钥配置

1
2
3
4
5
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 配置多账户：

1
2
3
4
5
6
7
8
9
10
11
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 提出，适合有计划性发布周期的项目：

1
2
3
4
5
6
7
8
9
10
11
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

分支类型：

分支命名规范生命周期合并目标
mainmain永久-
developdevelop永久-
featurefeature/<name>临时develop
releaserelease/<version>临时main + develop
hotfixhotfix/<version>临时main + develop
1
2
3
4
5
6
7
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 更为简洁，适合持续部署的项目：

1
2
3
4
5
main:  A──B──C──D──E──F──G
           │        │
feature:   B──C──D  │
                    │
feature:            E──F──G

核心原则：

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

23.5.3 Trunk-Based Development

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

1
2
3
4
5
6
7
8
9
10
11
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 FlowGitHub FlowTrunk-Based
发布周期计划性发布持续部署持续集成
团队规模中大型中小型任意
CI/CD 成熟度中等高极高
学习曲线陡峭平缓中等
适用项目库/框架Web应用微服务/SaaS

23.6 Git 高级技巧

23.6.1 暂存与恢复

1
2
3
4
5
6
7
8
9
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 提交修改

1
2
3
4
5
6
7
8
9
10
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 二分查找与问题定位

1
2
3
4
5
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 子模块与子树

1
2
3
4
5
6
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 大文件管理

1
2
3
4
5
6
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 最佳实践

提交者规范：

  1. 标题：遵循 Conventional Commits 格式
  2. 描述模板：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
## 变更类型
- [ ] feat: 新功能
- [ ] fix: 修复缺陷
- [ ] refactor: 重构
- [ ] docs: 文档
- [ ] test: 测试

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

## 关联 Issue
Closes #

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

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

审查者规范：

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

23.7.2 代码所有权与 CODEOWNERS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# .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 配置：

1
2
3
4
5
6
7
8
9
[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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# .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
1
2
3
4
5
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 分支保护规则

推荐的分支保护配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 钩子自动化工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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 变更日志自动生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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工作流

1
2
3
4
5
6
7
8
9
# 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自动化

1
2
3
4
5
# 使用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实践

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 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 代码质量自动化

1
2
3
4
5
6
7
8
9
10
11
# 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 本章小结

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

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

23.13 习题与项目练习

基础练习

  1. 仓库操作：创建一个 Python 项目仓库，配置 .gitignore，完成首次提交并推送到 GitHub。

  2. 分支实践：创建功能分支开发一个新特性，完成后分别使用 --ff-only、--no-ff、--squash 三种策略合并，观察历史记录差异。

  3. 冲突解决：在两个分支中修改同一文件的不同位置和相同位置，练习冲突解决流程。

进阶练习

  1. 交互式变基：使用 git rebase -i 整理一个包含 5 个提交的功能分支，实践 reword、squash、fixup、reorder 操作。

  2. Git Flow 实战：使用 Git Flow 模型管理一个项目，完成从功能开发到版本发布的完整流程。

  3. CI/CD 配置：为一个 Python 项目配置 GitHub Actions，包含 lint、测试、安全检查和自动发布。

项目练习

  1. 协作模拟项目：组建 3-4 人小组，模拟完整的协作流程：

    • Fork 仓库并创建功能分支
    • 提交 Pull Request 并进行代码审查
    • 解决冲突并合并
    • 配置 CI/CD 自动化流水线
    • 使用 Conventional Commits 和自动变更日志

  2. Git Hooks 工具：编写一套完整的 Git Hooks 脚本，实现：

    • pre-commit：自动运行 ruff、black、mypy
    • commit-msg：验证提交信息格式
    • pre-push：运行完整测试套件

思考题

  1. 在什么场景下应该选择 merge 而非 rebase？反之呢？请从历史可追溯性、协作安全性、回滚便利性三个维度分析。

  2. 如何设计一个适合 50 人以上团队的 Git 工作流？需要考虑哪些因素（代码所有权、审查效率、集成频率、发布策略）？

23.14 延伸阅读

23.14.1 Git官方资源

23.14.2 工作流与协作

23.14.3 工具与规范

23.14.4 CI/CD平台

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