git notes and git bundle

git notes overview

git notes allows you to attach metadata to commits without modifying the commit itself. Notes are stored separately in the .git/notes/ directory and are not part of the commit hash. This means you can add, modify, or remove notes without rewriting history. Notes are useful for attaching review comments, test results, build metadata, or any other information that does not belong in the commit message.

Unlike commit messages which are immutable and shared with every clone, notes are opt-in. You must explicitly push and pull notes with git push origin refs/notes/* and git fetch origin refs/notes/*. This makes notes a flexible layer of metadata that can be shared or kept local as needed.

Adding and viewing notes

git notes add attaches a note to a commit. By default, it attaches to HEAD. You can specify a commit reference to attach to a specific commit. git notes show displays the note for a given commit. Notes can be added, replaced, or appended to existing notes.

# Add a note to the current HEAD commit
git notes add -m 'Reviewed and approved by Alice'

# Add a note to a specific commit
git notes add -m 'Test passed on CI' a1b2c3d

# View a note
git notes show HEAD
# Output: Reviewed and approved by Alice

# View note for a specific commit
git notes show a1b2c3d

# List all commits with notes
git notes list

Copying and appending notes

git notes copy duplicates a note from one commit to another. git notes append adds text to an existing note without replacing it. This is useful for building up a review trail where multiple reviewers add their feedback to the same commit.

# Copy a note from one commit to another
git notes copy HEAD a1b2c3d

# Append to an existing note
git notes append -m 'Additional feedback: looks good'

# Append multiline notes
git notes append -m 'Review 1: Approved
Review 2: Minor changes suggested'

# Remove a note
git notes remove HEAD

# Edit a note interactively
git notes edit

Namespaced notes with --ref

The --ref flag lets you create separate namespaces for notes. This is useful for storing different types of metadata in isolated namespaces. For example, you could have one namespace for code reviews, another for test results, and another for build information. Each namespace is stored in its own ref under refs/notes/.

# Add a code review note
git notes add --ref=review -m 'LGTM' HEAD

# Add a test results note
git notes add --ref=test -m 'All 42 tests passed' HEAD

# View specific namespace
git notes show --ref=review HEAD
git notes show --ref=test HEAD

# Push review notes
git push origin refs/notes/review

# Fetch all notes namespaces
git fetch origin 'refs/notes/*:refs/notes/*'

git bundle overview

git bundle packages a set of commits and their objects into a single file. This file can be transferred via email, USB drive, or any file transfer mechanism without requiring a Git server. The recipient can unpack the bundle to reconstruct the commits and history. Bundles are useful for air-gapped networks, large repositories with limited bandwidth, or one-time transfers.

# Create a bundle with all commits
git bundle create repo.bundle main

# Create a bundle with specific commits
git bundle create feature.bundle main..feature/login

# Create a bundle with a tag
git bundle create release.bundle v1.0

# Verify a bundle is valid
git bundle verify repo.bundle

# List contents of a bundle
git bundle unbundle repo.bundle

# Clone from a bundle
git clone repo.bundle extracted-repo

# Fetch from a bundle into an existing repo
git fetch repo.bundle main:main

# Check if a bundle has new commits
git bundle verify repo.bundle HEAD

Use cases for notes and bundles

Notes and bundles solve different problems but both extend Git beyond basic version control. Notes add a layer of metadata that travels with commits but is not part of the commit itself. Bundles enable Git workflows in environments where a server is not available or practical.

• Notes: attach code review comments to specific commits
• Notes: record CI/CD build results alongside commits
• Notes: store test coverage data per commit
• Notes: add deployment metadata without modifying commit messages
• Bundles: transfer code via email to air-gapped environments
• Bundles: ship large repositories on USB drives
• Bundles: create portable archives of feature branches
• Bundles: offline code review with full history