---
title: "Git Notes for Metadata and Progress Tracking"
url: "https://www.dariuszparys.com/git-notes-for-metadata-and-progress-tracking"
author: "Dariusz Parys"
published: 2025-12-19T06:53:23.000Z
updated: 2025-12-19T06:53:23.000Z
description: "Git Notes let you store metadata on commits without changing SHA hashes. See how Klammer and Gemini Conductor use them for stacked branches and AI tracking."
tags:
  - "TIL"
---

# 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](https://developers.googleblog.com/conductor-introducing-context-driven-development-for-gemini-cli/) 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:

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

Viewing notes in the log:

```bash
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:

```bash
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:

```bash
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.