Re: [RFC/PATCH] Make "git notes add" more user-friendly when there are existing notes

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Mar 30, 2011, 06:54 UTC
Message-ID: <4D92D399.4090404@drmicha.warpmail.net>
In-Reply-To: <201103300202.55973.johan@herland.net>

Johan Herland venit, vidit, dixit 30.03.2011 02:02:

Show 26 quoted lines

> Currently, "notes add" (without -f/--force) will abort when the given object
> already has existing notes. This makes sense for the modes of "git notes add"
> that would necessarily overwrite the old message (when using the -m/-F/-C/-c
> options). However, when no options are given (meaning the notes are created
> from scratch in the editor) it is not very user-friendly to abort on existing
> notes, and forcing the user to run "git notes edit".
> 
> Instead, it is better to simply "redirect" to "git notes edit" automatically,
> i.e. open the existing notes in the editor and let the user edit them.
> This patch does just that.
> 
> This changes the behavior of "git notes add" without options when notes
> already exist for the given object, but I doubt that many users really depend
> on the previous failure from "git notes add" in this case.
> 
> Signed-off-by: Johan Herland <johan@herland.net>
> ---
> 
> On Tuesday 29 March 2011, Junio C Hamano wrote:
>> Michael J Gruber <drmicha@warpmail.net> writes:
>>> and while at it rename "add" to "edit"
>> That one I think is older wart that may be harder to change.
> 
> Here's one attempt at giving Michael a nicer "git notes add" without
> breaking too many existing users. It's not very pretty, but I hope it
> gets the job done without inconveniencing current users too much.

That is certainly an improvement, though I'm still wondering how large a change we're aiming at, given Junio's remarks. Things I would like to throw in:

* options vs. arguments:

"tag", "branch" etc. use options for subcommands, e.g. "tag -d", "branch -d" etc. "remote", "stash" use arguments, e.g. "remote add", "stash list". I don't see us unifying that, but we should decide about a direction to go for "new" commands and stick to that. I feel that options are the way to go. What I really feel strongly about is that we should decide once and then stick to that for future commands (and may be gradually revamping).

* singular vs. plural:

All our porcelain commands are singular even when they deal with multiple items (tag, branch, remote, submodule, ...). "notes" is the only exception, why not have it be "note"? (That would also open up a migration strategy, though the usual suspects may not even bother ;))

* "notes message":

The term seems to be used to distinguish between the content of a note and the note object (blob content vs. blob object). A regular git user may think it is the commit message in the notes log, i.e.:

git log $(git notes get-ref)

I'm wondering whether we should actually expose those note commit messages. If notes are shared then editing a note may require an explanation just like other commits do, especially when they get used for other things than "notes" in the proper sense.

If we do that, then -m,-c,-C etc. would need to be analogous to "git commit -m,-c,-C", i.e. about note commit messages, not about the actual note. If we completely discard the possibility that users will look at the notes log and write note commit messages, we can use the "regular commit message <-> notes content" analogy for the options that we partially have now (and adjust -c,-C).

Cheers, Michael