git-range-diff(1)

SYNOPSIS

git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
        [--no-dual-color] [--creation-factor=<factor>]
        [--left-only | --right-only]
        ( <range1> <range2> | <rev1>…<rev2> | <base> <rev1> <rev2> )
        [[--] <path>…]

DESCRIPTION

このコマンドは、パッチシリーズの2つのバージョン、またはより一般的には2つのコミット範囲(マージコミットは無視)の違いを表示します。

<path> 引数が存在する場合、これらのコミット範囲はそれに応じて制限されます。

そのために、最初に、互いに対応する両方のコミット範囲からコミットのペアを見つけます。 2つのコミットは、パッチ間の差分(つまり、作者情報、コミットメッセージ、およびコミット差分)がパッチのサイズと比較して適度に小さい場合に一致していると言われます。詳細については、下記「Algorithm」を参照してください。

最後に、一致するコミットのリストが2番目のコミット範囲の順序で表示され、すべての祖先が表示された直後に一致しないコミットが挿入されます。

コミット範囲を指定するには、以下の3つの方法があります:

<range1> <range2> : どちらのコミット範囲も <base>..<rev> または <rev>^! または <rev>^-<n> 形式にすることができます。詳細については、 gitrevisions(7)の「SPECIFYING RANGES」を参照してください。
<rev1>...<rev2> : これは、 <rev2>..<rev1> <rev1>..<rev2> と同じです。
<base> <rev1> <rev2> : これは <base>..<rev1> <base>..<rev2> と同じです。

OPTIONS

--no-dual-color: コミットdiffが異なる場合、 git range-diff は元の差分の色付けを再現し、例えば、追加された正確な行に変更があったとき、背景が赤/緑である外側の -/+ 差分マーカーを追加して見やすくします。

さらに、最初のコミット範囲にのみ存在するコミット差分行は「薄暗く」(dimmed)表示され(これは、 color.diff.<slot> 構成設定を使用してオーバーライドできます。ここで、 <slot> は contextDimmed と oldDimmed と newDimmed のうちの1つです)、2番目のコミット範囲にのみ存在するコミット差分行は太字(bold)で示されています(これは、構成設定 color.diff.<slot> を使用してオーバーライドできます。<slot> は contextBold または oldBold または newBold のいずれかです)。

