Заметки к коммитам

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

git notes — выход из положения. Заметка хранится рядом с коммитом, под refs/notes/commits, и её добавление оставляет коммит побайтово тем же. То есть она работает на уже опубликованной истории — а это ровно тот момент, когда дописать что-то хочется сильнее всего.

Типичное применение: ревью, которое его одобрило; тикет, который он закрыл; почему его откатили; в какой релиз он попал.

Как написать

Выберите коммит. Под сообщением есть секция Заметка: Добавить заметку, печатаете, Сохранить заметку. Несколько строк — не проблема.

Написание заметки под сообщением уже отправленного коммита и её сохранение

Сохранение заметки — обычное действие Gitcito: оно показывает тост, а Отмена возвращает прежний текст, включая восстановление удалённой заметки.

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

Как найти

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

Из командной строки git log --notes печатает их под каждым сообщением.

Как поделиться

Вот часть, которая удивляет всех: обычный git push не отправляет заметки, а обычный git fetch их не забирает. Они живут вне refs/heads и refs/tags, так что рефспеки по умолчанию их просто пропускают. Заметки, написанные на вашем ноутбуке, остаются на вашем ноутбуке, пока кто-нибудь не перенесёт их явно.

Инструменты → Заметка → Отправить заметки / Получить заметки, по каждому удалённому репозиторию. Они выполняют:

git push <remote> refs/notes/commits
git fetch <remote> +refs/notes/commits:refs/notes/commits

Передаётся только ссылка заметок к коммитам — собственные локальные для машины ссылки Gitcito (например, вердикты локального CI) намеренно не публикуются.

Некоторым хостингам нужно, чтобы заметки были включены или разрешены на их стороне; отказ оттуда — политика хостинга, а не ограничение Gitcito.

Нет общего удалённого репозитория или нет права записи? Безопасная передача может упаковать заметки репозитория в зашифрованный файл, который коллега импортирует напрямую — с предпросмотром того, что попадёт внутрь, и явным выбором перезаписи для расходящихся заметок.

Ограничения

Одна ссылка заметок. Gitcito читает и пишет только стандартную refs/notes/commits. Пользовательские пространства имён (git notes --ref=review) не выведены наружу — репозиторий, который их использует, здесь этих заметок не увидит.
Расходящиеся заметки не сливаются. Если двое аннотировали один и тот же коммит и оба сделали пуш, git отклонит второй. Разрешать это придётся через git notes merge в терминале.
Заметки не попадают ни в резервную копию перед вычисткой, ни в снимки. Это обычные ссылки, и они переживают нормальные операции, но репозиторий, склонированный заново, начинает без них.

См. также: Коммиты · Граф коммитов