Git仓库无法切换至已存在的client1分支问题求助

本地克隆的Git仓库中，远程存在client1分支，但执行git checkout client1时报错：

fatal: reference is not a tree: client1
NativeCommandExitException: Program "git.exe" ended with non-zero exit code: 128.

其他客户端分支可正常切换。尝试通过以下命令创建本地分支并关联远程：

git checkout -b client1 origin/client1
git branch --set-upstream-to=origin/client1 client1

操作成功，但切换到该分支时始终收到警告：warning: refname 'client1' is ambiguous.

当前使用GitPython自动化切换所有客户端分支，对比其与main分支特定文件的diff，但client1等分支出现上述错误或警告。已通过git show-ref --heads | grep 'client1'确认远程存在该分支，仓库为全新克隆，全局Git配置仅包含基础设置：

user.name=SAY-MY-NAME
user.email=guss-maill@company.com
fetch.prune=true

client1分支基于main分支创建多年，偶尔执行git merge main同步变更，当前比main分支有更多超前提交。

附相关命令输出：
执行git cat-file -p origin/client1; git cat-file -p origin/client1^{tree}的输出：

tree 07a8a9cf1c77ae9bf82ec27a66d2d29d880028cd
parent 44f13b1dea8d46a6cb75c0bc7eec381b2edbe341
author support-adv<support.adv@company.com> 1689602681 -0300
committer support-adv<support.adv@company.com> 1689602681 -0300

client1 - Update version manually IOS
040000 tree 0a871f58d94685e7c10c5a287374b983e8720e90    .fvm
100644 blob 18e95f252defc45e73c3a1f9d8a2a59216a45eea    .gitignore
040000 tree 22f59bec469873082fea408cd1a505b6402a6509    .vscode
100644 blob 3862e40bfbc0450aa40c247472c07eb306c8b2c1    README.md
040000 tree 474a601150e28bdbc37e8fba292176a803aa914a    ReleaseV5
100644 blob 5e948bb1a39a59a539d24a6ac450f71d70ab51ca    diretrizes.md
040000 tree 633a38f482975801a7549a15d9039d0d9a1672cc    smart

问题原因 #

1. 初始切换失败：全新克隆后本地无client1分支的缓存引用，直接执行git checkout client1时，Git无法在本地找到对应分支引用，且未自动从远程拉取该分支的引用信息。
2. 分支名称歧义：创建本地client1分支后，Git中同时存在本地分支refs/heads/client1和远程跟踪分支refs/remotes/origin/client1两个同名引用，直接使用client1时Git无法明确指向目标，因此抛出歧义警告。

解决方法 #

1. 修复初始分支切换失败 #

先拉取所有远程分支的最新引用：

git fetch origin

再使用跟踪命令自动创建并关联本地分支：

git checkout --track origin/client1

该命令等价于手动创建分支并设置上游的组合操作，更简洁且不易出错。

2. 消除分支名称歧义警告 #

有两种可行方案：

• 方案一：使用完整引用路径
  操作分支时指定完整的引用路径，明确区分本地和远程分支：
  • 切换本地分支：git checkout refs/heads/client1
  • 在GitPython中调用时，同样使用完整引用路径，避免歧义。
• 方案二：关闭歧义警告（不推荐）
  若无需区分本地与远程分支的同名引用，可通过配置关闭警告：

  git config --global core.warnAmbiguousRefs false
  

  此方式仅隐藏警告，未从根源解决引用歧义问题，不建议长期使用。

3. 验证修复效果 #

切换分支检查是否仍有警告：

git checkout client1

查看分支关联状态：

git branch -vv

确认本地client1分支已正确关联origin/client1，且切换过程无歧义警告。

内容的提问来源于stack exchange，提问作者Joao Victor