Русский ▾ Topics ▾ Latest version ▾ git-notes last updated in 2.50.0

НАЗВАНИЕ

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

ОБЗОР

git notes [list [<объект>]]
git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<разрыв-абзаца>] [--[no-]stripspace] [-F <файл> | -m <сообщение> | (-c | -C) <объект>] [-e] [<объект>]
git notes copy [-f] ( --stdin | <объект-источник> [<объект-назначение>] )
git notes append [--allow-empty] [--[no-]separator | --separator=<разрыв-абзаца>] [--[no-]stripspace] [-F <файл> | -m <сообщение> | (-c | -C) <объект>] [-e] [<объект>]
git notes edit [--allow-empty] [<объект>] [--[no-]stripspace]
git notes show [<объект>]
git notes merge [-v | -q] [-s <стратегия> ] <ссылка-на-заметки>
git notes merge --commit [-v | -q]
git notes merge --abort [-v | -q]
git notes remove [--ignore-missing] [--stdin] [<объект>…​]
git notes prune [-n] [-v]
git notes get-ref

ОПИСАНИЕ

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

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

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

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

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

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

ПОДКОМАНДЫ

list

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

add

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

copy

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

В режиме --stdin принимает строки в формате

<объект-источник> ПРОБЕЛ <объект-назначение> [ ПРОБЕЛ <остальное> ] ПЕРЕВОД_СТРОКИ

на стандартном вводе и копирует заметки из каждого <объекта-источника> в соответствующий <объект-назначение>. (Необязательный <остальное> игнорируется, чтобы команда могла читать ввод, передаваемый перехватчику 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 <сообщение>
--message=<сообщение>

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

-F <файл>
--file=<файл>

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

-C <объект>
--reuse-message=<объект>

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

-c <объект>
--reedit-message=<объект>

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

--allow-empty

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

--separator=<разрыв-абзаца>
--separator
--no-separator

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

--stripspace
--no-stripspace

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

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

  • сжать несколько последовательных пустых строк в одну пустую строку

  • удалить пустые строки из начала и конца ввода

  • добавить отсутствующий \n в последнюю строку, если необходимо.

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

--ref=<ссылка>

Управлять деревом заметок в <ссылка>. Это переопределяет GIT_NOTES_REF и конфигурацию core.notesRef. Ссылка определяет полное имя ссылки, если она начинается с refs/notes/; когда она начинается с notes/, добавляется префикс refs/, а в противном случае добавляется префикс refs/notes/, чтобы сформировать полное имя ссылки.

--ignore-missing

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

--stdin

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

-n
--dry-run

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

-s <стратегия>
--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. Ссылка на заметки, хранящаяся в символической ссылке (symref) .git/NOTES_MERGE_REF, обновляется до результирующего коммита.

--abort

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

-q
--quiet

При слиянии заметок работать тихо.

-v
--verbose

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

ОБСУЖДЕНИЕ

Заметки коммитов — это blob-объекты, содержащие дополнительную информацию об объекте (обычно информацию, дополняющую сообщение коммита). Эти blob-объекты берутся из ссылок на заметки. Ссылка на заметки обычно представляет собой ветку, которая содержит «файлы», пути которых являются именами объектов, которые они описывают, с включением некоторых разделителей каталогов по соображениям производительности сноска:[Допустимые имена путей имеют форму bf/fe/30/…​/680d5a…​: последовательность имён каталогов по две шестнадцатеричные цифры, за которыми следует имя файла с остальной частью идентификатора объекта.].

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

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

СТРАТЕГИИ СЛИЯНИЯ ЗАМЕТОК

Стратегия слияния заметок по умолчанию — 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>

Заметки:
    Tested-by: Johannes Sixt <j6t@kdbg.org>

В принципе, заметка — это обычный Git blob-объект, и принимается любой вид (не-)формата. Вы можете безопасно для двоичных данных создавать заметки из произвольных файлов, используя 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.<имя>.mergeStrategy

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

notes.displayRef

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

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

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

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

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

notes.rewrite.<команда>

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

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

notes.rewriteMode

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

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

notes.rewriteRef

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

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

Может быть переопределена с помощью переменной среды GIT_NOTES_REWRITE_REF. См. notes.rewrite.<команда> выше для дальнейшего описания её формата.

ОКРУЖЕНИЕ

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.<команда> и notes.rewriteRef.

GIT

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