Git
英文 ▾ 主題 ▾ 最新版本 ▾ git-for-each-ref 最後更新於 2.47.0

名稱

git-for-each-ref - 輸出每個 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> 的 ref，並根據給定的 <format> 顯示它們，並根據給定的 <key> 排序。如果給定 <count>，則在顯示這麼多 ref 後停止。<format> 中的內插值可以選擇以指定主機語言的字串常值引用，允許它們在該語言中直接求值。

選項

<pattern>…​

如果給定一個或多個模式，則僅顯示與至少一個模式匹配的 ref，無論是使用 fnmatch(3) 還是字面上的，在後一種情況下，完全或從開頭到斜線匹配。

--stdin

如果提供 --stdin，則從標準輸入讀取模式列表，而不是從引數列表讀取。

--count=<count>

預設情況下，此命令顯示所有與 <pattern> 匹配的 ref。此選項使其在顯示這麼多 ref 後停止。

--sort=<key>

要排序的欄位名稱。加上 - 前綴表示按值的降序排序。未指定時，會使用 refname。你可以多次使用 --sort=<key> 選項，在這種情況下，最後一個鍵會成為主鍵。

--format=<format>

一個字串，從正在顯示的 ref 及其指向的物件內插 %(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>

僅列出指向給定物件的 ref。

--merged[=<object>]

僅列出其提示可從指定 commit 到達的 ref（如果未指定，則為 HEAD）。

--no-merged[=<object>]

僅列出其提示無法從指定 commit 到達的 ref（如果未指定，則為 HEAD）。

--contains[=<object>]

僅列出包含指定 commit 的 ref（如果未指定，則為 HEAD）。

--no-contains[=<object>]

僅列出不包含指定 commit 的 ref（如果未指定，則為 HEAD）。

--ignore-case

排序和篩選 ref 時不區分大小寫。

--omit-empty

在格式展開為空字串的格式化 ref 之後，不列印換行符。

--exclude=<pattern>

如果給定一個或多個模式，則僅顯示不匹配任何排除模式的 ref。比對使用與上面的 <pattern> 相同的規則完成。

--include-root-refs

除了常規 ref 之外，還列出根 ref（HEAD 和偽 ref）。

欄位名稱

可以從引用物件中的結構化欄位使用各種值內插到結果輸出中，或作為排序鍵。

對於所有物件，可以使用以下名稱

refname

ref 的名稱（$GIT_DIR/ 後面的部分）。對於 ref 的明確短名稱，請附加 :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）。當 ref 沒有足夠的元件時，如果使用正數 <N> 進行剝離，則結果會變成空字串；如果使用負數 <N> 進行剝離，則結果會變成完整的 refname。兩者都不是錯誤。

strip 可以用作 lstrip 的同義詞。

objecttype

物件的類型 (blob、tree、commit、tag)。

objectsize

物件的大小（與 *git cat-file -s* 報告的大小相同）。附加 :disk 以取得物件在磁碟上佔用的位元組大小。請參閱下面 CAVEATS 區段中有關磁碟大小的注意事項。

objectname

物件名稱（又稱 SHA-1）。對於物件名稱的非模糊縮寫，請附加 :short。對於具有所需長度的物件名稱縮寫，請附加 :short=<length>，其中最小長度為 MINIMUM_ABBREV。可以超過長度以確保物件名稱的唯一性。

deltabase

如果給定物件以增量形式儲存，則此值會展開為其增量基底的物件名稱。否則，它會展開為 null 物件名稱（全部為零）。

upstream

顯示的 ref 的「上游」本地 ref 名稱。如同上面的 refname，會遵循 :short、:lstrip 和 :rstrip。此外，還會遵循 :track 以顯示「[ahead N, behind M]」，以及 :trackshort 以顯示精簡版本：「>」(超前)、「<」(落後)、「<>」(超前且落後) 或「=」(同步)。如果遇到未知的上游 ref，:track 也會印出「[gone]」。附加 :track,nobracket 可顯示不含方括號的追蹤資訊 (例如「ahead N, behind M」)。

對於任何遠端追蹤分支 %(upstream)，%(upstream:remotename) 和 %(upstream:remoteref) 分別參照遠端名稱和追蹤的遠端 ref 名稱。換句話說，可以使用 refspec %(upstream:remoteref):%(upstream) 從 %(upstream:remotename) 提取，來明確且個別地更新遠端追蹤分支。

如果 ref 沒有相關的追蹤資訊，則無效。除了 nobracket 以外的所有選項都是互斥的，如果一起使用，則會選擇最後一個選項。

push

代表顯示的 ref 的 @{push} 位置的本地 ref 名稱。如同 upstream，會遵循 :short、:lstrip、:rstrip、:track、:trackshort、:remotename 和 :remoteref 選項。如果沒有設定 @{push} ref，則產生空字串。

HEAD

如果 HEAD 符合目前的 ref (已簽出的分支)，則為 *，否則為 ' '。

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) 後面有具有值或字串常值的 atom，則會印出 %(then) 後面的所有內容，否則如果使用 %(else) atom，則會印出 %(else) 後面的所有內容。我們在評估 %(then) 之前的字串時會忽略空格，這在使用 %(HEAD) atom (會印出「*」或「 」) 且我們只想對 HEAD ref 套用 if 條件時很有用。附加「:equals=<string>」或「:notequals=<string>」可比較 %(if:…​) 和 %(then) atom 之間的值與給定的字串。

symref

給定符號 ref 參照的 ref。如果不是符號 ref，則不印出任何內容。如同上面的 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

如果 ref 已簽出至任何連結的工作樹中，則為該工作樹的絕對路徑。否則為空字串。

ahead-behind:<committish>

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

is-base:<committish>

在最多一列中，會出現 (<committish>)，表示最有可能用作產生 <committish> 的分支起點的 ref。此選擇是使用啟發式方法進行：選擇可將 <committish> 的第一個父系歷史記錄中，但不屬於 ref 的第一個父系歷史記錄中的提交次數降至最低的 ref。

例如，考慮下列數個 ref 的第一個父系歷史記錄圖

*--*--*--*--*--* 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 的第一個父系歷史記錄的最早交集位於 B 和 C 的通用第一個父系祖先，而順序中最早的 ref 會中斷關聯。

請注意，如果 <committish> 的第一個父系歷史記錄與已篩選的 ref 的第一個父系歷史記錄不相交，則不會出現此符號。

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 來完成。

在任何情況下，若欄位名稱參照到 ref 所指物件不適用的欄位，都不會造成錯誤。而是會返回一個空字串。

對於日期類型的欄位，有一個特殊情況，您可以透過加入 : 後接日期格式名稱來指定日期格式（請參閱 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 的用法。列出所有 head 的前綴

#!/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)"

注意事項

請注意，磁碟上物件的大小會準確報告，但在得出關於哪些 ref 或物件導致磁碟使用量的結論時應謹慎。打包的非差異物件的大小可能遠大於與其進行差異比較的物件的大小，但是哪個物件是基準，哪個是差異是任意的，並可能在重新打包期間發生變化。

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

注意事項

當結合多個 --contains 和 --no-contains 篩選器時，只會顯示至少包含一個 --contains 提交，且不包含任何 --no-contains 提交的參考。

當結合多個 --merged 和 --no-merged 篩選器時，只會顯示可以從至少一個 --merged 提交訪問，且不能從任何 --no-merged 提交訪問的參考。

另請參閱

git-show-ref[1]

GIT

屬於 git[1] 套件的一部分

scroll-to-top