Git

git-for-each-ref 最后更新于 2.47.0

名称

git-for-each-ref - 输出每个引用上的信息

概要

git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
		   [(--sort=<key>)…] [--format=<format>]
		   [--include-root-refs] [ --stdin | <pattern>… ]
		   [--points-at=<object>]
		   [--merged[=<object>]] [--no-merged[=<object>]]
		   [--contains[=<object>]] [--no-contains[=<object>]]
		   [--exclude=<pattern> …]

描述

迭代所有与<pattern>匹配的引用，并根据给定的<format>显示它们，然后根据给定的<key>集合对它们进行排序。如果给出了<count>，则在显示了这么多引用后停止。<format>中的插值值可以选择在指定的宿主语言中被引用为字符串文字，允许它们在该语言中直接求值。

选项

<pattern>…: 如果给出了一个或多个模式，则仅显示与至少一个模式匹配的引用，使用 fnmatch(3) 或字面意义，在后一种情况下，完全匹配或从开头匹配到一个斜杠。
--stdin: 如果提供了--stdin，则模式列表从标准输入而不是从参数列表中读取。
--count=<count>: 默认情况下，该命令显示所有与<pattern>匹配的引用。此选项使其在显示了这么多引用后停止。
--sort=<key>: 要排序的字段名称。在值的降序排列中添加前缀-。如果未指定，则使用refname。您可以多次使用--sort=<key>选项，在这种情况下，最后一个键成为主键。
--format=<format>: 一个字符串，它从被显示的引用及其指向的对象中插值%(fieldname)。此外，字符串文字%%呈现为%，%xx（其中xx是十六进制数字）呈现为十六进制代码为xx的字符。例如，%00插值为\0（NUL），%09插值为\t（TAB），%0a插值为\n（LF）。

如果未指定，则<format>默认为%(objectname) SPC %(objecttype) TAB %(refname)。
--color[=<when>]: 尊重--format选项中指定的任何颜色。<when>字段必须是always、never或auto之一（如果<when>不存在，则表现得好像给出了always）。
--shell
--perl
--python
--tcl: 如果给出，替换%(fieldname)占位符的字符串将被引用为适合指定宿主语言的字符串文字。这旨在产生可以直接eval的脚本。
--points-at=<object>: 仅列出指向给定对象的引用。
--merged[=<object>]: 仅列出其顶端可以从指定提交（如果未指定，则为 HEAD）到达的引用。
--no-merged[=<object>]: 仅列出其顶端无法从指定提交（如果未指定，则为 HEAD）到达的引用。
--contains[=<object>]: 仅列出包含指定提交（如果未指定，则为 HEAD）的引用。
--no-contains[=<object>]: 仅列出不包含指定提交（如果未指定，则为 HEAD）的引用。
--ignore-case: 排序和过滤引用不区分大小写。
--omit-empty: 在格式化后的引用中，如果格式展开为空字符串，则不要打印换行符。
--exclude=<pattern>: 如果给出了一个或多个模式，则仅显示不匹配任何排除模式的引用。匹配使用与上面的<pattern>相同的规则。
--include-root-refs: 除了常规引用外，还列出根引用（HEAD 和伪引用）。

字段名称

引用对象中结构化字段中的各种值可用于插值到结果输出中，或用作排序键。

对于所有对象，可以使用以下名称

refname

引用的名称（$GIT_DIR/ 之后的部分）。对于引用的非歧义短名称，附加:short。选项 core.warnAmbiguousRefs 用于选择严格的缩写模式。如果附加了lstrip=<N>（rstrip=<N>），则从 refname 的开头（结尾）剥离<N>个以斜杠分隔的路径组件（例如，%(refname:lstrip=2) 将 refs/tags/foo 转换为 foo，而 %(refname:rstrip=2) 将 refs/tags/foo 转换为 refs）。如果<N>是一个负数，则从指定的末尾剥离尽可能多的路径组件，以保留-<N>个路径组件（例如，%(refname:lstrip=-2) 将 refs/tags/foo 转换为 tags/foo，而 %(refname:rstrip=-1) 将 refs/tags/foo 转换为 refs）。当引用没有足够的组件时，如果使用正 <N> 剥离，结果将变为空字符串，如果使用负 <N> 剥离，结果将变为完整的 refname。两者都不是错误。

strip 可用作 lstrip 的同义词。

objecttype

对象的类型（blob、tree、commit、tag）。

