稀疏检出仅控制工作区文件可见性，与分支无关；它不创建、切换或隔离分支，只在checkout时决定哪些路径写入工作目录。
稀疏检出不是“分支管理工具”，它只控制工作区文件可见性，和分支本身无关——你不能靠 git sparse-checkout 创建、切换或隔离分支。
稀疏检出和分支是两个正交机制
很多人误以为用 git sparse-checkout set apps/payment 就能“只拉 payment 分支”，这是典型混淆。Git 的分支（branch）指向的是 commit，而稀疏检出（sparse-checkout）只在 checkout 阶段决定哪些路径写入工作目录。即使你在 feature/auth 分支上执行 git sparse-checkout set libs/auth，你看到的仍是该分支下所有 commit 中满足路径规则的文件，而不是“auth 分支”——根本不存在这个分支。
常见错误现象：
-
git checkout feature/checkout后发现apps/web目录不见了，但git log --oneline apps/web却能查到历史 —— 因为路径没被 sparse 规则覆盖，只是没检出 - 在
main上 sparse 检出docs/，然后git switch -c new-docs，再git add .却把整个docs/提交了，但libs/core里刚改的代码没被纳入 —— 这不是 bug，是预期行为：sparse 只影响工作区呈现，不影响暂存区逻辑
真正需要的是“路径+分支”的组合策略
在 monorepo 中做模块化开发，核心诉求其实是：**每次只关注一个子路径下的变更，并确保该路径在目标分支上有独立演进能力**。这需要三件事协同：
- 使用
git worktree为不同模块/分支创建隔离工作区（例如git worktree add ../payment-worktree main） - 每个 worktree 内启用 cone mode 稀疏检出：
git sparse-checkout init --cone，再git sparse-checkout set apps/payment - 配合
git switch -c feature/payment-v2在该 worktree 中新建分支，所有操作天然限定在apps/payment路径内（git status不会显示其他路径变更）
注意：--cone 模式强制要求路径模式是前缀式（如 apps/payment/**），不支持 **/test.js 这类 glob；它更安全、性能更好，且与 git add . 行为一致 —— 这是避免误提交的关键。
CI 构建时 sparse-checkout 的陷阱
很多团队在 CI 脚本里写 git clone --filter=tree:0 -n $URL + git sparse-checkout set apps/web，结果构建失败，报错 fatal: pathspec 'apps/web' did not match any files。原因很直接：你没指定要检出哪个 commit。
必须显式运行 git checkout $BRANCH_NAME 或 git restore --source=$COMMIT --staged --worktree -- apps/web，否则 Index 是空的，sparse 规则无处生效。
推荐做法：
- CI 使用
git clone --filter=tree:0 --no-checkout $URL cd repo && git sparse-checkout init --cone && git sparse-checkout set apps/web-
git checkout origin/main（或你实际要构建的 ref）—— 这一步不能省
漏掉最后一步，npm install 或 make build 就会因找不到 package.json 直接退出。
cone mode 下 git add . 的行为边界
在 cone mode 启用后，git add . 不再递归扫描整个工作目录，而是只遍历 sparse 规则匹配的路径及其子目录。这是优点，也是危险点：
- 如果你在
apps/web下新增了apps/web/src/utils/new.js，git add .会正常加入暂存区 - 但如果你不小心在
libs/shared（未被 sparse 包含）下改了一个文件，git add .完全无视它 —— 看似安全，实则容易遗漏跨模块修复 - 更隐蔽的问题：
git add -u会把已跟踪但被 sparse 排除路径下的修改标记为 deleted，而git add -A在 cone mode 下等价于git add .，不会恢复这些文件
所以，别依赖 git add . 做“全量暂存”。对涉及多路径的变更，明确用 git add apps/web/ libs/shared/ 列出具体路径。
真正难的不是配置 sparse-checkout，而是让团队理解：它不改变 Git 的分支模型，也不替代权限或发布流程；它只是把工作区从“全部文件”变成“你声明的视图”。一旦路径规则和分支生命周期脱节，问题就会出现在最意想不到的地方——比如某次 git merge 后，git status 显示 clean，但 git diff HEAD 却有几百行差异，只因为 sparse 规则没覆盖新引入的 config 目录。
