Git sparse-checkout 怎么只恢复仓库中的一个目录

仓库很大、只想处理其中一个服务目录时，不必把所有文件都恢复到工作区。推荐用 Git 的 cone 模式：先用 git clone --sparse 建立稀疏工作树，再执行 git sparse-checkout set --cone 目标目录。这样目标目录及其子文件会出现，未选中的目录仍由 Git 管理，但不会完整展开到当前工作区。

先确认命令和目录边界

先看 Git 版本，再确认目标目录确实存在于当前分支。下面示例假设要处理仓库里的 services/api，目录名只是示例，不代表某个真实项目。

步骤一：从仓库窗口进入稀疏工作区

如果使用带界面的 Git 客户端，先打开仓库窗口，沿着“Repositories（仓库）→ 当前仓库 → Workspace（工作区）→ Sparse checkout（稀疏检出）”进入设置面板。不同客户端的文字可能略有不同，关键是找到仓库级的稀疏检出入口；不要把它和忽略规则或远端分支过滤混为一谈。

如果仓库还没有本地副本，用命令完成同一动作：

# 只建立稀疏工作树，避免一开始展开全部文件
 git clone --sparse  demo-repo
 cd demo-repo

# 查看 Git 版本，确认命令入口可用
 git --version

进入下一步前，界面应显示当前仓库名称、工作分支和稀疏检出入口；命令行方式则应已经进入仓库目录。

步骤二：只恢复一个目录

在客户端的目录选择面板中点击“Add directory（添加目录）”，选择仓库相对路径 services/api，确认模式为“Cone / Directory”，再点击“Apply（应用）”。如果客户端没有这个面板，直接执行下面的 Git 命令更可靠：

# 按目录启用 cone 模式，并让工作树只保留 api 目录
 git sparse-checkout set --cone services/api

# 列出当前规则，确认目标目录已被记录
 git sparse-checkout list

set 会更新稀疏规则并同步工作区。cone 模式不仅包含 services/api 下的文件，还会保留仓库根目录文件以及到达该目录所需的父级目录文件，因此看到少量顶层文件是正常现象。

验收时重点看三处：目录列表显示 services/api，文件树中能打开该目录，状态栏没有待应用的稀疏规则。图形界面只是操作提示，实际边界仍以 Git 命令返回的目录列表为准。

步骤三：追加目录和切换范围

如果后续需要同时查看前端目录，不要手工复制文件，使用追加操作：

# 在已有稀疏检出上追加另一个目录
 git sparse-checkout add services/web

# 再次核对两个目录是否都在规则中
 git sparse-checkout list

如果想从 services/api 切换到 docs，使用 set --cone docs，它会替换当前选择；如果只是增加目录才用 add。这两个动作不要混用，否则工作区范围会比预期更大。

步骤四：处理异常后恢复完整仓库

稀疏检出遇到合并冲突、外部工具把文件写回工作区，或者某些操作暂时展开了目录时，可以先处理冲突，再运行 git sparse-checkout reapply 重新套用规则。规则范围外若有未跟踪且未被忽略的文件，Git 可能保留目录并给出提示；先保存、提交或移动这些文件，不要直接删除。

# 重新应用已有的稀疏规则，不改变目录选择
 git sparse-checkout reapply

# 确认没有需要保留的本地改动后，恢复完整工作树
 git status --short
 git sparse-checkout disable

disable 会关闭稀疏检出并让完整跟踪文件重新出现在工作区。它不是删除仓库，也不会替你处理未提交改动；执行前仍要看 git status。

常见问题

为什么选了子目录后根目录文件也还在？

这是 cone 模式的正常行为。根目录文件和通往所选目录的父级目录文件可能被保留，便于项目识别和进入目标路径。

什么时候需要 --no-cone？

只有按文件模式、排除规则等复杂匹配时才考虑非 cone 模式。普通的“只恢复一个目录”优先使用 cone 模式，它的规则更直观，也更适合目录型工作区。

稀疏检出会不会删除我的未跟踪文件？

如果目录外存在未跟踪且未被忽略的文件，Git 会尽量避免直接移除并给出提示。先用 git status --short 检查，再决定是保留、移动还是提交。

这套路径的核心是把“选择目录”和“恢复全部文件”分成两个明确动作：用 set --cone 控制范围，用 list 验收，用 add 扩展，最后用 disable 回到普通工作树。