git sparse-checkout 只拉取指定文件夹必须启用 cone 模式
许多开发者可能并不清楚，Git 的 sparse-checkout 默认处于“非 cone”模式。这意味着你需要手动编写完整的路径规则，而且不支持通配符递归——例如，你写入 src/*，它根本不会生效。在实际项目开发中，几乎没有人会采用非 cone 模式，因为这种方式极易遗漏文件、维护成本高昂，在执行 git read-tree -mu HEAD 时也常常出现错误。因此，正确的做法是在初始化时就直接加上 --cone 参数。
那么，cone 模式具体该如何使用呢？初始化时携带 --cone 参数，即可启用简化后的规则：在路径末尾添加 /* 表示该目录下的所有内容（包含子目录），不加则仅匹配单个文件或空目录。以下几个关键点值得留意：
git sparse-checkout init --cone是必须执行的第一步，不可跳过。- 之后通过
git sparse-checkout add src/ docs/来添加所需路径。请注意，结尾的斜杠是可选的，但建议统一加上——src/与src的效果完全相同。 - 如果你之前没有执行过 init 操作，直接向
.git/info/sparse-checkout写入内容是不起作用的，因为配置中并未开启 sparseCheckout，系统也不会自动创建这个文件。
拉取前必须先执行 fetch 再 pull，不能跳过 fetch 步骤
另一个常见的误区是，不少开发者直接运行 git pull origin main，结果却发现目标文件夹并没有出现。问题在于，执行 pull 之前并未通过 fetch 获取远程的最新提交。sparse-checkout 仅影响工作区的检出行为，并不会改变 fetch 的工作方式。因此，标准的操作流程应该是：
- 首先关联远程仓库：
git remote add origin（如果尚未关联） - 然后明确指定要 fetch 的目标分支：
git fetch origin main（避免默认拉取所有分支） - 接着使用
git sparse-checkout set src/ tests/（推荐使用set而非add，因为它会覆盖旧规则并自动重置工作区） - 最后执行
git checkout origin/main或git switch -c main --track origin/main创建本地分支并完成检出
需要特别说明的是：git pull 等同于 fetch + merge，但在 sparse-checkout 环境下，merge 操作可能因为缺失文件而引发冲突或静默失败，因此更为稳妥的做法是采用 fetch + checkout 的组合。
文件夹路径写错会导致检出为空，且没有任何提示信息
还有一个很容易踩中的陷阱：sparse-checkout 并不会校验路径是否存在。例如，你把 src/frontend 误写成了 src/frontent，或者忽略了父目录直接写成 frontend/，执行 git checkout 后工作区就会是空的——连 .git 外壳都看不到，看起来就像什么都没拉取下来。那么，如何进行排查呢？
- 先确认远程分支中确实存在该路径：
git ls-tree -d origin/main -- src/（-d 参数仅列出目录） - 检查
.git/info/sparse-checkout文件的内容是否与git ls-tree的输出一致 - 运行
git sparse-checkout list查看当前生效的规则（Git 2.32 及以上版本支持） - 临时关闭 sparse-checkout：
git config --unset core.sparsecheckout，然后执行git read-tree -mu HEAD看能否完整检出——以此判断是路径问题还是权限或网络问题
git archive 更适用于一次性导出，不要将其当作工作流的替代方案
最后需要提及的是，有人看到 git archive --format=zip --output=out.zip origin/main:src/ 能够快速获取文件夹，就误以为这是“拉取”的正确方式。但这条命令生成的是快照 ZIP，不包含 Git 历史记录，无法进行 commit、push，也无法跟踪后续的变更。它的适用场景非常有限：
- 在 CI/CD 构建过程中提取源码片段（例如只打包
dist/用于发布） - 向非开发者提供一份静态代码包
- 确定文件始终只读、不会修改、也不会提交回仓库
只要后续需要进行 git add / commit / push 操作，就必须遵循 sparse-checkout 流程——archive 提供的是快照，而 sparse-checkout 创建的是活跃的工作区。
真正容易被忽视的一点是：sparse-checkout 初始化之后，.git 目录中仍然存储着完整的对象数据库（只是工作区没有展开），因此磁盘占用并不会明显减少。如果目标确实是“节省空间”，需要配合 shallow clone（--depth 1）一起使用，但要注意 shallow 仓库无法执行 push 操作，也不能 checkout 其他分支。
