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 结构与当前规则不完全匹配时。

Git Changelog Generator

使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……

下载

• 每次切换分支后，先运行 git sparse-checkout reapply（Git 2.25+），它会读取当前规则并清理/补全工作区
• 更稳妥的做法是：切换前先清空工作区非 .git 文件（git clean -fdx），再 git checkout <branch></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</branch>（检查目录是否存在）或 git cat-file -t <branch>:package.json</branch>（检查文件是否存在）
• 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。