Re: [PATCHv12 00/23] git notes

On Thursday 28 January 2010, Junio C Hamano wrote:

The earlier frustration of mine was about adding a note, not adding _to_
 a note.  The semantic difference I described with add/edit was "adding
 anew" vs "modify".

Once I realize that Dscho's original "edit" lacks an explicit "adding
anew" and it simply means "replace if exists otherwise add", then I can
agree the argument that "adding anew" mode is not necessary.

The semantic difference your add/edit try to capture works at a different
level.  They are "append to it" vs "replace it".  Current "edit -m 'foo'"
that replaces feels to me quite counterintuitive.

If two modes are useful, then I would suggest to deprecate the use of
"edit" subcommand with -m/-F (because its name doesn't tell the user
 which one between "append" and "replace" it happens to implement) and
 instead introduce two more explicit subcommands, "append" and "replace".
  For the same reason, "add" would cause confusion between "is this to
 add a new note" vs "is this to add _to_ a new note", and I'd recommend
 against it.

"edit" could still open an editor to "modify" existing one (and if there
is no existing one, then the editor starts empty).

On the other hand, if "replace" is not very useful, then it might be
enough to just introduce a new "append" subcommand.  Or course, we could
redefine the useless "replace" semantics from "edit -m/-F" and change it
to always append.

Ok, I see your point, and I largely agree with your analysis. I'll attempt 
to summarize what we want from "git notes" in this regard:

- git notes add: Add a new note. Open editor for giving the note contents.
  Barf if a note already exists for the given object.

	Options:
	-m <msg>, --message <msg>: Specify note contents on command-line instead
		of opening editor. (Multiple -m options are concatenated.)

	-F <file>, --file <file>: Get note contents from the given file instead
		of opening editor.

	-f, --force: Instead of barfing, replace/overwrite existing notes.

- git notes append: Append to an existing note; create new note if needed.
  Open editor for giving the (additional) note contents.

	Options:
	-m <msg>, --message <msg>: (Same as above)
	-F <file>, --file <file>: (Same as above)

- git notes edit: Edit an existing note. Create new note if needed (?)
  Open editor for editing the existing note contents.

	No options (deprecate existing -m and -F options)

Is this what you had in mind? AFAICS it should cover all interesting use 
cases.


...Johan

-- 
Johan Herland, [off-list ref]
www.herland.net