# 當在 git clone 之後看不到所有遠端分支的問題分析與解決方案

在團隊協作或維護大型專案時，經常會遇到一個常見問題，就是在執行 `git clone` 之後，發現用 `git branch -a` 或 `git branch -r` 看不到所有遠端分支 (remote branches)。這個現象不僅讓人困惑，也會影響開發流程，我們在實務上已經有兩三位同仁遇到了，所以我覺得可以寫一篇文章分享一下問題發生的原因與解法。

![Image](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/15acc4a6229583a0523d-e8f80ee6-d1c5-4b6d-bfdc-da96ad995724.webp)

### 認識 git clone 背後的原理

當你執行 `git clone` 時，Git 會做以下幾件事：

1.  **建立本地儲存庫** (local repository)
    
    初始化 `.git` 目錄與相關設定。
    
2.  **設定遠端** (remote)
    
    自動**設立遠端來源**與**抓取規則**。
    
3.  **下載資料** (fetch)
    
    預設會下載所有分支的 commit 歷史與內容。
    
4.  **建立本地分支** (branch)
    
    根據遠端 `HEAD` 指向 (通常是 `main` 或 `master` 分支) 建立本地分支，其他分支則以「**遠端追蹤分支**」存在。
    

上述四個動作，其實可以換成以下命令：

```bash
mkdir github-copilot-configs
cd github-copilot-configs

git init -b main
git remote add origin https://github.com/doggy8088/github-copilot-configs.git
git fetch origin
git checkout main
```

但其實一個 `git clone` 命令就可以完成，所以初學者不容易遇到本篇文章描述的問題：

```bash
git clone https://github.com/doggy8088/github-copilot-configs.git
cd github-copilot-configs
```

但這個「預設」行為，會受到一些額外的參數或使用情境影響，導致你在 `git clone` 之後看不到完整的遠端分支列表。

### 常見導致分支缺失的情境

在維護大型專案時，或是使用 CI/CD 工具時，為了減少 `git clone` 這種「完整複製」帶來的衝擊，我們通常會限制下載的資料量，這樣可以加快速度與節省空間。以下是一些常見的情境：

1.  淺層複製 (shallow clone)
    
    如果你用 `--depth` 參數，例如：
    
    ```bash
    git clone --depth 1 https://github.com/user/repo.git
    ```
    
    這會只下載最近一次的 commit 物件，也會只抓取**預設分支**，其他遠端分支就不會同步下來，所以你用 `git branch -r` 是看不到任何其他遠端分支的。
    
    > 注意: 在我們公司，大部分專案的「預設分支」都是 `develop`。
    
2.  單一分支複製 (single-branch)
    
    如果你用 `--single-branch` 或 `--branch` 參數，例如：
    
    ```bash
    git clone --single-branch --branch develop https://github.com/user/repo.git
    ```
    
    這會**只下載 `develop` 分支**，其他分支的資料與追蹤分支都不會同步，所以你用 `git branch -r` 也將看不到任何其他遠端分支。
    
3.  遠端 `fetch` 設定異常
    
    檢查 `.git/config` 裡的 `remote.origin.fetch`，正常應該是：
    
    ```
    +refs/heads/*:refs/remotes/origin/*
    ```
    
    如果只設定了單一分支，例如：
    
    ```
    +refs/heads/main:refs/remotes/origin/main
    ```
    
    那麼你就只會看到 `main` 分支，你用 `git branch -r` 也將看不到任何其他遠端分支。
    
4.  本地快取未更新
    
    如果你 `git clone` 之後，遠端有人新增分支，但你沒執行 `git fetch`，就看不到新分支。
    

### 解決方案

如果你在 `git clone` 之後，發現看不到所有遠端分支，可以按照以下步驟檢查與修正：

1.  修正 fetch 規則
    
    先檢查 fetch 設定：
    
    ```bash
    git config --get remote.origin.fetch
    ```
    
    如果不是 `+refs/heads/*:refs/remotes/origin/*`，請修正：
    
    ```bash
    git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
    ```
    
    > 注意: 上述命令會更新你的本機儲存庫下的 `.git/config` 檔案，讓 `git fetch` 時能夠抓取所有遠端分支。
    
2.  取得所有分支資料
    
    如果你是淺層複製，可以補全資料：
    
    ```bash
    git fetch --unshallow
    ```
    
    如果不是，直接 fetch 即可：
    
    ```bash
    git fetch origin
    ```
    
3.  強制同步分支清單
    
    清理不存在的遠端分支並同步：
    
    ```bash
    git remote prune origin
    git fetch --all --prune --tags
    ```
    
4.  檢查所有分支
    
    ```bash
    git branch -a
    ```
    
    你應該會看到像這樣的結果：
    
    ```
    * main
      remotes/origin/HEAD -> origin/main
      remotes/origin/main
      remotes/origin/develop
      remotes/origin/feature-x
      ...
    ```
    
5.  建立本地分支 (如有需要)
    
    如果你要切換到遠端的某個分支 (例如 `feature-x`) ：
    
    ```bash
    git checkout -b feature-x origin/feature-x
    ```
    
    或
    
    ```bash
    git switch feature-x
    ```
    

### 進階技巧與常見疑問

1.  如果只想抓某幾個分支？
    
    可以這樣設定：
    
    ```bash
    git remote set-branches --add origin feature-x
    git fetch origin feature-x
    ```
    
2.  如果想一次把所有遠端分支都建立成本地分支？
    
    可以用以下 Bash 腳本：
    
    ```bash
    for branch in `git branch -r | grep -v '\->'`; do
      git branch --track ${branch#origin/} $branch
    done
    ```
    
3.  如果 git clone 時就想要完整所有分支？
    
    直接不要加 `--depth`、`--single-branch` 等參數即可，預設會抓所有分支。
    

### 結論

所以 git clone 後看不到所有遠端分支，絕大多數是因為**git clone 時使用的參數**或**遠端 fetch 設定**造成的，只要按照上述步驟檢查與修正，幾乎都能順利解決。

-   建議平時 clone 專案時，除非有特殊需求，盡量不要加 `--depth` 或 `--single-branch`。
-   如遇到分支列表異常，優先檢查 `fetch` 設定與執行 `git fetch --prune`。

希望這篇文章能幫助你快速排除 Git 分支看不到的問題，讓你的協作流程更順暢！

### 相關連結

-   [Git - git-fetch Documentation](https://git-scm.com/docs/git-fetch)
-   [git - How to fetch all remote branches? - Stack Overflow](https://stackoverflow.com/a/39957858/910074)
-   [使用 Git 的部分複製功能 (Partial Clones) 快速下載專案原始碼](/post/2023/10/31/How-to-use-Git-Partial-Clones)