How to Separate notes by category (Git)

As we saw in the previous example, we can add notes to the commits; however, in some cases, it makes sense to store the information sorted by categories. Notes are stored in refs/notes/commits, but we can add multiple references so that we can easily sort and list the various scopes of the notes.

Step 1 : we need a new branch that tracks the origin/stable-3.1 branch; we name the branch notesReferences, and create and checkout the branch with the following command:

git checkout -b notesReferences --track origin/stable-3.1

Step 2 : In this post, we will find the commit and add some extra information to the commit in multiple notes' reference specifications. Start by listing the top 10 commits on the branch so we have something to copy and paste from:

git log -10 --oneline

Step 3 : Add a note for the da6e87bc3 commit:

git notes add -m "test note"

Step 4 : Now, to add a note for the b4f07df commit in the ref notesByCategory, we must use the --ref option for git notes. This has to be specified before the add option:

git notes --ref  notesByCategory add -m "570bba5" b4f07df

Step 5 : Now that we have a note, we should be able to list it with a single git log -1 command. You actually need to specify that you want to list the notes from the specific ref. This can be done with the --notes=notesByCategory option for git log:

git log -1 b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a --notes=notesByCategory

Step 6 : Git shows the notesByCategory notes. Git defaults to adding notes to refs/notes/commits, but we have explicitly specified to show notesByCategory. It would be nice if you could show the notesByCategory notes' reference by default so you don't have to use --notes=notesByCategory. This can be done by configuring Git as follows:

git config notes.displayRef "refs/notes/notesByCategory"

Step 7 : By configuring this option, you are telling Git to always list these notes

git log -1

Step 8 : No, we did not overwrite the setting to list notes in the default refs. This will configure Git to show all the notes:

git config notes.displayRef 'refs/notes/*'

Step 9 : If we now add another note in refs/notes/defect, we should be able to list it without specifying which notes' reference we want to list when using git log

git notes --ref defect add -m "Bug:357" b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a

Step 10 : Now, list the commit with git log:

git log -1 b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a

Git shows both notes, which is what we would expect.

Step 11 : We have been discussing the refs/notes/notesByCategory reference and so on. As you know, we refer to the remote branches as references, such as refs/remotes/origin/stable-3.2, but the local branches also have references such as refs/heads/develop, for instance. Create a branch that starts from refs/notes/notesByCategory. Also, checkout the branch:

git checkout -b myNotes notes/notesByCategory

Step 12 : The myNotes branch now points to HEAD on refs/notes/notesByCategory. Listing the files on the branch will show a file with the commit hash of the commit we have added the notes to:

ls

Step 13 : Showing the file content will show the text we used as note text:

cat b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a

As you can see, the abbreviated commit hash 570bba5 we added as a note for b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a is in the file.