Setup and Config

• git
• config
• help
• bugreport
• Credential helpers

Getting and Creating Projects

• init
• clone

Basic Snapshotting

• add
• status
• diff
• commit
• notes
• restore
• reset
• rm
• mv

Branching and Merging

• branch
• checkout
• switch
• merge
• mergetool
• log
• stash
• tag
• worktree

Sharing and Updating Projects

• fetch
• pull
• push
• remote
• submodule

Inspection and Comparison

• show
• log
• diff
• difftool
• range-diff
• shortlog
• describe

Patching

• apply
• cherry-pick
• diff
• rebase
• revert

Debugging

• bisect
• blame
• grep

Email

• am
• apply
• imap-send
• format-patch
• send-email
• request-pull

External Systems

• svn
• fast-import

Server Admin

• daemon
• update-server-info

Guides

• gitattributes
• Command-line interface conventions
• Everyday Git
• Frequently Asked Questions (FAQ)
• Glossary
• Hooks
• gitignore
• gitmodules
• Revisions
• Submodules
• Tutorial
• Workflows
• All guides...

Administration

• clean
• gc
• fsck
• reflog
• filter-branch
• instaweb
• archive
• bundle

Plumbing Commands

• cat-file
• check-ignore
• checkout-index
• commit-tree
• count-objects
• diff-index
• for-each-ref
• hash-object
• ls-files
• ls-tree
• merge-base
• read-tree
• rev-list
• rev-parse
• show-ref
• symbolic-ref
• update-index
• update-ref
• verify-pack
• write-tree

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

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

Many Git porcelainish commands take a mixture of flags (i.e. parameters that begin with a dash -) and parameters meant for the underlying git rev-list command they use internally and flags and parameters for the other commands they use downstream of git rev-list. The primary purpose of this command is to allow calling programs to distinguish between them. There are a few other operation modes that have nothing to do with the above "help parse command line options".

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

操作模式

--parseopt 的选项

筛选选项

输出选项

对象选项

文件选项

其他选项

修订参数 <rev> 通常(但不一定)命名一个提交对象。 它使用所谓的 ‘扩展 SHA-1’ 语法。 这里有多种对象名称的拼写方式。 本列表末尾列出的对象名称用于命名提交中包含的树和二进制对象。

<sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e

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

<describeOutput(描述输出)>,例如 v1.7.4.2-679-g3bee7fb

来自 git describe 的输出;即一个最接近的标记,后面可选择一个破折号和提交次数,再后面是一个破折号、一个 g 和一个缩写的对象名称。

<引用名>, 例如 master, heads/master, refs/heads/master

符号引用名称。 例如,master 通常指 refs/heads/master 引用的提交对象。 如果你同时拥有 heads/master 和 tags/master ,你可以明确地说 heads/master 来告诉 Git 你指的是哪一个。 当 <引用名> 有歧义时,会根据以下规则取第一个匹配项来消除歧义:

1. 如果'$GIT_DIR/<引用名>' 存在,这就是你的意思(这通常只对 HEAD、FETCH_HEAD、ORIG_HEAD、MERGE_HEAD、REBASE_HEAD、REVERT_HEAD、CHERRY_PICK_HEAD、BISECT_HEAD 和 AUTO_MERGE 有用);

2. 否则,如果存在,则使用 refs/<引用名>;

3. 否则,如果存在 refs/tags/<引用名>,则使用 refs/tags/<引用名>;

4. 否则,如果存在 refs/heads/<引用名>,则使用 refs/heads/<引用名>;

5. 否则,如果存在 refs/remotes/<引用名>,则使用 refs/remotes/<引用名>;

6. 否则,如果存在 refs/remotes/<引用名>/HEAD,则使用 refs/remotes/<引用名>/HEAD。

   HEAD

   命名工作区中的更改所基于的提交。

   FETCH_HEAD

   记录您上次调用 git fetch 时 从远程仓库获取的分支。

   ORIG_HEAD

   命令(git am、git merge、git rebase、git reset)时创建的, 用于记录这些命令执行前`HEAD`的位置, 以便于将分支的顶端 改回执行这些命令前的状态。

   MERGE_HEAD

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

   REBASE_HEAD

   会记录当前停止操作的提交, 原因可能是冲突或 交互式变基中的 edit 命令。

   REVERT_HEAD

   记录您在运行 git 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 的快捷方式。

[<引用名>]@{<日期>}, 例如: master@{yesterday}, HEAD@{5 minutes ago}

