简体中文 ▾ 主题 ▾ 最新版本 ▾ git-rev-parse 最后更新于 2.52.0

名称

git-rev-parse - 挑选并整理参数

概要

git rev-parse [<options>] <arg>…​

描述

许多 Git porcelainish（面向用户的）命令接收混合的标志（即以破折号 - 开头的参数）以及它们内部使用的底层 git rev-list 命令所需的参数，还有它们在 git rev-list 之后使用的其他命令的标志和参数。此命令的主要目的是允许调用程序对它们进行区分。还有一些其他操作模式与上述“帮助解析命令行选项”无关。

除非另有说明，否则大多数选项和操作模式要求您在 git 仓库或受 git 仓库控制的工作树中运行此命令，否则将导致致命错误。

选项

操作模式

这些选项中的每一个都必须出现在命令行最前面。

--parseopt

在选项解析模式下使用 git rev-parse（参见下文 PARSEOPT 部分）。此模式下的命令可以在仓库或由仓库控制的工作树之外使用。

--sq-quote

在 shell 引用模式下使用 git rev-parse（参见下文 SQ-QUOTE 部分）。与下方的 --sq 选项相比，此模式仅执行引用操作。不对命令输入执行其他任何操作。此模式下的命令可以在仓库或由仓库控制的工作树之外使用。

--parseopt 的选项

--keep-dashdash

仅在 --parseopt 模式下有意义。告诉选项解析器回显遇到的第一个 --，而不是跳过它。

--stop-at-non-option

仅在 --parseopt 模式下有意义。让选项解析器在遇到第一个非选项参数时停止。这可用于解析本身带有选项的子命令。

--stuck-long

仅在 --parseopt 模式下有意义。如果可用，以长格式输出选项，并将其参数紧贴在选项后。

过滤选项

--revs-only

不输出非 git rev-list 命令所需的标志和参数。

--no-revs

不输出 git rev-list 命令所需的标志和参数。

--flags

不输出非标志参数。

--no-flags

不输出标志参数。

输出选项

--default <arg>

如果用户未提供参数，则使用 <arg> 代替。

--prefix <arg>

表现得就像是在工作树的 <arg> 子目录中调用 git rev-parse 一样。任何相对文件名都会被解析为以 <arg> 为前缀，并以该形式打印。

这可用于转换在子目录中运行的命令的参数，以便在移动到仓库顶层后仍然可以使用它们。例如

prefix=$(git rev-parse --show-prefix)
cd "$(git rev-parse --show-toplevel)"
# rev-parse provides the -- needed for 'set'
eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")"
--verify

验证是否提供了且仅提供了一个参数，并且它可以转换为可用于访问对象数据库的原始 20 字节 SHA-1。如果是，则将其输出到标准输出；否则报错。

如果您想确保输出确实命名了对象数据库中的对象和/或可以用作所需的特定类型对象，您可以将 ^{type} 剥离运算符添加到参数中。例如，git rev-parse "$VAR^{commit}" 将确保 $VAR 命名了一个现有的提交对象（即提交，或指向提交的注解标签）。要确保 $VAR 命名了任何类型的现有对象，可以使用 git rev-parse "$VAR^{object}"。

请注意，如果您正在验证来自不受信任来源的名称，明智的做法是使用 --end-of-options，以免将名称参数误认为是另一个选项。

-q
--quiet

仅在 --verify 模式下有意义。如果第一个参数不是有效的对象名称，则不输出错误消息；而是静默地以非零状态退出。成功时，有效对象名称的 SHA-1 会打印到标准输出。

--sq

通常输出是每个标志和参数占一行。此选项使输出变为单行，并为 shell 使用进行了适当的引用。当您期望参数包含空格和换行符时很有用（例如在使用 git diff-* 的 pickaxe -S 时）。与 --sq-quote 选项相比，命令输入仍然按常规方式解析。

--short[=<length>]

与 --verify 相同，但将对象名称缩短为至少 length 个字符的唯一前缀。最小长度为 4，默认值为 core.abbrev 配置变量的有效值（参见 git-config[1]）。

--not

显示对象名称时，在它们前面加上 ^，并从已经带有 ^ 前缀的对象名称中剥离该前缀。

--abbrev-ref[=(strict|loose)]

对象名称的非歧义短名称。选项 core.warnAmbiguousRefs 用于选择严格缩写模式。

