Git 克隆后目录为空，提示 remote HEAD refers to nonexistent ref

git clone 已经接收了对象并完成解析，最后却出现：

warning: remote HEAD refers to nonexistent ref, unable to checkout.

进入克隆目录，只看到 .git，项目文件没有检出。先保留这个目录：对象可能已经下载成功，失败的是根据远端默认分支选择工作区内容这一步。

本文处理的条件是：远端有可访问的分支，但远端 HEAD 指向一个不存在的分支。例如仓库只有 main，远端 HEAD 却仍指向 refs/heads/master。默认分支删除、迁移或仓库生成流程中的引用不一致，都可能形成这种状态；具体原因要结合仓库实际设置确认，不能仅凭提示认定某个托管平台版本有缺陷。

先确认分支和对象是否已经取回

在刚克隆的目录中执行以下只读检查：

git status
git branch -a
git ls-remote --symref origin HEAD 'refs/heads/*'

git branch -a 列出本地分支和已经取回的远端跟踪分支。如果能看到 remotes/origin/main，说明本地已有一个可以进一步检查的远端分支引用。

git ls-remote 直接查询远端当前公开给你的引用；--symref 还会显示服务端提供的符号引用指向。将 HEAD 的目标与 refs/heads/ 下实际列出的分支对照。若目标不存在，而其他分支存在，就符合默认分支指向失效的场景。

有些服务端或协议交互下，失效的 HEAD 不一定完整显示。没有看到 ref: 行，不等于证明远端正常；需要管理员核对默认分支设置及仓库引用。若连一个分支都没列出，也不要直接套用 main：先确认这是空仓库、访问受限，还是克隆了错误的地址。

已有 origin/main 时，直接检出实际分支

以下示例假定你已经确认远端实际分支名为 main，并且本地尚未创建同名分支。分支叫 develop 或其他名称时，按实际值替换：

git switch --track origin/main
git status
git branch -vv

第一条命令从 origin/main 创建并切换到本地 main，同时建立上游跟踪关系。之后项目文件应出现在工作区，git status 应显示当前位于 main，git branch -vv 中应能看到它跟踪 origin/main。

如果已经存在本地 main，不要重复创建，也不要使用强制重置选项。先确认该分支是否有自己的提交及上游配置，再决定是否切换。对于已经写入本地文件的目录，应先检查、保留这些文件；切换因文件冲突被拒绝时，不要为了绕过拒绝加 --discard-changes。

如果本地没有 origin/main，但远端查询确实列出了 refs/heads/main，可能是之前的克隆只取了部分分支。可以保留现有目录，在新目录里明确指定分支重新克隆：

git clone --branch main 'https://git.example.com/team/project.git' project-main-check

将示例地址替换为实际仓库 URL，目标目录使用尚不存在的名称。--branch main 明确指定初始检出的分支，不再依赖远端 HEAD 选中它。这里应填写已经确认存在的分支名；该选项也接受标签，误填标签会得到分离的 HEAD，不能当作建立了正常的开发分支。

本地能工作后，还需要修正远端默认分支

手动检出只恢复了当前工作区。其他人继续普通克隆时，仍可能遇到同一提示。仓库管理员应在托管平台的仓库设置中，把默认分支改为已经存在、且团队确认应作为默认入口的分支。

修改前记录原来的默认分支及相关自动化约定。默认分支会影响新克隆的初始分支，也可能影响依赖平台默认值的合并请求、构建和发布流程。不要仅为了消除警告就创建一个没有业务意义的 master，更不要把另一分支强推过去覆盖已有历史。

如果平台界面已经显示 main，而实际克隆行为仍与之不一致，应由管理员核对平台记录和底层 Git 仓库的 HEAD 是否一致，并采用该平台支持的修复方式。不同平台会维护额外的仓库元数据，直接修改磁盘文件不能保证这些数据一起更新。

还要分清下面这个命令的作用：

git remote set-head origin -a

它查询远端，并更新本地的 refs/remotes/origin/HEAD，不修改服务器上的默认分支。只有远端已经给出正确目标、对应的远端跟踪分支也已经取回时，它才适合用来同步本地的默认分支别名。远端本身仍指向不存在的分支时，不能靠它完成服务端修复。

用一次普通克隆确认远端修复

管理员调整后，再查询一次远端引用，并在新的目录里进行不带 --branch 的普通克隆：

git ls-remote --symref 'https://git.example.com/team/project.git' HEAD 'refs/heads/*'
git clone 'https://git.example.com/team/project.git' project-default-check

检查三个结果：默认引用指向预期分支；普通克隆不再报上述警告；新目录自动检出了预期文件和分支。此前使用 --branch 成功，只能证明指定分支可以克隆，不能证明默认入口已经修好。

若修改默认分支影响了既有工作流，应由管理员按事先记录恢复到团队确认的有效分支，并复查相关自动化配置。不要把已经失效的旧引用当作必须恢复的正确状态。已有本地提交和工作文件不需要为这条警告而删除；新建的检查目录确认无待保留内容后再单独清理。