objectsize

对象的大小（与git cat-file -s 报告的相同）。附加:disk 以获取对象在磁盘上占用的字节大小。有关磁盘大小的说明，请参见下面的“警告”部分。

objectname

对象名称（又名 SHA-1）。对于对象名称的非歧义缩写，附加:short。对于具有所需长度的对象名称的缩写，附加:short=<length>，其中最小长度为 MINIMUM_ABBREV。长度可能会超过以确保对象名称的唯一性。

deltabase

这将扩展到给定对象的增量基的对象名称，如果它被存储为增量。否则，它将扩展为零对象名称（全为零）。

upstream

可以被视为显示引用的“上游”的本地引用的名称。以与上面的refname相同的方式尊重:short、:lstrip 和 :rstrip。此外，尊重:track 以显示 "[ahead N, behind M]"，并尊重:trackshort 以显示简短版本：">"（领先）、"<"（落后）、"<>"（领先和落后）或 "="（同步）。:track 还会在遇到未知上游引用时打印 "[gone]"。附加:track,nobracket 以显示没有括号的跟踪信息（即 "ahead N, behind M"）。

对于任何远程跟踪分支%(upstream)，%(upstream:remotename) 和 %(upstream:remoteref) 分别引用远程的名称和跟踪的远程引用的名称。换句话说，远程跟踪分支可以使用 refspec %(upstream:remoteref):%(upstream) 从%(upstream:remotename) 中提取，以便显式地和单独地更新。

如果引用没有与之关联的跟踪信息，则没有效果。除了nobracket 之外，所有选项都是互斥的，但如果一起使用，则选择最后一个选项。

push

代表显示引用的@{push} 位置的本地引用的名称。尊重:short、:lstrip、:rstrip、:track、:trackshort、:remotename 和 :remoteref 选项，就像upstream 一样。如果未配置@{push} 引用，则生成空字符串。

HEAD

如果 HEAD 与当前引用（已检出的分支）匹配，则为*，否则为 ' '。

color

更改输出颜色。后面跟着:<colorname>，其中颜色名称在 git-config[1] 的“配置文件”部分的“值”下有描述。例如，%(color:bold red)。

align

将 %(align:…) 和 %(end) 之间的內容左、中或右對齊。 "align:" 後面跟著 width=<width> 和 position=<position>，以逗號分隔，順序不限，其中 <position> 可以是 left、right 或 middle，預設為 left，而 <width> 是對齊內容的總長度。為了簡潔，可以省略 "width=" 和/或 "position=" 前綴，直接使用 <width> 和 <position>。例如，%(align:<width>,<position>)。如果內容的長度超過寬度，則不會執行任何對齊。如果與 --quote 一起使用，%(align:…) 和 %(end) 之間的所有內容都將被引用，但如果嵌套，則只有最頂層執行引用。

if

用作 %(if)…%(then)…%(end) 或 %(if)…%(then)…%(else)…%(end)。如果在 %(if) 後面有一個帶有值或字串文字的原子，則會列印 %(then) 後面的所有內容，否則如果使用了 %(else) 原子，則會列印 %(else) 後面的所有內容。在評估 %(then) 之前的字串時，我們忽略空格，這在我們使用 %(HEAD) 原子（列印 "*" 或 " "）時很有用，並且我們只想對 HEAD 引用應用 if 條件。附加 ":equals=<string>" 或 ":notequals=<string>" 以將 %(if:…) 和 %(then) 原子之間的值與給定的字串進行比較。

symref

給定符號引用所引用的引用。如果不是符號引用，則不列印任何內容。與上面的 refname 一樣，尊重 :short、:lstrip 和 :rstrip 選項。

signature

提交的 GPG 簽章。

signature:grade

顯示 "G" 代表良好（有效）簽章，"B" 代表不良簽章，"U" 代表有效簽章但有效性未知，"X" 代表已過期的良好簽章，"Y" 代表由已過期金鑰生成的良好簽章，"R" 代表由已撤銷金鑰生成的良好簽章，"E" 代表無法檢查簽章（例如，缺少金鑰），"N" 代表沒有簽章。

signature:signer

提交的 GPG 簽章的簽署者。

signature:key

提交的 GPG 簽章的金鑰。

signature:fingerprint

提交的 GPG 簽章的指紋。

signature:primarykeyfingerprint

提交的 GPG 簽章的主金鑰指紋。

signature:trustlevel

