简体中文 ▾ 主题 ▾ 最新版本 ▾ git-check-ref-format 最后更新于 2.43.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 层次结构中，而标签存储在引用命名空间的 refs/tags 层次结构中（通常在 $GIT_DIR/refs/heads 和 $GIT_DIR/refs/tags 目录中，如果引用由 git gc 打包，则作为文件 $GIT_DIR/packed-refs 中的条目）。

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. 冒号 : 用于 srcref:dstref 形式，在 fetch 和 push 操作中表示“使用 srcref 的值并将其存储在 dstref 中”。它也可以用于选择特定的对象，例如与 'git cat-file' 一起使用时：“git cat-file blob v1.3.3:refs.c”。

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

使用 --branch 选项时，该命令接受一个名称并检查其是否可用作有效的分支名称（例如，在创建新分支时）。但请注意，使用旧的 checkout 语法时可能会引用分离的 HEAD 状态。 git check-ref-format --branch $name 所实现的规则可能比 git check-ref-format refs/heads/$name 所说的更严格（例如，破折号可以出现在引用组件的开头，但在分支名称的开头是明确禁止的）。当在仓库中运行带有 --branch 选项时，输入会首先针对“上一次检出语法” @{-n} 进行扩展。例如，@{-1} 是指通过 "git switch" 或 "git checkout" 操作检出的上一个内容的引用方式。此选项应由高层命令（porcelains）使用，以便在任何预期分支名称的地方接受此语法，从而使它们表现得如同您输入了分支名称一样。值得注意的是，作为例外，“上一次检出操作”在第N次检出的内容不是分支时，可能会导致提交对象名称。

选项

--[no-]allow-onelevel

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

--refspec-pattern

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

--normalize

通过移除任何开头的斜杠 (/) 字符并将名称组件之间连续的斜杠合并为单个斜杠来标准化 refname。如果标准化后的 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] 套件的一部分

scroll-to-top