git-for-each-ref · Git 中文參考

# git-for-each-ref > 原文： [https://git-scm.com/docs/git-for-each-ref](https://git-scm.com/docs/git-for-each-ref) ## 名稱 git-for-each-ref - 每個參考的輸出信息 ## 概要 ``` git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)…?] [--format=<format>] [<pattern>…?] [--points-at=<object>] (--merged[=<object>] | --no-merged[=<object>]) [--contains[=<object>]] [--no-contains[=<object>]] ``` ## 描述迭代匹配`<pattern>`的所有引用并根據給定的`<format>`顯示它們，然后根據給定的`<key>`集對它們進行排序。如果給出`<count>`，則在顯示許多參考后停止。 `<format>`中的插值可以選擇引用指定主語言中的字符串文字，允許直接用該語言進行評估。 ## OPTIONS ``` <pattern>…? ``` 如果給出一個或多個模式，則僅顯示與至少一個模式匹配的refs，使用fnmatch（3）或字面意思，在后一種情況下完全匹配或從開頭到斜線。 ``` --count=<count> ``` 默認情況下，該命令顯示與`<pattern>`匹配的所有引用。此選項使其在顯示許多引用后停止。 ``` --sort=<key> ``` 要排序的字段名稱。前綴`-`按值的降序排序。未指定時，使用`refname`。您可以使用--sort =< key>選項多次，在這種情況下，最后一個鍵成為主鍵。 ``` --format=<format> ``` 一個字符串，用于插入顯示的ref及其指向的對象的`%(fieldname)`。如果`fieldname`以星號（`*`為前綴）并且ref指向標記對象，請使用標記對象引用的對象中的字段值（而不是標記對象中的字段）。未指定時，`<format>`默認為`%(objectname) SPC %(objecttype) TAB %(refname)`。它還將`%%`插入到`%`，`%xx`其中`xx`是十六進制數字，插入到十六進制代碼`xx`的字符中;例如`%00`內插到`\0`（NUL），`%09`到`\t`（TAB）和`%0a`到`\n`（LF）。 ``` --color[=<when>] ``` 尊重`--format`選項中指定的任何顏色。 `<when>`字段必須是`always`，`never`或`auto`之一（如果`<when>`不存在，則表現得好像`always`一樣）。 ``` --shell ``` ``` --perl ``` ``` --python ``` ``` --tcl ``` 如果給定，則替換`%(fieldname)`占位符的字符串將被引用為適合指定宿主語言的字符串文字。這是為了生成一個可以直接“評估”的scriptlet。 ``` --points-at=<object> ``` 僅列出指向給定對象的引用。 ``` --merged[=<object>] ``` 僅列出可從指定提交（HEAD，如果未指定）可訪問的引用的refs，與`--no-merged`不兼容。 ``` --no-merged[=<object>] ``` 僅列出其指針無法從指定的提交（如果未指定，則為HEAD）可訪問的refs，與`--merged`不兼容。 ``` --contains[=<object>] ``` 僅列出包含指定提交的引用（如果未指定，則為HEAD）。 ``` --no-contains[=<object>] ``` 僅列出不包含指定提交的引用（如果未指定，則為HEAD）。 ``` --ignore-case ``` 排序和過濾refs不區分大小寫。 ## 字段名稱來自引用對象中的結構化字段的各種值可用于插入到結果輸出中，或作為排序鍵。對于所有對象，可以使用以下名稱： ``` refname ``` ref的名稱（$ GIT_DIR /之后的部分）。對于ref附加`: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/tags/foo` COD17]）。當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 ``` 如果將其存儲為delta，則會擴展為給定對象的delta base的對象名稱。否則它會擴展為空對象名稱（全為零）。 ``` upstream ``` 本地引用的名稱，可以被視為顯示引用的“上游”。以與上述`refname`相同的方式尊重`:short`，`:lstrip`和`:rstrip`。另外尊重`:track`以顯示“[前N，后M]”和`:trackshort`以顯示簡潔版本：“>” （提前），“<” （后面），“<>” （前后）或“=”（同步）。每當遇到未知的上游引用時，`:track`也會打印“[gone]”。附加`:track,nobracket`以顯示沒有括號的跟蹤信息（即“在N之前，在M之后”）。對于任何遠程跟蹤分支`%(upstream)`，`%(upstream:remotename)`和`%(upstream:remoteref)`分別指代遠程名稱和被跟蹤遠程ref的名稱。換句話說，遠程跟蹤分支可以通過使用refspec `%(upstream:remoteref):%(upstream)`從`%(upstream:remotename)`獲取來顯式和單獨更新。如果ref沒有與之關聯的跟蹤信息，則無效。除`nobracket`之外的所有選項都是互斥的，但如果一起使用，則選擇最后一個選項。 ``` push ``` 本地引用的名稱，表示顯示的引用的`@{push}`位置。與`upstream`一樣，`:short`，`:lstrip`，`:rstrip`，`:track`，`:trackshort`，`:remotename`和`:remoteref`選項。如果未配置`@{push}` ref，則生成空字符串。 ``` HEAD ``` _*_ 如果HEAD匹配當前ref（檢出的分支），否則。 ``` color ``` 更改輸出顏色。后跟`:<colorname>`，其中顏色名稱在 [git-config [1]](https://git-scm.com/docs/git-config) 的“CONFIGURATION FILE”部分的值下描述。例如，`%(color:bold red)`。 ``` align ``` 左，中，或右對齊％（對齊：...）和％（結束）之間的內容。 “對齊：”之后是以逗號分隔的任何順序的`width=<width>`和`position=<position>`，其中`<position>`是左，右或中間，默認為左，`<width>`是內容的總長度對齊。為簡潔起見，可以省略“width =”和/或“position =”前綴，并且< width>和< position>用來代替。例如，`%(align:<width>,<position>)`。如果內容長度大于寬度，則不執行對齊。如果與`--quote`一起使用，則引用％（align：...）和％（end）之間的所有內容，但如果嵌套，則只有最頂層執行引用。 ``` if ``` 用作％（if）...％（然后）...％（結束）或％（如果）...％（然后）...％（否則）...％（結束）。如果在％（if）之后有一個帶有值或字符串文字的原子，則打印％（then）之后的所有內容，否則如果使用％（else）原子，則打印％（else）之后的所有內容。我們在％（然后）之前評估字符串時忽略空格，當我們使用打印“*”或“”的％（HEAD）原子并且我們想要僅在條件下應用_時這很有用 _HEAD_ 參考。附加“：equals =< string>”或“：notequals =< string>”比較％（if：...）和％（then）原子與給定字符串之間的值。_ ``` symref ``` 給定符號ref引用的引用。如果不是符號引用，則不打印任何內容。以與`refname`相同的方式尊重`:short`，`:lstrip`和`:rstrip`選項。除上述內容外，對于提交和標記對象，標題字段名稱（`tree`，`parent`，`object`，`type`和`tag`）可用于指定標題字段中的值。對于提交和標記對象，特殊的`creatordate`和`creator`字段將對應于`committer`或`tagger`字段中的相應日期或名稱 - 電子郵件 - 日期元組，具體取決于對象類型。這些用于處理帶注釋和輕量級標簽的混合。將name-email-date元組作為其值（`author`，`committer`和`tagger`）的字段可以后綴`name`，`email`和`date`以提取指定的組件。提交和標記對象中的完整消息是`contents`。它的第一行是`contents:subject`，其中subject是提交消息的所有行的連接，直到第一個空行。下一行是`contents:body`，其中body是第一個空白行之后的所有行。可選的GPG簽名是`contents:signature`。使用`contents:lines=N`獲得消息的第一`N`行。另外，由 [git-interpre-trailers [1]](https://git-scm.com/docs/git-interpret-trailers) 解釋的預告片作為`trailers`（或通過使用歷史別名`contents:trailers`）獲得。使用`trailers:only`可以省略拖車塊中的非拖車線。可以從預告片中刪除空格連續，以便每個預告片單獨出現在一行上，其全部內容為`trailers:unfold`。兩者可以一起用作`trailers:unfold,only`。出于排序目的，具有數值的字段按數字順序排序（`objectsize`，`authordate`，`committerdate`，`creatordate`，`taggerdate`）。所有其他字段用于按字節值順序排序。還有一個按版本排序的選項，這可以通過使用fieldname `version:refname`或其別名`v:refname`來完成。在任何情況下，引用不適用于ref引用的對象的字段的字段名稱不會導致錯誤。它返回一個空字符串。作為日期類型字段的特殊情況，您可以通過添加`:`后跟日期格式名稱來指定日期的格式（請參閱 [git-rev-list [1]的`--date`選項的值](https://git-scm.com/docs/git-rev-list)需要）。像％（對齊）和％（如果）這樣的原子總是需要匹配的％（結束）。我們稱它們為“開放原子”，有時將它們表示為％（$ open）。當特定于腳本語言的引用生效時，頂級開放原子與其匹配的％（結束）之間的所有內容都根據開放原子的語義進行評估，并且僅引用頂級開放原子的結果。 ## 例子直接生成格式化文本的示例。顯示最近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）...％（然后）...％（else）...％（end）的用法的示例。這為當前分支添加星號前綴。 ``` git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ ``` 顯示％（if）...％（然后）...％（結束）的用法的示例。這將打印authorname（如果存在）。 ``` git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" ``` ## CAVEATS 請注意，磁盤上對象的大小是準確報告的，但應該注意得出哪些引用或對象負責磁盤使用的結論。打包的非delta對象的大小可能遠大于對其增量的對象的大小，但是選擇哪個對象是基礎并且delta是任意的并且在重新打包期間可能會發生變化。還要注意，對象的多個副本可能存在于對象數據庫中;在這種情況下，未定義將報告哪個副本的大小或增量基數。 ## 也可以看看 [git-show-ref [1]](https://git-scm.com/docs/git-show-ref) ## GIT 部分 [git [1]](https://git-scm.com/docs/git) 套件