Git 單分支檢出實戰：淺層克隆、稀疏檢出與遷移場景全解析

當倉庫龐大（數 GB 歷史）、頻寬受限、或僅需特定分支部署時，完整 git clone 既浪費時間又佔用空間。Git 提供多種單分支檢出策略，本文對比各方案優劣，並給出生產環境最佳實踐。

方案對比速覽

核心命令詳解

1. 單分支完整歷史（官方推薦語法）

git clone --branch <分支名> --single-branch <倉庫URL> [目標目錄]
# 示例
git clone --branch release/v1.2 --single-branch https://github.com/user/repo.git ./deploy

注意： 目標目錄必須為空，否則報錯 fatal: destination path '.' already exists。

2. 淺層克隆：極速部署首選

# 僅獲取最新提交，體積最小
git clone --branch main --depth=1 https://github.com/user/repo.git

# 需要標籤時
git clone --branch v2.0 --depth=1 --tags https://github.com/user/repo.git

3. 稀疏檢出：大型 Monorepo 必備

git clone --filter=blob:none --sparse https://github.com/user/repo.git
cd repo
git sparse-checkout set frontend/src backend/api  # 僅檢出指定目錄

4. 遷移場景：現有目錄強制覆蓋

cd /existing/deploy/path
git init
git remote add -f origin https://github.com/user/repo.git
git config core.sparseCheckout true
echo "dist/*" > .git/info/sparse-checkout
git pull origin main --allow-unrelated-histories  # 強制合併無關歷史

CI/CD 流水線最佳實踐

# .gitlab-ci.yml / GitHub Actions 片段
variables:
  GIT_DEPTH: 1          # 淺層克隆
  GIT_STRATEGY: fetch   # 僅獲取變更

deploy_job:
  script:
    - git clone --branch $CI_COMMIT_REF_NAME --depth=1 $CI_REPOSITORY_URL .
    - ./build-and-deploy.sh

常見坑點與對策

• 淺層倉庫無法推送： 執行 git fetch --unshallow 恢復完整歷史
• --single-branch 後需切換分支：git fetch origin <新分支> && git checkout <新分支>
• 子模組未獲取： 加參數 --recurse-submodules --depth=1
• 標籤缺失： 顯式加 --tags 或後續 git fetch --tags

總結

單分支檢出不是單一命令，而是根據「體積敏感度、歷史需求、寫入權限、目錄結構」四個維度選型：部署用 --depth=1、開發用 --single-branch、Monorepo 用稀疏檢出、遷移用裸倉庫初始化。掌握組合拳，讓 Git 操作從「等待下載」變為「即時可用」。