提交的 GPG 簽章的信任級別。可能的輸出是 ultimate、fully、marginal、never 和 undefined。

worktreepath

引用在其中被檢出的工作樹的絕對路徑，如果它在任何鏈接的工作樹中被檢出。否則為空字串。

ahead-behind:<committish>

兩個整數，以空格分隔，表示將輸出引用與格式中指定的 <committish> 進行比較時，分別超前和落後的提交次數。

is-base:<committish>

最多在一行中，將出現 (<committish>) 以指示最有可能用作產生 <committish> 的分支的起點的引用。此選擇是使用啟發式方法做出的：選擇將 <committish> 的第一父歷史中的提交次數降到最低，並且不在引用的第一父歷史中的引用。

例如，考慮以下幾個引用的第一父歷史圖

*--*--*--*--*--* refs/heads/A
\
 \
  *--*--*--* refs/heads/B
   \     \
    \     \
     *     * refs/heads/C
      \
       \
	*--* refs/heads/D

在此，如果 A、B 和 C 是過濾後的引用，並且格式字串為 %(refname):%(is-base:D)，則輸出將為

refs/heads/A:
refs/heads/B:(D)
refs/heads/C:

這是因為 D 的第一父歷史與過濾後的引用的第一父歷史的最早交集位於 B 和 C 的共同第一父祖先，並且通過排序順序中最早的引用來打破平局。

請注意，如果 <committish> 的第一父歷史不與過濾後的引用的第一父歷史相交，則此令牌將不會出現。

describe[:options]

一個人類可讀的名稱，如 git-describe[1]；對於不可描述的提交，為空字串。 describe 字串後面可以是冒號和一個或多個以逗號分隔的選項。

tags=<bool-value>: 不只考慮註釋標籤，還考慮輕量級標籤；有關詳細信息，請參閱 git-describe[1] 中的對應選項。
abbrev=<number>: 使用至少 <number> 個十六進制數字；有關詳細信息，請參閱 git-describe[1] 中的對應選項。
match=<pattern>: 僅考慮與給定的 glob(7) 模式匹配的標籤，排除 "refs/tags/" 前綴；有關詳細信息，請參閱 git-describe[1] 中的對應選項。
exclude=<pattern>: 不要考慮與給定的 glob(7) 模式匹配的標籤，排除 "refs/tags/" 前綴；有關詳細信息，請參閱 git-describe[1] 中的對應選項。

除了以上內容之外，對於提交和標籤物件，可以使用標頭欄位名稱（tree、parent、object、type 和 tag）來指定標頭欄位中的值。欄位 tree 和 parent 也可以使用修飾符 :short 和 :short=<length>，就像 objectname 一樣。

對於提交和標籤物件，特殊的 creatordate 和 creator 欄位將對應於 committer 或 tagger 欄位中的適當日期或姓名-電子郵件-日期元組，具體取決於物件類型。這些旨在用於處理註釋標籤和輕量級標籤的混合。

對於標籤物件，以星號 (*) 為前綴的 fieldname 會擴展到剝離物件的 fieldname 值，而不是標籤物件本身的值。

具有姓名-電子郵件-日期元組作為其值的欄位（author、committer 和 tagger）可以附加 name、email 和 date 以提取命名組件。對於電子郵件欄位（authoremail、committeremail 和 taggeremail），可以附加 :trim 以獲取沒有尖括號的電子郵件，以及 :localpart 以從修剪後的電子郵件中獲取 "@" 符號之前的部分。除了這些之外，還可以使用的 :mailmap 選項以及對應的 :mailmap,trim 和 :mailmap,localpart（順序無關）根據 .mailmap 文件或根據 mailmap.file 或 mailmap.blob 配置變數中設置的文件來獲取姓名和電子郵件的值（請參閱 gitmailmap[5]）。

物件中的原始數據為 raw。

raw:size: 物件的原始數據大小。

請注意，--format=%(raw) 不能與 --python、--shell、--tcl 一起使用，因為這些語言可能不支持其字串變數類型中的任意二進制數據。

提交或標籤物件中的訊息為 contents，可以從中使用 contents:<part> 來提取各種部分

contents:size: 提交或標籤訊息的字節大小。
contents:subject: 訊息的第一段，通常是一行，被視為提交或標籤訊息的 "主旨"。除了 contents:subject 之外，欄位 subject 也可用於獲取相同的結果。 :sanitize 可以附加到 subject，以獲取適合文件名的主旨行。
contents:body: 提交或標籤訊息中緊隨 "主旨" 的其餘部分。
contents:signature: 標籤的可选 GPG 签名。
contents:lines=N: 訊息的前 N 行。

