必须先执行git fetch，否则本地无法识别远程分支；git branch -r为空即表明未获取远程引用信息，需用git fetch origin或git fetch origin 分支名同步，再通过git switch -c或git checkout -b创建本地分支。
远程分支“看不见”或“检不出”，90%不是 Git 坏了，而是本地没拿到它的引用信息——必须先 git fetch，否则所有后续操作都基于空壳。
git branch -r 为空或查不到目标分支
这是最常见表象：Web 界面明明有 feature/login-v2，但运行 git branch -r 输出里压根没有它。
- 根本原因：远程分支名（如
origin/feature/login-v2）只是你本地仓库里的一个引用，它不会自动同步；不执行git fetch，这个引用就不存在 - 验证方式：运行
git ls-remote --heads origin | grep login—— 如果这里也看不到，说明远程仓库确实没该分支，或你没权限；如果这里能看到，但git branch -r看不到，就是本地没 fetch - 别用
git pull origin feature/login-v2替代：它会尝试合并到当前分支，而你还没本地分支，必然失败 - 稳妥做法：
git fetch origin（拉全量远程分支信息）；若只想省带宽，用git fetch origin feature/login-v2，但注意这只会更新origin/feature/login-v2这一个引用
git switch -c xxx origin/xxx 报错 “not a valid ref”
错误信息典型如：error: Cannot setup tracking information because remote 'origin' does not have branch 'xxx' 或 fatal: 'origin/xxx' is not a valid ref。
抓取指定 GitHub用户的 Stars 项目，生成标准化中文 Markdown 报告。用户提及「分析 GitHub stars」「导出收藏项目」「汇总 GitHub 星标」「生成 stars 报告」或粘贴含 ?tab=stars 的链接时触发。执行通过 bash...
- 这不是拼写错误，而是
origin/xxx这个引用在本地根本未被创建——git fetch没成功或没执行 - 检查 .git/config 中的 fetch 配置：如果只有
+refs/heads/main:refs/remotes/origin/main这类单分支配置，其他分支永远不会被拉下来；应改为+refs/heads/*:refs/remotes/origin/* - 修复命令：
git config --replace-all remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"，然后重试git fetch origin - Git 2.23+ 用户注意：
git switch -c xxx origin/xxx要求origin/xxx必须是已存在的本地远程引用，不能“模糊匹配”；旧版git checkout xxx会自动 fallback 创建，但这容易掩盖配置问题
VSCode 显示分支名但 git pull 失败
编辑器右下角显示 “feature/login-v2”，点拉取却报：your configuration specifies to merge with the ref 'refs/heads/feature/login-v2' from the remote, but no such ref was fetched。
- 说明该本地分支的 upstream 设置（
branch.feature/login-v2.merge）指向了一个本地并不存在的远程引用 - 本质是分支已存在，但上游配置失效：可能是远程分支被删过、重命名过，或当初创建时 fetch 不完整
- 临时救急：
git branch --set-upstream-to=origin/feature/login-v2 feature/login-v2，前提是origin/feature/login-v2现在已存在（即你刚git fetch过） - 更彻底的做法：
git branch -d feature/login-v2删除本地分支，再用git switch -c feature/login-v2 origin/feature/login-v2重建，确保跟踪关系干净
分支名含斜杠 / 或大小写敏感导致失败
比如远程有 origin/bugfix/AB-123，但输成 origin/bugfix/ab-123 或漏掉斜杠直接写 ab-123，都会失败。
- Git 对分支名完全大小写敏感，
Feature/Login≠feature/login - 远程分支在命令中必须写成
origin/xxx形式，不能省略origin/；remotes/origin/xxx是内部存储路径，不能用于命令行 - 安全查法：
git branch -r | grep -i ab-123（加-i忽略大小写），或直接git ls-remote --heads origin看原始命名 - 特殊字符（如空格、中文）在某些 shell 下需加引号，但强烈建议避免使用——远程仓库策略可能禁止这类命名
真正卡住人的地方，往往不是命令记错，而是误以为“远程有 = 本地能直接用”。Git 的远程分支引用是显式同步的，不是实时反射。只要记住：任何检出、跟踪、pull 之前，先看 git branch -r 是否列出目标；没列出来，就 git fetch —— 别跳步，别猜，别信编辑器 UI 显示的分支名就是可靠的本地引用。
