Diagnose and fix the issue where a Git repository's remote branches are not visible, restoring the restricted fetch configuration to full mode.
Background Knowledge
When using git clone --depth=1 or git clone --single-branch to clone a repository, Git automatically restricts the fetch refspec in .git/config to pull only the default branch. For example:
[remote "origin"]
url = https://example.com/repo.git
fetch = +refs/heads/master:refs/remotes/origin/master
This causes both git fetch --all and git branch -a to see only the default branch, with other remote branches completely invisible. However, those branches still exist on the remote repository; the local configuration simply does not pull them.
Understanding this root cause is important—the problem is not the network or permissions, but a single line of local configuration.
Workflow
Step 1: Diagnose the problem
Run the following three commands together to gather enough information to determine the root cause:
# 1. 查看本地能看到的所有分支
git branch -a
# 2. 查看 fetch refspec 配置（关键诊断点）
git config --get remote.origin.fetch
# 3. 直接查询远程服务器上实际存在的分支
git ls-remote --heads origin
Decision logic:
git config --get remote.origin.fetch Output |
Meaning | Handling |
|---|---|---|
+refs/heads/master:refs/remotes/origin/master |
fetch is restricted to a single branch | Continue to Step 2 to fix |
+refs/heads/main:refs/remotes/origin/main |
Same as above (only the default branch name differs) | Continue to Step 2 to fix |
+refs/heads/*:refs/remotes/origin/* |
fetch configuration is normal | The problem is elsewhere; see "Other situations" |
Also compare the results of git branch -a and git ls-remote --heads origin :
- If
ls-remoteshows more branches thanbranch -a, it is confirmed to be a local fetch configuration issue - If
ls-remotealso has only one branch, then the remote really has only one branch, and no fix is needed
Step 2: Modify the fetch refspec
Change the fetch rule from a single branch to wildcard mode:
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
This command changes the fetch line in .git/config from:
+refs/heads/master:refs/remotes/origin/master
to:
+refs/heads/*:refs/remotes/origin/*
The asterisk * means match all branch names, which is the default configuration for a normal git clone(without --single-branch).
Step 3: Fetch all remote branches
git fetch --all
At this point, Git will fetch references for all branches from the remote according to the new wildcard rule.
Step 4: Verify the result
git branch -a
Confirm that all remote branches now appear under remotes/origin/ . Show the full branch list to the user.
Step 5 (optional): Complete the commit history
If the repository is a shallow clone (--depth=1), the above steps only complete the branch references, and the commit history is still truncated. If the user needs the full history:
git fetch --unshallow
This downloads the complete commit history, and the time required depends on the repository size. Only execute it when the user explicitly needs it, because the full history of a large repository can be very large.
Determine whether it is a shallow clone:
git rev-parse --is-shallow-repository
# true = 浅克隆，false = 完整历史
Other situations
If the fetch refspec is already a wildcard but branches are still not visible, troubleshoot in the following order:
- Network issue：
git ls-remote --heads originwhether it can successfully connect to the remote - Permission issue: whether there is permission to access all branches of the remote repository
- Stale cache: try
git remote update origin --pruneto clean up stale remote references - Multiple remotes: check
git remote -v, the branch may be on another remote
Notes
- Modifying the fetch refspec is a safe operation and will not affect existing local branches or the working tree
git fetch --allonly downloads references and related objects, and will not automatically create local branches or modify the working tree- If the user needs to work on a certain remote branch, they can use
git checkout <branch-name>to automatically create a tracking branch