1. 引言 {#introduction}
Git 是现代软件开发中不可或缺的版本控制工具。它通过提交（commit）记录项目状态的变化，而分支（branch）和标签（tag）则为这些提交赋予了可读性强的名称。然而，Git 对这些引用（ref）的命名有着严格的限制，本文将探讨这些限制及其背后的原因。
本文测试环境为 Debian 12（Bookworm）系统，使用 GNU Bash 5.2.15 和 Git 2.39.2。除非特别说明，大部分内容适用于大多数 POSIX 兼容环境。
2. Git 中的名称 {#git-names}
每个提交都有一个唯一的哈希标识符。但在实际开发中，某些提交（如里程碑、功能完成、版本发布）更为重要，因此 Git 提供了标签、分支等机制为这些提交赋予易于理解的名称。
我们可以通过 git show-ref 命令查看仓库中所有的引用：
$ git show-ref
6d0264be17baa5e2c0525e5f72e15098156f140d refs/heads/branch1
3b34787f960ce7f140a4a55fb649bf1745c397ff refs/heads/branch2
467173b6e09077c07daad32315f9fa1b661bd675 refs/heads/branch3
ade5f229cc37c52689a4e43c42025c9fd62fca76 refs/heads/master
ae0d1f5879bcfcb771ce1435956934c7e38aec5a refs/tags/base
以上输出显示了主分支 master、三个其他分支和一个标签 base。需要注意的是，Git 对这些引用的命名有诸多限制。
3. Git 分支与标签命名规则 {#naming-rules}
3.1. 分隔符与结构 {#separators}
与 UNIX 路径类似，Git 使用 / 作为引用路径的分隔符：
ref/heads/branch1
但 Git 对 / 的使用也有以下限制：
✅ 允许使用 / 构建引用层级
❌ 除非使用 --allow-onelevel，否则引用名必须包含至少一个 /
❌ 不允许连续的 /（除非使用 --normalize）
Git 的引用在文件系统中以目录结构存在：
$ tree .git/refs/
.git/refs/
├── heads
│ ├── branch1
│ ├── branch2
│ ├── branch3
│ └── master
└── tags
└── base
3.2. 不允许以 . 开头或以 .lock 结尾 {#dot-lock}
引用的任意一部分不能以 . 开头，也不能以 .lock 结尾。这是为了避免与隐藏文件或 Git 内部锁文件混淆。
3.3. 禁止的字符与序列 {#forbidden-chars}
为避免与 shell 特性冲突或解析歧义，以下字符和序列在引用名中是禁止的：
❌ ..
❌ @{
❌ ASCII 控制字符（如空格、Delete）
❌ ~
❌ ^
❌ :
❌ ?
❌ *（除非使用 --refspec-pattern 作为通配符）
❌ [
❌ \
这些限制主要是为了避免：
- 与 Git 的父提交语法冲突（如
~,^） - 与 refspec 分隔符冲突（如
:） - 与通配符解析冲突（如
*） - 与 reflog 语法冲突（如
@{）
3.4. 禁止的名称 {#forbidden-names}
虽然 @ 字符本身是允许的，但在很多 Git 版本中，单独使用 @ 作为引用名是不被允许的。
此外，以下特殊引用名也不能作为自定义引用名使用：
❌ HEAD
❌ FETCH_HEAD
❌ ORIG_HEAD
❌ MERGE_HEAD
4. Shell 上下文中的注意事项 {#shell-considerations}
虽然 Git 没有明文禁止，但在实际使用中，某些字符在 shell 环境中可能导致问题：
⚠️ 重定向符号：
$ git tag more>changes 601fea3
如果没有用引号包裹 more>changes，Git 实际上会创建名为 more 的标签，并将 changes 作为文件创建。
⚠️ 变量插值：
$ git tag dollar$bills 601fea3
如果 $bills 变量未定义，标签名为 dollar；否则，标签名可能变成 dollar100 这样的结果。
⚠️ 路径长度限制：某些系统对文件路径长度有限制，过长的引用名可能导致创建失败。
5. 总结 {#summary}
Git 的引用命名虽然类似文件系统路径，但为了兼容性、安全性和可读性，引入了多种限制。这些限制包括：
✅ 使用 / 构建层级结构
❌ 禁止使用特殊字符如 ~, ^, :, *, ? 等
❌ 禁止使用 . 开头或 .lock 结尾
❌ 避免与 shell 特性冲突（如变量插值、重定向）
❌ 避免使用 Git 内部保留名称（如 HEAD）
理解这些限制有助于避免在使用 Git 时遇到命名相关的“踩坑”问题。