在后缀为'@' 的引用后,用一对括号括起来的日期说明(例如 \{yesterday/}、{1 个月 2 周 3 天 1 小时 1 秒前} 或 {1979年02月26日 18:30:00})指定了引用在之前某个时间点的值。 该后缀只能紧跟在引用名称之后使用,且引用必须有现存日志($GIT_DIR/logs/<ref>)。需要注意的是,这个后缀查找的是*本地*引用在给定时间内的状态;例如,上周本地 master 分支中的情况。如果要查看特定时间内的提交,请参阅 --since 和 --until。

<引用名>@{<n>}, e.g. master@{1}

在后缀为 @ 的引用后,用一对括号(如 {1}、{15})括起来的序号说明指定了该引用的 n 次先验值。 例如,master@{1} 是 master 的直接先验值,而 master@{5} 是 master 的第 5 个先验值。该后缀只能紧跟在引用名称之后使用,并且引用必须有现存日志($GIT_DIR/logs/<引用名>)。

@{<n>}, e.g. @{1}

你可以使用带有空引用部分的"@"结构来获取当前分支的引用日志条目。例如,如果你在分支 blabla 上,那么 @{1} 与 blabla@{1} 的意思相同。

@{-<n>}, e.g. @{-1}

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

[<分支名>]@{upstream}, e.g. master@{upstream}, @{u}

分支 B 可以设置为在远程 R 的分支 X(使用 branch.<名称>.merge 配置)(使用 branch.<名称>.remote`配置)之上构建。B@{u} 指的是远程 R 分支 X 的远程跟踪分支,通常位于 `refs/remotes/R/X。

[<分支名>]@{push}, e.g. master@{push}, @{push}

后缀 @{push} 报告的是在 branchname 签出时运行 git push 时 "我们会推送到哪里" 的分支(如果没有指定分支名,则报告当前的 HEAD)。就像 @{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} 相同,没有必要使用。

这个后缀用大写字母拼写时也被接受,无论大小写,意思都一样。

<修订号>^[<n>],例如 HEAD^, v1.5.1^0

修订参数的后缀 ^ 表示该提交对象的第一个父对象。 ^<n>'表示第 <n> 个父提交(即 '<rev>^ 等同于 <rev>^1)。 作为一条特殊规则,<rev>^0 表示提交本身,在 <rev> 是指向提交对象的标记对象的对象名时使用。

<修订>~[<n>], e.g. HEAD~, master~3

修订参数的后缀 ~ 表示该提交对象的第一代父对象。 修订参数的后缀 ~<n> 表示该提交对象的 <n> 代祖先,仅次于第一代父对象。 例如,<rev>~3 等同于 <rev>^^^,后者等同于 <rev>^1^1^1。 请参阅下面的示例,了解这种形式的用法。

<修订>^{<类型>}, e.g. v0.99.8^{commit}

后缀 ^ 后跟有一对括号的对象类型名称,表示在 <修订> 处递归引用该对象,直到找到 <类型> 类型的对象或该对象无法再被引用(在这种情况下,barf)。 例如,如果 <修订> 是一个提交对象,那么 <修订>^/{commit/} 就描述了相应的提交对象。 同样,如果 <修订> 是一个树对象,那么 <修订>^/{tree/} 就描述了相应的树对象。 <修订>^0 是 <rev>^/{commit/} 的简写。

<修订>^/{object/} 可以用来确保 <修订> 命名了一个存在的对象,而不要求 <修订> 是一个标记,也不需要取消引用 <修订>;因为一个标记已经是一个对象,所以即使取消引用一次也不一定能找到一个对象。

可以使用 <修订>^/{tag} 来确保 <修订> 标识现有的标记对象。

<rev>^{}, e.g. v0.99.8^{}

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

<修订>^{/<文本>},例如 HEAD^{/fix nasty bug(修复讨厌的 BUG)}

版本参数的后缀 ^,后面是包含以斜线为首的文本的括号对,与下面的 :/fix nasty bug 语法相同,但它返回的是 ^ 之前的 <修订> 中最年轻的匹配提交。

:/<文本>,例如 :/fix nasty bug

冒号后的斜线和文本,用于命名提交信息与指定正则表达式匹配的提交。 该名称会返回可从任何引用(包括 HEAD)到达的最年轻的匹配提交。 正则表达式可以匹配提交信息的任何部分。要匹配以字符串开头的提交信息,可以使用 :/^foo。特殊序列 :/! 用于修饰匹配内容。:/!-foo 执行负匹配,而 :/!!foo 则匹配字面意义上的 ! 字符,后接 foo。以 :/! 开头的其他序列暂时保留。 根据给定的文本,shell 的分词规则可能需要额外的引号。

<修订>:<路径>,例如 HEAD:README, master:./README

