简体中文 ▾ 主题 ▾ 最新版本 ▾ git-check-ref-format 最后更新于 2.52.0

名称

git-check-ref-format - 确保引用名称格式正确

概要

git check-ref-format [--normalize]
       [--[no-]allow-onelevel] [--refspec-pattern]
       <refname>
git check-ref-format --branch <branchname-shorthand>

描述

检查给定的refname是否可接受，如果不可接受则以非零状态退出。

在 Git 中，引用用于指定分支和标签。分支头存储在 refs/heads 层级中，而标签存储在引用命名空间（通常是 $GIT_DIR/refs/heads 和 $GIT_DIR/refs/tags 目录，或者如果引用被 git gc 打包，则作为 $GIT_DIR/packed-refs 文件中的条目）的 refs/tags 层级中。

Git 对引用的命名方式施加以下规则：

  1. 它们可以包含斜杠 / 用于分层（目录）分组，但任何斜杠分隔的组件都不能以点 . 开头，也不能以序列 .lock 结尾。

  2. 它们必须包含至少一个 /。这强制要求存在一个类别，如 heads/、tags/ 等，但实际名称不受限制。如果使用了 --allow-onelevel 选项，则此规则无效。

  3. 它们不能在任何地方包含两个连续的点 ..。

  4. 它们不能在任何地方包含 ASCII 控制字符（即字节值小于 \040 或 \177 DEL）、空格、波浪号 ~、插入符号 ^ 或冒号 :。

  5. 它们不能在任何地方包含问号 ?、星号 * 或开方括号 [。有关此规则的例外情况，请参见下面的 --refspec-pattern 选项。

  6. 它们不能以斜杠 / 开头或结尾，也不能包含多个连续的斜杠（有关此规则的例外情况，请参见下面的 --normalize 选项）。

  7. 它们不能以点 . 结尾。

  8. 它们不能包含序列 @{。

  9. 它们不能是单个字符 @。

  10. 它们不能包含 \。

这些规则使得基于 shell 脚本的工具易于解析引用名称，避免了在引用名称未加引号（错误地）使用时被 shell 进行路径名扩展，并且还可以避免某些引用名称表达式中的歧义（参见 gitrevisions[7]）。

  1. 双点 .. 通常用在 ref1..ref2 中，在某些上下文中，此表示法表示 ^ref1 ref2（即不在 ref1 中，但在 ref2 中）。

  2. 波浪号 ~ 和插入符号 ^ 用于引入后置第 n 个父级和剥洋葱操作。

  3. 冒号 : 在 fetch 和 push 操作中用于 srcref:dstref，表示“使用 srcref 的值并将其存储在 dstref 中”。它也可用于选择特定对象，如 'git cat-file'： "git cat-file blob v1.3.3:refs.c"。

  4. at-open-brace @{ 用于表示访问 reflog 条目。

使用 --branch 选项时，该命令接受一个名称并检查其是否可用作有效的分支名称（例如，在创建新分支时）。但在使用可能引用分离 HEAD 状态的旧 checkout 语法时要小心。git check-ref-format --branch $name 实现的规则可能比 git check-ref-format refs/heads/$name 更严格（例如，连字符可以出现在 ref 组件的开头，但在分支名称的开头是明确禁止的）。当在存储库中使用 --branch 选项运行时，输入首先会针对“旧 checkout 语法” @{-n} 进行扩展。例如，@{-1} 是引用使用“git switch”或“git checkout”操作最后签出的内容的一种方式。此选项应由高级命令使用，以接受在期望分支名称的任何地方使用此语法，这样它们就可以像您键入分支名称一样运行。请注意，作为例外，“旧 checkout 操作”可能会导致提交对象名称，当 N 次最后签出的内容不是分支时。

选项

--allow-onelevel
--no-allow-onelevel

控制是否接受单级引用名称（即，不包含多个 / 分隔组件的引用名称）。默认值为 --no-allow-onelevel。

--refspec-pattern

将 <refname> 解释为 refspec 的引用名称模式（与远程存储库一起使用）。如果启用此选项，<refname> 允许在 refspec 中包含单个 *（例如，foo/bar*/baz 或 foo/bar*baz/，但不能是 foo/bar*/baz*）。

--normalize

通过删除任何前导斜杠（/）字符并将名称组件之间的连续斜杠压缩为单个斜杠来规范化refname。如果规范化后的引用名称有效，则将其打印到标准输出并以状态 0 退出，否则以非零状态退出。（--print 是 --normalize 的已弃用写法。）

示例

  • 打印最后签出内容的名称

    $ git check-ref-format --branch @{-1}

  • 确定用于新分支的引用名称

    $ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }

GIT

Git[1] 套件的一部分