Git Branch Notes

Read this in other languages: Chinese.

Welcome to Git Branch Notes! A CLI tool for managing Git branch notes, stored in a dedicated git ref so they can be shared across your team without polluting feature branches and without merge conflicts.

npm package location

Installation

npm install -g git-branch-notes

How notes are stored (v2)

Branch notes live in a dedicated git ref refs/notes/branch-notes, used as a key-value store keyed by branch name (not commit SHA). Each branch's note is an independent entry inside that ref's tree.

This means:

• No pollution of feature branches. Notes never appear in your feature branch history, never get committed to main/feature-x, and never cause conflicts with business code.
• Survives branch updates. Notes are keyed by branch name, so when a branch gets new commits, its note stays. It does not drift off to an old commit.
• Team-shared via git. Sync with git-bn sync — git natively fetches/pushes the notes ref.
• Conflict-free for different branches. Since each branch is a separate entry in the tree, two teammates editing different branches' notes merge cleanly. Same-branch edits are auto-resolved by timestamp (newer wins).
• No pollution from cherry-pick / rebase. Notes are tied to branch names, not commit SHAs, so cherry-picking or rebasing commits never carries notes to other branches.

How to use

Set note for a branch

git-bn set "Working on new feature"            # current branch
git-bn set -b feature-branch "Working on new feature"

Get note for a branch

git-bn get                # current branch
git-bn get main

List branches with notes

git-bn list                # branches that have notes
git-bn list -a             # all branches (incl. without notes)
git-bn list -r             # remote branches only
git-bn list -l             # local branches only

View notes mapping

git-bn mapping

Sync notes with your team

git-bn sync                # pull + merge + push the notes ref (recommended)
git-bn pull                # pull & merge only
git-bn push                # push only

sync does a structured 3-way merge keyed by branch name. Different-branch edits never conflict; same-branch edits are resolved by the newer timestamp and reported.

Clean up notes for deleted branches

git-bn prune --dry-run     # preview
git-bn prune               # remove notes for branches that no longer exist

Migrate from v1 (branch-notes.json)

git-bn migrate             # imports notes from legacy branch-notes.json into the notes ref
git-bn migrate -f path/to/branch-notes.json

Typical team workflow

# Alice, on feature-A
git-bn set "implementing login"
git-bn sync

# Bob, on feature-B, at the same time
git-bn set "implementing payments"
git-bn sync                # auto-merges with Alice's notes, no conflict

Features

• 📝 Add notes to Git branches
• 🗂️ Stored in refs/notes/branch-notes (keyed by branch name)
• 🚫 No pollution of feature branches; no conflicts with business code
• 🔄 Team-shared via git fetch/push of the notes ref
• 🤝 Conflict-free concurrent edits to different branches
• ⏱️ Timestamp + author tracking per note

Example