在團隊協作或維護大型專案時，經常會遇到一個常見問題，就是在執行 git clone 之後，發現用 git branch -a 或 git branch -r 看不到所有遠端分支 (remote branches)。這個現象不僅讓人困惑，也會影響開發流程，我們在實務上已經有兩三位同仁遇到了，所以我覺得可以寫一篇文章分享一下問題發生的原因與解法。
認識 git clone 背後的原理
當你執行 git clone 時，Git 會做以下幾件事：
-
建立本地儲存庫 (local repository)
初始化 .git 目錄與相關設定。
-
設定遠端 (remote)
自動設立遠端來源與抓取規則。
-
下載資料 (fetch)
預設會下載所有分支的 commit 歷史與內容。
-
建立本地分支 (branch)
根據遠端 HEAD 指向 (通常是 main 或 master 分支) 建立本地分支，其他分支則以「遠端追蹤分支」存在。
上述四個動作，其實可以換成以下命令：
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 命令就可以完成，所以初學者不容易遇到本篇文章描述的問題：
git clone https://github.com/doggy8088/github-copilot-configs.git
cd github-copilot-configs
但這個「預設」行為，會受到一些額外的參數或使用情境影響，導致你在 git clone 之後看不到完整的遠端分支列表。
常見導致分支缺失的情境
在維護大型專案時，或是使用 CI/CD 工具時，為了減少 git clone 這種「完整複製」帶來的衝擊，我們通常會限制下載的資料量，這樣可以加快速度與節省空間。以下是一些常見的情境：
-
淺層複製 (shallow clone)
如果你用 --depth 參數，例如：
git clone --depth 1 https://github.com/user/repo.git
這會只下載最近一次的 commit 物件，也會只抓取預設分支，其他遠端分支就不會同步下來，所以你用 git branch -r 是看不到任何其他遠端分支的。
注意: 在我們公司，大部分專案的「預設分支」都是 develop。
-
單一分支複製 (single-branch)
如果你用 --single-branch 或 --branch 參數，例如：
git clone --single-branch --branch develop https://github.com/user/repo.git
這會只下載 develop 分支，其他分支的資料與追蹤分支都不會同步，所以你用 git branch -r 也將看不到任何其他遠端分支。
-
遠端 fetch 設定異常
檢查 .git/config 裡的 remote.origin.fetch，正常應該是：
+refs/heads/*:refs/remotes/origin/*
如果只設定了單一分支，例如：
+refs/heads/main:refs/remotes/origin/main
那麼你就只會看到 main 分支，你用 git branch -r 也將看不到任何其他遠端分支。
-
本地快取未更新
如果你 git clone 之後，遠端有人新增分支，但你沒執行 git fetch，就看不到新分支。
解決方案
如果你在 git clone 之後，發現看不到所有遠端分支，可以按照以下步驟檢查與修正：
-
修正 fetch 規則
先檢查 fetch 設定：
git config --get remote.origin.fetch
如果不是 +refs/heads/*:refs/remotes/origin/*，請修正：
git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
注意: 上述命令會更新你的本機儲存庫下的 .git/config 檔案，讓 git fetch 時能夠抓取所有遠端分支。
-
取得所有分支資料
如果你是淺層複製，可以補全資料：
git fetch --unshallow
如果不是，直接 fetch 即可：
git fetch origin
-
強制同步分支清單
清理不存在的遠端分支並同步：
git remote prune origin
git fetch --all --prune --tags
-
檢查所有分支
git branch -a
你應該會看到像這樣的結果：
* main
remotes/origin/HEAD -> origin/main
remotes/origin/main
remotes/origin/develop
remotes/origin/feature-x
...
-
建立本地分支 (如有需要)
如果你要切換到遠端的某個分支 (例如 feature-x) ：
git checkout -b feature-x origin/feature-x
或
git switch feature-x
進階技巧與常見疑問
-
如果只想抓某幾個分支？
可以這樣設定：
git remote set-branches --add origin feature-x
git fetch origin feature-x
-
如果想一次把所有遠端分支都建立成本地分支？
可以用以下 Bash 腳本：
for branch in `git branch -r | grep -v '\->'`; do
git branch --track ${branch#origin/} $branch
done
-
如果 git clone 時就想要完整所有分支？
直接不要加 --depth、--single-branch 等參數即可，預設會抓所有分支。
結論
所以 git clone 後看不到所有遠端分支，絕大多數是因為git clone 時使用的參數或遠端 fetch 設定造成的，只要按照上述步驟檢查與修正，幾乎都能順利解決。
- 建議平時 clone 專案時，除非有特殊需求，盡量不要加
--depth 或 --single-branch。
- 如遇到分支列表異常，優先檢查
fetch 設定與執行 git fetch --prune。
希望這篇文章能幫助你快速排除 Git 分支看不到的問題，讓你的協作流程更順暢！
相關連結