簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-for-each-ref 最後更新於 2.50.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 (空字元)，%09 為 \t (製表符)，%0a 為 \n (換行符)。

未指定時，<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>)，則從引用名稱的前面（後面）剝離 <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> 剝離，結果將是完整的引用名稱。兩者都不是錯誤。

strip 可用作 lstrip 的同義詞。

objecttype

物件的型別（blob、tree、commit、tag）。

objectsize

物件的大小（與 git cat-file -s 報告的相同）。附加 :disk 以獲取物件在磁碟上佔用的位元組大小。請參閱下面 CAVEATS 部分中關於磁碟大小的說明。

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} 位置的本地引用名稱。與 upstream 一樣遵循 :short、:lstrip、:rstrip、:track、:trackshort、:remotename 和 :remoteref 選項。如果沒有配置 @{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) 原子時很有用，該原子列印“*”或“ ”，並且我們只想將 if 條件應用於 HEAD 引用。附加“:equals=<string>”或“:notequals=<string>”以將 %(if:...) 和 %(then) 原子之間的值與給定字串進行比較。

symref

給定符號引用所指向的引用。如果不是符號引用，則不列印任何內容。與上述 refname 相同的方式遵循 :short、:lstrip 和 :rstrip 選項。

signature

提交的 GPG 簽名。

signature:grade

“G”表示有效（good）簽名，“B”表示無效（bad）簽名，“U”表示有效但未知有效性（unknown validity）的簽名，“X”表示已過期（expired）的有效簽名，“Y”表示由已過期金鑰生成（expired key）的有效簽名，“R”表示由已撤銷金鑰生成（revoked key）的有效簽名，“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 擴充套件為剝離物件（peeled object）的 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)"

注意事項

請注意，磁碟上的物件大小報告是準確的，但應謹慎得出關於哪個引用或物件導致磁碟使用量的結論。未壓縮的非增量物件的大小可能遠大於以其為增量的物件的大小，但選擇哪個物件是基準哪個是增量是任意的，並且在重新打包期間可能會更改。

另請注意，物件資料庫中可能存在物件的多個副本；在這種情況下，報告哪個副本的大小或增量基準是未定義的。

注意事項

當組合多個 --contains 和 --no-contains 過濾器時，僅顯示包含至少一個 --contains 提交且不包含任何 --no-contains 提交的引用。

當組合多個 --merged 和 --no-merged 過濾器時，只顯示可從至少一個 --merged 提交到達且不可從任何 --no-merged 提交到達的引用。

另請參閱

git-show-ref[1]

GIT

Git[1] 套件的一部分

scroll-to-top