Git稀疏检出仅控制工作区路径可见性，不减少对象下载；真正节省空间需结合partial clone（--filter=blob:none）与cone模式sparse-checkout，并用reapply刷新工作区。
Git 稀疏检出本身不支持“按分支过滤内容”，它只控制工作区中哪些路径可见，而所有分支的 commit、tree 对象仍完整存在于 .git 目录里——真正影响加载范围的是你 checkout 的分支 + .git/info/sparse-checkout（或 cone mode 规则）的交集。
为什么 checkout 特定分支后仍看到无关目录？
常见现象：已配置 sparse-checkout，执行 git checkout feature/ui 后，src/backend/ 还在工作区里。这不是 bug，而是因为你之前 checkout 过 main 或其他包含该路径的分支，Git 没自动清理残留。
- Git 不会自动删除未被当前 sparse 规则覆盖但已存在于工作区的文件——它只保证“新增检出”符合规则
- 必须手动触发重同步：
git read-tree -mu HEAD（强制根据当前索引和 sparse 规则刷新工作区） - 如果当前分支不含某些路径（比如
feature/ui根本没改过docs/），即使规则里写了/docs/，也不会检出——sparse-checkout 只决定“允许检出哪些”，不决定“一定能检出哪些”
如何确保切换分支时自动应用 sparse 规则？
默认情况下，git checkout 或 git switch 不会重新应用 sparse 规则，尤其当目标分支的 tree 结构与当前规则不完全匹配时。
使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……
- 每次切换分支后，先运行
git sparse-checkout reapply（Git 2.25+），它会读取当前规则并清理/补全工作区 - 更稳妥的做法是：切换前先清空工作区非
.git文件（git clean -fdx），再git checkout <branch>，最后git sparse-checkout reapply - 注意：
git clean -fdx会删掉所有未跟踪文件，慎用；生产环境建议加-n先预览
git sparse-checkout set 与分支内容不一致怎么办？
执行 git sparse-checkout set /src/frontend/ /package.json 后，git status 显示 clean，但 ls 为空——说明目标分支压根没有这些路径，或者它们在该分支的 commit 中不存在。
- 先确认路径真实存在：
git ls-tree -d <branch> src/frontend（检查目录是否存在）或git cat-file -t <branch>:package.json（检查文件是否存在） - cone mode 下路径必须以
/开头，且不能带通配符；写成src/frontend/（缺/）会被忽略 - 如果路径存在但未检出，可能是索引未更新：运行
git read-tree -m -u HEAD强制重载 - 某些 CI 环境（如 GitHub Actions）默认禁用 sparse-checkout，需显式设置
fetch-depth: 0并手动调用git sparse-checkout init --cone
超大项目中 sparse-checkout + partial clone 的组合陷阱
想省空间，很多人会同时用 --filter=blob:none 和 sparse-checkout。但这两者协作有严格前提：
-
--filter=blob:none只在克隆时生效，后续git fetch默认不继承该 filter；如需持续 lazy-fetch，得配git config remote.origin.partialCloneFilter blob:none - 首次
git checkout时若遇到未下载的 blob，Git 会自动 fetch ——但前提是远程支持 protocol v2；自建 Git 服务器若未启用 v2，会卡住或报错remote error: upload-pack: not our ref -
sparse-checkout规则对git log --oneline src/frontend/无效：log 仍扫描全部历史，只是文件列表被过滤；如需加速日志，得配合--follow或git log -- src/frontend/
最易被忽略的一点：sparse-checkout 是工作区层面的开关，它不改变 Git 内部对象图。哪怕你只检出一个 README.md，.git/objects 里依然存着整个仓库的 commit 和 tree——真正省空间靠的是 --filter，不是 sparse-checkout。两者必须配齐，且顺序不能错：先 filter，再 sparse，最后 reapply。
