git-bisect

Основные команды bisect: start, bad, good

Предположим, что вы пытаетесь найти коммит, в котором перестала работать функция, работавшая в версии v2.6.13-rc2 вашего проекта. Начните сеанс bisect следующим образом:

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

После того как вы укажете хотя бы один плохой и один хороший коммит, git bisect выберет коммит из середины этого диапазона истории, переключится на него и выведет примерно следующее:

Bisecting: 675 revisions left to test after this (roughly 10 steps)

Теперь следует скомпилировать выбранную версию и проверить её. Если она работает правильно, введите

$ git bisect good

Если эта версия не работает, введите

$ git bisect bad

После этого git bisect ответит примерно так:

Bisecting: 337 revisions left to test after this (roughly 9 steps)

Продолжайте повторять эту процедуру: собирайте дерево, проверяйте его и в зависимости от того, является ли оно хорошим или плохим, выполняйте git bisect good или git bisect bad, чтобы запросить следующий коммит для проверки.

В конце концов не останется ревизий для проверки, и команда выведет описание первого плохого коммита. Ссылка refs/bisect/bad будет указывать на этот коммит.

Сброс bisect

После сеанса bisect, чтобы очистить состояние бисекции и вернуться к исходному HEAD, выполните следующую команду:

git bisect reset

По умолчанию эта команда вернёт ваше дерево к коммиту, на который был выполнен checkout до git bisect start. (Новая команда git bisect start также сделает это, поскольку очищает состояние предыдущей бисекции.)

С помощью необязательного аргумента можно вместо этого вернуться к другому коммиту:

git bisect reset <commit>

Например, git bisect reset bisect/bad переключится на первую плохую ревизию, тогда как git bisect reset HEAD оставит вас на текущем коммите бисекции и вообще не будет переключать коммиты.

Другие термины

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

В таких случаях термины «хороший» и «плохой» могут сбивать с толку, если ими обозначать «состояние до изменения» и «состояние после изменения». Поэтому вместо терминов «хороший» и «плохой» можно использовать соответственно термины «старый» и «новый». (Однако обратите внимание: в одном сеансе нельзя смешивать термины «хороший» и «плохой» с терминами «старый» и «новый».)

При таком более общем использовании укажите коммит «нового» состояния, обладающий некоторым свойством, и коммит «старого» состояния, у которого этого свойства нет, с помощью git bisect. Каждый раз, когда git bisect переключается на коммит, проверяйте, обладает ли он этим свойством. Если обладает, пометьте коммит как «новый»; в противном случае — как «старый». По завершении бисекции git bisect сообщит, в каком коммите появилось это свойство.

Чтобы использовать «старый» и «новый» вместо «хорошего» и «плохого», выполните git bisect start без указания коммитов в качестве аргументов, а затем выполните следующие команды, чтобы добавить коммиты:

git bisect old [<rev>]

чтобы указать, что коммит предшествовал искомому изменению, или

git bisect new [<rev>…​]

чтобы указать, что он последовал за ним.

Чтобы напомнить себе, какие термины используются в данный момент, выполните

git bisect terms

Получить только старый термин можно с помощью git bisect terms --term-old или git bisect terms --term-good; git bisect terms --term-new и git bisect terms --term-bad помогут узнать, как обозначать коммиты, более новые, чем искомое изменение.

Если вместо «плохого»/«хорошего» или «нового»/«старого» вы хотите использовать собственные термины, можно выбрать любые названия (кроме существующих подкоманд bisect, таких как reset, start, …​), начав бисекцию с помощью

git bisect start --term-old <term-old> --term-new <term-new>

Например, если вы ищете коммит, в котором ухудшилась производительность, можно использовать

$ git bisect start --term-old fast --term-new slow

А если вы ищете коммит, в котором была исправлена ошибка, можно использовать

$ git bisect start --term-new fixed --term-old broken

Затем используйте git bisect <term-old> и git bisect <term-new> вместо git bisect good и git bisect bad для пометки коммитов.

Визуализация/просмотр bisect

