Git
英語 ▾ トピック ▾ 最新バージョン ▾ gitrevisions は 2.42.0 で最後に更新されました

名前

gitrevisions - Git のリビジョンと範囲の指定

概要

gitrevisions

説明

多くの Git コマンドは、引数としてリビジョンパラメータを取ります。コマンドによっては、特定のコミットを示すか、リビジョングラフを辿るコマンド(git-log[1]など)では、そのコミットから到達可能なすべてのコミットを示します。リビジョングラフを辿るコマンドでは、リビジョンの範囲を明示的に指定することもできます。

さらに、一部の Git コマンド(git-show[1]git-push[1] など)は、コミット以外のオブジェクト(例:BLOB(「ファイル」)、ツリー(「ファイルのディレクトリ」))を示すリビジョンパラメータも取ることができます。

リビジョンの指定

リビジョンパラメータ <rev> は通常、必ずしもそうではありませんが、コミットオブジェクトの名前を付けます。これは、「拡張 SHA-1」構文と呼ばれます。オブジェクト名を記述するさまざまな方法を以下に示します。このリストの最後に記載されているものは、コミットに含まれるツリーとBLOBの名前を付けます。

注記
このドキュメントは、git によって認識される「生の」構文を示しています。シェルやその他のUIでは、特殊文字を保護し、単語の分割を避けるために、追加の引用符が必要になる場合があります。
<sha1>、例:dae86e1950b1277e545cee180551750029cfe735dae86e

完全な SHA-1 オブジェクト名(40バイトの16進数文字列)、またはリポジトリ内で一意の先頭部分文字列。例:dae86e1950b1277e545cee180551750029cfe735 と dae86e は、リポジトリに dae86e で始まるオブジェクト名が他にない場合、同じコミットオブジェクトを指します。

<describeOutput>、例:v1.7.4.2-679-g3bee7fb

git describe の出力。つまり、最も近いタグ(オプションで、ダッシュとコミット数、ダッシュ、g、および省略されたオブジェクト名が続く)。

<refname>、例:masterheads/masterrefs/heads/master

シンボリックリファレンス名。例:master は通常、refs/heads/master が参照するコミットオブジェクトを意味します。heads/mastertags/master の両方が存在する場合、heads/master と明示的に指定して、どちらを意味するのか Git に伝えることができます。曖昧な場合は、<refname> は次の規則で最初のマッチを取ることによって曖昧さが解消されます。

  1. $GIT_DIR/<refname> が存在する場合は、それが意味するものです(これは通常、HEADFETCH_HEADORIG_HEADMERGE_HEADREBASE_HEADREVERT_HEADCHERRY_PICK_HEADBISECT_HEADAUTO_MERGE にのみ役立ちます)。

  2. そうでない場合、refs/<refname> が存在する場合。

  3. そうでない場合、refs/tags/<refname> が存在する場合。

  4. そうでない場合、refs/heads/<refname> が存在する場合。

  5. そうでない場合、refs/remotes/<refname> が存在する場合。

  6. そうでない場合、refs/remotes/<refname>/HEAD が存在する場合。

    HEAD

    作業ツリーの変更を元にしたコミットを指します。

    FETCH_HEAD

    最後の git fetch の呼び出しでリモートリポジトリからフェッチしたブランチを記録します。

    ORIG_HEAD

    HEAD を大幅に移動するコマンド(git amgit mergegit rebasegit reset)によって作成され、操作前の HEAD の位置を記録するため、それらを実行する前の状態にブランチの先端を簡単に変更できます。

    MERGE_HEAD

    git merge を実行したときに、ブランチにマージしているコミットを記録します。

    REBASE_HEAD

    リベース中は、競合または対話型リベースでの edit コマンドのために、操作が現在停止しているコミットを記録します。

    REVERT_HEAD

    git revert を実行したときに、元に戻しているコミットを記録します。

    CHERRY_PICK_HEAD

    git cherry-pick を実行したときに、チェリーピックしているコミットを記録します。

    BISECT_HEAD

    git bisect --no-checkout を実行したときに、テスト対象の現在のコミットを記録します。

    AUTO_MERGE

    マージ操作で競合が発生した場合、ort マージ戦略が作業ツリーに書き込んだ状態に対応するツリーオブジェクトを記録します。

