Git sparse-checkout怎样在 cone 模式与文件模式间切换

Git sparse-checkout 的两种输入方式不要混着理解：cone 模式接收目录，文件模式（non-cone）接收 gitignore 风格的路径规则。如果你的目标是保留 src/、docs/ 这类完整目录，优先使用 cone；如果需要只留下某类文件、排除某些子目录，再考虑文件模式。

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

先确认当前稀疏检出模式

我通常先从仓库的稀疏检出设置入口开始，而不是直接追加一条看不懂的规则。原创说明图中的“Cone directories”和“File patterns”是两个不同的操作入口：前者填写目录，后者填写路径模式。它们对应的是 Git 命令的两种参数语义，不是同一输入框换个名字。

在仓库根目录执行下面的命令，可以先知道当前保存的目录或规则：

# 查看当前稀疏检出规则，不会自动恢复所有文件
git sparse-checkout list

# 查看当前规则是否符合 Git 识别的稀疏规则形式
git sparse-checkout check-rules

list 适合快速确认“现在保留了什么”；check-rules 适合发现规则格式或模式语义不符合预期的情况。如果仓库还没有启用 sparse-checkout，可以先按下一节的 cone 方式初始化。

用 cone 模式按目录保留代码

cone 是默认更稳妥的目录选择方式。它把参数当成目录名处理，适合“保留后端源码和文档，但不要拉出测试数据目录”这样的工作区。每个目录下的内容会作为一个整体进入稀疏范围，阅读者不必手写大量通配符。

# 第一次启用时选择 cone 目录模式
git sparse-checkout init --cone

# 只保留 src 和 docs 两个目录；参数按目录解释
git sparse-checkout set --cone src docs

# 后续想再增加 examples，重新设置目录集合
git sparse-checkout set --cone src docs examples

如果仓库之前已经处于 non-cone，仍建议在重新设置时显式加上 --cone。这样做的重点不是“切换一个界面开关”，而是让本次命令明确告诉 Git：后面的参数是目录集合。路径名称中有空格时，用当前 shell 的引号规则包住目录名。

切换到文件模式处理精细匹配

当需求从“保留目录”变成“只保留特定文件类型或排除某类路径”时，可以切到 non-cone。文件模式把参数按 gitignore 风格规则处理，表达能力更强，但也更容易因为斜杠、否定规则和顺序造成误解。

# 显式切换到文件模式，后面的参数按路径规则解释
git sparse-checkout set --no-cone '/*' '!/docs/' '/src/**/go.mod'

# 查看已经写入的文件模式规则
git sparse-checkout list

上面的规则表达的是一种“保留根部可见内容、排除 docs、匹配 src 层级下的 go.mod”的思路。规则要根据仓库目录结构调整，不能把 cone 模式里的目录列表直接当成 non-cone 规则使用。Git 官方文档也提示，non-cone 虽然灵活，但存在与部分能力配合不佳等边界；如果目录模式已经能满足需求，就不必为了少写一个目录而切换。

切回 cone 模式时重写目录集合

如果发现文件模式越来越难维护，切回 cone 时不要只删除一两行旧规则。用 set --cone 重新给出完整目录集合，让 Git 按目录语义重建稀疏范围。

# 用完整目录集合重新建立 cone 规则
git sparse-checkout set --cone src docs

# 切回后列出当前目录集合，确认模式已回到目录语义
git sparse-checkout list

切换成功后，规则列表的含义也变了：cone 模式下它更接近“哪些目录定义了稀疏范围”，non-cone 下则是“哪些模式写入了规则文件”。因此不要只比较输出行数，先确认当前模式，再解释每一行的作用。

用 reapply 处理合并后的暂时路径

合并、变基或冲突处理可能会让工作区暂时出现原本不在稀疏范围内的路径。此时先保留当前规则，再重新应用一次，而不是立即切换模式：

# 重新把当前稀疏规则应用到工作区
git sparse-checkout reapply

# 再次查看规则，确认 reapply 没有改变模式本身
git sparse-checkout list

reapply 的作用是重新让工作区服从已有规则，不是把 cone 转成 non-cone，也不是从远端重新下载仓库。把“模式切换”和“规则重新应用”分开处理，排错时更容易判断到底是输入语义错了，还是工作区暂时被合并操作唤出了额外路径。

两种模式怎样选择

常见问题

cone 模式和文件模式能不能同时写？

不要把两种输入语义混在一次设置中。一次切换明确选择一种模式，再按该模式的规则重新给出完整输入。

为什么 set 之后目录没有按预期出现？

先检查是否误用了模式：cone 需要目录，non-cone 需要 gitignore 风格规则；随后运行 list 和 check-rules 查看保存的内容。

只想恢复全部文件应该怎么做？

可以使用 git sparse-checkout disable 关闭稀疏检出。关闭前先确认工作区没有需要保留的未提交变更。

把 Git sparse-checkout 当成“输入语义明确的工作区范围配置”会更容易维护：目录需求优先 cone，精细匹配才用 non-cone；每次切换都显式写模式，最后用 list、check-rules 或 reapply 进行对应层次的确认。