Нотатки до комітів

Повідомлення коміта пишеться один раз і потім замерзає: змінити його означає переписати коміт, дати йому новий хеш і зламати всіх, хто вже має старий. За годину після коміта це нормально, за тиждень — неможливо.

git notes — це вихід. Нотатка зберігається поруч із комітом, під refs/notes/commits, і прикріплення нотатки лишає коміт байт у байт таким самим. Тож це працює для історії, яку вже опубліковано — а саме тоді вам найбільше й хочеться щось додати.

Типове застосування: рев’ю, яке його схвалило, тікет, який він закрив, чому його відкотили, у який реліз він поїхав.

Як написати

Виберіть коміт. Під повідомленням є секція Нотатка: Додати нотатку, наберіть текст, Зберегти нотатку. Кілька рядків — нормально.

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

Якщо очистити текст і зберегти, нотатка зникає; порожніх нотаток не буває.

Як знайти

Нотаток не видно у звичайному лозі, і це головна причина, чому люди їх ніколи не відкривають. Gitcito позначає коміт, який несе нотатку, невеликою іконкою в колонці повідомлень графа, тож анотацію можна знайти, не знаючи наперед, що вона там є.

З командного рядка git log --notes виводить їх під кожним повідомленням.

Як ділитися ними

Ось частина, яка дивує всіх: звичайний git push не пушить нотаток, а звичайний git fetch їх не забирає. Вони живуть поза refs/heads і refs/tags, тож типові refspec-и повністю їх оминають. Нотатки, написані на вашому ноутбуці, лишаються на вашому ноутбуці, доки хтось не перенесе їх явно.

Інструменти → Нотатка → Запушити нотатки / Отримати нотатки, для кожного віддаленого репозиторію. Вони виконують:

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 у терміналі.
• Нотатки не резервуються бекапом перед очищенням і не входять у знімки. Це звичайні рефи, і вони переживають нормальні операції, але репозиторій, переклонований з нуля, стартує без них.

Дивіться також: Коміти · Граф комітів