Русский ▾ Topics ▾ Latest version ▾ git-range-diff last updated in 2.52.0

НАЗВАНИЕ

git-range-diff — Сравнить два диапазона коммитов (например, две версии ветки)

ОБЗОР

git range-diff [--color=[<когда>]] [--no-color] [<параметры-сравнения>]
	[--no-dual-color] [--creation-factor=<фактор>]
	[--left-only | --right-only] [--diff-merges=<формат>]
	[--remerge-diff]
	( <диапазон1> <диапазон2> | <ред1>…​<ред2> | <основа> <ред1> <ред2> )
	[[--] <путь>…​]

ОПИСАНИЕ

Эта команда показывает различия между двумя версиями серии патчей или, в более общем смысле, двумя диапазонами коммитов (игнорируя коммиты слияния).

При наличии аргументов <путь> эти диапазоны коммитов соответствующим образом ограничиваются.

Для этого он сначала находит пары коммитов из обоих диапазонов коммитов, которые соответствуют друг другу. Считается, что два коммита соответствуют, когда разница между их патчами (т.е. информация об авторе, сообщение коммита и сравнение коммитов) достаточно мала по сравнению с размером патчей. Подробности см. в разделе “Алгоритм” ниже.

Наконец, список соответствующих коммитов показывается в порядке второго диапазона коммитов, причём несоответствующие коммиты вставляются сразу после того, как все их предки были показаны.

Существует три способа указания диапазонов коммитов:

  • <диапазон1> <диапазон2>: Любой диапазон коммитов может иметь вид <основа>..<ред>, <ред>^! или <ред>^-<число>. Более подробную информацию см. в разделе УКАЗАНИЕ ДИАПАЗОНОВ в gitrevisions[7].

  • <ред1>...<ред2>. Это эквивалентно <ред2>..<ред1> <ред1>..<ред2>.

  • <основа> <ред1> <ред2>: Это эквивалентно <основа>..<ред1> <основа>..<ред2>.

ПАРАМЕТРЫ

--no-dual-color

Когда сравнения коммитов отличаются, git range-diff воссоздаёт цветовую схему исходных сравнений и добавляет внешние маркеры сравнения -/+ с фоном красным/зелёным, чтобы было легче увидеть, например, когда произошло изменение в том, какие именно строки были добавлены.

Кроме того, строки сравнения коммитов, которые присутствуют только в первом диапазоне коммитов, показываются "затемнёнными" (это можно переопределить с помощью настройки конфигурации color.diff.<слот>, где <слот> — один из contextDimmed, oldDimmed и newDimmed), а строки сравнения коммитов, которые присутствуют только во втором диапазоне коммитов, показываются жирным шрифтом (это можно переопределить с помощью настроек конфигурации color.diff.<слот>, где <слот> — один из contextBold, oldBold или newBold).

Это известно range-diff как "двойная раскраска". Используйте --no-dual-color, чтобы вернуться к раскраске всех строк в соответствии с внешними маркерами сравнения (и полностью игнорировать внутреннее сравнение, когда дело доходит до цвета).

--creation-factor=<percent>

Устанавливает фактор корректировки стоимости создания/удаления в <процент>. По умолчанию 60. Попробуйте большее значение, если git range-diff ошибочно считает большое изменение полной перезаписью (удаление одного коммита и добавление другого), и меньшее значение в обратном случае. Объяснение того, почему это необходимо, см. в разделе “Алгоритм” ниже.

--left-only

Подавлять коммиты, отсутствующие в первом указанном диапазоне (или "левом диапазоне" при использовании формата <ред1>...<ред2>).

--right-only

Подавлять коммиты, отсутствующие во втором указанном диапазоне (или "правом диапазоне" при использовании формата <ред1>...<ред2>).

--diff-merges=<формат>

Вместо игнорирования коммитов слияния генерировать для них сравнения, используя соответствующий параметр --diff-merges=<формат> команды git-log[1], и включать их в сравнение.

Примечание: В обычном случае режим remerge будет наиболее естественным для использования, поскольку он показывает только сравнение поверх того, что произвёл бы механизм слияния Git. Другими словами, если коммит слияния является результатом неконфликтующего git merge, режим remerge будет представлять его пустым сравнением.

--remerge-diff

Удобный параметр, эквивалентный --diff-merges=remerge.

--notes[=<ссылка>]
--no-notes

Этот флаг передаётся программе git log (см. git-log[1]), которая генерирует патчи.

<диапазон1> <диапазон2>

Сравнивает коммиты, указанные двумя диапазонами, где <диапазон1> считается более старой версией <диапазон2>.

<ред1>…​<ред2>

Эквивалентно передаче <ред2>..<ред1> и <ред1>..<ред2>.

<основа> <ред1> <ред2>

Эквивалентно передаче <основа>..<ред1> и <основа>..<ред2>. Обратите внимание, что <основа> не обязательно должна быть точной точкой ветвления веток. Пример: после перемещения ветки my-topic команда git range-diff my-topic@{u} my-topic@{1} my-topic покажет различия, внесённые перемещением.

