处理 git 引用名称时，您一直想要的全部功能。

概述

此crate提供了一些类型，允许验证git引用名称，创建新的有效引用名称，对它们的结构进行断言，并将它们分解为其组件。

基本类型

基本类型有

• RefStr
• RefString

它们分别是对 [str] 和 String 的包装，同时保证了它们也是按照 git-check-ref-format (它也直接暴露为 check_ref_format) 有效的引用名称。这两种类型都被称为 "引用字符串"。

请注意，这表明引用名称必须是有效的UTF-8，而git本身并不要求这一点。

引用字符串可以迭代，可以产生 &str 或 Component。一个 Component 保证不包含 '/' 分隔符，因此也可以方便地构造已知的有效引用字符串。 [lit] 模块包含许多类型（及其 const 值）可以转换为 Component，因此可以用于构造已知的有效引用字符串。

name 模块还提供了一些常用的引用字符串/组件的常量值，这对于模式匹配很有用。

“"macro"”功能启用了refstring!和component!宏，这些宏可以方便地构造编译时验证的RefString和Component。

引用规范模式

类型

• refspec::PatternStr
• refspec::PatternString

保证它们的值是有效的引用字符串，但此外最多可以包含一个"*"字符。因此，可以将引用字符串转换为引用规范模式，但不能反过来。引用规范模式通常用于将远程引用映射到本地引用（参见git-fetch）。

“"macro"”功能启用了refspec::pattern!宏，该宏构造了一个编译时验证的refspec::PatternString。

结构化引用字符串

引用字符串可能是Qualified的，这基本上意味着它们以"refs/"开头。Qualified引用字符串也至少需要三个组件（例如："refs/heads/main"），这使得处理常见的命名约定变得更加容易。

Qualified引用可以是Namespaced的，或者可以指定一个命名空间（命名空间可以嵌套）。Namespaced引用也是Qualified的，并且可以去除它们的命名空间。

关于Git引用命名约定

Git引用本质上是指向其传统存储位置的路径名，该位置在存储库中（$GIT_DIR/refs）。与（UNIX）文件路径不同，它们受到一些限制，如git-check-ref-format中所述。

除此之外，还有一些关于分层命名的约定，其中一些由git CLI等工具特别处理。例如

• refs/heads/..也被称为“分支”。

  省略"refs/heads/"前缀通常是被接受的。这样的分支名称也被称为“缩写”引用。

• refs/tags/..假设包含标签。

  git特别处理标签，具体来说，它坚持认为它们在存储库的所有副本中必须是全局唯一的。

• refs/remotes/../..是存储“远程跟踪分支”的地方。

  在 git 中，"remotes" 之后的第一个元素被认为是远程仓库的名称（如配置文件中所示），而之后的任何内容都被认为是简写分支。但是请注意，远程名称本身可能包含 '/' 分隔符，因此在没有访问配置的情况下通常无法提取分支名称。

• refs/namespaces/.. 是隐藏的，除非启用了 gitnamespaces。

  命名空间的结构是递归的：它们包含完整的引用，这些引用本身也可以是命名空间（例如，refs/namespaces/a/refs/namespaces/b/refs/heads/branch）。请注意，与远程名称不同，命名空间名称不能包含正斜杠，但没有工具会强制执行这一点。

还有其他这样的引用层次结构 git 知道，而这个crate并不试图涵盖所有这些。更重要的是，git 对引用层次结构没有任何限制：只要它们不与常规的冲突，应用程序可以引入任何它们想要的层次结构。

这限制了在除了引用名称以外的附加信息下，可以在常规引用之间进行的转换：例如，如果不了解所有可能的远程名称，通常无法将远程跟踪分支转换为分支（或简写）。

因此，这个crate并不试图解释与引用相关的所有可能的语义，而是试图使库消费者更容易做到这一点。