Re: [PATCH 1/4] gitweb: notes feature

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 5, 2010, 16:10 UTC
Message-ID: <7veikzfysv.fsf@alter.siamese.dyndns.org>
In-Reply-To: <201002051136.43738.johan@herland.net>

Johan Herland <johan@herland.net> writes:

> I already maintain a TODO list at the end of the cover letter to the notes 
> series. Here is a preview of it (I plan to send the next iteration of 
> jh/notes as soon as v1.7.0 is released):
> ...

Random additional thoughts.

* Futureproofing

We have to admit that our notes support, especially on the output side, is still in its infancy. We may want to advertise it as such -- highly experimental and subject to change.

* format-patch

To add notes to format-patch output, we might want to do something like:

    $ git format-patch --notes-ref=commits --notes-ref=amlog -1

and produce:

    From 8bff7c5383ed833bd1df9c8d85c00a27af3e5b02 Mon Sep 17 00:00:00 2001
    From: Andrew Myrick <amyrick@apple.com>
    Date: Sat, 30 Jan 2010 03:14:22 +0000
    Subject: [PATCH] git-svn: persistent memoization
    X-Notes: pulled on Fri Feb 5 07:36:12 2010 -0800
     from git://git.bogomips.org/git-svn.git/
    X-Notes-amlog: <1264821262-28322-1-git-send-email-amyrick@apple.com>

    Make memoization of the svn:mergeinfo processing functions persistent with
    ...

Points to notice:

 - There is no point forcing users to spell "--notes-ref" parameter
   starting from refs/notes/; we should DWIM if they are missing;

 - We would want to allow more than one notes hierarchy specified. This
   would affect format_note() function---take list of struct notes_tree,
   perhaps;

 - Allow callers of tell format_note() to add the name of the notes
   hierarchy the note came from (or just always add it if it is not the
   default "refs/notes/commits").

 - For format-patch that produces a mbox output, the email header part may
   be a better place to put notes (obeying the usual "indent by one space
   to continue the line" convention).

* "log --format=%N" and "log --show-notes"

Currently %N expands to the hardcoded "log --show-notes" default format. We can probably keep it that way. When the user asked for a non default notes hierarchy (i.e. other than refs/notes/commits), we may want to adjust "Notes:" string to use "Notes-%s:" to show which hierarchy it came from, and concatenate them together.

For "log --show-notes" output, we also might want to move the notes to the header part like I illustrated above in format-patch output, instead of "start with unindented Notes: and indented body at the end". I.e. instead of showing this:

    $ git log --notes-ref=amlog -1 4d0cc22
    commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
    Author: Junio C Hamano <gitster@pobox.com>
    Date:   Thu Feb 4 11:10:44 2010 -0800

        fast-import: count --max-pack-size in bytes

        Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
        ...
        Acked-by: Nicolas Pitre <nico@fluxnic.net>

    Notes:
        <7v4olwbyvf.fsf_-_@alter.siamese.dyndns.org>

show it like this:

    $ git log --notes-ref=amlog -1 4d0cc22
    commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
    Author: Junio C Hamano <gitster@pobox.com>
    Date:   Thu Feb 4 11:10:44 2010 -0800
    Notes-amlog: <7v4olwbyvf.fsf_-_@alter.siamese.dyndns.org>

        fast-import: count --max-pack-size in bytes

        Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
        ...
        Acked-by: Nicolas Pitre <nico@fluxnic.net>