git-blame

Название

git-blame — показать, какая редакция и какой автор последними изменили каждую строку файла

Краткое описание

git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
          [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
          [--ignore-rev <rev>] [--ignore-revs-file <file>]
          [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
          [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file>

Описание

Добавляет к каждой строке указанного файла сведения о редакции, в которой эта строка была изменена в последний раз. При необходимости аннотирование можно начать с указанной редакции.

При указании одного или нескольких раз параметр -L ограничивает аннотирование заданными строками.

Происхождение строк автоматически отслеживается при переименовании всего файла (в настоящее время отключить отслеживание переименований нельзя). Чтобы отслеживать строки, перемещённые из одного файла в другой, скопированные и вставленные из другого файла и т. д., см. параметры -C и -M.

Отчёт не содержит сведений о строках, которые были удалены или заменены; для этого необходимо воспользоваться таким инструментом, как git diff, или интерфейсом «pickaxe», кратко описанным в следующем абзаце.

Помимо аннотирования файлов, Git также позволяет искать в истории разработки момент, когда фрагмент кода появился в изменении. Это позволяет отследить, когда фрагмент кода был добавлен в файл, перемещён или скопирован между файлами, а затем удалён или заменён. Для этого выполняется поиск текстовой строки в diff. Небольшой пример использования интерфейса pickaxe для поиска blame_usage:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

Параметры

-b

Показывать пустой SHA-1 для граничных коммитов. Этим также можно управлять с помощью параметра конфигурации blame.blankBoundary.

--root

Не считать корневые коммиты границами. Этим также можно управлять с помощью параметра конфигурации blame.showRoot.

--show-stats

Добавлять дополнительную статистику в конец вывода blame.

-L <start>,<end>

-L :<funcname>

Аннотировать только диапазон строк, заданный параметрами <start>,<end>, или регулярным выражением имени функции <funcname>. Можно указывать несколько раз. Пересекающиеся диапазоны допускаются.

Параметры <start> и <end> необязательны. -L <start> или -L <start>, задаёт диапазон от <start> до конца файла. -L ,<end> задаёт диапазон от начала файла до <end>.

Параметры <start> и <end> могут иметь один из следующих форматов:

<number>

Если <start> или <end> — число, оно задаёт абсолютный номер строки (нумерация начинается с 1).
/<regex>/

В этом формате используется первая строка, соответствующая заданному POSIX <regex>. Если <start> — регулярное выражение, поиск выполняется от конца предыдущего диапазона -L, если он есть, или от начала файла. Если <start> — ^/<regex>/, поиск выполняется от начала файла. Если <end> — регулярное выражение, поиск начинается со строки, заданной параметром <start>.
+<offset> или -<offset>

Допустимо только для <end>; задаёт число строк до или после строки, указанной параметром <start>.

Если вместо <start> и <end> указан параметр :<funcname>, он представляет собой регулярное выражение, задающее диапазон от первой строки имени функции, соответствующей <funcname>, до следующей строки имени функции. Параметр :<funcname> выполняет поиск от конца предыдущего диапазона -L, если он есть, или от начала файла. Параметр ^:<funcname> выполняет поиск от начала файла. Имена функций определяются так же, как git diff определяет заголовки фрагментов исправления (см. Defining a custom hunk-header в gitattributes[5]).

-l

Показывать полный идентификатор редакции (по умолчанию: выкл.).

-t

Показывать необработанную временную метку (по умолчанию: выкл.).

-S <revs-file>

Использовать редакции из <revs-file> вместо вызова git-rev-list[1].

--reverse <start>..<end>

Проходить историю вперёд, а не назад. Вместо редакции, в которой появилась строка, показывается последняя редакция, в которой строка существовала. Для этого требуется диапазон редакций, например <start>..<end>, в котором путь, для которого выполняется blame, существует в <start>. Для удобства git blame --reverse <start> считается равным git blame --reverse <start>..HEAD.

--first-parent

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

-p

--porcelain

Выводить данные в формате, предназначенном для обработки программами.

--line-porcelain

Выводить данные в формате porcelain, но для каждой строки печатать сведения о коммите, а не только при первом упоминании коммита. Подразумевает параметр --porcelain.

--incremental

Выводить результат по мере его формирования в формате, предназначенном для обработки программами.

--encoding=<encoding>

Задать кодировку для вывода имён авторов и сводок коммитов. Значение none отключает преобразование данных в выводе blame. Дополнительные сведения см. в обсуждении кодировок на странице руководства git-log[1].

--contents <file>

Аннотировать содержимое из <file>, начиная с <rev>, если оно указано, и HEAD в противном случае. Можно указать -, чтобы команда читала содержимое файла из стандартного ввода.

--date <format>

Задать формат вывода дат. Если --date не указан, используется значение переменной конфигурации blame.date. Если переменная конфигурации blame.date также не задана, используется формат iso. Поддерживаемые значения см. в описании параметра --date на странице git-log[1].

--progress

--no-progress

Включить отображение сведений о ходе выполнения в потоке стандартного вывода ошибок, даже если он не подключён к терминалу. По умолчанию сведения о ходе выполнения выводятся только при подключении к терминалу. Нельзя использовать --progress вместе с --porcelain или --incremental.

-M[<num>]

Обнаруживать строки, перемещённые или скопированные внутри файла. Когда коммит перемещает или копирует блок строк (например, исходный файл содержит A, а затем B, а коммит изменяет его на B, а затем A), традиционный алгоритм blame замечает только половину перемещения и обычно приписывает строки, перемещённые вверх (то есть B), родительскому коммиту, а строки, перемещённые вниз (то есть A), — дочернему коммиту. С этим параметром обе группы строк приписываются родительскому коммиту благодаря дополнительным проходам проверки.

Параметр <num> необязателен, но задаёт минимальное количество буквенно-цифровых символов, перемещение или копирование которых Git должен обнаружить внутри файла, чтобы связать эти строки с родительским коммитом. Значение по умолчанию — 20.

-C[<num>]

В дополнение к -M, обнаруживать строки, перемещённые или скопированные из других файлов, изменённых в том же коммите. Это полезно при реорганизации программы и перемещении кода между файлами. Если этот параметр указан дважды, команда дополнительно ищет копии из других файлов в коммите, который создаёт файл. Если параметр указан трижды, команда дополнительно ищет копии из других файлов в любом коммите.

Параметр <num> необязателен, но задаёт минимальное количество буквенно-цифровых символов, перемещение или копирование которых между файлами Git должен обнаружить, чтобы связать эти строки с родительским коммитом. Значение по умолчанию — 40. Если задано несколько параметров -C, вступает в силу аргумент <num> последнего параметра -C.

--ignore-rev <rev>

Не учитывать изменения, внесённые редакцией, при определении авторства строк, как если бы это изменение никогда не происходило. Строки, изменённые или добавленные игнорируемым коммитом, будут приписаны предыдущему коммиту, изменившему эту строку или соседние строки. Этот параметр можно указывать несколько раз, чтобы игнорировать несколько редакций. Если задан параметр конфигурации blame.markIgnoredLines, строки, изменённые игнорируемым коммитом и приписанные другому коммиту, будут помечены символом ? в выводе blame. Если задан параметр конфигурации blame.markUnblamableLines, строки, затронутые игнорируемым коммитом, авторство которых не удалось приписать другой редакции, будут помечены символом *. В режимах porcelain для них выводятся соответственно ignored и unblamable на отдельных строках.

--ignore-revs-file <file>

Игнорировать редакции, перечисленные в <file>, формат которого должен совпадать с форматом fsck.skipList. Этот параметр можно указывать несколько раз; перечисленные файлы обрабатываются после всех файлов, заданных параметром конфигурации blame.ignoreRevsFile. Пустое имя файла "" очищает список редакций из ранее обработанных файлов.

--color-lines

В стандартном формате окрашивать аннотации строк по-разному, если они относятся к тому же коммиту, что и предыдущая строка. Это упрощает различение блоков кода, добавленных разными коммитами. По умолчанию используется голубой цвет; его можно изменить с помощью параметра конфигурации color.blame.repeatedLines.

--color-by-age

В стандартном формате окрашивать аннотации строк в зависимости от возраста строки. Параметр конфигурации color.blame.highlightRecent задаёт цвет для каждого возрастного диапазона.

-h

Показать справочное сообщение.

-c

Использовать тот же режим вывода, что и git-annotate[1] (по умолчанию: выкл.).

--score-debug

Добавлять отладочную информацию о перемещении строк между файлами (см. -C) и строк внутри файла (см. -M). Первое указанное число — оценка. Это количество буквенно-цифровых символов, для которых было обнаружено перемещение между файлами или внутри файла. Для того чтобы git blame считал эти строки кода перемещёнными, значение должно превышать определённый порог.

-f

--show-name

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

-n

--show-number

Показывать номер строки в исходном коммите (по умолчанию: выкл.).

-s

Не выводить имя автора и временную метку.

-e

--show-email

Показывать адрес электронной почты автора вместо его имени (по умолчанию: выкл.). Этим также можно управлять с помощью параметра конфигурации blame.showEmail.

-w

Игнорировать пробельные символы при сравнении версий родительского и дочернего коммитов, чтобы определить происхождение строк.

--diff-algorithm=(patience|minimal|histogram|myers)

Выбрать алгоритм diff. Доступны следующие варианты:

default
myers: Базовый жадный алгоритм diff. В настоящее время используется по умолчанию.
minimal: Потратить дополнительное время, чтобы гарантировать создание минимально возможного diff.
patience: Использовать алгоритм «patience diff» при создании исправлений.
histogram: Этот алгоритм расширяет алгоритм patience, чтобы «поддерживать редко встречающиеся общие элементы».

Например, если для переменной diff.algorithm задано значение, отличное от значения по умолчанию, и вы хотите использовать значение по умолчанию, необходимо указать параметр --diff-algorithm=default.

--abbrev=<n>

Вместо стандартного 7+1 шестнадцатеричных цифр сокращённого имени объекта использовать <m>+1 цифр, где <m> не меньше <n>, но при этом обеспечивает уникальность имён объектов-коммитов. Обратите внимание: один столбец используется для символа каретки, обозначающего граничный коммит.

Формат по умолчанию

Если не указан параметр --porcelain или --incremental, команда git blame выводит аннотацию для каждой строки, содержащую:

сокращённое имя объекта-коммита, из которого происходит строка;
идентификатор автора (по умолчанию имя и дата автора, если не указан параметр -s или -e); и
номер строки

перед содержимым строки.

Формат porcelain

В этом формате каждая строка выводится после заголовка; минимальный заголовок содержит первую строку со следующими данными:

40-байтовый SHA-1 коммита, которому приписана строка;
номер строки в исходном файле;
номер строки в итоговом файле;
для строки, начинающей группу строк из коммита, отличного от предыдущего, — количество строк в этой группе. В последующих строках это поле отсутствует.

После этой строки заголовка для каждого коммита как минимум один раз выводятся следующие сведения:

имя автора (author), адрес электронной почты (author-mail), время (author-time) и часовой пояс (author-tz); аналогично — сведения о коммитере.
имя файла в коммите, которому приписана строка;
первая строка сообщения журнала коммита (summary).

После приведённого выше заголовка выводится содержимое самой строки с префиксом TAB. Это позволяет добавлять новые элементы заголовка в будущем.

В формате porcelain обычно опускаются сведения о коммитах, которые уже выводились. Например, две строки, приписанные одному коммиту, будут показаны обе, но сведения об этом коммите будут выведены только один раз. Информация, относящаяся к отдельным строкам, не объединяется, например редакции, помечаемые как ignored или unblamable. Это повышает эффективность, но читателю может потребоваться хранить больше состояния. Параметр --line-porcelain позволяет выводить полные сведения о коммите для каждой строки, что упрощает (но снижает эффективность) обработку, например:

# count the number of lines attributed to each author
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

Указание диапазонов

В отличие от параметров git blame и git annotate в старых версиях git, диапазон аннотации можно ограничить как диапазонами строк, так и диапазонами редакций. Параметр -L, ограничивающий аннотацию диапазоном строк, можно указывать несколько раз.

Если нужно найти происхождение строк 40–60 файла foo, можно использовать параметр -L следующим образом (эти варианты равнозначны — оба задают 21 строку, начиная со строки 40):

git blame -L 40,60 foo
git blame -L 40,+21 foo

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

git blame -L '/^sub hello {/,/^}$/' foo

это ограничивает аннотацию телом подпрограммы hello.

Если вас не интересуют изменения, сделанные до версии v2.6.18 или более трёх недель назад, можно использовать спецификаторы диапазона редакций, аналогичные git rev-list:

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

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

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

git log --diff-filter=A --pretty=short -- foo

затем аннотировать изменения между этим коммитом и его родительскими коммитами, используя обозначение commit^!:

git blame -C -C -f $commit^! -- foo

Пошаговый вывод

При вызове с параметром --incremental команда выводит результат по мере его формирования. Обычно сначала выводятся строки, затронутые более поздними коммитами (то есть строки аннотируются не по порядку); этот режим предназначен для интерактивных средств просмотра.

Формат вывода похож на формат porcelain, но не содержит самих строк файла, который аннотируется.

Каждая запись blame всегда начинается строкой следующего вида:
```
<40-byte-hex-sha1> <sourceline> <resultline> <num-lines>
```
Нумерация строк начинается с 1.
При первом появлении коммита в потоке вместе с ним печатаются различные дополнительные сведения. В начале каждой строки стоит односоставная метка, обозначающая тип сведений о коммите (автор, адрес электронной почты, коммитер, даты, сводка и т. д.).

В отличие от формата porcelain, имя файла указывается всегда и завершает запись:

filename <whitespace-quoted-filename-goes-here>

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

Примечание

Для разработчиков парсеров: чтобы сделать обработку устойчивее, просто игнорируйте все строки между первой и последней (<40-byte-hex-sha1> и строками filename), если вам неизвестны слова-метки в начале строк «расширенной информации» (или если они вас не интересуют). Тогда, если в будущем появятся дополнительные сведения (например, кодировка коммита или расширенный комментарий к коммиту), это не повлияет на средство просмотра blame.

Сопоставление авторов

См. gitmailmap[5].

Конфигурация

Всё, что находится ниже этой строки в данном разделе, выборочно включено из документации git-config[1]. Содержимое совпадает с тем, что приведено там:

blame.blankBoundary: Показывать пустое имя объекта коммита для граничных коммитов в git-blame[1]. По умолчанию этот параметр выключен.
blame.coloring: Определяет цветовую схему для вывода blame. Возможные значения: repeatedLines, highlightRecent или none (значение по умолчанию).
blame.date: Задает формат вывода дат в git-blame[1]. Если параметр не задан, используется формат iso. Поддерживаемые значения см. в описании параметра --date в git-log[1].
blame.showEmail: Показывать адрес электронной почты автора вместо его имени в git-blame[1]. По умолчанию этот параметр выключен.
blame.showRoot: Не считать корневые коммиты границами в git-blame[1]. По умолчанию этот параметр выключен.
blame.ignoreRevsFile: Игнорировать ревизии, перечисленные в файле (по одному полному имени объекта на строку), в git-blame[1]. Пробелы и комментарии, начинающиеся с #, игнорируются. Этот параметр можно указывать несколько раз. Пустое имя файла сбрасывает список игнорируемых ревизий. Этот параметр обрабатывается до параметра командной строки --ignore-revs-file.
blame.markUnblamableLines: Помечать в выводе git-blame[1] строки, измененные игнорируемой ревизией, которые не удалось связать с другим коммитом, с помощью *.
blame.markIgnoredLines: Помечать в выводе git-blame[1] строки, измененные игнорируемой ревизией и связанные с другим коммитом, с помощью ?.

См. также

git-annotate[1]

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-blame