🚀 如何从 GitHub 大仓库中只下载指定目录（以 “初中” 目录为例）

在使用 GitHub 时，我们有时会遇到仓库体积特别大（例如几十 GB），
但其实我们只需要其中某一个目录，比如 初中、高中 或 小学 等。
本文将介绍一种 高效、不下载整个仓库 的方法，只获取所需目录内容。

---

🧠 背景问题

有时候你会遇到类似这种仓库：

https://github.com/xxxxxx/ChinaTextbook

整个仓库体积高达 41GB+，
而你只想下载其中的：

https://github.com/xxxxxx/ChinaTextbook/tree/master/初中

如果直接执行：

git clone https://github.com/xxxxxx/ChinaTextbook.git

那会把整个仓库下载下来，非常耗时且占用大量磁盘空间。

---

✅ 解决方案：使用 git sparse-checkout

git sparse-checkout 是 Git 2.25+ 提供的一个功能，
可以让我们只检出（checkout）仓库中部分目录，
从而节省时间与存储。

---

🧩 实操步骤

以下是在 Windows 下的完整命令流程（macOS / Linux 同理）：

# 1. 克隆仓库（但不立即下载文件内容）
git clone --filter=blob:none --no-checkout https://github.com/xxxxxx/ChinaTextbook.git

# 2. 进入仓库目录
cd ChinaTextbook

# 3. 启用稀疏检出模式
git sparse-checkout init --cone

# 4. 只设置要下载的目录（例如 “初中”）
git sparse-checkout set 初中

# 5. 检出主分支
git checkout master

⚠️ 注意：

• 有些新仓库的默认分支是 main，但老仓库一般是 master。

• 如果执行 git checkout main 提示错误：

  error: pathspec 'main' did not match any file(s) known to git
  

  那就说明该仓库使用的是 master 分支。

---

🔍 如何确认分支名？

执行以下命令查看分支：

git branch -a

示例输出：

* master
  remotes/origin/master

说明主分支是 master，那么就用：

git checkout master

---

🎯 结果

执行完以上命令后，本地只会下载仓库中 初中 目录下的文件，
不会下载整个 40GB 的仓库内容！

目录结构大概如下：

ChinaTextbook/
 └── 初中/
      ├── 语文/
      ├── 数学/
      ├── 英语/
      └── ...

---

📦 想下载多个目录？

如果你还想同时下载多个目录，比如：

初中
高中
小学

可以这样设置：

git sparse-checkout set 初中 高中 小学

Git 会自动拉取这些目录。

---

🧹 清理与退出稀疏模式

如果后续需要恢复完整仓库，可以执行：

git sparse-checkout disable

这样就能重新下载整个仓库的内容。

---

🏁 总结

步骤	命令	说明
1	git clone --filter=blob:none --no-checkout <repo>	只拉取元数据
2	git sparse-checkout init --cone	启用稀疏检出
3	git sparse-checkout set <目录>	指定要下载的子目录
4	git checkout master	检出实际内容

---

🧰 适用场景

• 大型数据集仓库（如 10GB+）
• 只想获取某个子目录（如 dataset/train）
• GitHub 下载限速或空间不足
• 迁移部分目录到 Gitee 或本地存储

---

✨ 结语

通过 git sparse-checkout，
我们可以像“点菜”一样精准获取所需目录，
再也不用被庞大的仓库体积困扰！