SYNOPSIS

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> …]

DESCRIPTION

<pattern> に一致するすべてのrefを繰り返し、指定された <key> の組に従って並べ替えた後、指定の <format> に従って表示します。 <count> が指定されている場合は、その数のrefを表示した後で停止します。 <format> のプレースホルダで差し込みされる値は、オプションで、指定のホストプログラム言語の文字列リテラルとなるようクォートでき、そのホストプログラム言語で直接評価できます。

OPTIONS

<pattern>…

1つ以上のパターンが指定されている場合、少なくとも1つのパターンに一致する参照のみが表示されます。fnmatch(3) を使用するか、文字通り(lietrally)に書くかです。文字通りに書いた場合場合、完全に一致するか、最初からスラッシュ(/)まで一致するかです。

--stdin

--stdin が指定されている場合、 パターンのリストは引数リストからではなく標準入力から読み取られます。

--count=<count>

デフォルトでは、コマンドは <pattern> に一致するすべてのrefを表示します。このオプションは、指定の数のrefを表示した後に停止します。

--sort=<key>

並べ替えるフィールド名。 プレフィックス - を使用すると、 値の降順で並べ替えます。 並べ替えるフィールド名を指定しない場合 refname が使用されます。 --sort=<key> オプションは複数回使用できます。 その場合、最後のキーが主キー(primary key)になります。

--format=<format>

表示されている ref とそれが指すオブジェクトを %(フィールド名) によって差し込みする書式文字列。 更に、 リテラル文字列の %% は % とレンダリングされ、 %xx は16進数 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>]

指定のコミット(指定されていない場合はHEAD)から先端に到達できるrefのみをリストします。

--no-merged[=<object>]

指定のコミット(指定されていない場合はHEAD)から先端に到達できないrefのみをリストします。

--contains[=<object>]

指定のコミット(指定されていない場合はHEAD)を含むrefのみをリストします。

--no-contains[=<object>]

指定のコミット(指定されていない場合はHEAD)を含まないrefのみをリストします。

--ignore-case

refの並べ替え(sort)とフィルタリングでは英大文字小文字を区別しません。

--omit-empty

フォーマットが空の文字列に展開されるフォーマット済み ref の後に改行を出力しないでください。

--exclude=<pattern>

1つ以上のパターンが与えられている場合、 除外されたパターンとマッチしない refs のみが表示されます。 マッチングは、 上記 の <pattern> と同じルールを使用して行われます。

--include-root-refs

通常の ref 以外の ルート ref (head と 疑似 refs)をリストします。

FIELD NAMES

参照オブジェクトの構造化フィールドのさまざまな値を使用して、結果の出力に差し込みしたり、ソートキーとして使用したりできます。

すべてのオブジェクトで、以下の名前を使用できます:

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

デルタとして保存されている場合、これは指定されたオブジェクトのデルタベースのオブジェクト名に展開されます。それ以外の場合は、ヌルオブジェクト名(すべてゼロ)に展開されます。

upstream

表示されたrefから「上流」(upstream)と見なすことができるローカル参照の名前。 上記の refname と同じように、 :short や :lstrip や :rstrip を尊重します。さらに、 :track は [ahead N, behind M] を表示し、 :trackshort は > (ahead) または < (behind) または "<>" (ahead and behind) または "=" (in sync) という簡潔なバージョンを表示します。 :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) の「CONFIGURATION FILE」セクションの「Values」で説明されています。 たとえば、 %(color:bold red) です。

align

コンテンツを %(align:…) から %(end) の間で左揃え、中央揃え、または右揃えにします。 align: の後には、 width=<width> と position=<position> がコンマ(,)で区切られた任意の順序で続きます。ここで、 <position> は left または right または middle のいずれかで、<position> の デフォルトは left で <width> のデフォルトは配置されたコンテンツの全長です。 簡潔にするために、 width= および/または position= プレフィックスを省略して、代わりに裸の <width> および <position> を使用することができます。 たとえば、 %(align:<width>,<position>) です。 コンテンツの長さがwidthよりも大きい場合、位置合わせは実行されません。 --quote とともに使用すると、 %(align:…) から %(end) の間のすべてがクォートされまれますが、ネストされている場合は、最上位レベルのみがクォートされます。

if

%(if) … %(then) … %(end) または %(if) … %(then) … %(else) … %(end) として使用されます。 %(if) の後に値または文字列リテラルを持つアトムがある場合は、 %(then) の後のすべてが出力されます。そうでない場合、 %(else) アトムが使用されている場合は、 %(else) の後のすべてが出力されます。 %(then) の前の文字列を評価するときはスペースを無視します。これは、 * または ` ` のいずれかを出力する %(HEAD) アトムを使用し、 HEAD ref にのみ if 条件を適用する場合に役立ちます。 :equals=<string> または :notequals=<string> を追加して、 %(if:…) アトムと %(then) アトムの間の値を指定された文字列と比較します。(訳注:つまり、 %(if) から %(then) の間がconditionである)

symref

与えられたシンボリックrefが参照するref。シンボリックrefでない場合、何も出力されません。上記の refname と同じ方法で、 :short と :lstrip と :rstrip オプションを尊重します。

signature

コミットのGPG署名。

signature:grade

