浅克隆深入

学完这篇你会掌握什么

• 理解 浅克隆深入 的核心作用和适用场景
• 掌握 浅克隆深入 的基本用法和常用参数
• 深入理解 git clone --depth 和 --shallow-since 的工作原理、适用场景以及浅克隆的局限性与风险。
• 理解 概述 相关的概念
• 掌握 基本用法 相关的操作
• 知道在什么场景下使用该命令，什么场景下避免使用

先想一个问题

你的 Git 仓库越来越大，clone 越来越慢，日常操作也开始卡顿。你想知道有哪些方法可以优化，又不确定哪些优化手段适合自己的项目场景。

概述

浅克隆（shallow clone）通过限制下载的历史深度来加速克隆操作。在 CI/CD、大型仓库和快速原型开发中非常实用。

基本用法

--depth

# 只克隆最近 1 次提交
git clone --depth 1 https://github.com/user/repo.git

# 克隆最近 10 次提交
git clone --depth 10 https://github.com/user/repo.git

每个 --depth N 会下载最近 N 次提交及其对应的文件快照。

--shallow-since

# 克隆指定日期之后的所有提交
git clone --shallow-since="2025-01-01" https://github.com/user/repo.git

# 与 --depth 结合使用
git clone --depth 100 --shallow-since="2025-01-01" https://github.com/user/repo.git

--shallow-exclude

# 克隆除特定提交及其祖先之外的部分
git clone --shallow-exclude="v1.0" https://github.com/user/repo.git

适用场景对比

局限性

1. 无法完整访问历史

# 浅克隆中无法访问超出 --depth 的提交
git log --oneline
# 只显示浅层的历史

2. 无法推送

# 默认浅克隆不能 push 到远端
git push origin main
# 错误: failed to push some refs
# 需要先 unshallow

3. 无法从浅层创建新分支（部分场景）

4. 某些 Git 操作受限

git merge
git log --all  # 不完整
git bisect     # 不完整

转换为完整克隆

# 通过 fetch 补全历史
git fetch --unshallow

# 或指定深度
git fetch --depth=500

# 完成后即变为完整克隆

与 partial clone 的组合

# 同时使用 shallow + blobless partial clone
git clone --depth 1 --filter=blob:none https://github.com/user/repo.git

# 按需获取 blob
git checkout feature-branch  # 自动下载需要的 blob

CI 最佳实践

# GitHub Actions - 默认已经是 shallow clone
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 需要完整历史时设为 0

# GitLab CI
variables:
  GIT_DEPTH: 1

继续学习

1. performance/partial-clone — Partial clone 详解
2. performance/gc-repack-strategies — gc/repack 策略
3. performance/large-repo-optimization — 大型仓库优化

给你的练习

1. 在一个测试仓库中练习该命令的基本用法，观察执行前后的状态变化
2. 尝试该命令的不同参数选项，对比输出结果的差异
3. 模拟一个需要使用该命令的实际场景，完整走一遍操作流程

延伸阅读

沿着同一主题继续深入：

• Partial Clone：按需获取 Git 对象
• Scalar Git 深入