跳至主要内容

处理分支和标签名称中的特殊字符

Git 对分支和标签名称中允许的字符非常宽松。当从命令行 shell 使用 Git 时,您可能需要转义或引用特殊字符。

关于分支和标签名称

大多数仓库使用简单的分支名称,例如 mainupdate-icons。标签名称通常也遵循基本格式,例如版本号,如 v1.2.3。分支名称和标签名称也可能使用路径分隔符 (/) 来进行结构化,例如 area/itemlevel-1/level-2/level-3。除了某些例外情况(例如,名称不能以斜杠开头或结尾,或者名称中不能包含连续的斜杠)之外,Git 对分支和标签名称中可以使用哪些字符几乎没有限制。有关更多信息,请参阅 Git 文档中的 "git-check-ref-format"。

为什么需要转义特殊字符

当使用 CLI 时,您可能会遇到分支或标签名称包含对 shell 环境有特殊含义的特殊字符的情况。为了在 Git 命令中安全地使用这些字符,必须对它们进行引用或转义,否则命令可能会产生意想不到的效果。

例如,$ 字符被许多 shell 用于引用变量。大多数 shell 会将像 hello-$USER 这样的有效分支名称解释为等同于单词 "hello",后面跟着一个连字符,然后是 USER 变量的当前值,而不是字面字符串 hello-$USER。如果分支名称包含 $ 字符,则必须阻止 shell 将其扩展为变量引用。类似地,如果分支名称包含分号 (;),大多数 shell 会将其解释为命令分隔符,因此需要对其进行引用或转义。

如何在分支和标签名称中转义特殊字符

大多数包含特殊字符的分支和标签名称可以通过将名称包含在单引号中来处理,例如 'hello-$USER'

  • Bash shell 中,将字符串用单引号括起来可以保留单引号内字符的字面值。
  • Zsh 的行为类似于 Bash,但是可以通过 RC_QUOTES 选项配置此行为。
  • PowerShell 在单引号内也按字面意义处理字符。

对于这些 shell,主要例外情况是当分支或标签名称本身包含单引号时。在这种情况下,您应该查阅 shell 的官方文档。

命名分支和标签

如果可能,请创建不包含特殊字符的分支和标签名称,因为这些字符需要转义。用于分支名称和标签名称的安全默认字符集是

  • 英文字母(azAZ
  • 数字(09
  • 有限的标点符号
    • 句点 (.)
    • 连字符 (-)
    • 下划线 (_)
    • 正斜杠 (/)

为了避免混淆,您应该以字母开头分支名称。

GitHub 中的名称限制

GitHub 限制了少量分支和标签名称的推送。这些限制是

  • 没有看起来像 Git 对象 ID 的名称(40 个字符,只包含 0-9 和 A-F),以防止与实际的 Git 对象 ID 混淆。
  • 没有以 refs/ 开头的名称,以防止与 Git refs 的完整名称混淆。有关 refs 的更多信息,请参阅 Git 文档中的“Git References”。