日本語 ▾ トピック ▾ 最新バージョン ▾ 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>, 例: dae86e1950b1277e545cee180551750029cfe735, dae86e

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

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

git describe の出力。すなわち、最も近いタグに、オプションでダッシュとコミット数、さらにダッシュ、g、短縮されたオブジェクト名が続く。

<refname>, 例: master, heads/master, refs/heads/master

シンボリック参照名。例えば、master は通常、refs/heads/master によって参照されるコミットオブジェクトを意味します。たまたま heads/mastertags/master の両方がある場合、どちらを意味するかを Git に伝えるために明示的に heads/master と指定できます。曖昧な場合、<refname> は以下の規則で最初に一致するものによって区別されます。

  1. $GIT_DIR/<refname> が存在する場合、それが意味されます (これは通常、HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD, REBASE_HEAD, REVERT_HEAD, CHERRY_PICK_HEAD, BISECT_HEAD および AUTO_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

    git amgit mergegit rebasegit reset のように HEAD を大幅に移動させるコマンドによって作成され、それらの操作の前に 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 ファイルのいずれかから取得されることに注意してください。参照名のエンコーディングは指定されていませんが、一部の出力処理が UTF-8 の参照名を想定する可能性があるため、UTF-8 が推奨されます。

@

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

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

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

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

参照に @ 接尾辞とブレースで囲まれた序数指定 (例: {1}, {15}) を続けると、その参照の n 番目に前の値が指定されます。例えば、master@{1}master の直前の値であり、master@{5}master の 5 番目に前の値です。この接尾辞は参照名の直後にのみ使用でき、その参照には既存のログ ($GIT_DIR/logs/<refname>) が必要です。

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

@ 構成を空の参照部分で使用して、現在のブランチの参照ログエントリにアクセスできます。たとえば、ブランチ 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} は、branchname がチェックアウトされている場合 (または、ブランチ名が指定されていない場合は現在の HEAD) に git push が実行された場合に「プッシュする場所」となるブランチを報告します。@{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} と同じであり、必要ありません。

このサフィックスは大文字で表記されても受け入れられ、大文字小文字にかかわらず同じ意味を持ちます。

<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> が存在することを確実に指定できます。タグはすでにオブジェクトであるため、オブジェクトに到達するために一度も逆参照する必要はありません。

<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:README, master:./README

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

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

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

以下は、ジョン・ロエリガーによる図解です。コミットノード 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 r2r2 から到達可能なコミットを意味しますが、r1 (つまり r1 とその祖先) から到達可能なコミットは除外します。

ドット範囲表記

.. (二点) 範囲表記

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

... (三点) 対称差分表記

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

これらの2つの省略記法では、いずれかの端を省略して、デフォルトでHEADとすることができます。例えば、origin..origin..HEAD の省略記法で、「originブランチからフォークして以来、私は何をしたか?」と尋ねます。同様に、..originHEAD..origin の省略記法で、「私が彼らからフォークして以来、originは何をしたか?」と尋ねます。なお、..HEAD..HEAD を意味し、これはHEADから到達可能でも到達不可能でもある空の範囲です。

2つの異なる範囲を取るように特別に設計されたコマンド (例: 2つの範囲を比較する "git range-diff R1 R2") は存在しますが、それらは例外です。特に明記されていない限り、コミットのセットに対して動作するすべての "git" コマンドは単一のリビジョン範囲で動作します。言い換えれば、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> が指定されない場合は 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