克隆 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。Cone 模式是為選取目錄而設計，因此請列出目錄路徑，而非個別檔案。

路徑請以儲存庫根目錄為基準，並沿用已追蹤路徑的拼法與大小寫。如果選取後沒有看到預期的檔案，可以用 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 說明文件。