Git Notes for Metadata and Progress Tracking

I recently started exploring Git Notes, a feature that allows you to attach extra information to Git commits without changing the commit itself.

I’ve been applying this in my private project, Klammer, a CLI tool for managing "stacked branches" on Azure DevOps. I also noticed that Google’s Gemini Conductor uses a similar approach for tracking implementation progress.

What are Git Notes?

In a standard workflow, if you want to change a commit message, you have to "amend" it, which changes the commit's SHA-1 hash. This can cause issues if you've already pushed the code.

Git Notes solve this by storing data in a separate reference (refs/notes/). This acts like a "sticky note" attached to a commit: the note can be edited or added later without ever touching the actual commit hash or history.

Real-World Applications

Managing Stacked Branches (Klammer)

In Klammer, which facilitates stacked branch workflows for Azure DevOps, metadata is required to track the relationships between different branches in a stack.

Instead of cluttering the commit message with technical metadata that reviewers don't need to see, I use Git Notes to store information about the "stack state." This keeps the history clean while allowing the CLI tool to know exactly where a commit fits within a sequence of pull requests.

Context-Driven Development (Gemini Conductor)

Google’s Gemini Conductor uses Git Notes to track implementation progress.

As the AI assists with development, it records the current state of a task directly onto the commit. Because these notes are non-destructive, the tool can update the "progress status" as the code evolves without triggering a chain reaction of rehashes across a branch.

Core Commands

Adding a note to the current commit:

git notes add -m "Stack Metadata: parent_branch=feature-1"

Viewing notes in the log:

git log

Pushing notes to a remote

By default, notes are not pushed. You must push them explicitly to share them with other developers or CI/CD tools:

git push origin "refs/notes/*"

Automatically fetching notes

To ensure you always see notes added by others or by automation tools, add this to your Git config:

git config --add remote.origin.fetch "+refs/notes/*:refs/notes/*"

Summary

Git Notes let you attach metadata to commits without rewriting history. I'm using them in Klammer to track stack relationships; Google's doing the same in Gemini Conductor for implementation progress. Same pattern: operational data on commits, no history rewrite. Recently discovered, never heard of it before.