必须启用cone模式，因非cone模式需手动写完整路径规则、不支持递归通配符且易出错；正确流程是先git sparse-checkout init --cone，再用set或add添加目录路径，结尾斜杠可选但建议统一。
git sparse-checkout 只拉指定文件夹必须开 cone 模式
默认 sparse-checkout 是“非 cone”模式，它要求你手动写完整路径规则，且不支持通配符递归（比如 src/* 会失败）。实际中几乎没人用非 cone 模式——容易漏文件、难维护、git read-tree -mu HEAD 容易报错。
正确做法是初始化时加 --cone 参数，它启用简化规则：路径末尾加 /* 表示该目录下所有内容（含子目录），不加则只匹配单个文件或空目录。
-
git sparse-checkout init --cone是必须的第一步，不能跳过 - 之后再用
git sparse-checkout add src/ docs/添加路径，注意结尾斜杠可选但建议统一加（src/和src效果相同） - 如果之前没 init 过，直接
echo "src/" >> .git/info/sparse-checkout会无效——因为 config 没开 sparseCheckout，也不会自动创建.git/info/sparse-checkout
拉取前必须先 fetch 再 pull，不能跳过 fetch
很多人执行 git pull origin main 后发现文件夹没出来，其实是 pull 前没 fetch 到远程最新提交。sparse-checkout 只影响工作区检出，不改变 fetch 行为。
标准流程是：
-
git remote add origin <url></url>（如果还没关联） -
git fetch origin main（明确 fetch 目标分支，避免默认拉所有分支） -
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 其他分支。
