Git Notes: Git's coolest, most unloved­ feature (2022)

Original Article ↗ Hacker News Discussion ↗

Awareness and Forge Support

  • Many long-time Git users say they’d never heard of git-notes before.
  • Lack of UI in major forges is seen as the main reason: if GitHub/GitLab surfaced notes, usage would jump.
  • GitHub once displayed notes but removed support; motives discussed include reducing ease of migration and lock‑in.
  • GitLab feature requests for notes support have been closed as “not a focus”.
  • Forgejo/Codeberg recently added notes support, held up as an example that alternative forges can differentiate here.
  • Chicken‑and‑egg dynamic: providers don’t support notes because users don’t use them; users don’t use them because providers don’t support them.

Commit Messages vs Notes vs Trailers

  • Debate over when to use notes versus just writing richer commit messages.
  • Arguments for commit messages:
    • Always replicated; no extra setup.
    • Unlimited length; standard tooling (blame, log) already built around them.
  • Arguments for notes:
    • Don’t change commit hashes; can be added later without rewriting history.
    • Good for “forward‑in‑time” info (e.g., “this introduced bug #123”, incident links, test status).
  • Git trailers highlighted as a structured alternative embedded in commit messages (e.g., Change-Id, skip‑CI, ticket numbers).

History Rewriting and Technical Pitfalls

  • Many questions about how notes behave under amend/rebase/squash.
  • Notes can be propagated during rewrites, but only with non‑obvious notes.rewrite* configuration; defaults are confusing.
  • Some reports of bugs (e.g., amend within rebase losing notes).
  • This ties into a larger, heated debate over rebasing vs merge commits, “history destruction”, and Git’s poor support for mapping rewritten commits to their originals.

Real‑World Use Cases

  • Internal code review metadata (tickets, infra constraints, incident threads) kept in notes instead of PRs or long messages.
  • Marking which commits have been tested, or linking pipeline output hashes to source commits.
  • LibreOffice/AOO used notes to track cherry‑pick status from a mirrored repo.
  • Email‑based workflows use notes to attach non‑commit‑message commentary to patches (research notes, version changes).

Skepticism and Organizational Fit

  • Some consider notes a gimmick: most teams already rely on external trackers (Jira, etc.) and PR UIs, especially for non‑developers.
  • Others argue notes are valuable “developer‑only” metadata and a step toward decentralized, offline review/intent preservation.

Alternatives, Adjacent Features, and Future Ideas

  • References to Fossil, Mercurial + Heptapod, Gerrit (Change-Id), stacked diffs, and tools like Jujutsu / git-branchless as better at tracking mutable changes.
  • Mentions of other “hidden” Git features: pickaxe (git log -S/-G), bisect, reflog, range-diff, etc.
  • Several people suggest using notes (or trailers) as a place to store LLM prompts, reasoning traces, or AI‑generated‑code markers.