--symbolic

通常对象名称以 SHA-1 形式输出（带有可能的 ^ 前缀）；此选项使它们以尽可能接近原始输入的形式输出。

--symbolic-full-name

这类似于 --symbolic，但它省略了非引用的输入（即分支或标签名称；或者当您想要命名“master”分支但存在不幸命名的“master”标签时，更明确地消除“heads/master”形式的歧义），并将它们显示为完整引用名称（例如“refs/heads/master”）。

--output-object-format=(sha1|sha256|storage)

允许从当前仓库支持的任何对象格式输入 OID。

指定“sha1”会在必要时进行转换并返回 sha1 OID。

指定“sha256”会在必要时进行转换并返回 sha256 OID。

指定“storage”会在必要时进行转换并返回以存储哈希算法编码的 OID。

对象选项

--all

显示在 refs/ 中找到的所有引用。

--branches[=<pattern>]
--tags[=<pattern>]
--remotes[=<pattern>]

分别显示所有分支、标签或远程跟踪分支（即分别在 refs/heads、refs/tags 或 refs/remotes 中找到的引用）。

如果给出了 pattern，则仅显示与给定 shell 通配符匹配的引用。如果模式不包含通配符字符（?、* 或 [），则通过附加 /* 将其转换为前缀匹配。

--glob=<pattern>

显示所有与 shell 通配符模式 pattern 匹配的引用。如果模式不是以 refs/ 开头，则会自动添加该前缀。如果模式不包含通配符字符（?、* 或 [），则通过附加 /* 将其转换为前缀匹配。

--exclude=<glob-pattern>

不包括与下一个 --all、--branches、--tags、--remotes 或 --glob 将要考虑的 <glob-pattern> 匹配的引用。此选项的重复使用会累积排除模式，直到下一个 --all、--branches、--tags、--remotes 或 --glob 选项（其他选项或参数不会清除累积的模式）。

当应用于 --branches、--tags 或 --remotes 时，给出的模式不应分别以 refs/heads、refs/tags 或 refs/remotes 开头，并且当应用于 --glob 或 --all 时，它们必须以 refs/ 开头。如果要匹配结尾的 /*，则必须显式给出。

--exclude-hidden=(fetch|receive|uploadpack)

通过查阅适当的 fetch.hideRefs、receive.hideRefs 或 uploadpack.hideRefs 配置以及 transfer.hideRefs（请参阅 git-config[1]），不包括会被 git-fetch、git-receive-pack 或 git-upload-pack 隐藏的引用。此选项会影响下一个伪引用选项 --all 或 --glob，并在处理它们之后清除。

--disambiguate=<prefix>

显示名称以给定前缀开头的所有对象。<prefix> 必须至少包含 4 个十六进制数字，以避免错误地列出仓库中的每一个对象。

文件选项

--local-env-vars

列出本地仓库的 GIT_* 环境变量（例如 GIT_DIR 或 GIT_WORK_TREE，但不包括 GIT_EDITOR）。仅列出变量名称，即使已设置，也不会列出它们的值。

--path-format=(absolute|relative)

控制某些其他选项的行为。如果指定为绝对路径，则这些选项打印的路径将是绝对且规范化的。如果指定为相对路径，则路径将尽可能相对于当前工作目录。默认值是特定于选项的。

此选项可以多次指定，并且仅影响命令行中位于其后的参数，直到命令行结束或下一次出现此选项为止。

以下选项受 --path-format 修改

--git-dir

如果定义了 $GIT_DIR，则显示它。否则显示 .git 目录的路径。显示的路径如果是相对路径，则相对于当前工作目录。

如果未定义 $GIT_DIR 且未检测到当前目录位于 Git 仓库或工作树中，则向 stderr 打印消息并以非零状态退出。

--git-common-dir

如果定义了 $GIT_COMMON_DIR，则显示它，否则显示 $GIT_DIR。

--resolve-git-dir <path>

检查 <path> 是否是有效的仓库或指向有效仓库的 gitfile，并打印仓库的位置。如果 <path> 是一个 gitfile，则打印已解析的真实仓库路径。

--git-path <path>

解析 "$GIT_DIR/<path>" 并将其他路径重定位变量（如 $GIT_OBJECT_DIRECTORY、$GIT_INDEX_FILE 等）考虑在内。例如，如果 $GIT_OBJECT_DIRECTORY 设置为 /foo/bar，则 "git rev-parse --git-path objects/abc" 返回 /foo/bar/abc。

--show-toplevel

显示工作树顶层目录的（默认情况下为绝对）路径。如果没有工作树，则报告错误。

--show-superproject-working-tree

显示使用当前仓库作为其子模块的超项目工作树的根目录的绝对路径（如果存在）。如果当前仓库未被任何项目用作子模块，则不输出任何内容。

--shared-index-path

在拆分索引模式下显示共享索引文件的路径，如果不在拆分索引模式下，则为空。

以下选项不受 --path-format 影响

--absolute-git-dir

类似于 --git-dir，但其输出始终是规范化的绝对路径。

--is-inside-git-dir

当当前工作目录位于仓库目录下方时打印 "true"，否则打印 "false"。

--is-inside-work-tree

当当前工作目录位于仓库工作树内部时打印 "true"，否则打印 "false"。

--is-bare-repository

当仓库是裸仓库（bare）时打印 "true"，否则打印 "false"。

--is-shallow-repository

当仓库是浅克隆（shallow）仓库时打印 "true"，否则打印 "false"。

--show-cdup

当从子目录调用命令时，显示相对于当前目录的顶层目录路径（通常是一系列 "../" 或空字符串）。

--show-prefix

当从子目录调用命令时，显示相对于顶层目录的当前目录路径。

--show-object-format[=(storage|input|output|compat)]

显示用于仓库存储在 .git 目录中的、输入、输出或兼容性的对象格式（哈希算法）。对于输入，可能会打印多个算法，以空格分隔。如果请求 compat 且未启用兼容性算法，则打印空行。如果未指定，默认值为 "storage"。

--show-ref-format

显示用于该仓库的引用存储格式。

其他选项

--since=<datestring>
--after=<datestring>

解析日期字符串，并为 git rev-list 输出相应的 --max-age= 参数。

--until=<datestring>
--before=<datestring>

解析日期字符串，并为 git rev-list 输出相应的 --min-age= 参数。

<arg>…​

要解析的标志和参数。

指定版本

版本参数 <rev> 通常（但不一定）命名一个提交对象。它使用所谓的 扩展 SHA-1 语法。以下是拼写对象名称的各种方法。此列表末尾附近列出的内容命名了提交中包含的树和二进制大对象（blob）。

注意
 本文档显示了 git 所见的“原始”语法。shell 和其他 UI 可能需要额外的引用来保护特殊字符并避免单词拆分。
<sha1>，例如 dae86e1950b1277e545cee180551750029cfe735，dae86e

完整的 SHA-1 对象名称（40 字节的十六进制字符串），或在仓库中唯一的引导子字符串。例如，如果仓库中没有其他以 dae86e 开头的对象，则 dae86e1950b1277e545cee180551750029cfe735 和 dae86e 都命名同一个提交对象。

<describeOutput>，例如 v1.7.4.2-679-g3bee7fb

git describe 的输出；即最近的标签，可选地后跟一个破折号和提交数量，再后跟一个破折号、一个 g 和一个缩写的对象名称。

<refname>，例如 master，heads/master，refs/heads/master

符号引用名称。例如，master 通常指 refs/heads/master 所引用的提交对象。如果你同时有 heads/master 和 tags/master，你可以显式地写 heads/master 来告诉 Git 你指哪一个。当有歧义时，<refname> 通过采取以下规则的第一个匹配项来消除歧义：

  1. 如果 $GIT_DIR/<refname> 存在，这就是你的意思（这通常只对 HEAD、FETCH_HEAD、ORIG_HEAD、MERGE_HEAD、REBASE_HEAD、REVERT_HEAD、CHERRY_PICK_HEAD、BISECT_HEAD 和 AUTO_MERGE 有用）；

  2. 否则，如果 refs/<refname> 存在，则为它；

  3. 否则，如果 refs/tags/<refname> 存在，则为它；

  4. 否则，如果 refs/heads/<refname> 存在，则为它；

  5. 否则，如果 refs/remotes/<refname> 存在，则为它；

  6. 否则，如果 refs/remotes/<refname>/HEAD 存在，则为它。

    HEAD

    命名你基于工作树中更改的那个提交。

    FETCH_HEAD

    记录你通过上次 git fetch 调用从远程仓库获取的分支。

    ORIG_HEAD

    由以剧烈方式移动 HEAD 的命令（git am、git merge、git rebase、git reset）创建，用于记录操作前的 HEAD 位置，以便您可以轻松地将分支顶端变回运行它们之前的状态。

    MERGE_HEAD

    记录您在运行 git merge 时正在合并到您的分支中的提交。

    REBASE_HEAD

    在变基（rebase）期间，记录当前操作停止的提交，原因可能是冲突或交互式变基中的 edit 命令。

    REVERT_HEAD

    记录您在运行 git revert 时正在撤销（revert）的提交。

    CHERRY_PICK_HEAD

    记录您在运行 git cherry-pick 时正在挑选（cherry-pick）的提交。

    BISECT_HEAD

    记录您在运行 git bisect --no-checkout 时要测试的当前提交。

    AUTO_MERGE

    记录当合并操作导致冲突时，ort 合并策略写入工作树的对应于该状态的树对象。

请注意，上述 refs/* 情况中的任何一个都可能来自 $GIT_DIR/refs 目录或 $GIT_DIR/packed-refs 文件。虽然未指定引用名称编码，但首选 UTF-8，因为某些输出处理可能假设引用名称为 UTF-8。

@

单独的 @ 是 HEAD 的快捷方式。

[<refname>]@{<date>}，例如 master@{yesterday}，HEAD@{5 minutes ago}

后跟后缀 @ 并带有括在括号中的日期规范的引用（例如 {yesterday}、{1 month 2 weeks 3 days 1 hour 1 second ago} 或 {1979-02-26 18:30:00}）指定了该引用在过去某个时间点的值。此后缀只能紧跟在引用名称之后使用，并且该引用必须具有现有日志（$GIT_DIR/logs/<ref>）。请注意，这是查找给定时间您本地引用的状态；例如，您本地的 master 分支上周的内容。如果您想查看在特定时间内做出的提交，请参阅 --since 和 --until。

<refname>@{<n>}，例如 master@{1}

后跟后缀 @ 并带有括在括号中的序数规范（例如 {1}，{15}）的引用指定了该引用之前的第 n 个值。例如 master@{1} 是 master 的紧前值，而 master@{5} 是 master 的第 5 个前值。此后缀只能紧跟在引用名称之后使用，并且该引用必须具有现有日志（$GIT_DIR/logs/<refname>）。

@{<n>}，例如 @{1}

你可以使用 @ 结构配合空的引用部分来获取当前分支的 reflog 条目。例如，如果你在分支 blabla 上，那么 @{1} 的意思与 blabla@{1} 相同。

@{-<n>}，例如 @{-1}

结构 @{-<n>} 表示在当前分支之前检出的第 <n> 个分支/提交。

[<branchname>]@{upstream}，例如 master@{upstream}，@{u}

分支 B 可以设置为在分支 X（配置为 branch.<name>.merge）之上构建，该分支位于远程 R（配置为 branch.<name>.remote）上。B@{u} 指的是从远程 R 获取的分支 X 的远程跟踪分支，通常位于 refs/remotes/R/X。

[<branchname>]@{push}，例如 master@{push}，@{push}

后缀 @{push} 报告了如果检出 branchname（如果未指定分支名称，则为当前 HEAD）时运行 git push，“我们将推送到哪里”的分支。与 @{upstream} 一样，我们报告对应于远程该分支的远程跟踪分支。

这是一个让它更清晰的例子

$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c mybranch origin/master

$ git rev-parse --symbolic-full-name @{upstream}
refs/remotes/origin/master

$ git rev-parse --symbolic-full-name @{push}
refs/remotes/myfork/mybranch

在示例中请注意，我们设置了一个三角工作流，从一个位置拉取并推送到另一个位置。在非三角工作流中，@{push} 与 @{upstream} 相同，不需要它。

此后缀在以大写拼写时也会被接受，并且无论大小写如何，其含义都相同。

<rev>^[<n>]，例如 HEAD^, v1.5.1^0

版本参数的后缀 ^ 表示该提交对象的第一个父提交。^<n> 表示第 <n> 个父提交（即 <rev>^ 等同于 <rev>^1）。作为一个特殊规则，<rev>^0 表示提交本身，并在 <rev> 是指向提交对象的标签对象的对象名称时使用。

<rev>~[<n>]，例如 HEAD~, master~3

版本参数的后缀 ~ 表示该提交对象的第一个父提交。版本参数的后缀 ~<n> 表示该命名提交对象的第 <n> 代祖先提交对象，仅跟随第一个父提交。即 <rev>~3 等同于 <rev>^^^，等同于 <rev>^1^1^1。请参阅下文以获取此形式用法的插图。

<rev>^{<type>}，例如 v0.99.8^{commit}

后缀 ^ 后跟括在括号中的对象类型名称，表示递归解引用 <rev> 处的对象，直到找到 <type> 类型的对象或无法再解引用该对象为止（在这种情况下，报错）。例如，如果 <rev> 是提交相关对象（commit-ish），<rev>^{commit} 描述相应的提交对象。同样，如果 <rev> 是树相关对象（tree-ish），<rev>^{tree} 描述相应的树对象。<rev>^0 是 <rev>^{commit} 的简写。

<rev>^{object} 可用于确保 <rev> 命名了一个存在的对象，而不需要 <rev> 是一个标签，并且不需要解引用 <rev>；因为标签本身就是一个对象，所以即使为了获得对象也不需要解引用它一次。

<rev>^{tag} 可用于确保 <rev> 标识一个现有的标签对象。

<rev>^{}，例如 v0.99.8^{}

后缀 ^ 后跟一对空括号表示该对象可能是一个标签，并递归解引用标签，直到找到非标签对象。

<rev>^{/<text>}，例如 HEAD^{/fix nasty bug}

版本参数的后缀 ^，后跟包含以斜杠开头的文本的括号，与下文的 :/fix nasty bug 语法相同，不同之处在于它返回的是在 ^ 之前可从 <rev> 到达的最年轻的匹配提交。

:/<text>，例如 :/fix nasty bug

冒号后跟斜杠，后跟文本，命名一个提交信息与指定正则表达式匹配的提交。此名称返回任何引用（包括 HEAD）可达到的最年轻匹配提交。正则表达式可以匹配提交信息的任何部分。要匹配以字符串开头的消息，可以使用例如 :/^foo。特殊序列 :/! 保留用于对匹配内容进行修饰。:/!-foo 执行否定匹配，而 :/!!foo 匹配字面量 ! 字符，后跟 foo。任何其他以 :/! 开头的序列目前均为保留。根据给定的文本，shell 的单词拆分规则可能需要额外的引用。

<rev>:<path>，例如 HEAD:README，master:./README

后缀 : 后跟路径，命名冒号前部分命名的树相关对象中给定路径处的 blob 或树。以 ./ 或 ../ 开头的路径相对于当前工作目录。给定的路径将被转换为相对于工作树的根目录。这对于从具有与工作树相同树结构的提交或树中寻址 blob 或树最有用。

:[<n>:]<path>，例如 :0:README，:README

冒号，可选地后跟阶段编号（0 到 3）和冒号，后跟路径，命名索引中给定路径处的 blob 对象。缺失的阶段编号（以及跟随它的冒号）命名第 0 阶段条目。在合并期间，阶段 1 是共同祖先，阶段 2 是目标分支的版本（通常是当前分支），阶段 3 是正在合并的分支的版本。

这是一个由 Jon Loeliger 制作的插图。提交节点 B 和 C 都是提交节点 A 的父节点。父提交从左到右排序。

G   H   I   J
 \ /     \ /
  D   E   F
   \  |  / \
    \ | /   |
     \|/    |
      B     C
       \   /
        \ /
         A
A =      = A^0
B = A^   = A^1     = A~1
C =      = A^2
D = A^^  = A^1^1   = A~2
E = B^2  = A^^2
F = B^3  = A^^3
G = A^^^ = A^1^1^1 = A~3
H = D^2  = B^^2    = A^^^2  = A~2^2
I = F^   = B^3^    = A^^3^
J = F^2  = B^3^2   = A^^3^2

指定范围

诸如 git log 之类的历史遍历命令对一组提交进行操作，而不仅仅是单个提交。

对于这些命令，使用前一节中描述的符号指定单个版本，意味着从给定提交可达的提交集。

指定多个版本意味着从任何给定提交可达的提交集。

提交的可达集是提交本身及其祖先链中的提交。

有几种符号可以指定一组连接的提交（称为“版本范围”），如下所示。

提交排除

^<rev>（插入符号）符号

要排除可从提交中达到的提交，使用前缀 ^ 符号。例如，^r1 r2 表示从 r2 可达但排除从 r1 可达（即 r1 及其祖先）的提交。

点号范围符号

..（双点）范围符号

^r1 r2 集合运算出现得太频繁，因此有一个简写形式。当你有两个提交 r1 和 r2（根据上述指定版本中解释的语法命名）时，你可以请求从 r2 可达但从 r1 可达的那些提交，通过 ^r1 r2，它可以写成 r1..r2。

...（三点）对称差符号

类似的符号 r1...r2 称为 r1 和 r2 的对称差，定义为 r1 r2 --not $(git merge-base --all r1 r2)。它是从 r1（左侧）或 r2（右侧）中任一侧可达，但不能同时从两者中可达的提交集。

在这两种简写符号中，你可以省略一端并让其默认为 HEAD。例如，origin.. 是 origin..HEAD 的简写，询问“自从我从 origin 分支派生以来我做了什么？”同样，..origin 是 HEAD..origin 的简写，询问“自从我从他们派生以来 origin 做了什么？”请注意，.. 将意味着 HEAD..HEAD，这是一个既可从 HEAD 可达又不可达的空范围。

确实存在专门设计用于接收两个不同范围的命令（例如 "git range-diff R1 R2" 用于比较两个范围），但它们是例外。除非另有说明，所有对一组提交进行操作的“git”命令都在单个版本范围内工作。换句话说，将两个“双点范围符号”彼此相邻书写，例如

$ git log A..B C..D

对于大多数命令而言，并没有指定两个版本范围。相反，它将命名一个单一的连接提交集，即那些可从 B 或 D 可达，但不可从 A 或 C 可达的提交。在像这样的线性历史中

---A---B---o---o---C---D

因为 A 和 B 可从 C 达到，所以这两个点号范围指定的版本范围是单个提交 D。

其他 <rev>^ 父提交简写符号

存在另外三种简写，对于合并提交特别有用，用于命名由提交及其父提交形成的集合。

r1^@ 符号表示 r1 的所有父提交。

r1^! 符号包括提交 r1，但排除其所有父提交。单独来看，此符号表示单个提交 r1。

<rev>^-[<n>] 符号包括 <rev> 但排除第 <n> 个父提交（即 <rev>^<n>..<rev> 的简写），如果未给出则 <n> = 1。这对于合并提交通常很有用，你可以只传递 <commit>^- 来获取合并提交 <commit> 中合并进来的分支中的所有提交（包括 <commit> 本身）。

虽然 <rev>^<n> 是关于指定单个提交父项的，但这三种符号也考虑了它的父项。例如，你可以说 HEAD^2^@，但是你不能说 HEAD^@^2。

版本范围摘要

<rev>

包含可从 <rev> 达到的提交（即 <rev> 及其祖先）。

^<rev>

排除可从 <rev> 达到的提交（即 <rev> 及其祖先）。

<rev1>..<rev2>

包含可从 <rev2> 达到但排除那些可从 <rev1> 达到的提交。当省略 <rev1> 或 <rev2> 时，它默认为 HEAD。

<rev1>...<rev2>

包含可从 <rev1> 或 <rev2> 达到但排除那些可从两者都达到的提交。当省略 <rev1> 或 <rev2> 时，它默认为 HEAD。

<rev>^@，例如 HEAD^@

后跟 at 符号的 ^ 后缀与列出 <rev> 的所有父提交相同（意思是，包括任何可从其父提交达到的内容，但不包括提交本身）。

<rev>^!，例如 HEAD^!

后跟感叹号的 ^ 后缀与提供提交 <rev> 及其所有以 ^ 为前缀的父提交以排除它们（及其祖先）相同。

<rev>^-<n>，例如 HEAD^-, HEAD^-2

等同于 <rev>^<n>..<rev>，如果未给出则 <n> = 1。

这里有几个使用上面 Loeliger 插图的例子，仔细阐述了符号扩展和选择的每一步

   Args   Expanded arguments    Selected commits
   D                            G H D
   D F                          G H I J D F
   ^G D                         H D
   ^D B                         E I J F B
   ^D B C                       E I J F B C
   C                            I J F C
   B..C   = ^B C                C
   B...C  = B ^F C              G H D E B C
   B^-    = B^..B
	  = ^B^1 B              E I J F B
   C^@    = C^1
	  = F                   I J F
   B^@    = B^1 B^2 B^3
	  = D E F               D G H E F I J
   C^!    = C ^C^@
	  = C ^C^1
	  = C ^F                C
   B^!    = B ^B^@
	  = B ^B^1 ^B^2 ^B^3
	  = B ^D ^E ^F          B
   F^! D  = F ^I ^J D           G H D F

PARSEOPT

在 --parseopt 模式下，git rev-parse 帮助整理选项，为 shell 脚本提供 C 内置命令所拥有的相同功能。它就像一个选项规范化器（例如拆分聚合值的单个开关），有点像 getopt(1) 所做的那样。

它在标准输入上接收要解析和理解的选项规范，并在标准输出上回显一个字符串，该字符串适合 sh(1) eval 来用规范化参数替换参数。如果出现错误，它会在标准错误流上输出用法，并以代码 129 退出。

注意：将结果传递给 eval 时，请确保引用它。请参见下文示例。

输入格式

git rev-parse --parseopt 输入格式完全基于文本。它有两部分，由仅包含 -- 的行分隔。分隔符之前的行（应为一行或多行）用于用法说明。分隔符之后的行描述选项。

每一行选项具有此格式

<opt-spec><flags>*<arg-hint>? SP+ help LF
<opt-spec>

其格式为短选项字符，然后是逗号分隔的长选项名称。这两个部分不是必需的，但至少需要一个。不得包含任何 <flags> 字符。h,help、dry-run 和 f 是正确的 <opt-spec> 示例。

<flags>

<flags> 是 *、=、? 或 !。

  • 如果选项需要参数，请使用 =。

  • 使用 ? 表示选项接受可选参数。您可能需要使用 --stuck-long 模式来明确解析可选参数。

  • 使用 * 表示不应在为 -h 参数生成的用法说明中列出此选项。它会在 gitcli[7] 中记录的 --help-all 中显示。

  • 使用 ! 使对应的取反长选项不可用。

<arg-hint>

如果指定了 <arg-hint>，它将用作带参数选项的帮助输出中的参数名称。<arg-hint> 由第一个空格终止。通常使用破折号分隔多字参数提示中的单词。

在删除空格后，行的其余部分用作与选项相关的帮助信息。

空行会被忽略，不符合此规范的行用作选项组标题（在行首添加一个空格可以特意创建此类行）。

示例

OPTS_SPEC="\
some-command [<options>] <args>...

some-command does foo and bar!
--
h,help!   show the help

foo       some nifty option --foo
bar=      some cool option --bar with an argument
baz=arg   another cool option --baz with a named argument
qux?path  qux may take a path argument but has meaning by itself

  An option group Header
C?        option C with an optional argument"

eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"

用法文本

当上述示例中的 "$@" 为 -h 或 --help 时，将显示以下用法文本

usage: some-command [<options>] <args>...

    some-command does foo and bar!

    -h, --help            show the help
    --[no-]foo            some nifty option --foo
    --[no-]bar ...        some cool option --bar with an argument
    --[no-]baz <arg>      another cool option --baz with a named argument
    --[no-]qux[=<path>]   qux may take a path argument but has meaning by itself

An option group Header
    -C[...]               option C with an optional argument

SQ-QUOTE

在 --sq-quote 模式下，git rev-parse 在标准输出上回显适合 sh(1) eval 的单行。此行通过规范化 --sq-quote 之后的参数来创建。除了引用参数外，不执行任何其他操作。

如果您希望命令输入在输出 shell 引用之前仍然由 git rev-parse 按常规方式解释，请参阅 --sq 选项。

示例

$ cat >your-git-script.sh <<\EOF
#!/bin/sh
args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
command="git frotz -n24 $args"          # and use it inside a handcrafted
					# command line
eval "$command"
EOF

$ sh your-git-script.sh "a b'c"

示例

  • 打印当前提交的对象名称

    $ git rev-parse --verify HEAD

  • 打印 $REV shell 变量中版本的提交对象名称

    $ git rev-parse --verify --end-of-options $REV^{commit}

    如果 $REV 为空或不是有效版本，这将报错。

  • 类似于上面

    $ git rev-parse --default master --verify --end-of-options $REV

    但如果 $REV 为空，将打印 master 的提交对象名称。

GIT

Git[1] 套件的一部分