notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

[Giuseppe Bilotta]

On Fri, Feb 5, 2010 at 11:36 AM, Johan Herland <johan@herland.net> wrote:
>
> 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):
>
>
> - Suggestion by Matthieu Moy and Sverre Rabbelier:
>  Add notes support to git-format-patch, where note contents in
>  refs/notes/format-patch are added to the "comments section"
>  (i.e. following the '---' separator) of generated patches.
>
> - Better integration with rebase/amend/cherry-pick. Optionally bring
>  notes across a commit rewrite. Controlled by command-line options
>  and/or config variables. Add "git notes move" and "git notes copy"
>  to suit. Junio says:
>    I used to fix minor issues (styles, decl-after-stmt, etc.) using
>    rebase-i long after running "am" in bulk, but these days I find
>    myself going back to my "inbox" and fix them in MUA; this is
>    only because I know these notes do not propagate across rebases
>    and amends -- adjusting the workflow to the tool's limitation is
>    not very good.

It might be useful to this purpose to have a notes.<refname>.* config
space, like for branches. This would allows us to define per-namespace
attribute for notes, such as whether or not they get across rebases,
whether or not (and how) they are output in format-patch, in logs, etc

> - Junio says:
>  The interface to tell tools to use which notes ref to use should be
>  able to say "these refs", not just "this ref" i.e. GIT_NOTES_REF=a:b
>  just like PATH=a:b:c...); I am fairly certain that we would want to
>  store different kind of information in separate notes trees and
>  aggregate them, as we gain experience with notes.

I would say that this only makes sense when reading notes, since when
you are writing a note you probably want to add it to a single
specific namespace.

For multiple refs I was thinking about shell expansion patterns, with
syntax such as {a,b} rather than a:b; even shell globs might make
sense (so e.g. * would mean 'all existing notes ref namespaces', bug*
all namespaces starting with bug, etc).

Of course the use of multiple namespaces also means that users
(whether human or script) need to be able to teel which namespace each
note comes from.

> - Junio says:
>  There should be an interface to tell tools to use which notes refs via
>  command line options; "!alias" does not TAB-complete, and "git lgm"
>  above doesn't, either. "git log --notes=notes/amlog --notes=notes/other"
>  would probably be the way to go.

As mentioned elsewhere in this thread, this might be better as a git
option rather than a subcommand option: git --notes-ref=amlog:other
log or git --notes-ref={amlog,other} log.

If I may be allowed to add a suggestion to put in the list, I would
like to see notes attachable to named refs (branch heads in
particular). From a cursory reading of your patches currently in pu it
would seem that you explicitly prohibit this case currently. However,
this has many possible uses, ranging from longer branch descriptions
to tracking information to improve survival in case of remote rebases.

