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 initCreate the note for the current branch, specifying the motivation for the branch -
git branchnotes updateAdd a new milestone to the history - 'git branchnotes show [ reason | status | history ]` Print the reason/current state/history of the branch
-
git branchnotes editEdit the full JSON description -
git branchnotes printPrint the full JSON description to the standard output. Potentially useful for filters. -
git branchnotes readRead 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.
Top comments (17)
Instead of storing the branch notes as files in the working directory, which clutters up the project history with changes to the notes, why not store the notes in git? Utilizing
git hash-object,git mktree,git commit-tree, andgit update-refyou can manipulate git references without ever having to touch files in the working directory. With appropriate changes to.git/config, you can push custom refs to git{hub,lab,etc}.I think that there are tradeoffs to that solution. When things go wrong, debugging arbitrary git references seems painful. Using files makes the solution more transparent. KISS
I don't think working with git references is particularly difficult (we're doing that anyway!), and I think it's a huge win over cluttering your repository history with metadata updates to your notes. I think I'm going to put together a proof of concept implementation.
This is really good solution. I wish this can become part of git itself. Can you consider opening a feature request on github for git and suggest this solution. The maintainer of git may consider making it part of git itself.
I did not consider that, but I can try.
Another direction to take might be to recognize this as one of many opportunities for a new version control system that is entirely DLT. Commit messages, object descriptions/annotations are all the same thing: text attached to timelines or individual points in time. Even issues, discussions, PR messages (and more!) are all text objects that could live as first class members of the DAG instead of out-of-band in multitudes of formats haphazardly in multiple libraries. This explosion of complexity goes away if you replace git with a more generalized timeline "semantic version control" system. It is after all 20 years old and ripe for opportunities.
That's an interesting comment and an interesting idea. But I am wondering, if we can build such a tool, won't it be heavy?
No heavier than any existing DLT approach. The differentiating factor is that while being a crypto protocol, it is not built from the bitcoin POV. The goal is to provide timeline dynamics to any semantic data, and the initial complexity is outweighed by all of the very interesting properties that arise later on: replication (similar to fast forward- only git merges), streamlined crypto guarantees on data integrity, auditability, and similar to git, it enables sovereign boundaries between closed and open "source" just like you can interop between closed and open repos.
Actually that's probably the most important consequence of a non-bitcoin derived DLT: the interop novelty. Instead of having a data silo exposed via an"off chain" shape via an API, you have a time-based DSL (like git) that provides clone, merge, fork, etc. operations. This means you can clone a src graph (like current git) but also you can get versioned, "on chain" projections that include other aspects: comments/text metadata like discussed in your article but also "commit messages" (an arbitrary silo to be sure), issues, discussions, and more, but also swagger-like schema metadata. This metadata plus data all in the same hypergraph is what enables the amazing properties!
Why not just creating a pull request and add a description there?
My question exactly...
I think pull requests are a good option as some pointed out, but a "pull request" is not part of git, and is part of a vendor lock-in. I think there's value in being git-centric and not tied down to a vendor, as well as being portable.
Someone else already mentioned git reference, which I would highly recommend looking into.
On some previous projects we had tooling that would run some hooks to run tests and check if the coverage had dropped before allowing you to push up. It stored the metadata in references . There was or course overrides, but it helped save some cloud money on smaller projects that didn't have an intensive test suite. Also for some test suites you can just run tests for the given changes based upon the AST/related/touched code to help alleviate long local runs slowing down developer productivity; gotta find the right trade off/balance as usual.
Two things: 1) Bravo for realizing the difference between git and all the lock-in on top. 2) Thanks for liking my post. I actually already have the protocol fleshed out. If I can't get any traction though I'm gonna give it up...and this is after over a decade of work put into it! If you know anyone else who is aware of the internal structure of git and other DLT approaches and wants to produce the the thing that can eat git (and git ops), be sure to check out ibgib dot link or dot com. Pathetic I have to spam people in comments like this, but it's a very small niche that can even grok these things, let alone anyone with any vision.
Any reason why you don't just create a draft pr for the branch?
Creating a PR/MR relies on using GitHub, GitLab, Gitea or similar systems. Above solution works with plain git if I understand it correctly. However probably the notes become part of the git history which adds some noise not related to the source code.
Well, in my opinion, it is so wrong.
If you work on a task and you need to switch, commit with a WIP message.
If you go back to your card and don’t understand why you did it, it’s fine. But if it’s not clear completely at all in 20-30 minutes, I think something wrong with your codebase, consider refactoring etc, or your task is not clear defined, ambiguous or looks mostly as an epic. I’ve been working as a software developer for 9 years on different projects, but I have never faced the same issue
The repository lack information about license in README.md file, and does not include LICENSE or COPYING file with the text of the license. Could you please add it? Thanks in advance.
Consider using TODO lists. They are easy to maintain and all IDEs have tool to work with them.
Rule of thumb:
Plan your work with todo
Keep your todo only in branches. Main branch must not has todos