Git 子路径分支创建失败：refs 文件与目录冲突

在 GitLab 上创建 test/xxx 这样的层级分支，本地 git branch 成功，push 却被拒；换到 GitLab 网页上建分支，同样失败。这不是权限或网络问题，而是 git 分支引用存储模型的结构性限制：同一个前缀不能既是分支又是分支的前缀目录。本文记录一次完整排查：现象、根因、两种解决方式，以及分支命名上的预防措施。

现象

某个托管在 GitLab 上的仓库需要从 develop 创建层级分支 test/feature/pack-script 用于脚本开发：

• 本地创建成功：git branch test/feature/pack-script develop 没有报错（本地不存在 test 分支）
• push 到远端被拒，报错原文：

fatal: cannot lock ref 'refs/heads/test/feature/pack-script': 'refs/heads/test' exists; cannot create 'refs/heads/test/feature/pack-script'

• 在 GitLab 网页上建分支同样失败，排除权限和网络问题

原因：D/F 冲突（directory/file conflict）

git 的分支引用按路径存储在 refs/heads/ 下，每个分支对应一个文件（或 packed-refs 里的一条路径）：

• refs/heads/test——已存在的 test 分支，是一个文件
• refs/heads/test/feature/pack-script——要求 refs/heads/test/ 是一个目录

同一路径不能既是文件又是目录，两者互斥。远端恰好有一个遗留的 test 分支（一条 develop 之外的提交线），所以任何 test/xxx 形态的分支都建不出来。

最小复现只需要三行：

git init demo && cd demo
git commit --allow-empty -m "chore: init"
git branch test                          # 先有 test
git branch test/feature/pack-script      # fatal: cannot lock ref ...

解决

方案一：换名，一级前缀避开 test（推荐，立即可用）：

git push origin develop:refs/heads/test_feature/pack-script
# 或 tests/feature/pack-script、pack-script 等其他形态

方案二：删除或改名远端 test 分支，之后即可使用 test/ 前缀。删除前需要确认这条分支确已废弃：如果它包含 develop 之外的内容（不是 develop 的祖先），直接删除会丢掉那条提交线。检查方式：

git merge-base --is-ancestor origin/test origin/develop && echo "已包含，可安全删除"

该命令退出码为 0 表示 test 的提交都已包含在 develop 中；非 0 表示存在 develop 之外的提交，需要先合并或由维护人确认废弃。

要点

规划层级分支名（a/b/c 形态）前，先确认一级前缀没被单独占用：

git ls-remote --heads origin | grep -E 'refs/heads/test$'

几个结论：

• 该约束在本地、远端、GitLab 网页三处一致，属于 git ref 存储的结构性限制，与服务端软件无关
• 分支命名规范里如果预留了层级前缀（feat/、release/、test/），一级名字就不要再单独用作分支，反之亦然