git-notes

Имя

git-notes — добавление заметок к объектам или просмотр заметок

Синопсис

git notes [list [<object>]]
git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
git notes show [<object>]
git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
git notes merge --commit [-v | -q]
git notes merge --abort [-v | -q]
git notes remove [--ignore-missing] [--stdin] [<object>…]
git notes prune [-n] [-v]
git notes get-ref

Описание

Добавляет, удаляет или читает заметки, связанные с объектами, не изменяя сами объекты.

По умолчанию заметки сохраняются и читаются из refs/notes/commits, но это значение по умолчанию можно переопределить. См. разделы ПАРАМЕТРЫ, КОНФИГУРАЦИЯ и ОКРУЖЕНИЕ ниже. Если эта ссылка не существует, она будет незаметно создана при первой необходимости сохранить заметку.

Обычно заметки используют, чтобы дополнить сообщение коммита, не изменяя сам коммит. Заметки можно показывать с помощью git log вместе с исходным сообщением коммита. Чтобы отличить эти заметки от сообщения, хранящегося в объекте коммита, заметки форматируются с отступом, как и сообщение, после строки без отступа «Заметки (<refname>):» (или «Заметки:» для refs/notes/commits).

Заметки также можно добавлять к патчам, подготовленным с помощью git format-patch, используя параметр --notes. Такие заметки добавляются к патчу в качестве комментария после строки-разделителя из трёх дефисов.

Чтобы изменить набор заметок, показываемых с помощью git log, см. обсуждение notes.displayRef в разделе КОНФИГУРАЦИЯ.

Сведения о том, как переносить заметки между командами, переписывающими коммиты, см. в конфигурации notes.rewrite.<command>.

Подкоманды

list

Вывести объект заметок для указанного объекта. Если объект не указан, показать список всех объектов заметок и объектов, к которым они относятся (в формате «<note-object> <annotated-object>»). Эта подкоманда используется по умолчанию, если подкоманда не указана.

add

Добавить заметки к указанному объекту (по умолчанию — к HEAD). Прервать выполнение, если у объекта уже есть заметки (для перезаписи существующих заметок используйте -f). Однако при интерактивном использовании add (когда содержимое заметок вводится в редакторе) существующие заметки будут открыты в редакторе вместо прерывания выполнения (как в подкоманде edit). Если указано несколько параметров -m и -F, между сообщениями будет вставлена пустая строка. Используйте параметр --separator, чтобы указать другой разделитель. Перед добавлением заметки можно интерактивно отредактировать и уточнить сообщение или сообщения, заданные параметрами -m и -F, используя -e (в редакторе).

copy

Скопировать заметки первого объекта на второй объект (по умолчанию — на HEAD). Прервать выполнение, если у второго объекта уже есть заметки или у первого объекта заметок нет (для перезаписи существующих заметок второго объекта используйте -f). Эта подкоманда эквивалентна: git notes add [-f] -C $(git notes list <from-object>) <to-object>

В режиме --stdin считывать из стандартного ввода строки в формате

<from-object> SP <to-object> [ SP <rest> ] LF

и копировать заметки из каждого <from-object> в соответствующий ему <to-object>. (Необязательный параметр <rest> игнорируется, чтобы команда могла прочитать входные данные, переданные хуку post-rewrite.)

--stdin нельзя использовать вместе с именами объектов, указанными в командной строке.

append

Добавить новые сообщения, заданные параметрами -m или -F, к существующей заметке либо создать новую заметку, если её нет, для указанного объекта (по умолчанию — HEAD). При добавлении к существующей заметке перед каждым новым сообщением вставляется пустая строка в качестве разделителя абзацев. Разделитель можно настроить с помощью параметра --separator. Перед добавлением заметки можно интерактивно отредактировать заметки для добавления, заданные параметрами -m и -F, используя -e (в редакторе).

edit

Редактировать заметки для указанного объекта (по умолчанию — для HEAD).

show

Показать заметки для указанного объекта (по умолчанию — для HEAD).

merge

Слить указанную ссылку на заметки с текущей ссылкой на заметки. Будет предпринята попытка внести в текущую ссылку на заметки («локальную») изменения, сделанные в указанной ссылке на заметки («удалённой») после базового коммита слияния (если он есть).

