SYNOPSIS

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

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とそれが指すオブジェクトを %(fieldname) によってを差し込みする書式文字列。 fieldname の前にアスタリスク(*)が付いていて、refがタグオブジェクトを指している場合は、(タグオブジェクトのフィールドではなく)タグオブジェクトが参照するオブジェクトのフィールドの値を使用します。このオプションを指定しない場合、 <format> はデフォルトで %(objectname) SPC %(objecttype) TAB %(refname) です。また %% は % を差し込み、 %xx (xx は16進数)は16進コード xx の文字を差し込みます。 たとえば、%00 は \0 (NUL) を、 %09 は \t (TAB) を、 %0a は \n (LF) を、それぞれ差し込みます。

--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 の後に改行を出力しないでください。

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を比較したときの、 それぞれ前方と後方のコミット数をあらわします。

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

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

name-email-dateタプルを値として持つフィールド(author と committer と tagger)には、名前付きコンポーネントを抽出するために name と email と date の接尾辞を付けることができます。メールフィールド(authoremail と committeremail と taggeremail)の場合、 :trim を追加すると山かっこ(<, >)なしでメールを取得し、 :localpart を追加すると電子メールアドレスをトリミングして @ 記号の前の部分を取得できます。

オブジェクトの生データは 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 オプションのが取る値を参照してください)。

%(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