Git Basics: Attach Local Review Notes Without Rewriting a Commit

A local annotation can record review context while preserving the annotated commit ID. Git notes store that extra text under a separate ref.

Prepare a scratch directory

Tested on Linux with Git 2.52.0 and GNU Bash 5.2.37. You need Bash, a text editor, the named runtime, and standard mktemp, rm, and rmdir utilities. The examples use only controlled local data; generated fixture directories are cleaned automatically.

Keep the same terminal open. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-notes.sh:

#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
fixture_dir="$(mktemp -d)"
trap 'rm -rf -- "$fixture_dir"' EXIT
export GIT_CONFIG_NOSYSTEM=1
export GIT_CONFIG_GLOBAL=/dev/null
export GIT_AUTHOR_NAME='Example Author'
export GIT_AUTHOR_EMAIL='author@example.invalid'
export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
export GIT_AUTHOR_DATE='2026-10-28T00:00:00+00:00'
export GIT_COMMITTER_DATE="$GIT_AUTHOR_DATE"
git init -q -b main "$fixture_dir/repo"
cd -- "$fixture_dir/repo"
git config commit.gpgsign false
git config core.hooksPath /dev/null
git commit -qm 'Reviewed snapshot' --allow-empty
before="$(git rev-parse HEAD)"
git notes --ref=review add -m 'Local smoke test passed.' HEAD
printf 'Attached note:\n'
git notes --ref=review show HEAD
test "$before" = "$(git rev-parse HEAD)"
printf 'Annotated commit ID: unchanged\n'
printf 'Notes namespace:\n'
git for-each-ref --format='%(refname)' refs/notes/
printf 'Commit message:\n'
git log -1 --format=%s --no-notes

Run it:

bash demonstrate-notes.sh

Observed output:

Attached note:
Local smoke test passed.
Annotated commit ID: unchanged
Notes namespace:
refs/notes/review
Commit message:
Reviewed snapshot

Read the result

The review shorthand selects refs/notes/review. Adding a note creates notes history separately from the original commit. The equality check proves HEAD did not move, and the final command still prints the original commit message.

Apply it carefully

Notes are not automatically shared by an ordinary branch push or fetched by every clone configuration. Agree on an explicit notes-ref transfer policy if a team depends on them. A note is editable context, not an authenticated approval or an enforcement gate. Run this script from an ordinary shell with no repository-selection variables such as GIT_DIR or GIT_WORK_TREE set. All commits and cleanup stay inside the newly created temporary fixture.

The official reference describes the behavior and options. These checks cover the fixture above rather than every input or platform.

Clean up

Remove the saved source, return to the starting directory, then remove the empty practice directory:

rm -- demonstrate-notes.sh
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect its remaining contents rather than deleting unknown files.

Acknowledgements

This post was created with assistance from AI.