Если возникнут конфликты и стратегия автоматического разрешения конфликтов заметок (см. раздел «СТРАТЕГИИ СЛИЯНИЯ ЗАМЕТОК») не указана, будет использоваться обработчик manual. Этот обработчик извлекает конфликтующие заметки в специальное рабочее дерево (.git/NOTES_MERGE_WORKTREE) и предлагает пользователю вручную разрешить там конфликты. После этого пользователь может либо завершить слияние с помощью git notes merge --commit, либо отменить его с помощью git notes merge --abort.

remove

Удалить заметки для указанных объектов (по умолчанию — для HEAD). Если в командной строке указан ноль или один объект, это эквивалентно передаче пустого сообщения заметки подкоманде edit.

В режиме --stdin также удаляются имена объектов, переданные через стандартный ввод. Иными словами, --stdin можно использовать вместе с именами объектов из командной строки.

prune

Удалить все заметки для несуществующих или недостижимых объектов.

get-ref

Вывести текущую ссылку на заметки. Это простой способ получить текущую ссылку на заметки (например, из скриптов).

Параметры

-f

--force

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

-m <msg>

--message=<msg>

Использовать указанное сообщение заметки (вместо запроса ввода). Если указано несколько параметров -m, их значения объединяются в отдельные абзацы.

-F <file>

--file=<file>

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

-C <object>

--reuse-message=<object>

Использовать указанный blob-объект (например, другую заметку) в качестве сообщения заметки. (Чтобы копировать заметки между объектами, используйте вместо этого git notes copy <object>.) Подразумевает --no-stripspace, поскольку по умолчанию сообщение копируется дословно.

-c <object>

--reedit-message=<object>

Как -C, но при указании -c запускается редактор, чтобы пользователь мог дополнительно отредактировать сообщение заметки.

--allow-empty

Разрешить сохранение пустого объекта заметки. По умолчанию пустые заметки удаляются автоматически.

--separator=<paragraph-break>

--separator

--no-separator

Задать строку, используемую в качестве пользовательского разделителя абзацев (при необходимости в конце добавляется символ новой строки). Если указано --no-separator, между абзацами не добавляются разделители. По умолчанию используется пустая строка.

--stripspace

--no-stripspace

Очистить пробельные символы. В частности (см. git-stripspace[1]):

удалить пробельные символы в конце всех строк
заменить несколько идущих подряд пустых строк одной пустой строкой
удалить пустые строки в начале и конце ввода
при необходимости добавить отсутствующий \n в конец последней строки.

--stripspace используется по умолчанию, за исключением -C/--reuse-message. Однако имейте в виду, что это зависит от порядка аналогичных параметров. Например, в случае -C <object> -m<message> будет использоваться --stripspace, поскольку значение по умолчанию для -m переопределяет предшествующий параметр -C. Это известное ограничение, которое может быть устранено в будущем.

--ref=<ref>

Работать с деревом заметок в <ref>. Переопределяет GIT_NOTES_REF и настройку core.notesRef. Если ссылка начинается с refs/notes/, указывается её полное имя; если она начинается с notes/, к ней добавляется префикс refs/, а в остальных случаях для формирования полного имени ссылки добавляется префикс refs/notes/.

--ignore-missing

Не считать ошибкой запрос на удаление заметок для объекта, к которому заметки не прикреплены.

--stdin

Допустим только для remove и copy. См. соответствующие подкоманды.

-n

--dry-run

Ничего не удалять; только вывести имена объектов, заметки для которых были бы удалены.

-s <strategy>

--strategy=<strategy>

При слиянии заметок разрешать конфликты заметок с помощью указанной стратегии. Поддерживаются следующие стратегии: manual (по умолчанию), ours, theirs, union и cat_sort_uniq. Этот параметр переопределяет настройку notes.mergeStrategy. Дополнительные сведения о каждой стратегии слияния заметок см. в разделе «СТРАТЕГИИ СЛИЯНИЯ ЗАМЕТОК» ниже.

--commit

Завершить выполняющееся git notes merge. Используйте этот параметр после разрешения конфликтов, сохранённых командой git notes merge в .git/NOTES_MERGE_WORKTREE. Это изменяет частичный коммит слияния, созданный командой git notes merge (сохранённый в .git/NOTES_MERGE_PARTIAL), добавляя заметки из .git/NOTES_MERGE_WORKTREE. Ссылка на заметки, хранящаяся в символической ссылке .git/NOTES_MERGE_REF, обновляется и указывает на результирующий коммит.

