Git稀疏检出失效：如何仅从Git仓库拉取单个目录？

修复现有仓库的步骤 #

如果已经执行了初始命令但仍拉取全量仓库，按以下步骤排查修复：

1. 确认稀疏检出配置已生效：

   git config --get core.sparsecheckout
   

   若返回值不是true，重新设置：

   git config core.sparsecheckout true
   

2. 重置并修正sparse-checkout文件（避免重复或格式错误）：

   echo "<dir1>/" > .git/info/sparse-checkout
   

   注意：路径后加/确保匹配目录而非同名文件，且路径需与仓库内实际路径完全一致（区分大小写）。
3. 触发稀疏检出更新（旧版Git需手动执行此步骤）：

   git read-tree -mu HEAD
   

4. 重新拉取目标分支：

   git pull origin <pull_branch_name>
   

更可靠的替代方法（Git 2.25+） #

Git 2.25版本后推出了原生的git sparse-checkout命令，比手动配置更稳定：

mkdir <dir> && cd <dir>
git init
git remote add origin <GIT_URL>
# 初始化稀疏检出，--cone模式适合单目录场景，性能更优
git sparse-checkout init --cone
# 添加需要拉取的目标目录
git sparse-checkout add <dir1>/
# 拉取目标分支
git pull origin <pull_branch_name>

超大型仓库最优解：部分克隆 #

如果仓库体积极大，可直接用部分克隆减少初始拉取的负载，结合稀疏检出：

# --filter=blob:none 只拉取提交记录和目录结构，不拉取文件内容
# --sparse 直接初始化稀疏检出
git clone --filter=blob:none --sparse <GIT_URL> <dir>
cd <dir>
# 添加需要的目录
git sparse-checkout add <dir1>/

内容的提问来源于stack exchange，提问作者Coder117