Git sparse-checkout 怎样只签出 monorepo 子目录

在 monorepo 中只处理一个应用或服务时，不必把所有目录都展开到工作区。Git 的 sparse-checkout 可以把工作树收缩到指定子目录：已有仓库直接执行 git sparse-checkout set --cone apps/web，需要多个目录时把路径一起写入，最后用 git sparse-checkout list 和 git status 核对结果。

官方地址：https://git-scm.com/docs/git-sparse-checkout

下面以一个包含 apps/web、services/api 和 tools/release 的 monorepo 为例。文章只讨论工作区如何按目录收缩、扩展和恢复，不把“没有展开”误解成“远端仓库已经删除”。

先确认仓库和目标目录

如果仓库已经在本地，先进入它，并确认没有需要保留的未提交文件。sparse-checkout 会改变工作区中哪些跟踪文件被展开；未提交改动、冲突文件或未忽略的未跟踪文件可能让目录看起来没有完全收缩。

# 进入 monorepo，并先确认当前分支和工作区状态
cd monorepo
git branch --show-current
git status --short

# 查看仓库顶层目录，确认目标路径拼写与大小写
git ls-tree -d --name-only HEAD

如果 git status --short 已经列出重要改动，先提交或暂存这些改动，再调整稀疏范围。不要直接把“目录没有出现”当成路径不存在；先用 git ls-tree 在当前提交中确认它是不是目录。

用 cone 模式只签出一个子目录

对常规 monorepo，优先使用 cone 模式。它接收目录而不是任意通配模式，命令更容易读，也能让 Git 用更适合目录树的规则处理工作区。

# 只展开 web 应用目录；--cone 明确采用目录模式
git sparse-checkout set --cone apps/web

# 查看当前生效的目录规则
git sparse-checkout list

# 观察工作区是否只保留目标内容及必要的父级文件
git status --short
find . -maxdepth 2 -type d | sort

set 会设置 sparse-checkout 所需的仓库配置，并根据参数更新工作目录。cone 模式下，目标目录下的文件会递归保留；顶层文件以及目标目录的父级目录中必要的文件也可能出现，这是目录模式的正常结果，不表示整个 monorepo 都被展开了。

如果这是刚克隆的仓库，也可以在克隆后立刻设置范围：

# 先完成普通克隆，再进入仓库设置稀疏范围
git clone https://example.com/acme/monorepo.git monorepo
cd monorepo

# 将工作区收缩到前端应用目录
git sparse-checkout set --cone apps/web

上面的远端地址只是命令结构示例；实际项目应替换成你有权限访问的仓库地址。若目标是减少首次传输量，应另行评估部分克隆或过滤器，它们和 sparse-checkout 解决的是不同层面的问题。

增加多个目录并核对“导出结果”

只处理前端和 API 服务时，可以一次设置两个目录，也可以在已有规则上追加。一次性设置适合重新定义范围，add 适合保留当前范围再增加模块。

# 重新定义范围：只展开前端和 API 两个目录
git sparse-checkout set --cone apps/web services/api

# 在不移除现有目录的情况下，再加入发布工具
git sparse-checkout add --cone tools/release

# 用规则列表和目录树双重核对最终范围
git sparse-checkout list
git status --short
find apps services tools -maxdepth 2 -type d 2>/dev/null | sort

可以把这一步理解成“提交一份目录选择单”：set 是重新提交选择，add 是补充选择，list 是查看当前已保存的选择。结果核对时重点看目标目录是否存在、无关的大目录是否没有被展开，以及 git status 是否出现意外删除。

工作区文件没有出现，不代表对象已经从 Git 历史或索引中消失。sparse-checkout 通过工作树和索引中的稀疏状态控制哪些内容展开，因此后续切换分支、合并或使用外部工具后，必要时需要重新应用规则。

规则没有生效时用 reapply 重新应用

合并、变基或某些外部工具操作可能临时把稀疏范围之外的文件展开；反过来，冲突和未提交改动也可能阻止 Git 立即收缩。先处理冲突或决定如何保留改动，再重新应用当前规则。

# 重新把现有 sparse-checkout 规则应用到工作区
git sparse-checkout reapply

# 若使用过稀疏索引且外部工具兼容性不好，可改回普通索引
git sparse-checkout reapply --no-sparse-index

# 再次查看已保存规则和工作区状态
git sparse-checkout list
git status --short

不要一看到多出文件就立刻执行强制删除。先检查是否有冲突、未跟踪文件或本地改动；这些内容可能是 Git 为避免数据丢失而保留的。确认工作区安全后，再决定是否清理不需要的文件。

如果需要匹配具体文件模式而不是目录，可以使用 --no-cone，但官方文档指出它有性能、语义和维护上的缺点，常规 monorepo 目录选择不建议从 cone 模式切换过去。

需要完整仓库时恢复工作区

当任务从单个模块扩大到整个仓库时，使用 disable 关闭 sparse-checkout，让工作树重新包含全部跟踪文件：

# 关闭稀疏检出并恢复完整工作区
git sparse-checkout disable

# 确认 sparse-checkout 已关闭，并检查恢复后的状态
git config --get core.sparseCheckout || true
git status --short

恢复前仍要处理未提交改动和冲突。关闭稀疏检出只改变工作区的展开范围，不会替你提交、丢弃或修复业务代码。后续如果再次只处理某个模块，可以重新执行 git sparse-checkout set --cone 目录。

相关问题

为什么目标目录旁边还有顶层文件？

cone 模式会保留顶层文件以及目标目录父级路径中的必要文件，这是目录规则的一部分。判断是否成功，应看无关子目录是否被收缩，而不是要求工作树只剩一个文件夹。

set 和 add 有什么区别？

set 用新的目录集合替换当前选择；add 在现有选择上追加目录。想缩小范围时用 set，想保留原模块并加入新模块时用 add。

为什么 sparse-checkout 后 status 里出现删除？

先确认是否把工作区状态和索引异常混在一起，并检查有没有真实的未提交改动、冲突或外部工具写入。不要直接提交这类变化；先用 git sparse-checkout list、git status 和 reapply 还原到可解释状态。

总结一下：monorepo 只处理一个子目录时，优先用 git sparse-checkout set --cone 目录；多个目录可继续用 add，每次用 list 和工作区状态核对，规则被合并或外部工具打乱后用 reapply，任务结束再用 disable 恢复完整工作区。