And one last comment: how do notes behave wrt to cloning and remote
handling? Am I correct in my understanding that notes are (presently)
local only? Would it make sense to have them cloned to something like
the refs/notes/remotes/* namespace?





-- 
Giuseppe "Oblomov" Bilotta

Re: notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

[Johan Herland]

On Friday 05 February 2010, Giuseppe Bilotta wrote:
> On Fri, Feb 5, 2010 at 11:36 AM, Johan Herland wrote:
> > - Better integration with rebase/amend/cherry-pick. Optionally
> > bring notes across a commit rewrite. Controlled by command-line
> > options and/or config variables. Add "git notes move" and "git
> > notes copy" to suit. Junio says:
> >    I used to fix minor issues (styles, decl-after-stmt, etc.) using
> >    rebase-i long after running "am" in bulk, but these days I find
> >    myself going back to my "inbox" and fix them in MUA; this is
> >    only because I know these notes do not propagate across rebases
> >    and amends -- adjusting the workflow to the tool's limitation is
> >    not very good.
>
> It might be useful to this purpose to have a notes.<refname>.* config
> space, like for branches. This would allows us to define
> per-namespace attribute for notes, such as whether or not they get
> across rebases, whether or not (and how) they are output in
> format-patch, in logs, etc

Yes, that is a possibility, but first we need the infrastructure itself 
for doing this.

> > - Junio says:
> >  The interface to tell tools to use which notes ref to use should
> > be able to say "these refs", not just "this ref" i.e.
> > GIT_NOTES_REF=a:b just like PATH=a:b:c...); I am fairly certain
> > that we would want to store different kind of information in
> > separate notes trees and aggregate them, as we gain experience with
> > notes.
>
> I would say that this only makes sense when reading notes, since when
> you are writing a note you probably want to add it to a single
> specific namespace.

Of course.

> > - Junio says:
> >  There should be an interface to tell tools to use which notes refs
> > via command line options; "!alias" does not TAB-complete, and "git
> > lgm" above doesn't, either. "git log --notes=notes/amlog
> > --notes=notes/other" would probably be the way to go.
>
> As mentioned elsewhere in this thread, this might be better as a git
> option rather than a subcommand option: git --notes-ref=amlog:other
> log or git --notes-ref={amlog,other} log.

Maybe. Making it a git option makes it (GIT_NOTES_REF/--notes-ref) 
consistent with things like GIT_WORK_TREE/--work-tree and 
GIT_DIR/--git-dir, but then I'm not sure whether notes will affect the 
behaviour of enough commands to warrant it becoming a git option.

Consider for example the -m/--message subcommand option which can be 
applied to several subcommands (commit, tag, notes, etc.), but that 
does not make it a candidate for "promotion" to a git option (i.e. 
git -m "foo" commit).

> If I may be allowed to add a suggestion to put in the list, I would
> like to see notes attachable to named refs (branch heads in
> particular). From a cursory reading of your patches currently in pu
> it would seem that you explicitly prohibit this case currently.
> However, this has many possible uses, ranging from longer branch
> descriptions to tracking information to improve survival in case of
> remote rebases.

Nope. There is no explicit prohibition on anything. On a fundamental 
level, Git-notes simply maps a given SHA1 (the annotated object) to 
another SHA1 (the object holding the annotation itself). In principle 
you can annotate _any_ SHA1, it doesn't even have to exist as a git 
object!

In fact, something like the following abomination should solve 
your "problem" quite easily:

  git notes add $(echo "refs/heads/master" | git hash-object --stdin)

(...washing my hands...)

> And one last comment: how do notes behave wrt to cloning and remote
> handling? Am I correct in my understanding that notes are (presently)
> local only? Would it make sense to have them cloned to something like
> the refs/notes/remotes/* namespace?

They are no more local than any other ref, except that they are outside 
the refspecs that are "usually" pushed/fetched (refs/heads/ and 
refs/tags/).

	git push <remote> refs/notes/<foo>
	git fetch <remote> refs/notes/<foo>[:refs/notes/<foo>]
	etc.

should all work as expected.


...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

[Jakub Narebski]

On Fri, 5 Feb 2010, Johan Herland wrote:
> On Friday 05 February 2010, Giuseppe Bilotta wrote:

> > If I may be allowed to add a suggestion to put in the list, I would
> > like to see notes attachable to named refs (branch heads in
> > particular). From a cursory reading of your patches currently in pu
> > it would seem that you explicitly prohibit this case currently.
> > However, this has many possible uses, ranging from longer branch
> > descriptions to tracking information to improve survival in case of
> > remote rebases.
> 
> Nope. There is no explicit prohibition on anything. On a fundamental 
> level, Git-notes simply maps a given SHA1 (the annotated object) to 
> another SHA1 (the object holding the annotation itself). In principle 
> you can annotate _any_ SHA1, it doesn't even have to exist as a git 
> object!

I guess that it isn't currently possible to map _path_ (here: fully 
qualified name of ref, i.e. "refs/heads/master" in example) to SHA1
rather than SHA1 to SHA1, as fan-outs assumes mapping of SHA1 (to 
object).

> 
> In fact, something like the following abomination should solve 
> your "problem" quite easily:
> 
>   git notes add $(echo "refs/heads/master" | git hash-object --stdin)
> 
> (...washing my hands...)

This actually annotates (existing or not) _blob_ object with 
"refs/heads/master" as contents (git-hash-object defaults to -t blob).

> 
> > And one last comment: how do notes behave wrt to cloning and remote
> > handling? Am I correct in my understanding that notes are
> > (presently) local only? Would it make sense to have them cloned to
> > something like the refs/notes/remotes/* namespace?
> 
> They are no more local than any other ref, except that they are
> outside the refspecs that are "usually" pushed/fetched (refs/heads/
> and refs/tags/).
> 
> 	git push <remote> refs/notes/<foo>
> 	git fetch <remote> refs/notes/<foo>[:refs/notes/<foo>]
> 	etc.
> 
> should all work as expected.

It would be nice, but I guess not possible, to have notes autofollowed 
on fetch, like tags are autofollowed...

-- 
Jakub Narebski
Poland

Re: notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

[Giuseppe Bilotta]

On Fri, Feb 5, 2010 at 4:27 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> On Fri, 5 Feb 2010, Johan Herland wrote:
>> On Friday 05 February 2010, Giuseppe Bilotta wrote:
>
>> > If I may be allowed to add a suggestion to put in the list, I would
>> > like to see notes attachable to named refs (branch heads in
>> > particular). From a cursory reading of your patches currently in pu
>> > it would seem that you explicitly prohibit this case currently.
>> > However, this has many possible uses, ranging from longer branch
>> > descriptions to tracking information to improve survival in case of
>> > remote rebases.
>>
>> Nope. There is no explicit prohibition on anything. On a fundamental
>> level, Git-notes simply maps a given SHA1 (the annotated object) to
>> another SHA1 (the object holding the annotation itself). In principle
>> you can annotate _any_ SHA1, it doesn't even have to exist as a git
>> object!
>
> I guess that it isn't currently possible to map _path_ (here: fully
> qualified name of ref, i.e. "refs/heads/master" in example) to SHA1
> rather than SHA1 to SHA1, as fan-outs assumes mapping of SHA1 (to
> object).
>
>>
>> In fact, something like the following abomination should solve
>> your "problem" quite easily:
>>
>>   git notes add $(echo "refs/heads/master" | git hash-object --stdin)
>>
>> (...washing my hands...)
>
> This actually annotates (existing or not) _blob_ object with
> "refs/heads/master" as contents (git-hash-object defaults to -t blob).

Well, it still might work assuming the git tools know that they have
to look for these notes too when looking notes up. If we tolerate the
funky failure in the unlikely case of a file whose content matches a
ref name, it could be used to implement the feature without having to
remove the assumption that notes pretargets are SHA1. I do believe
that removing that assumption would be a smoother way to go, although
I have no idea how hard it would be to implement.

>> > And one last comment: how do notes behave wrt to cloning and remote
>> > handling? Am I correct in my understanding that notes are
>> > (presently) local only? Would it make sense to have them cloned to
>> > something like the refs/notes/remotes/* namespace?
>>
>> They are no more local than any other ref, except that they are
>> outside the refspecs that are "usually" pushed/fetched (refs/heads/
>> and refs/tags/).
>>
>>       git push <remote> refs/notes/<foo>
>>       git fetch <remote> refs/notes/<foo>[:refs/notes/<foo>]
>>       etc.
>>
>> should all work as expected.
>
> It would be nice, but I guess not possible, to have notes autofollowed
> on fetch, like tags are autofollowed...

Tags have the idiosincracy of living in the same namespace regardless
of where they come from, and I believe there a little too high a risk
of conflicts to do this with notes too. It might make sense to add a
default fetch of +refs/notes/*:refs/notes/remotes/<remote>/*, but the
real question is what would pushing do, in case of conflicting notes.

-- 
Giuseppe "Oblomov" Bilotta

Re: notes TODOs (was: Re: [PATCH 1/4] gitweb: notes feature)

[Jakub Narebski]

Giuseppe Bilotta <giuseppe.bilotta@gmail.com> writes:

> If I may be allowed to add a suggestion to put in the list, [...]

What I would like to see (besides --notes-ref or --notes option,
either as an option to git wrapper, or as an option to git-show,
git-format-patch, git-log and git-rev-list (I think that's all)),
is for git-notes to have a subcommand to move notes from one object
to the other:

  'git notes' move [-f] <oldobject> <newobject>

Both source and target should be required, as I am not sure if more
common would be moving note from some object to HEAD, or from HEAD to
some object.  The '-f'/'--force' option is in the case when note for
<newobject> exists (although it might be better to concatenate notes
in the future), and when <oldobject> and <newobject> are of different
types (unless we want som DWIM type coercion).

It could be used to make notes move to amended commit, for example:

  $ git commit --amend
  $ git notes move ORIG_HEAD HEAD # or HEAD@{1} HEAD

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: notes TODOs

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

>   'git notes' move [-f] <oldobject> <newobject>

I suspect "copy" to keep the old one than "move" would be a lot more
sensible, especially when you are talking about people (like me) who amend
often.  They cannot get it right in their first try by definition ;-), and
their very original edition is sometimes easier to start from than their
second edition, when they are trying to come up with the final edition of
the commit.  Using "move" to lose the notes from the old object will make
it harder to go back to the original and start amending from there.

Re: notes TODOs

[Jakub Narebski]

On Sat, 6 Feb 2010, Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> >   'git notes' move [-f] <oldobject> <newobject>
> 
> I suspect "copy" to keep the old one than "move" would be a lot more
> sensible, especially when you are talking about people (like me) who amend
> often.  They cannot get it right in their first try by definition ;-), and
> their very original edition is sometimes easier to start from than their
> second edition, when they are trying to come up with the final edition of
> the commit.  Using "move" to lose the notes from the old object will make
> it harder to go back to the original and start amending from there.

True.  It would be better then to have "git notes copy ...", and perhaps
even a configuration option to have --amend copy notes to new version
automatically.

You can always get note before move with

  GIT_NOTES_REF=refs/notes/commit^ <git command>

(assuming that you use default notes ref).  But that would work for
"git show", but not for "git log --walk-reflogs".


P.S. I have tried to use 'git notes edit v1.6.6.1', and while it annotates
a tag object, the message in editor make it look like you are annotating
the commit it points to.

-- 
Jakub Narebski
Poland