git sparse checkout部分检出的配置【攻略】

Git sparse checkout仅控制工作区路径显示，不减少对象下载；真正省空间需结合partial clone（--filter=blob:none）与--cone模式初始化，并用reapply刷新工作区。

Git sparse checkout 听起来像“只拉几个文件进来”，但实际没那么简单——它管的是工作区里能看到哪些路径，对象库该下多大还是下多大。想省磁盘、省带宽，得把 partial clone 和 sparse-checkout 绑在一起用，否则只是“表面轻量”。

git sparse-checkout init --cone 是当前最稳的起点

别再用老办法往 .git/info/sparse-checkout 里一行行 echo 路径了。Git 2.25+ 推荐 git sparse-checkout init --cone，它启用“锥形模式”（cone mode），规则更简洁、性能更好、也少踩坑。

• --cone 模式下，指定目录名（比如 torch/nn），Git 自动包含它的所有子目录，外加所有父级路径（像 torch/ 和根目录下的 setup.py）
• 不加 --cone 就是传统非锥形模式，得写 !/docs/** 这种 gitignore 风格规则，容易漏、难调试
• 执行后 Git 自动设置 core.sparseCheckout=true 和 core.sparseCheckoutCone=true，并生成带注释的 .git/info/sparse-checkout

只检出、不下载：必须加 --filter=blob:none

光开 sparse-checkout 不管用。如果你先 git clone 再 git sparse-checkout set，Git 还是会把整个仓库的 blob（文件内容）全拉到 .git/objects 里——只是不解压到工作区而已。真正节省空间，得从克隆那一刻就过滤。

• 正确做法：git clone --filter=blob:none --no-checkout ，进目录后 git sparse-checkout init --cone && git sparse-checkout set torch/nn torch/cuda setup.py
• --filter=blob:none 表示跳过所有文件内容下载；后续首次访问某个文件时，Git 会按需 fetch（lazy fetch）
• 注意：该参数要求远程服务器支持 protocol v2（GitHub、GitLab 2021 年后基本都支持，自建 Gitea/GitServer 需确认）

git sparse-checkout set 后工作区没更新？试试 reapply

常见场景：执行 git sparse-checkout set src/web components/ui 后，src/web 目录空空如也，git status 也显示 clean。这不是失败，而是 Git 没触发重检出。

• 运行 git sparse-checkout reapply 强制重新应用规则，把匹配路径的文件从索引写入工作区
• 如果提示 “error: Your local changes would be overwritten”，说明那些路径下已有未跟踪文件（比如你手动创建过 src/web/index.html），Git 不敢覆盖——先 git clean -fd 或手动删掉冲突文件
• 也可以用 git read-tree -m -u HEAD 替代 reapply，但更底层、风险略高，日常推荐 reapply

切换分支时 sparse-checkout 规则会失效？不是 bug，是设计

在 sparse 模式下切分支，Git 默认只更新你“关心”的路径。比如在 main 分支只检出了 src/web，切到 feat/api 后，src/web 会更新，但 src/backend 即使该分支有改动也不会出现在工作区——这是预期行为，不是卡住了。

• 如果某次切分支后发现关键文件“消失”，先运行 git sparse-checkout list 确认当前规则是否还在
• 需要临时看全量？用 git sparse-checkout disable，它会清掉 SKIP_WORKTREE 标志并恢复全部文件（但不会重新下载 blob）
• 注意：git commit -a 在 sparse 模式下**不会**把未检出路径里的修改当删除处理，这点和直觉相反，但能避免误删

真正麻烦的从来不是怎么配 sparse-checkout，而是团队协作时别人没开、CI 流水线没设 filter、或者某个脚本硬编码了 ls src/ 却忘了目录可能根本不存在——这些地方比命令本身更容易翻车。