Чтобы просмотреть оставшиеся подозрительные коммиты в gitk, выполните во время бисекции следующую команду (вместо подкоманды visualize можно использовать view):

$ git bisect visualize

Git определяет наличие графической среды с помощью различных переменных окружения:

Если ни одна из этих переменных окружения не установлена, вместо неё используется git log. Можно также передать параметры командной строки, например -p и --stat.

$ git bisect visualize --stat

Журнал bisect и повторное воспроизведение bisect

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

$ git bisect log

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

$ git bisect reset
$ git bisect replay that-file

Пропуск проверки коммита

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

Например:

$ git bisect good/bad                        # previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize                        # oops, that is uninteresting.
$ git reset --hard HEAD~3                # try 3 revisions before what
                                        # was suggested

Затем соберите и проверьте выбранную ревизию, после чего обычным способом пометьте её как хорошую или плохую.

Пропуск bisect

Вместо того чтобы самостоятельно выбирать соседний коммит, можно поручить это Git, выполнив команду:

$ git bisect skip                 # Current version cannot be tested

Однако если пропустить коммит, соседний с искомым, Git не сможет точно определить, какой из этих коммитов был первым плохим.

Можно пропустить диапазон коммитов, а не только один коммит, используя обозначение диапазона. Например:

$ git bisect skip v2.5..v2.6

Это указывает процессу бисекции, что не следует проверять коммиты после v2.5 и вплоть до v2.6 включительно.

Обратите внимание: если нужно также пропустить первый коммит диапазона, выполните команду:

$ git bisect skip v2.5 v2.5..v2.6

Это указывает процессу бисекции пропустить коммиты между v2.5 и v2.6 включительно.

Следующий шаг bisect

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

$ git bisect next

Эта команда может пригодиться, чтобы продолжить процесс бисекции после прерывания, вызванного переключением на другую ревизию.

Сокращение бисекции с помощью дополнительных параметров bisect start

Если вы знаете, какая часть дерева связана с исследуемой проблемой, можно ещё больше сократить число проверок, указав параметры pathspec при выполнении команды bisect start:

$ git bisect start -- arch/i386 include/asm-i386

Если заранее известно несколько хороших коммитов, можно сузить диапазон бисекции, указав все хорошие коммиты сразу после плохого коммита при выполнении команды bisect start:

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

Запуск bisect

Если у вас есть скрипт, способный определить, является ли текущий исходный код хорошим или плохим, можно выполнить бисекцию с помощью команды:

git bisect run <cmd> [<arg>…​]

Обратите внимание: при запуске с помощью <arg> команда <cmd> должна завершаться с кодом 0, если текущий исходный код хороший/старый, и с кодом от 1 до 127 включительно (кроме 125), если текущий исходный код плохой/новый.

Любой другой код завершения прервёт процесс бисекции. Следует учитывать, что программа, завершающая работу через exit(-1), оставляет значение $? = 255 (см. справочную страницу exit(3)), поскольку значение обрезается с помощью & 0377.

Специальный код завершения 125 следует использовать, когда текущий исходный код невозможно проверить. Если скрипт завершится с этим кодом, текущая ревизия будет пропущена (см. раздел git bisect skip выше). Значение 125 выбрано как наибольшее разумное для этой цели, поскольку оболочки POSIX используют значения 126 и 127 для обозначения определённых ошибок (127 означает, что команда не найдена, 126 — команда найдена, но не может быть запущена; эти подробности не имеют значения, поскольку для bisect run это обычные ошибки в скрипте).

Во время сеанса bisect вам может потребоваться внести временные изменения (например, s/#define DEBUG 0/#define DEBUG 1/ в файл заголовка или применить «патч к ревизии, в которой отсутствует этот коммит, поскольку он нужен для обхода другой проблемы, не относящейся к текущей бисекции») к проверяемой ревизии.

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

Получение справки

Используйте git bisect, чтобы получить краткое описание использования, и git bisect help или git bisect -h, чтобы получить подробное описание использования.