此外，由 git-interpret-trailers[1] 解釋的尾部作為 trailers[:options] 獲得（或通過使用歷史別名 contents:trailers[:options]）。有關有效 [:option] 值，請參閱 git-log[1] 的 trailers 部分。

為了排序目的，具有數值的值的欄位按數值順序排序（objectsize、authordate、committerdate、creatordate、taggerdate）。所有其他欄位都用於按其位元組值順序排序。

還有一個按版本排序的選項，這可以通过使用欄位名稱 version:refname 或其別名 v:refname 來實現。

在任何情况下，引用不適用於引用所引用的物件的欄位名稱都不会造成錯誤。它會返回一個空字串。

作為日期類型欄位的特例，您可以通過添加冒號 (:) 後面跟著日期格式名稱來指定日期的格式（請參閱 git-rev-list[1] 的 --date 選項所接受的值）。如果在 --sort 關鍵字中提供了此格式化，則引用將根據格式化字串的位元組值排序，而不是根據基礎時間戳記的數值排序。

某些原子，例如 %(align) 和 %(if)，始终需要匹配的 %(end)。我们称它们为“打开原子”，有时用 %($open) 表示它们。

当脚本语言特定引用生效时，顶级打开原子与其匹配的 %(end) 之间的任何内容都将根据打开原子的语义进行评估，并且只有其来自顶层的結果将被引用。

示例

直接产生格式化文本的示例。显示最近的 3 个已标记的提交

#!/bin/sh

git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
Ref: %(*refname)

%(*body)
' 'refs/tags'

一个简单的示例，显示了在输出上使用 shell eval 的方式，展示了 --shell 的用法。列出所有头的的前缀

#!/bin/sh

git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
while read entry
do
	eval "$entry"
	echo `dirname $ref`
done

关于标签的更详细的报告，展示了格式可能是一个完整的脚本

#!/bin/sh

fmt='
	r=%(refname)
	t=%(*objecttype)
	T=${r#refs/tags/}

	o=%(*objectname)
	n=%(*authorname)
	e=%(*authoremail)
	s=%(*subject)
	d=%(*authordate)
	b=%(*body)

	kind=Tag
	if test "z$t" = z
	then
		# could be a lightweight tag
		t=%(objecttype)
		kind="Lightweight tag"
		o=%(objectname)
		n=%(authorname)
		e=%(authoremail)
		s=%(subject)
		d=%(authordate)
		b=%(body)
	fi
	echo "$kind $T points at a $t object $o"
	if test "z$t" = zcommit
	then
		echo "The commit was authored by $n $e
at $d, and titled

    $s

Its message reads as:
"
		echo "$b" | sed -e "s/^/    /"
		echo
	fi
'

eval=`git for-each-ref --shell --format="$fmt" \
	--sort='*objecttype' \
	--sort=-taggerdate \
	refs/tags`
eval "$eval"

一个展示 %(if)…%(then)…%(else)…%(end) 用法的示例。此示例会在当前分支前添加星号。

git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/

一个展示 %(if)…%(then)…%(end) 用法的示例。此示例会打印作者姓名（如果存在）。

git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"

注意事项

请注意，磁盘上对象的大小被准确地报告，但应谨慎得出关于哪些引用或对象负责磁盘使用量的结论。打包的非 delta 对象的大小可能远大于针对其进行 delta 的对象的大小，但哪个对象是基础对象以及哪个对象是 delta 对象的选择是任意的，并且在重新打包期间可能会发生变化。

还要注意，对象数据库中可能存在对象的多个副本；在这种情况下，将报告哪个副本的大小或 delta 基础是未定义的。

注意

当组合多个 --contains 和 --no-contains 过滤器时，只会显示包含至少一个 --contains 提交并且不包含任何 --no-contains 提交的引用。

当组合多个 --merged 和 --no-merged 过滤器时，只会显示从至少一个 --merged 提交可达并且不从任何 --no-merged 提交可达的引用。

参见

git-show-ref[1]

是 git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

补丁

调试

电子邮件

外部系统

服务器管理

指南

管理

管道命令

名称

概要

描述

选项

字段名称

示例

注意事项

注意

参见

GIT

for-each-ref