Attaching notes to git branches

The problem

Beside my coding activity for work, I have several personal projects active. Clearly, I work on them in my free time and since they are personal projects, it can happen that for some reason I stop working on them for a long stretch of time.

The problem is that when I decide to resume a personal project, more often than not I do not remember what I was doing when I stopped working. Maybe there are a couple of branches open and I wonder if there is still work to do on them or if they are ready to be merged on the main branch, or…

I thought that it would be nice if I could attach to every branch a note about what that branch is about, what I did so far and what still need to be done. Since I work on several computers, I would like those notes to be managed as they were tracked files, allowing me to access the same information wherever I work.

The research

I looked around for some solution, but I couldn’t find anything that suited me. First I found git branch --edit-description, but the description is written in the config file and it is not possible to push it to other repositories. Also, I considered for a while git notes, but it has two drawbacks for me. First, you can attach a note to a git object (blob, commit, tree), but branches are not git objects; sure, you could attach the note to the commit where the branch was created, but this would require to search for the branching point every time you want to read the note; moreover, while pushing notes is possible, it is not really straightforward. Therefore git notes could be a solution, but definitively not the ideal one.

The solution

Therefore, I decided to bake my own solution in the form of branchnotes, a Ruby script with a CLI similar to git (that can be run as a git external command) that allows you to add notes to a branch and manage them.

The idea is that a branch has a motivation (why did you create the branch? Sure, a descriptive name helps, but sometimes you need more) and an history of events (that is, the milestones that you reached so far). The most recent event is the current status of the branch.

The notes for branch foo are stored in JSON format in .branchnotes/foo under the repository root. The note files are tracked and pushed using normal git commands.

A brief overview of the implemented commands follows. See the README.md file for more information.

• git branchnotes init Create the note for the current branch, specifying the motivation for the branch
• git branchnotes update Add a new milestone to the history
• ‘git branchnotes show ( reason | status | history )` Print the reason/current state/history of the branch
• git branchnotes edit Edit the full JSON description
• git branchnotes print Print the full JSON description to the standard output. Potentially useful for filters.
• git branchnotes read Read the full JSON description from the standard input. Potentially useful for filters.

Current version (2024-08-08) is still 1.0.0 and it can be a bit rough around the edges, but it should be fairly usable.