上記の refs/* のいずれも、$GIT_DIR/refs ディレクトリまたは $GIT_DIR/packed-refs ファイルから取得される可能性があります。ref 名のエンコーディングは指定されていませんが、一部の出力処理では ref 名を UTF-8 と仮定するため、UTF-8 が推奨されます。

@

@ 単体は HEAD のショートカットです。

[<refname>]@{<date>}、例:master@{yesterday}HEAD@{5 minutes ago}

ref の後にサフィックス @ と、ブレースで囲まれた日付指定(例:{yesterday}{1 month 2 weeks 3 days 1 hour 1 second ago}、または {1979-02-26 18:30:00})を付けたものは、以前の時点での ref の値を指定します。このサフィックスは、ref 名の直後にのみ使用でき、ref には既存のログ($GIT_DIR/logs/<ref>)が必要です。これは、特定の時点での**ローカル** ref の状態(例:先週のローカルの master ブランチにあったもの)を検索することに注意してください。特定の期間に行われたコミットを確認したい場合は、--since--until を参照してください。

<refname>@{<n>}、例:master@{1}

ref の後にサフィックス @ と、ブレースで囲まれた序数指定(例:{1}{15})を付けたものは、その ref の n 番目の以前の値を指定します。たとえば、master@{1}master の直前の値であり、master@{5}master の 5 番目の以前の値です。このサフィックスは、ref 名の直後にのみ使用でき、ref には既存のログ($GIT_DIR/logs/<refname>)が必要です。

@{<n>}、例:@{1}

空の ref 部分で @ 構文を使用すると、現在のブランチの reflog エントリを取得できます。たとえば、blabla ブランチにいる場合、@{1}blabla@{1} と同じ意味になります。

@{-<n>}、例:@{-1}

@{-<n>} 構文は、現在のブランチの前にチェックアウトされた <n> 番目のブランチ/コミットを意味します。

[<branchname>]@{upstream}、例:master@{upstream}@{u}

ブランチ B は、リモート R(branch.<name>.remote で設定)にあるブランチ X(branch.<name>.merge で設定)の上に構築されるように設定できます。B@{u} は、リモート R から取得したブランチ X のリモート追跡ブランチを参照し、通常は refs/remotes/R/X にあります。

[<branchname>]@{push}、例:master@{push}@{push}

サフィックス@{push}は、git pushbranchnameをチェックアウトした状態で実行された場合(branchnameを指定しない場合は現在のHEAD)に「プッシュ先のブランチ」を示します。@{upstream}と同様に、リモートにあるそのブランチに対応するリモート追跡ブランチを報告します。

より明確にするために、例を示します。

$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c mybranch origin/master

$ git rev-parse --symbolic-full-name @{upstream}
refs/remotes/origin/master

$ git rev-parse --symbolic-full-name @{push}
refs/remotes/myfork/mybranch

この例では、ある場所からプルし、別の場所にプッシュする三角形のワークフローを設定していることに注意してください。三角形ではないワークフローでは、@{push}@{upstream}と同じであり、@{push}は必要ありません。

このサフィックスは大文字で記述した場合も受け入れられ、大文字小文字を問わず同じ意味になります。

<rev>^[<n>]、例:HEAD^, v1.5.1^0

リビジョンパラメータのサフィックス^はそのコミットオブジェクトの最初の親を意味します。^<n>はn番目の親を意味します(つまり、<rev>^<rev>^1と同等です)。特別なルールとして、<rev>^0はそのコミット自体を意味し、<rev>がコミットオブジェクトを参照するタグオブジェクトのオブジェクト名である場合に使用されます。

<rev>~[<n>]、例:HEAD~, master~3

リビジョンパラメータのサフィックス~はそのコミットオブジェクトの最初の親を意味します。リビジョンパラメータのサフィックス~<n>は、指定されたコミットオブジェクトのn世代前の祖先であるコミットオブジェクトを意味し、最初の親のみをたどります。つまり、<rev>~3<rev>^^^と同等であり、<rev>^1^1^1と同等です。この形式の使用方法については、以下を参照してください。

<rev>^{<type>}、例:v0.99.8^{commit}

サフィックス^の後に中括弧で囲まれたオブジェクトの種類名が続く場合、<rev>にあるオブジェクトを、<type>の種類のオブジェクトが見つかるか、オブジェクトがもう参照解除できなくなるまで(その場合はエラー)、再帰的に参照解除します。例えば、<rev>がコミット風の場合、<rev>^{commit}は対応するコミットオブジェクトを表します。同様に、<rev>がツリー風の場合、<rev>^{tree}は対応するツリーオブジェクトを表します。<rev>^0<rev>^{commit}の略記です。

<rev>^{object}は、<rev>がタグである必要がなく、<rev>を参照解除する必要がないため、存在するオブジェクトを<rev>が確実に指名するために使用できます。タグはすでにオブジェクトであるため、オブジェクトを取得するために一度も参照解除する必要はありません。

<rev>^{tag}は、<rev>が既存のタグオブジェクトを識別していることを確認するために使用できます。

<rev>^{}、例:v0.99.8^{}

サフィックス^の後に空の中括弧が続く場合、オブジェクトはタグである可能性があり、非タグオブジェクトが見つかるまでタグを再帰的に参照解除します。

<rev>^{/<text>}、例:HEAD^{/fix nasty bug}

リビジョンパラメータのサフィックス^の後に、スラッシュで始まるテキストを含む中括弧が続く場合、以下の:/fix nasty bug構文と同じですが、^の前にある<rev>から到達可能な、最も若い一致するコミットを返します。

:/<text>、例::/fix nasty bug

コロンの後にスラッシュ、そしてテキストが続く場合、コミットメッセージが指定された正規表現に一致するコミットを指名します。この名前は、HEADを含む任意の参照から到達可能な、最も若い一致するコミットを返します。正規表現はコミットメッセージの任意の部分と一致させることができます。文字列で始まるメッセージと一致させるには、例として:/^fooを使用できます。特別なシーケンス:/!は、一致するものの修飾子として予約されています。:/!-fooは否定的な一致を実行し、:/!!fooはリテラルの!文字の後にfooが続くものと一致します。:/!で始まるその他のシーケンスは、現時点では予約されています。指定されたテキストによっては、シェルの単語分割ルールで追加の引用が必要になる場合があります。

<rev>:<path>、例:HEAD:READMEmaster:./README

サフィックス:の後にパスが続く場合、コロンの前にある部分で指定されたツリー風オブジェクト内の指定されたパスにあるブロブまたはツリーを指定します。./または../で始まるパスは、現在の作業ディレクトリを基準とします。指定されたパスは、作業ツリーのルートディレクトリを基準とした相対パスに変換されます。これは、作業ツリーと同じツリー構造を持つコミットまたはツリーからブロブまたはツリーを参照する場合に最も役立ちます。

:[<n>:]<path>、例::0:README:README

コロンの後に、オプションでステージ番号(0~3)とコロンが続き、さらにパスが続く場合、指定されたパスにあるインデックス内のブロブオブジェクトを指定します。ステージ番号(とその後のコロン)がない場合、ステージ0のエントリを指定します。マージ中は、ステージ1は共通の祖先、ステージ2はターゲットブランチのバージョン(通常は現在のブランチ)、ステージ3はマージされているブランチからのバージョンです。

Jon Loeligerによる説明図です。コミットノードBとCの両方がコミットノードAの親です。親コミットは左から右に並んでいます。

G   H   I   J
 \ /     \ /
  D   E   F
   \  |  / \
    \ | /   |
     \|/    |
      B     C
       \   /
        \ /
         A
A =      = A^0
B = A^   = A^1     = A~1
C =      = A^2
D = A^^  = A^1^1   = A~2
E = B^2  = A^^2
F = B^3  = A^^3
G = A^^^ = A^1^1^1 = A~3
H = D^2  = B^^2    = A^^^2  = A~2^2
I = F^   = B^3^    = A^^3^
J = F^2  = B^3^2   = A^^3^2

範囲の指定

git logなどの履歴トラバーシングコマンドは、単一のコミットではなく、コミットの集合に対して動作します。

これらのコマンドでは、前セクションで説明した表記法を使用して単一のレビジョンを指定すると、指定されたコミットから「到達可能」なコミットの集合を意味します。

複数のリビジョンを指定すると、指定されたコミットのいずれかから到達可能なコミットの集合を意味します。

コミットの到達可能集合とは、コミット自体とその祖先チェーン内のコミットです。

接続されたコミットの集合(「リビジョン範囲」と呼ばれる)を指定するための表記法がいくつかあり、以下に示します。

コミットの除外

^<rev>(キャレット)表記

コミットから到達可能なコミットを除外するには、プレフィックス^表記を使用します。例:^r1 r2は、r2から到達可能だがr1から到達可能なコミット(つまり、r1とその祖先)を除外したコミットを意味します。

ドット範囲表記

..(2つのドット)範囲表記

^r1 r2集合演算は非常に頻繁に現れるため、そのための省略記法があります。2つのコミットr1r2(上記の「リビジョンの指定」で説明した構文に従って命名)がある場合、r1から到達可能なコミットを除外したr2から到達可能なコミットを要求できます。これは^r1 r2と表記され、r1..r2と書くことができます。

...(3つのドット)対称差表記

同様の表記r1...r2は、r1r2の対称差と呼ばれ、r1 r2 --not $(git merge-base --all r1 r2)として定義されます。これは、r1(左側)またはr2(右側)のいずれかから到達可能だが、両方から到達可能ではないコミットの集合です。

これらの2つの省略記法では、一方を省略してHEADをデフォルトにすることができます。例えば、origin..origin..HEADの省略記法であり、「originブランチからフォークして以来、私は何をしたのか?」という質問をします。同様に、..originHEAD..originの省略記法であり、「私がフォークして以来、originは何をしたのか?」という質問をします。..HEAD..HEADを意味し、HEADから到達可能であり、到達不可能でもある空の範囲であることに注意してください。

2つの異なる範囲を具体的に受け取るように設計されたコマンド(例:「git range-diff R1 R2」で2つの範囲を比較する)は存在しますが、例外です。特に明記されていない限り、コミットの集合に対して動作するすべての「git」コマンドは、単一のレビジョン範囲に対して動作します。言い換えれば、2つの「2ドット範囲表記」を並べて記述した場合(例:

$ git log A..B C..D

は、ほとんどのコマンドでは2つのリビジョン範囲を指定するわけではありません。代わりに、BまたはDから到達可能だが、AまたはCから到達不可能なコミット、つまり単一の接続されたコミット集合を指定します。このような線形履歴では

---A---B---o---o---C---D

AとBはCから到達可能であるため、これらの2つのドット範囲で指定されたリビジョン範囲は単一のコミットDになります。

その他の<rev>^親省略記法

特にマージコミットの場合、コミットとその親コミットによって形成される集合を指定するために、他に3つの省略記法があります。

r1^@表記は、r1のすべての親を意味します。

r1^!表記にはコミットr1が含まれますが、そのすべての親は除外されます。それ自体では、この表記は単一のコミットr1を示します。

<rev>^-[<n>]表記には<rev>が含まれますが、<n>番目の親は除外されます(つまり、<rev>^<n>..<rev>の省略記法)。指定されていない場合は<n> = 1です。これは、マージコミット<commit><commit>自体を含む)でマージされたブランチのすべてのコミットを取得するために<commit>^-を渡すことができるマージコミットで一般的に役立ちます。

<rev>^<n>は単一のコミットの親を指定することについてでしたが、これらの3つの表記法は親も考慮します。例えば、HEAD^2^@と言うことができますが、HEAD^@^2と言うことはできません。

リビジョン範囲の概要

<rev>

<rev>(つまり<rev>とその祖先)から到達可能なコミットを含めます。

^<rev>

<rev>(つまり<rev>とその祖先)から到達可能なコミットを除外します。

<rev1>..<rev2>

<rev2>から到達可能だが<rev1>から到達不可能なコミットを含めます。<rev1>または<rev2>のいずれかが省略された場合、デフォルトでHEADになります。

<rev1>...<rev2>

<rev1>または<rev2>のいずれかから到達可能だが、両方から到達不可能なコミットを含めます。<rev1>または<rev2>のいずれかが省略された場合、デフォルトでHEADになります。

<rev>^@、例:HEAD^@

サフィックス^の後にアットマークが続く場合、<rev>のすべての親をリストすることと同じです(つまり、親から到達可能なものはすべて含めますが、コミット自体は含めません)。

<rev>^!、例:HEAD^!

サフィックス^の後に感嘆符が続く場合、コミット<rev>とそのすべての親に^プレフィックスを付けて除外すること(およびその祖先)と同じです。

<rev>^-<n>、例:HEAD^-, HEAD^-2

<rev>^<n>..<rev>と同等です。<n> が指定されていない場合は、<n> = 1 となります。

上記のLoeligerの図解を使用したいくつかの例を以下に示します。表記の展開と選択の各ステップを注意深く説明しています。

   Args   Expanded arguments    Selected commits
   D                            G H D
   D F                          G H I J D F
   ^G D                         H D
   ^D B                         E I J F B
   ^D B C                       E I J F B C
   C                            I J F C
   B..C   = ^B C                C
   B...C  = B ^F C              G H D E B C
   B^-    = B^..B
	  = ^B^1 B              E I J F B
   C^@    = C^1
	  = F                   I J F
   B^@    = B^1 B^2 B^3
	  = D E F               D G H E F I J
   C^!    = C ^C^@
	  = C ^C^1
	  = C ^F                C
   B^!    = B ^B^@
	  = B ^B^1 ^B^2 ^B^3
	  = B ^D ^E ^F          B
   F^! D  = F ^I ^J D           G H D F

Git

git[1] スイートの一部

scroll-to-top