git range-diff также принимает обычные параметры сравнения (см. git-diff[1]), в первую очередь параметры --color=[<когда>] и --no-color. Эти параметры используются при создании "сравнения между патчами", т.е. для сравнения автора, сообщения коммита и сравнения соответствующих старых/новых коммитов. В настоящее время нет возможности настраивать большинство параметров сравнения, передаваемых в git log при создании этих патчей.

СТАБИЛЬНОСТЬ ВЫВОДА

Вывод команды range-diff может изменяться. Он предназначен для человекочитаемого фарфорового вывода, а не для того, чтобы его можно было использовать в разных версиях Git для получения текстуально стабильного range-diff (в отличие от, например, параметра --stable команды git-patch-id[1]). Также нет эквивалента git-apply[1] для range-diff, вывод не предназначен для машинного чтения.

Это особенно верно при передаче параметров сравнения. В настоящее время некоторые параметры, такие как --stat, могут в качестве эмерджентного эффекта создавать вывод, который совершенно бесполезен в контексте range-diff. Будущие версии range-diff могут научиться интерпретировать такие параметры способом, специфичным для range-diff (например, для --stat создавать человекочитаемый вывод, который суммирует, как изменилась статистика различий).

КОНФИГУРАЦИЯ

Эта команда использует настройки diff.color.* и pager.range-diff (последняя включена по умолчанию). См. git-config[1].

ПРИМЕРЫ

Когда перемещение потребовало разрешения конфликтов слияния, сравните изменения, внесённые перемещением, непосредственно после этого с помощью:

$ 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-го коммита, а также его сравнение.

Когда вывод направляется на терминал, он по умолчанию раскрашен, как и обычный вывод git diff. Кроме того, первая строка (добавление коммита) зелёная, последняя строка (удаление коммита) красная, вторая строка (с идеальным совпадением) жёлтая, как заголовок коммита в выводе git show, а третья строка окрашивает старый коммит в красный, новый — в зелёный, а остальное — как заголовок коммита git show.

Однако наивное цветовое сравнение сравнений на самом деле немного трудно читается, так как оно окрашивает целые строки в красный или зелёный цвет. Например, строка, которая добавила «Что является неожиданным» в старом коммите, полностью красная, даже если целью старого коммита было что-то добавить.

Чтобы помочь с этим, range по умолчанию использует режим --dual-color. В этом режиме сравнение сравнений сохраняет исходные цвета сравнения и добавляет к строкам маркеры -/+, у которых фон красный или зелёный, чтобы было более очевидно, что они описывают, как изменилось само сравнение.

Алгоритм

Общая идея такова: мы генерируем матрицу стоимости между коммитами в обоих диапазонах коммитов, а затем решаем задачу назначения с наименьшей стоимостью.

Матрица стоимости заполняется следующим образом: для каждой пары коммитов генерируются оба сравнения и генерируется "сравнение сравнений" с 3 строками контекста, затем количество строк в этом сравнении используется в качестве стоимости.

Чтобы избежать ложных срабатываний (например, когда патч был удалён, а несвязанный патч был добавлен между двумя итерациями одной и той же серии патчей), матрица стоимости расширяется, чтобы учесть это, путём добавления записей с фиксированной стоимостью для массовых удалений/добавлений.

Пример: Пусть коммиты 1--2 будут первой итерацией серии патчей, а A--C — второй итерацией. Предположим, что A — это копия 2, а C — это копия 1, но с небольшим изменением (скажем, исправлена опечатка). Визуализируйте коммиты как двудольный граф:

    1            A

    2            B

		 C

Мы ищем «лучшее» объяснение новой серии в терминах старой. Мы можем представить «объяснение» как ребро в графе:

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

		 C

Это объяснение даётся «бесплатно», потому что изменений не было. Аналогично C можно объяснить с помощью 1, но это стоит некоторой стоимости c>0 из-за изменения:

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

В математических терминах мы ищем нечто вроде минимального по стоимости двудольного сопоставления; 1 сопоставляется с C с некоторой стоимостью и т.д. Базовый граф на самом деле является полным двудольным графом; стоимость, которую мы связываем с каждым ребром, — это размер сравнения между патчами двух коммитов. Чтобы также объяснить новые коммиты, мы вводим фиктивные узлы с обеих сторон:

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

    o            o

Стоимость ребра o--C — это размер сравнения C, изменённая на фактор корректировки, который должен быть меньше 100%. Стоимость ребра o--o равна нулю. Фактор корректировки необходим, потому что даже если 1 и C не имеют ничего общего, они всё равно могут иметь несколько пустых строк и тому подобное, возможно, делая назначение 1--C, o--o немного дешевле, чем 1--o, o--C, даже если 1 и C не имеют ничего общего. С фактором корректировки мы требуем гораздо большей общей части, чтобы считать патчи соответствующими.

Общее время, необходимое для вычисления этого алгоритма, складывается из времени, необходимого для вычисления n+m сравнений коммитов, а затем n*m сравнений патчей, плюс время, необходимое для вычисления назначения с наименьшей стоимостью между n и m сравнениями. Git использует реализацию алгоритма Йонкера-Фольгенанта для решения задачи назначения, который имеет кубическую временную сложность. Найденное в этом случае сопоставление будет выглядеть так:

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

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

СМ. ТАКЖЕ

git-log[1]

GIT

Является частью пакета git[1]