これは range-diff のための「dual coloring」として知られています。 --no-dual-color を使用すると、外側のdiffマーカーに従ってすべての行の色を反転します(色に関しては内側のdiffを完全に無視します)。
--creation-factor=<percent>: 作成/削除コストのファッジ係数を <percent> に設定します。デフォルトは60です。 git range-diff が誤って大きな変更を全体の書き換え(1つのコミットの削除と別のコミットの追加)と見なす場合は大きな値を試し、逆の場合は小さな値を試してください。これが必要な理由の説明については、下記「Algorithm」セクションを参照してください。
--left-only: 最初に指定された範囲(または <rev1>...<rev2> 形式を使用する場合は「左範囲」(left range)）から欠落しているコミットを隠し(suppress)ます。
--right-only: 2番目に指定された範囲(または <rev1>...<rev2> 形式を使用する場合は「右範囲」(right range)）から欠落しているコミットを隠し(supprss)ます。
--[no-]notes[=<ref>]: このフラグは、パッチを生成する git log プログラム(git-log(1) 参照)に渡されます。
<range1> <range2>: 2つの範囲で指定されたコミットを比較します。ここで、 <range1> は <range2> の古いバージョンと見なされます。
<rev1>…<rev2>: <rev2>..<rev1> と <rev1>..<rev2> を渡すのと同じです。
<base> <rev1> <rev2>: <base>..<rev1> と <base>..<rev2> を渡すのと同じです。 <base> は分岐の正確な分岐点である必要はないことに注意してください。例: ブランチ my-topic をリベースした後、 git range-diff my-topic@{u} my-topic@{1} my-topic は、リベースによって導入された違いを示します。

git range-diff は、通常のdiffオプション(git-diff(1) 参照)、特に --color=[<when>] および --no-color オプションも受け入れます。これらのオプションは、「パッチ間の差分」を生成するときに使用されます。つまり、作者、コミットメッセージ、および対応する古い/新しいコミットの差分を比較します。現在、これらのパッチを生成するときに git log に渡されるdiffオプションのほとんどは微調整する手段がありません。

OUTPUT STABILITY

range-diff コマンドの出力は変更される可能性があります。これは人間が読める磁器コマンドの出力であり、Gitのバージョン間でテキスト的に安定した range-diff を取得するために使用できるものではありません(git-patch-id(1) の --stable オプションのようなものとは対照的です)。 range-diff には git-apply(1) に相当するものもありません。出力は、プログラムで読み取ること(machine-readable)は意図されていません。

これは特に diff オプションを渡すときに当てはまります。現在、 --stat のようないくつかのオプションは、 range-diff のコンテキストでは全く役に立たない出力を生成することがあります。将来のバージョンの range-diff では、このようなオプションを range-diff 固有の方法で解釈するようになるかもしれません (例えば、 --stat は diffstat がどのように変化したかをまとめた、人間が読めるような出力を生成します)。

CONFIGURATION

このコマンドは、 diff.color.* および pager.range-diff 設定を使用します(後者はデフォルトでオンになっています)。 git-config(1) を参照してください。

EXAMPLES

リベースでマージの競合を解決する必要がある場合は、以下のコマンドを使用して、リベースによって導入された変更をその直後に比較します:

$ git range-diff @{u} @{1} @

git range-diff の典型的な出力は以下のようになります:

-:  ------- > 1:  0ddba11 Prepare for the inevitable!
1:  c0debee = 2:  cab005e Add a helpful message at the start
2:  f00dbal ! 3:  decafe1 Describe a bug
    @@ -1,3 +1,3 @@
     Author: A U Thor <author@example.com>

    -TODO: Describe a bug
    +Describe a bug
    @@ -324,5 +324,6
      This is expected.

    -+What is unexpected is that it will also crash.
    ++Unexpectedly, it also crashes. This is a bug, and the jury is
    ++still out there how to fix it best. See ticket #314 for details.

      Contact
3:  bedead < -:  ------- TO-UNDO

この例では、3つの古いコミットと3つの新しいコミットがあり、開発者は3番目を削除し、最初の2つの前に新しいコミットを追加し、2番目のコミットのコミットメッセージとその差分を変更しました。

出力が端末に送られるとき、通常の git diff の出力と同じように、デフォルトで色分けされています。さらに、最初の行(コミットの追加)は緑、最後の行(コミットの削除)は赤、2番目の行(完全一致)は git show の出力のコミットヘッダーのように黄色で、 3行目は、古いコミットを赤、新しいコミットを緑、残りを git show のコミットヘッダーのように色付けします。

ただし、単純な色分けされた「diffのdiff」は、行全体を赤または緑に色付けするため、実際には少し読みにくいです。たとえば、古いコミットで「予期しないもの」を追加した行は、古いコミットの目的が何かを追加することであったとしても、完全に赤くなります。

これを助けるために、 range はデフォルトで --dual-color モードを使用します。このモードでは、「diffのdiff」は元のdiffの色を保持し、行の前に「背景」が赤または緑の -/+ マーカーを付けて、diff自体がどのように変化したかをより明確にします。

Algorithm

一般的な考え方は次のとおりです: 両方のコミット範囲のコミット間にコストマトリックスを生成してから、最小コストの割り当てを解決します。

コストマトリックスはこのように入力されます: コミットのペアごとに、両方のdiffが生成され、3つのコンテキスト行で「diffのdiff」が生成され、そのdiffの行数がコストとして使用されます。

誤検知(たとえば、パッチが削除され、同じパッチシリーズの2つの反復の間に無関係のパッチが追加された場合)を回避するために、一括削除/追加の固定費エントリを追加することにより、コストマトリックスが拡張されて誤検知の回避が可能になります。

例: コミット 1--2 をパッチシリーズの最初の反復とし、 A--C を2番目の反復とします。 A は 2 のチェリーピックであり、 C は 1 のチェリーピックですが、わずかな変更(たとえば、タイプミス修正)があると仮定します。コミットを二部グラフ(bipartite graph)として視覚化する:

    1            A

    2            B

                 C

私たちは、新しい系列を古い系列の観点から「最適」に「説明」(explanation)することを求めています。「説明」はグラフの辺として表現することができます:

    1            A
               /
    2 --------'  B

                 C

この「説明」(explanation)は、変更がなかったため、「無料」で提供されます。同様に、 C は 1 を使用して「説明」できますが、変更のために「c>0」のコストがかかります:

    1 ----.      A
          |    /
    2 ----+---'  B
          |
          `----- C
          c>0

数学的に言えば、私たちが探しているのは、ある種の最小コストの二部マッチング(bipartite matching)です。 1 は、いくらかのコストで C と一致します。基礎となるグラフは、実際には完全2部グラフです。すべてのエッジに関連するコストは、2つのコミットのパッチ間の差分のサイズです。新しいコミットについても説明するために、両側にダミーノードを導入します:

    1 ----.      A
          |    /
    2 ----+---'  B
          |
    o     `----- C
          c>0
    o            o

    o            o

エッジ o--C のコストは、 C の差分のサイズであり、100％未満である必要があるファッジ係数(fudge factor)によって変更されます。エッジ o--o のコストは無料です。ファッジ係数が必要なのは、たとえ 1 と C に共通点がなくても、空行などがいくつか共有され、 1--C 、 o--o の代入が 1--o 、 o--C よりもわずかにコストが安くなる可能性があるためです。ファッジ係数を使用すると、パッチを対応するものと見なすためには、はるかに大きな共通部分が必要になります。

このアルゴリズムの計算に必要な全体の時間は、パッチの、n+mコミットdiff と n*m diff の計算に必要な時間に加えて、nとmのdiff間の最小コストの割り当ての計算に必要な時間です。 Gitは、Jonker-Volgenantアルゴリズムの実装を使用して、実行時の複雑さが3次である割り当ての問題を解決します。この場合に見つかった一致は以下のようになります:

    1 ----.      A
          |    /
    2 ----+---'  B
       .--+-----'
    o -'  `----- C
          c>0
    o ---------- o

    o ---------- o

GIT

Part of the git(1) suite

git-range-diff(1) Manual Page

NAME