良好(good)な(有効な)署名には「G」、 不良(bad)な署名には「B」、 有効性が不明(unknown)な良好な署名には「U」、有効期限が切れた(eXpired)良好な署名には「X」、 期限切れのキーによって作成された正常な署名には「Y」、 取り消されたキーによって作成された正常な署名には「R」、 (キーが見つからないなど)署名をチェックできない場合は「E」、 署名がない場合(no signature)は「N」です。

signature:signer

コミットのGPG署名の署名者。

signature:key

コミットのGPG署名のキー。

signature:fingerprint

コミットのGPG署名のフィンガープリント。

signature:primarykeyfingerprint

コミットの GPG 署名の主キー(primary key)のフィンガープリント。

signature:trustlevel

コミットの GPG 署名の信頼レベル(trust level)。 可能な出力は、 ultimate, fully, marginal, never, undefined です。

worktreepath

リンクされたワークツリー(linked worktree)でチェックアウトされている場合、refがチェックアウトされているワークツリーへの絶対パス。それ以外の場合は空文字列です。

ahead-behind:<committish>

空白で区切られた2つの整数が、 書式内で指定された <committish> と出力refを比較したときの、 それぞれ前方と後方のコミット数をあらわします。

is-base:<committish>

指定の <committish> を生成したブランチの開始点として最も可能性の高い ref であると選択した1行には (<committish>) と表記されます。 この選択は、ヒューリスティックを使用して行われます: つまり、 <committish> の最初の親の履歴の中でコミットの数を最小化する 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 の共通の祖先でフィルターされた ref 達の最初の親の履歴との間で直近の交差を持っていて、 B と C が同列の場合はソートされた順序で最も先の ref によって解決とするためです。

注意: このトークンは、 <committish> の最初の親の履歴がフィルターされたref達の最初の親の歴史と交差していない場合には表示されないことに注意してください。

describe[:options]

git-describe(1) のような人間が読み取り可能な名前。 describe 出来ないコミットの場合は空文字列。 describe 文字列の後には、 コロン(:)と1つ以上のコンマ(,)区切りオプション達が続く場合があります。

tags=<bool-value>

注釈付きタグのみを検討する代わりに、 軽量タグも検討してください。 詳細については、 git-describe(1) の対応するオプションを参照してください。

abbrev=<number>

少なくとも <number> 桁の16進数を使用します。 詳細については、 git-describe(1) の対応するオプションを参照してください。

match=<pattern>

refs/tags/ プレフィックスを除く、 指定の glob(7) パターンにマッチするタグのみを考慮します。 詳細については、 git-describe(1) の対応するオプションを参照してください。

exclude=<pattern>

refs/tags/ プレフィックスを除く、 指定の glob(7) パターンにマッチするタグを考慮しないでください。 詳細については、 git-describe(1) の対応するオプションを参照してください。

上記に加えて、commitとtagオブジェクトの場合、ヘッダーフィールド名(tree と parent と object と type と tag)を使用して、ヘッダーフィールドの値を指定できます。 フィールド tree と parent は、 objectname と同じように、修飾子 :short や :short=<length> とともに使用することもできます。

commitオブジェクトとtagオブジェクトの場合、特別な creatordate フィールドと creator フィールドは、オブジェクトタイプに応じて、 committer または tagger フィールドの適切な日付またはname-email-dateタプルに対応します。これらは、注釈付きタグと軽量タグの組み合わせでの作業を目的としています。

タグ・オブジェクトの場合、 アスタリスク(*)が付いた「フィールド名」は、 タグ・オブジェクト自体ではなく、 皮むきしたオブジェクト(peeled object)の「フィールド名」値に拡張されます。

名前と電子メールアドレスと日付(name-email-date)のタプルを値として持つフィールド(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

メッセージの最初の段落(通常は1行)は、コミットまたはタグメッセージの「件名」(subject)と見なされます。 contents:subject の代わりに、フィールド subject を使用して同じ結果を取得することもできます。 subject に追加できる :sanitize は、件名行をファイル名に適した形にします。

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) が必要です。 %(align) や %(if) などの一部のアトムを「開始アトム」(opening atoms)と呼び、 %($open) と表記することもあります。

スクリプト言語固有のクォートが有効な場合、トップレベルの開始アトムとそれに対応する %(end) の間のすべてが、トップレベル開始アトムのセマンティクスに従って評価され、そのトップレベルからの結果のみがクォートされます。

EXAMPLES

フォーマットされたテキストを直接生成する例。 直近の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)"

CAVEATS

注意: ディスク上のオブジェクトのサイズは正確に報告されますが、どのrefまたはオブジェクトがディスクの使用に関与しているかについて結論を出す際には注意が必要です。パックされた非デルタオブジェクトのサイズは、それに対してデルタするオブジェクトのサイズよりもはるかに大きい場合がありますが、ベースとデルタのオブジェクトの選択は任意であり、再パック中に変更される可能性があります。

注意: オブジェクトの複数のコピーがオブジェクトデータベースに存在する可能性があることにも注意してください。この場合、どのコピーのサイズまたはデルタベースが報告されるかは未定義です。

NOTES

複数の --contains フィルターと --no-contains フィルターを組み合わせる場合、少なくとも1つの --contains コミットを含み、 --no-contains コミットを含まない参照のみが表示されます。

複数の --merged フィルターと --no-merged フィルターを組み合わせると、少なくとも1つの --merged コミットから到達可能で、 --no-merged コミットのいずれからも到達できない参照のみが表示されます。

SEE ALSO

git-show-ref(1)

GIT

Part of the git(1) suite