--abort

Отменить или сбросить выполняющееся git notes merge, то есть слияние заметок с конфликтами. При этом просто удаляются все файлы, связанные со слиянием заметок.

-q

--quiet

При слиянии заметок не выводить сообщения.

-v

--verbose

При слиянии заметок выводить подробные сообщения. При очистке заметок выводить имена всех объектов, заметки для которых удаляются.

Обсуждение

Заметки к коммитам — это blob-объекты, содержащие дополнительную информацию об объекте (обычно сведения, дополняющие сообщение коммита). Эти blob-объекты берутся из ссылок на заметки. Ссылка на заметки обычно является веткой, содержащей «файлы», пути к которым соответствуют именам объектов, описываемых этими файлами; для повышения производительности в пути включено несколько разделителей каталогов ^[1].

Каждое изменение заметок создаёт новый коммит в указанной ссылке на заметки. Поэтому историю заметок можно просмотреть, например, с помощью команды git log -p notes/commits. В настоящее время в сообщении коммита указывается только операция, вызвавшая обновление, а авторство коммита определяется по обычным правилам (см. git-commit[1]). В будущем эти подробности могут измениться.

Ссылка на заметки также может указывать непосредственно на объект дерева. В этом случае историю заметок можно просмотреть с помощью команды git log -p -g <refname>.

Стратегии слияния заметок

По умолчанию используется стратегия слияния заметок manual. Она извлекает конфликтующие заметки в специальное рабочее дерево для разрешения конфликтов (.git/NOTES_MERGE_WORKTREE) и предлагает пользователю разрешить конфликты в этом рабочем дереве. После этого пользователь может либо завершить слияние с помощью git notes merge --commit, либо отменить его с помощью git notes merge --abort.

Пользователи могут выбрать одну из следующих автоматических стратегий слияния с помощью параметра -s/--strategy или соответствующей настройки notes.mergeStrategy:

ours автоматически разрешает конфликты заметок в пользу локальной версии (то есть текущей ссылки на заметки).

theirs автоматически разрешает конфликты заметок в пользу удалённой версии (то есть указанной ссылки на заметки, сливаемой с текущей ссылкой).

union автоматически разрешает конфликты заметок, объединяя локальную и удалённую версии.

cat_sort_uniq похожа на стратегию union, но дополнительно к объединению локальной и удалённой версий сортирует получившиеся строки и удаляет повторяющиеся строки из результата. Это эквивалентно применению конвейера команд оболочки «cat | sort | uniq» к локальной и удалённой версиям. Эта стратегия полезна, если заметки имеют построчный формат и при слиянии требуется избежать дублирования строк. Обратите внимание: если в локальной или удалённой версии до слияния есть повторяющиеся строки, эта стратегия слияния заметок также удалит их.

Примеры

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

$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Notes:
    Tested-by: Johannes Sixt <j6t@kdbg.org>

По сути, заметка — это обычный blob-объект Git, допускающий любые форматы (и их отсутствие). Заметки из произвольных файлов можно создавать с сохранением двоичных данных с помощью git hash-object:

$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ref=built add --allow-empty -C "$blob" HEAD

(Нельзя просто использовать git notes --ref=built add -F a.out HEAD, так как этот способ не сохраняет двоичные данные.) Разумеется, показывать заметки в нетекстовом формате с помощью git log не имеет смысла, поэтому для практической работы с такими заметками, вероятно, потребуется написать специальные инструменты.

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

core.notesRef: Ссылка на заметки, с которой следует читать заметки и работать вместо refs/notes/commits. Должно быть указано полное имя ссылки. Эту настройку можно переопределить с помощью переменных окружения и параметров командной строки.

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

notes.mergeStrategy

Стратегия слияния, используемая по умолчанию при разрешении конфликтов заметок. Должна иметь одно из значений: manual, ours, theirs, union или cat_sort_uniq. По умолчанию используется manual. Дополнительные сведения о каждой стратегии см. в разделе «СТРАТЕГИИ СЛИЯНИЯ ЗАМЕТОК» документации git-notes[1].

