CI 浅克隆与按需加深是什么
流水线常以 depth=1 起步，只取最新提交：依赖历史信息的任务（版本号计算、变更日志、diff 范围、blame）需要显式加深或切换完整克隆。原则是把「这条流水线真正需要的最小历史」写清楚，按任务分级，而不是无脑全量。
基本信息
| 浅克隆 | git clone --depth 1（平台侧常写作 fetch-depth: 1） |
|---|---|
| 需要标签 | fetch-depth: 0 或 git fetch --tags --depth=1 |
| 需要 diff | 确保比较基线在本地存在，否则先 fetch 对应引用 |
| 按需加深 | git fetch --deepen=50 origin main |
| 判断标准 | 该步骤是否用 describe/merge-base/blame，用就得补历史 |
典型使用场景
- 日常构建只取最新提交：最快，适合不依赖历史的编译与打包。
- 版本号计算：需要 tag 或 describe 时补标签与历史。
- 变更日志：需要提交区间时先保证区间两端在本地都可达。
- 增量构建对比：与上一次构建的提交做 diff，基线需先取到。
- 缓存策略配合：缓存键带上所需历史深度，避免缓存了浅历史又换基线。
- 发布流水线：发布步骤通常需要完整历史或标签，只在该步骤加深而不是全程全量。
- 排查历史问题：本地复现 blame 时先 unshallow，否则只能看到浅边界之后的内容。
按需加深示例
按需加深示例
git clone --depth 1 https://example.com/app.git # 最快起步：仅最新提交
cd app
git fetch --deepen=50 origin main # 按需补 50 层供 diff 使用
git diff --stat origin/main~20..HEAD # 对比最近的改动范围
git describe --tags --always # 需要版本号时先确认标签是否齐全
# 平台侧配置示例：job 的 fetch-depth 按任务分级设置任务与历史深度对照
| 任务 | 需要的历史 | 配置建议 |
|---|---|---|
| 编译打包 | 最新提交即可 | fetch-depth: 1 |
| 版本号/describe | 标签与足够深的历史 | fetch-depth: 0 或单独补标签 |
| 变更日志 | 提交区间两端可达 | 按需 deepen 到基线 |
| blame 排查 | 完整历史 | 单独全量检出 |
把「本次流水线需要的最小历史」写清楚（如最近 20 个提交），比统一全量克隆更省时间；需要完整历史的任务单独全量检出或先 unshallow，并在平台配置里注释原因，方便后人调整。