Re: [PATCH 1/8] Documentation/notes: document format of notes trees

[Jeff King <peff@peff.net>]

On Sat, May 08, 2010 at 10:19:35PM -0500, Jonathan Nieder wrote:

> How well does ‘git notes’ handle notes trees without a commit
> currently?  I remembered some rumor about a commitless mode in which
> the only history is the reflog, but I am not sure how much of that is
> implemented yet and I did not check.
> 
> If it was only groundless rumor (read: I made it up), then the last
> paragraph of the discussion should be removed.

My original textconv caching implementation used commitless notes. The
new version uses commits, but keeps the history truncated. As far as I
know, you can manipulate the latter with git-notes, but I haven't tried
much (adding a new note should make a history graph with length 2, which
will then get re-truncated the next time we add something to the cache
automatically). But certainly "list", "show", and "prune" should work,
which are the ones I would expect to be useful for such a cache.

> +It is also permitted for a notes ref to point directly to a tree
> +object, in which case the history of the notes can be read with
> +`git log -p -g <refname>`.

You would also use this to see the history of cache notes. They have
commits, but the only ancestry is in the reflog. So perhaps:

  Some notes refs may be "history-less", either because they point
  directly to a tree instead of a commit, or because their commits are
  truncated (the notes generated by textconv caching are an example of
  the latter). To see the local history of these refs, view the reflog
  with `git log -g <refname>`.

-Peff