后缀 : 和路径会在冒号前的树状对象中命名给定路径上的 blob 或树。 以'./' 或 ../ 开头的路径是相对于当前工作目录的。 给定路径将转换为相对于工作树根目录的路径。 这对于从与工作树具有相同树形结构的提交或树中查找 blob 或树最为有用。

:[<n>:]<路径>, e.g. :0:README, :README

一个冒号(可选)后面跟一个阶段编号(0 至 3)和一个冒号,冒号后面跟一个路径,用于命名索引中位于给定路径的 Blob 对象。如果缺少阶段号(以及后面的冒号),则命名为阶段 0 条目。在合并过程中,阶段 1 是共同祖先,阶段 2 是目标分支的版本(通常是当前分支),阶段 3 是被合并分支的版本。

下面是 Jon Loeliger 绘制的一幅插图。 提交节点 B 和 C 都是提交节点 A 的父节点。 父提交从左到右排序。

历史记录遍历命令,如 git log 会对一组提交进行操作,而不仅仅是单个提交。

对于这些命令,使用上一节中描述的符号指定一个修订版本,意味着从给定的提交开始 可达到 的一组提交。

指定多个修订版本指的是可从任何给定的提交版本到达的提交版本集。

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

有几种符号可以指定一组相连的提交(称为 "修订范围"),如下图所示。

排除提交

虚线范围符号

$ git log A..B C..D

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

其他 <修订号>^父级速记符号

<rev>

包括可从 <修订号> 到达的提交(即 <修订号> 及其祖先)。

^<修订号>

排除可从 <修订号> 到达的提交(即 <修订号> 及其祖先)。

<rev1>..<rev2>

包括可从 <修订号2> 进入的提交,但不包括可从 <修订号1> 进入的提交。 如果省略 <修订号1> 或 <修订号2>,则默认为 HEAD。

<修订号1>...<修订号2>

包括 <修订号1> 或 <修订号2> 均可访问的提交,但不包括 <修订号1> 和 <修订号2> 均可访问的提交。 省略 <修订号1> 或 <修订号2> 时,默认为 HEAD。

<修订>^@, e.g. HEAD^@

后缀 ^ 后跟一个 at(@) 符号,就等于列出了 <修订号> 的所有父提交(意思是,包括父提交中可触及的任何内容,但不包括提交本身)。

<修订号>^!,例如 HEAD^!

带感叹号的后缀 ^ 与提交 <修订号> 及其所有前缀为 ^ 的父节点相同,都是为了排除它们(及其祖先)。

<修订号>^-<n>,例如 HEAD^-, HEAD^-2

等价于 <修订号>^<n>..<修订号>,如果未给出,则 <n>= 1。

下面是一些使用上述 Loeliger 插图的示例,其中仔细说明了符号扩展和选择的每个步骤:

在 --parseopt 模式下,git rev-parse 可以帮助处理选项,为 shell 脚本带来与 C 语言内置程序相同的功能。它可以作为一个选项规范化器工作(例如分割单值和总值),有点像 getopt(1)。

它在标准输入端接收要解析和理解的选项说明,并在标准输出端回声一个适合 sh(1) eval 的字符串,以便用规范化参数替换参数。 如果出现错误,它会在标准错误流中输出使用情况,并以代码 129 退出。

注意:在将结果传递给 eval 时,请务必加上引号。 请参阅下面的示例。

输入格式

<指定选项><标记>*<参数提示>? SP+ help LF

示例

OPTS_SPEC="\
some-command [<选项>] <参数>...
some-command 会执行 foo 和 bar!
--
h,help! 显示帮助
foo 一些简便的选项 --foo bar= 一些很酷的选项 --bar 带着一个参数 baz=arg 其他很酷的选项 --baz 带着指定名称的参数 qux?path qux 会带上一个 path 参数,但是对它自己有意义
 一个选项组头
C? 带着一个可选参数的 C 选项
eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"

使用文本

usage: some-command [<选项>] <参数>...
 some-command 会执行 foo 和 bar!
 -h, --help 显示磅帮助
 --[no-]foo 一些简便的选项 --foo
 --[no-]bar ... 一些很酷的选项 --bar 带着一个参数
 --[no-]baz <arg> 另外很酷的选项 --baz 带着指定名称的参数
 --[no-]qux[=<路径>] qux 可能会带上一个对它自己有意义的路径参数
一个选项组的头部
 -C[...] 带着一个可选参数的选项 C

在 --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 "$@") # 引用用户提供的参数
command="git frotz -n24 $args" # 并手动将它在内部使用
					# 命令行
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[1] 文档