Как исключить коммиты переформатирования из git blame: -w и файлы ignore-revs

Что это такое

git blame указывает для каждой строки коммит, который изменил её последним. Запуск форматтера, изменение отступов или нормализация окончаний строк «меняют» каждую строку, и с этого момента blame указывает на коммит уборки вместо изменения, внёсшего логику. Документация предлагает три средства против этого:

• -w игнорирует пробельные различия при сравнении версий родительского и дочернего коммитов, чтобы определить происхождение строк.
• --ignore-rev <rev> рассматривает коммит так, будто его не было; затронутые им строки относят к более раннему коммиту, который их менял. --ignore-revs-file <file> читает такие коммиты из файла, а настройка blame.ignoreRevsFile применяет файл автоматически. С blame.markIgnoredLines переатрибутированные строки помечаются ?; с blame.markUnblamableLines строки, которые нельзя отнести ни к какому другому коммиту, помечаются *.
• -M обнаруживает строки, перемещённые или скопированные внутри файла, а -C — дополнительно строки, перемещённые или скопированные из других файлов, изменённых в том же коммите, поэтому рефакторинг с переносом кода сохраняет исходного автора.

Документация GitHub указывает, что файл .git-blame-ignore-revs в корне репозитория автоматически применяется в его представлении blame.

Почему это важно

Через blame ревьюеры, дежурные инженеры и агенты находят причины появления строки: сообщение коммита, запрос на включение изменений, задачу. История, в которой каждая строка указывает на «apply black» или «prettier 3.0», теряет этот след именно тогда, когда он нужен.

Как применять

• Выделяйте крупные механические изменения в отдельные коммиты без каких-либо иных изменений, чтобы их можно было игнорировать целиком.
• Добавьте полный хеш каждого такого коммита в .git-blame-ignore-revs со строкой комментария, объясняющей его, и включите файл в коммит.
• Выполните git config blame.ignoreRevsFile .git-blame-ignore-revs в каждом клоне (скриптом настройки или документированной однострочной командой); без этого командная строка файл не применяет.
• При исследовании по умолчанию используйте git blame -w -M -C, а для ограничения диапазона — -L <start>,<end>.
• Редакторы и хостинги кода читают тот же файл; прежде чем на это полагаться, выясните, какие именно это делают.

Подводные камни

Игнорирование коммита, содержащего также реальные изменения, скрывает их от blame. Хеши должны быть полными (документация конфигурации требует одно несокращённое имя объекта на строку); после переписывания истории перечисленные идентификаторы ни с чем не совпадают, поэтому файл нужно создать заново. На git log -S и git bisect это не влияет: при необходимости они по-прежнему находят коммит.