From: Nikita Shubin Date: Mon, 18 Apr 2022 07:35:25 +0000 (+0300) Subject: vcs: git: git-notes X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;p=brevno vcs: git: git-notes Introducinary about "git notes" and it's usage, covering some inner details about "git notes" structure. Signed-off-by: Nikita Shubin --- diff --git a/git/git_notes.md b/git/git_notes.md new file mode 100644 index 0000000..79e7df5 --- /dev/null +++ b/git/git_notes.md @@ -0,0 +1,293 @@ +# Незаконное руководство по git notes и показания к применению + +Команда **git notes** позволяет манипулировать заметками к коммиту, не меняя при этом его хэш. + +> Simply because notes namespaces are not something special in git, they are just ordinary branches with complete history. You can do + +**git notes**, фактически это отдельные отдельные "ветки", расположенные в **.git/refs/notes**, они не отображаются командой **git branch**. Их можно сравнить с **orphan branches** - немного похоже, +но коммиты в ```refs/notes/*```, содержат ссылки на деревья, которые в свою очередь содержат блобы с именами коммитов (любых - как из регулярных деревьев, так и из ```refs/notes/*```). + +Нужно разобрать https://stackoverflow.com/questions/18273879/git-get-the-commit-id-and-the-note-of-a-commit + +``` +$ git init +$ git config user.name "John Doe" +$ git config user.email johndoe@example.com +$ git add README.md +$ git commit -m "root commit" +$ git add file1 +$ git commit -m "add file1" +$ git add file2 +$ git commit -m "add file2" +$ git add file3 +$ git commit -m "add file3" +``` + +Предположим у нас есть такой проект (специально положил все файлы в корень проекта, чтобы избежать лишних деревьев в графе): + +![git-initial](git_notes/git-initial.tree.png) + +Добавим к нему **git notes**: + +``` +git notes add HEAD~3 -m "Hello Note One!" +git notes add HEAD~2 -m "Hello Note Two!" +git notes add HEAD -m "Hello Note HEAD!" +``` + +**git log** по умолчание выводит **notes** из **refs/notes/commits**, это поведение контролируется переменной окружения **GIT_NOTES_REF** или ключом конфигурации **core.notesRef**: + +``` +$ git --no-pager log +commit 54eb62cfb827810077391650c5434a4082db4276 (HEAD -> master) +Author: John Doe +Date: Thu Mar 31 16:19:04 2022 +0300 + + add file3 + +Notes: + Hello Note HEAD! + +commit d7ddbc3ac210ca0199ac6605b02e4b0c35e126ac +Author: John Doe +Date: Thu Mar 31 16:19:04 2022 +0300 + + add file2 + +commit bea58b9b945d27fad5d0779a4b86e5e33fbcc9e9 +Author: John Doe +Date: Thu Mar 31 16:19:04 2022 +0300 + + add file1 + +Notes: + Hello Note Two! + +commit 46794ca99c524be1bd300ba7e830bf2611229fcf +Author: John Doe +Date: Thu Mar 31 16:19:04 2022 +0300 + + root commit + +Notes: + Hello Note One! +``` + +Для начала убедимся, что это ветка: + +``` +$ git checkout notes/commits +$ git --no-pager log --oneline +c958b65 (HEAD, refs/notes/commits) Notes added by 'git notes add' +14967b4 Notes added by 'git notes add' +a048c64 Notes added by 'git notes add' +``` + +И построим граф, теперь уже для ветки **notes/commits**: + +![git-initial-notes-tree](git_notes/git-initial-notes-tree.png) + +Как мы видим это объекты коммитов, ну да кто бы сомневался, а это значит, что мы можем добавить note к уже существующему note ! + +``` +$ git notes add c958b65 -m "I Am A Note To A Note!" +$ git --no-pager show c958b65 +commit c958b65a4027b566a341903c27a6d020484a7666 (HEAD) +Author: John Doe +Date: Fri Apr 1 12:12:58 2022 +0300 + + Notes added by 'git notes add' + +Notes: + I Am A Note To A Note! + +diff --git a/54eb62cfb827810077391650c5434a4082db4276 b/54eb62cfb827810077391650c5434a4082db4276 +new file mode 100644 +index 0000000..c7aa303 +--- /dev/null ++++ b/54eb62cfb827810077391650c5434a4082db4276 +@@ -0,0 +1 @@ ++Hello Note HEAD! + +$ git --no-pager log notes/commits +commit 36438c1388cad56e020327a11918cc96d5c567dd (refs/notes/commits) +Author: John Doe +Date: Fri Apr 1 12:45:23 2022 +0300 + + Notes added by 'git notes add' + +commit c958b65a4027b566a341903c27a6d020484a7666 (HEAD) +Author: John Doe +Date: Fri Apr 1 12:12:58 2022 +0300 + + Notes added by 'git notes add' + +Notes: + I Am A Note To A Note! + +commit 14967b4531613477caad3d45d5c639b952218fc4 +Author: John Doe +Date: Fri Apr 1 12:12:58 2022 +0300 + + Notes added by 'git notes add' + +commit a048c6403d67a71b4f0279a54f7c3bbbf904eee0 +Author: John Doe +Date: Fri Apr 1 12:12:58 2022 +0300 + + Notes added by 'git notes add' +``` + +Граф при это поменялся не сильно, просто верхний коммит теперь указывает на дерево, которое в свою очередь указывает на четыре blob'a. + +![git-add-note-to-note](git_notes/git-add-note-to-note.png) + +Если внимательно посмотреть на дерево первого коммита в **notes/commits**, то мы увидим следующее: + +``` +$ git cat-file -p 5c0584bf4fe93ca289827ba9d2d5557f7356c207 +100644 blob 58589bd2a9c6361fe31740a7f4c6e73fb7663e9c 46794ca99c524be1bd300ba7e830bf2611229fcf +``` + +При этом содержимым блоба будет являться текст самой записки: + +``` +$ git cat-file -p 58589bd2a9c6361fe31740a7f4c6e73fb7663e9c +Hello Note One! +``` + +А имя файла **46794ca** это ничто иное как коммит к которому относится записка. + +``` +$ git cat-file -p 46794ca99c524be1bd300ba7e830bf2611229fcf +tree 9bd9e28a95ee603c5e584689c84d6b9c4acee7cd +author John Doe 1648732744 +0300 +committer John Doe 1648732744 +0300 + +root commit +``` + +## Бесконечное число ```refs/notes/*``` + +По умолчанию используется **refs/notes/commits** + +Число записок никак не ограничено, можно создать refs/notes/ + +## Default git notes namespace + +## merge git-notes + +``` +$ git notes --ref commits-new add -m "Merge me note" +$ git --no-pager log --show-notes="*" HEAD^..HEAD +commit 56fb198260e598ec762be8ed7b158c0ded4a3585 (HEAD -> master) +Author: John Doe +Date: Mon Apr 4 10:05:06 2022 +0300 + + add file3 + +Notes: + Hello Note HEAD! + +Notes (commits-new): + Merge me note +``` + +Попытка смержить два дерева notes, приведет к конфликту: + +``` +$ git notes merge commits-new +Auto-merging notes for 56fb198260e598ec762be8ed7b158c0ded4a3585 +CONFLICT (add/add): Merge conflict in notes for object 56fb198260e598ec762be8ed7b158c0ded4a3585 +Automatic notes merge failed. Fix conflicts in .git/NOTES_MERGE_WORKTREE and commit the result with 'git notes merge --commit', or abort the merge with 'git notes merge --abort'. +$ cat .git/NOTES_MERGE_WORKTREE/56fb198260e598ec762be8ed7b158c0ded4a3585 +<<<<<<< refs/notes/commits +Hello Note HEAD! +======= +Merge me note +>>>>>>> refs/notes/commits-new +$ git notes merge --abort +``` + +Конфликт легко разрешим руками (поддержки mergetool в git notes отсутствует), либо можно задать стратегию для merge (по умолчанию manual): + +``` +$ git notes merge --strategy=union commits-new +$ git --no-pager log --show-notes="*" HEAD^..HEAD +commit 56fb198260e598ec762be8ed7b158c0ded4a3585 (HEAD -> master) +Author: John Doe +Date: Mon Apr 4 10:05:06 2022 +0300 + + add file3 + +Notes: + Hello Note HEAD! + + Merge me note + +Notes (commits-new): + Merge me note +``` + +## git notes и cherry-pick + +## Показания к применению + +### Мета информация + +Сюда может входить информация о сборках, включая путь к артефакту. Можно убрать сюда привязку к тикету, чтобы убрать из текста коммита отвратительные номера Jira, Gitlab, чего угодно. + +Некоторые инструменты сохраняют здесь данные, например дополнительную информацию о конвертации из subversion в git. + +### Комментарии и обсуждения + +Поскольку к коммиту из notes можно привязывать опять же коммит из notes, это позволяет создавать, хоть целые ветки форумов или хранить в таком формате архив mail-lists. + +## Поддержка в git веб-мордах + +### Bitbucket + +Нет и не предвидится: +https://jira.atlassian.com/browse/BSERV-5450 + +Есть подтухший плагин: +https://github.com/daveychu/git-notes-plugin + +### Gitlab + +Нет и не предвидится: +https://gitlab.com/gitlab-org/gitlab/-/issues/15029 + +### Gogs, Gitee + +Опять же нет. + +## Что осталось за кадром + +- git notes append (смысл для неё тот же самый, что и для git add) +- любой blob в качестве note (пример есть в официальной документации) +- git notes copy (смысл и синтаксис вполне очевиден) + +## Визуализаторы для обучения + +- https://github.com/hoduche/git-graph +- https://github.com/functicons/git-graph +- https://github.com/git-school/visualizing-git + +## + +- https://git-scm.com/docs/git-notes +- https://gist.github.com/dnclive/8399055 +- https://alblue.bandlem.com/2011/11/git-tip-of-week-git-notes.html +- https://gerrit.googlesource.com/plugins/reviewnotes/%2B/master/src/main/resources/Documentation/refs-notes-review.md +- https://blog.adamspiers.org/2013/10/02/more-uses-for-git-notes/ +- https://www.ibm.com/docs/en/elm/6.0?topic=git-associating-work-items-commits +- https://dev.to/leehambley/effortlessly-maintain-a-high-quality-change-log-with-git-notes-4bm5 +- https://stackoverflow.com/questions/45672799/get-all-notes-for-a-commit-including-their-author-and-committer +- https://stackoverflow.com/questions/17018267/why-parent-is-stored-in-git-notes +- https://stackoverflow.com/questions/52202916/find-commit-with-specific-git-note +- https://stackoverflow.com/questions/18273879/git-get-the-commit-id-and-the-note-of-a-commit +- https://rubicotech.com/blog/advanced-git-features/ +- https://github.com/functicons/git-graph +- https://stackoverflow.com/questions/14585613/is-there-a-way-to-automatically-merge-notes-if-commits-for-those-notes-get-squas +- https://github.com/aspiers/git-config/blob/master/bin/git-rnotes diff --git a/git/git_notes/git-add-note-to-note.png b/git/git_notes/git-add-note-to-note.png new file mode 100644 index 0000000..f2f0a26 Binary files /dev/null and b/git/git_notes/git-add-note-to-note.png differ diff --git a/git/git_notes/git-initial-notes-tree.png b/git/git_notes/git-initial-notes-tree.png new file mode 100644 index 0000000..6aedc5a Binary files /dev/null and b/git/git_notes/git-initial-notes-tree.png differ diff --git a/git/git_notes/git-initial.tree.png b/git/git_notes/git-initial.tree.png new file mode 100644 index 0000000..164fe8c Binary files /dev/null and b/git/git_notes/git-initial.tree.png differ diff --git a/git/git_notes/git-notes-gitk-for-title.png b/git/git_notes/git-notes-gitk-for-title.png new file mode 100644 index 0000000..3fc5bb6 Binary files /dev/null and b/git/git_notes/git-notes-gitk-for-title.png differ