Эту настройку можно переопределить, передав параметр --strategy команде git-notes[1].

notes.<name>.mergeStrategy

Стратегия слияния, используемая при слиянии заметок в refs/notes/<name>. Переопределяет более общую настройку notes.mergeStrategy. Дополнительные сведения о доступных стратегиях см. в разделе «СТРАТЕГИИ СЛИЯНИЯ ЗАМЕТОК» документации git-notes[1].

notes.displayRef

Ссылка (или ссылки, если задан шаблон glob либо параметр указан несколько раз), из которой следует читать заметки при показе сообщений коммитов с помощью команд семейства git log, в дополнение к набору ссылок по умолчанию, заданному параметром core.notesRef или GIT_NOTES_REF.

Эту настройку можно переопределить с помощью переменной окружения GIT_NOTES_DISPLAY_REF, которая должна содержать разделённый двоеточиями список ссылок или шаблонов glob.

Для несуществующих ссылок будет выведено предупреждение, но шаблоны glob, которым не соответствует ни одна ссылка, будут молча проигнорированы.

Эту настройку можно отключить параметром --no-notes команд семейства git-log[1] или с помощью параметра --notes=<ref>, поддерживаемого этими командами.

Эффективное значение core.notesRef (возможно, переопределённое значением GIT_NOTES_REF) также неявно добавляется в список показываемых ссылок.

notes.rewrite.<command>

При переписывании коммитов с помощью <command> (в настоящее время amend или rebase), если значение этой переменной равно false, git не будет копировать заметки из исходного коммита в переписанный. По умолчанию используется true. См. также notes.rewriteRef ниже.

Эту настройку можно переопределить с помощью переменной окружения GIT_NOTES_REWRITE_REF, которая должна содержать разделённый двоеточиями список ссылок или шаблонов glob.

notes.rewriteMode

При копировании заметок во время переписывания коммита (см. параметр notes.rewrite.<command>) определяет, что делать, если у целевого коммита уже есть заметка. Должно иметь одно из значений: overwrite, concatenate, cat_sort_uniq или ignore. По умолчанию используется concatenate.

Эту настройку можно переопределить с помощью переменной окружения GIT_NOTES_REWRITE_MODE.

notes.rewriteRef

При копировании заметок во время переписывания коммита задаёт ссылку (с полным именем), заметки из которой следует копировать. Можно указать шаблон glob — в этом случае будут скопированы заметки из всех соответствующих ссылок. Эту настройку также можно указать несколько раз.

Значение по умолчанию отсутствует; чтобы включить переписывание заметок, необходимо настроить эту переменную. Установите для неё значение refs/notes/commits, чтобы включить переписывание заметок по умолчанию к коммитам.

Значение можно переопределить с помощью переменной окружения GIT_NOTES_REWRITE_REF. Дополнительное описание её формата см. выше в разделе notes.rewrite.<command>.

Окружение

GIT_NOTES_REF

На какую ссылку следует воздействовать при работе с заметками вместо refs/notes/commits. Это переопределяет настройку core.notesRef.

GIT_NOTES_DISPLAY_REF

Список ссылок или шаблонов glob, разделённых двоеточиями, указывающий, из каких ссылок, помимо значения по умолчанию из core.notesRef или GIT_NOTES_REF, следует читать заметки при отображении сообщений коммитов. Это переопределяет настройку notes.displayRef.

Для несуществующих ссылок будет выдано предупреждение, но шаблон glob, не соответствующий ни одной ссылке, будет молча проигнорирован.

GIT_NOTES_REWRITE_MODE

При копировании заметок во время переписывания коммитов определяет, что делать, если у целевого коммита уже есть заметка. Должно быть одним из значений: overwrite, concatenate, cat_sort_uniq или ignore. Это переопределяет настройку core.rewriteMode.

GIT_NOTES_REWRITE_REF

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

Если переменная окружения не задана, список копируемых заметок зависит от настроек notes.rewrite.<command> и notes.rewriteRef.

1. Допустимые имена путей имеют вид bf/fe/30/…/680d5a…: последовательность имён каталогов, состоящих из двух шестнадцатеричных цифр каждое, за которой следует имя файла с оставшейся частью идентификатора объекта.

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