As we saw in the previous example, we can add notes to the commits, but in some cases, it makes sense to store the information sorted by categories, such as featureImplemented, defect, and alsoCherryPick. As briefly explained at the beginning of the chapter, notes are stored in refs/notes/commits but we can add multiple references so that we can easily sort and list the different scopes of the notes.
To start this example, 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 Branch notesReferences set up to track remote branch stable-3.1 from origin. Switched to a new branch 'notesReferences'
Imagine a situation where we have corrected a defect and did everything we could to ensure the quality of the commit before releasing it. Nonetheless, we had to make another fix for the same defect.
So, we want to add a note to the reference refs/notes/alsoCherryPick, which should indicate that if you cherry pick this commit, you should also cherry pick the other commits as they fix the same defect.
In this example, we will find a commit and add some extra information to the commit in multiple notes' reference specifications:
- Start by listing the top ten commits on the branch so we have something to copy and paste from:
$ git log -10 --oneline da6e87b Prepare post 3.1.0 builds 16ca725 JGit v3.1.0.201310021548-r c6aba99 Fix order of commits in rebase todo file header 5a2a222 Prepare post 3.1.0 RC1 builds 6f0681e JGit v3.1.0.201309270735-rc1 a065a06 Attempt to fix graph layout when new heads are introduced b4f07df Prepare re-signing pgm's ueberjar to avoid SecurityException aa4bbc6 Use full branch name when getting ref in BranchTrackingStatus 570bba5 Ignore bitmap indexes that do not match the pack checksum 801aac5 Merge branch 'stable-3.0'
- Now, to add a note for the
b4f07dfcommit in the refalsoCherryPick, we must use the--refoption forgit notes. This has to be specified before theaddoption:$ git notes --ref alsoCherryPick add -m "570bba5" b4f07df - No output means success when adding notes. Now that we have a note, we should be able to list it with a single
git log -1command. However, this is not the case. You actually need to specify that you want to list the notes from the specific ref. This can be done with the--notes=alsoCherryPickoption forgit log:$ git log -1 b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a --notes=alsoCherryPick commit b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a Author: Matthias Sohn <[email protected]> Date: Tue Sep 24 09:11:47 2013 +0200 Prepare re-signing pgm's ueberjar to avoid SecurityException More output... Change-Id: Ia302e68a4b2a9399cb18025274574e31d3d3e407 Signed-off-by: Matthias Sohn <[email protected]> Notes (alsoCherryPick): 570bba5
- As you can see from the output, Git shows the
alsoCherryPicknotes. The reason for not showing is that Git defaults to adding notes intorefs/notes/commits. It would be nice if you could just show thealsoCherryPicknotes' reference by default. This can be done by configuring Git as follows:$ git config notes.displayRef "refs/notes/alsoCherryPick" - By configuring this option, you are telling Git to always list these notes. But what about the default notes? Have we overwritten the configuration to list the default
refs/notes/commitsnotes? We can check this withgit log -1to see if we still have the test note displayed:$ git log -1 commit da6e87bc373c54c1cda8ed563f41f65df52bacbf Author: Matthias Sohn <[email protected]> Date: Thu Oct 3 17:22:08 2013 +0200 Prepare post 3.1.0 builds Change-Id: I306a3d40c6ddb88a16d17f09a60e3d19b0716962 Signed-off-by: Matthias Sohn <[email protected]> Notes: test note
- No, we did not overwrite the setting to list notes in the default refs. Knowing that we can have as many
notes.displayRefconfigurations as we want, we should add all the refs we want to use in our repo. In some situations, it is even better to just addrefs/notes/*. This will configure Git to show all the notes:$ git config notes.displayRef 'refs/notes/*' - If we add another note in
refs/notes/defectnow, we should be able to list it without specifying which notes' reference we want to list when usinggit log. We are adding to the commit that already has a note in thealsoCherryPickreference:$ git notes --ref defect add -m "Bug:24435" b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a - Now, list the commit with
git log:$ git log -1 b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a commit b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a Author: Matthias Sohn <[email protected]> Date: Tue Sep 24 09:11:47 2013 +0200 Prepare re-signing pgm's ueberjar to avoid SecurityException See http://dev.eclipse.org/mhonarc/lists/jgit-dev/msg02277.html Change-Id: Ia302e68a4b2a9399cb18025274574e31d3d3e407 Signed-off-by: Matthias Sohn <[email protected]> Notes (alsoCherryPick): 570bba5 Notes (defect): Bug:24435
- Git shows both notes, which is what we would expect.
I have been writing about the refs/notes/alsoCherryPick 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 are also references such as refs/heads/develop for instance.
Since you can create a branch that starts at a specific reference, you should be able to create a branch that starts at the refs/notes/alsoCherrypick reference:
- Create a branch that starts from
refs/notes/alsoCherryPick. Also, checkout the branch:$ git checkout -b myNotes notes/alsoCherryPick Switched to a new branch 'myNotes'
- The
myNotesbranch now points toHEADonrefs/notes/alsoCherryPick. Listing the files on the branch will show a file with the commit hash of the commit we have added the notes to:$ ls b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a
- Showing the file content will show the text we used as note text:
$ cat b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a 570bba5
- As you can see, the abbreviated commit hash
570bba5we added as a note forb4f07df357fccdff891df2a4fa5c5bd9e83b4a4ais in the file. If we had a longer message, that message would also be shown here.