克隆 Git 仓库的子目录

要在 Git 项目中处理某个目录，可以使用 sparse-checkout 选择工作树中要检出的路径。这样仍是在原始仓库中工作，不会创建一个只包含该目录的独立仓库。

Sparse Checkout 的作用与限制

普通克隆会将仓库文件检出到工作树中。Git 的 sparse-checkout 允许你选择要在工作树中填充的跟踪路径，同时检出内容仍属于原仓库，并保留其历史记录。如果你主要需要处理某个模块，例如一个同时包含 backend 和 documentation 目录的项目中的 frontend，这种方式就很实用。

选择路径并不保证下载的数据更少。Sparse checkout 控制的是工作树；实际获取的仓库数据量取决于克隆选项和 Git 配置。如果你需要一个拥有独立历史记录的项目，源项目必须为该模块提供单独的仓库。

使用 Sparse Checkout 克隆仓库

首先确认已安装的 Git 提供 sparse-checkout 命令，例如检查 git help -a 的输出。只有在该接口可用时，才运行下面的命令。这些命令会在不填充工作树的情况下克隆仓库，然后选择 frontend。请将示例中的仓库 URL 和目录名替换为你自己的值；下方的 URL 和路径仅作示例。

下面这个独立的 Bash 示例会创建一个小型本地仓库，并选择其中的 frontend 目录：

set -eu
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT

git init --quiet "$work/source"
git -C "$work/source" config user.name "Example User"
git -C "$work/source" config user.email "example@example.com"
mkdir -p "$work/source/frontend" "$work/source/backend"
printf 'app source\n' > "$work/source/frontend/app.txt"
printf 'service source\n' > "$work/source/backend/service.txt"
git -C "$work/source" add frontend backend
git -C "$work/source" commit -m "Add project modules" >/dev/null
branch=$(git -C "$work/source" branch --show-current)

git clone --no-checkout --branch "$branch" "$work/source" "$work/project" >/dev/null 2>&1
git -C "$work/project" sparse-checkout init --cone
git -C "$work/project" sparse-checkout set frontend
git -C "$work/project" sparse-checkout list

frontend

对于远程项目，相应步骤依次为 git clone --no-checkout <repository-url> my_project、cd my_project、git sparse-checkout init --cone 和 git sparse-checkout set frontend。请按顺序运行。所选路径相对于仓库根目录。如果你安装的 Git 不提供 sparse-checkout，可改用 git clone <repository-url> my_project 来获取完整工作树。

更改所选目录

要将所选路径替换为 backend 和 documentation，请在仓库中运行 git sparse-checkout set backend documentation。如果要保留已选的 frontend，并再添加一个目录，请使用 git sparse-checkout add backend。锥形模式适用于选择目录，因此请列出目录路径，而不要列出单个文件。

路径应相对于仓库根目录，并与跟踪路径的拼写和大小写一致。如果选择后没有显示预期文件，可以运行 git ls-tree --name-only HEAD 检查顶层条目，再设置正确的目录。也可以从根目录开始写出完整路径来选择嵌套目录，例如 frontend/components。

验证检出结果并排查常见问题

运行 git sparse-checkout list 查看所选路径，并运行 git status --short 检查工作树。使用 git rev-parse --show-toplevel 确认当前所在的是目标仓库；所选目录名都是相对于该根目录解释的。

如果命令不可用、该 Git 安装不支持 sparse-checkout 接口，或仓库工作流程不允许使用它，请改用完整克隆。如果目录已选中但缺少预期文件，请检查该路径是否存在于当前检出的提交中，以及拼写是否正确。工作树中原本就存在的未跟踪文件，即使路径不在稀疏选择范围内，也仍可能显示出来。

如需了解更多信息，请参阅 Git sparse-checkout 文档、git clone 文档和 git help 文档。