Johan Herland [off-list ref] writes:
On Wednesday 27 January 2010, Junio C Hamano wrote:
quoted
Johan Herland [off-list ref] writes:
quoted
- Patch #23 is a new patch adding the "git notes add" command for
appending contents to notes (instead of editing/replacing).
I find this even more confusing. Originally I was puzzled by the lack of
"git notes add"; it took me for quite until I managed to figure out that
"git notes edit" was the command to use, even if I wanted to add notes to
a commit that I know that does not have any.
Not sure what you're getting at here.
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.
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