{"thread":{"id":"26905","subject":"[PATCH] git-notes.txt: clarify -C vs. copy and -F","startedAt":"2011-03-29T08:45:03Z","lastAt":"2011-08-25T18:50:42Z","messageCount":15,"participants":["Michael J Gruber","Johan Herland","Junio C Hamano","Lasse Makholm"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"164550","messageId":"09668994f10284cfa5243789a627dce8c2325bc6.1301388217.git.git@drmicha.warpmail.net","threadId":"26905","inReplyTo":null,"subject":"[PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-03-29T08:45:03Z","receivedAt":"2011-03-29T08:45:03Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"The current description of '-C' together with the analogy to 'git commit\n-C' can lead to the wrong conclusion that '-C' copies notes between\nobjects. Make this clearer by rewording and pointing to 'copy'.\n\nThe example for attaching binary notes with 'git hash-object' followed\nby 'git notes add -C' immediately raises the question: \"Why not use 'git\nnotes add -F'?\". Answer it (the latter is not binary-safe).\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nIn fact, the long name '--reuse-message' is really misleading, but I've been\naround long enough to refrain from trying to change it ;)\n\n Documentation/git-notes.txt |    7 +++++--\n 1 files changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 296f314..c63b593 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -138,8 +138,9 @@ OPTIONS\n \n -C <object>::\n --reuse-message=<object>::\n-\tTake the note message from the given blob object (for\n-\texample, another note).\n+\tTake the given blob object (for\texample, another note) as the\n+\tnote message. (Use `git notes copy <object>` instead to\n+\tcopy notes between objects.) \n \n -c <object>::\n --reedit-message=<object>::\n@@ -272,6 +273,8 @@ $ blob=$(git hash-object -w a.out)\n $ git notes --ref=built add -C \"$blob\" HEAD\n ------------\n \n+(You cannot simply use `git notes --ref=built add -F a.out HEAD`\n+because that is not binary-safe.)\n Of course, it doesn't make much sense to display non-text-format notes\n with 'git log', so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n-- \n1.7.4.1.607.g888da\n"},{"id":"164553","messageId":"201103291136.42830.johan@herland.net","threadId":"26905","inReplyTo":"09668994f10284cfa5243789a627dce8c2325bc6.1301388217.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2011-03-29T09:36:42Z","receivedAt":"2011-03-29T09:36:42Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Tuesday 29 March 2011, Michael J Gruber wrote:\n> The current description of '-C' together with the analogy to 'git\n> commit -C' can lead to the wrong conclusion that '-C' copies notes\n> between objects. Make this clearer by rewording and pointing to\n> 'copy'.\n>\n> The example for attaching binary notes with 'git hash-object'\n> followed by 'git notes add -C' immediately raises the question: \"Why\n> not use 'git notes add -F'?\". Answer it (the latter is not\n> binary-safe).\n>\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n\nAcked-by: Johan Herland <johan@herland.net>\n\n\n...Johan\n\n-- \nJohan Herland, <johan@herland.net>\nwww.herland.net\n"},{"id":"164601","messageId":"7vbp0tss6t.fsf@alter.siamese.dyndns.org","threadId":"26905","inReplyTo":"09668994f10284cfa5243789a627dce8c2325bc6.1301388217.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-03-29T18:22:02Z","receivedAt":"2011-03-29T18:22:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> The current description of '-C' together with the analogy to 'git commit\n> -C' can lead to the wrong conclusion that '-C' copies notes between\n> objects. Make this clearer by rewording and pointing to 'copy'.\n>\n> The example for attaching binary notes with 'git hash-object' followed\n> by 'git notes add -C' immediately raises the question: \"Why not use 'git\n> notes add -F'?\". Answer it (the latter is not binary-safe).\n>\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n> In fact, the long name '--reuse-message' is really misleading, but I've been\n> around long enough to refrain from trying to change it ;)\n\nYeah, it utterly is broken.  Why not fix it before people start making\nserious use of notes?\n\n>  Documentation/git-notes.txt |    7 +++++--\n>  1 files changed, 5 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 296f314..c63b593 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -138,8 +138,9 @@ OPTIONS\n>  \n>  -C <object>::\n>  --reuse-message=<object>::\n> -\tTake the note message from the given blob object (for\n> -\texample, another note).\n> +\tTake the given blob object (for\texample, another note) as the\n> +\tnote message. (Use `git notes copy <object>` instead to\n> +\tcopy notes between objects.) \n>  \n>  -c <object>::\n>  --reedit-message=<object>::\n> @@ -272,6 +273,8 @@ $ blob=$(git hash-object -w a.out)\n>  $ git notes --ref=built add -C \"$blob\" HEAD\n>  ------------\n>  \n> +(You cannot simply use `git notes --ref=built add -F a.out HEAD`\n> +because that is not binary-safe.)\n>  Of course, it doesn't make much sense to display non-text-format notes\n>  with 'git log', so if you use such notes, you'll probably need to write\n>  some special-purpose tools to do something useful with them.\n"},{"id":"164603","messageId":"7v7hbhss0g.fsf@alter.siamese.dyndns.org","threadId":"26905","inReplyTo":"7vbp0tss6t.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-03-29T18:25:51Z","receivedAt":"2011-03-29T18:25:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Michael J Gruber <git@drmicha.warpmail.net> writes:\n>\n>> The current description of '-C' together with the analogy to 'git commit\n>> -C' can lead to the wrong conclusion that '-C' copies notes between\n>> objects. Make this clearer by rewording and pointing to 'copy'.\n>>\n>> The example for attaching binary notes with 'git hash-object' followed\n>> by 'git notes add -C' immediately raises the question: \"Why not use 'git\n>> notes add -F'?\". Answer it (the latter is not binary-safe).\n>>\n>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n>> ---\n>> In fact, the long name '--reuse-message' is really misleading, but I've been\n>> around long enough to refrain from trying to change it ;)\n>\n> Yeah, it utterly is broken.  Why not fix it before people start making\n> serious use of notes?\n\nActually I take it back and throw it again after doubling it.  Not just\nthe long name, but using -C/-c is already utterly broken.  These are meant\nto reuse (meta)data associated with an existing object, not using some\ndata that happens to be stored in a random loose blob.  I don't think of\nany similar option anywhere in git.\n\nInstead of mucking with the documentation, why not fix the behaviour to\nmatch what -C/-c/--reuse usually means, which is what the documentation\ndescribes?\n"},{"id":"164607","messageId":"4D9226B4.20806@warpmail.net","threadId":"26905","inReplyTo":"7v7hbhss0g.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Michael J Gruber","fromEmail":"drmicha@warpmail.net","sentAt":"2011-03-29T18:36:36Z","receivedAt":"2011-03-29T18:36:36Z","isPatch":true,"sender":{"key":"drmicha@warpmail.net","avatar":null},"body":"Junio C Hamano venit, vidit, dixit 29.03.2011 20:25:\n> Junio C Hamano <gitster@pobox.com> writes:\n> \n>> Michael J Gruber <git@drmicha.warpmail.net> writes:\n>>\n>>> The current description of '-C' together with the analogy to 'git commit\n>>> -C' can lead to the wrong conclusion that '-C' copies notes between\n>>> objects. Make this clearer by rewording and pointing to 'copy'.\n>>>\n>>> The example for attaching binary notes with 'git hash-object' followed\n>>> by 'git notes add -C' immediately raises the question: \"Why not use 'git\n>>> notes add -F'?\". Answer it (the latter is not binary-safe).\n>>>\n>>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n>>> ---\n>>> In fact, the long name '--reuse-message' is really misleading, but I've been\n>>> around long enough to refrain from trying to change it ;)\n>>\n>> Yeah, it utterly is broken.  Why not fix it before people start making\n>> serious use of notes?\n\nYou seriously ask why? Because I've banged my head way to often by\nsuggesting behavior changes!\n\n> \n> Actually I take it back and throw it again after doubling it.  Not just\n> the long name, but using -C/-c is already utterly broken.  These are meant\n> to reuse (meta)data associated with an existing object, not using some\n> data that happens to be stored in a random loose blob.  I don't think of\n> any similar option anywhere in git.\n> \n> Instead of mucking with the documentation, why not fix the behaviour to\n> match what -C/-c/--reuse usually means, which is what the documentation\n> describes?\n\nBecause it's not what the doc describes. The current version is easy to\nmisunderstand, but in connection with the example it is clear how it is\nmeant, and that's how it is implemented. If I were to reimplement it I\nwould:\n\n- make \"notes add -C/-c\" really analogous to \"commit -c/-C\", i.e. do\n\"notes copy\"\n\n- make -F binary safe\n\nand while at it rename \"add\" to \"edit\", because I've been bitten too\noften by trying to add to a note using the \"add\" command. But all these\nare behavior changes/incompatibilities, i.e. a no-go.\n\nI don't mean to criticize the initial implementation of \"notes\", it just\nshows that we detect rough ui edges only after using a feature. I'm all\nfor changes, I just rarely can get myself to making a hopeless feature\nchange patch any more.\n\nMichael\n"},{"id":"164613","messageId":"7vd3l9rbnq.fsf@alter.siamese.dyndns.org","threadId":"26905","inReplyTo":"4D9226B4.20806@warpmail.net","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-03-29T19:04:25Z","receivedAt":"2011-03-29T19:04:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <drmicha@warpmail.net> writes:\n\n>>> Yeah, it utterly is broken.  Why not fix it before people start making\n>>> serious use of notes?\n>\n> You seriously ask why? Because I've banged my head way to often by\n> suggesting behavior changes!\n\nChange of a behaviour that nobody had chance to have seriously used for\nonly 6 weeks or so?  I'd call that a fair game.\n\n> If I were to reimplement it I would:\n>\n> - make \"notes add -C/-c\" really analogous to \"commit -c/-C\", i.e. do\n> \"notes copy\"\n\nThat is sensible.\n\n> - make -F binary safe\n\nLikewise.\n\n> and while at it rename \"add\" to \"edit\"\n\nThat one I think is older wart that may be harder to change.\n"},{"id":"164618","messageId":"7v1v1pr97x.fsf@alter.siamese.dyndns.org","threadId":"26905","inReplyTo":"7vd3l9rbnq.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-03-29T19:57:06Z","receivedAt":"2011-03-29T19:57:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Michael J Gruber <drmicha@warpmail.net> writes:\n>\n>>>> Yeah, it utterly is broken.  Why not fix it before people start making\n>>>> serious use of notes?\n>>\n>> You seriously ask why? Because I've banged my head way to often by\n>> suggesting behavior changes!\n>\n> Change of a behaviour that nobody had chance to have seriously used for\n> only 6 weeks or so?  I'd call that a fair game.\n\nOops, sorry I misread the timestamp.  It has been one year and 6 weeks.\nHmm, but still -C/-c is wrong.\n\nI am very strongly tempted to fix the semantics, though.\n"},{"id":"164644","messageId":"201103300202.55973.johan@herland.net","threadId":"26905","inReplyTo":"7vd3l9rbnq.fsf@alter.siamese.dyndns.org","subject":"[RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2011-03-30T00:02:55Z","receivedAt":"2011-03-30T00:02:55Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"Currently, \"notes add\" (without -f/--force) will abort when the given object\nalready has existing notes. This makes sense for the modes of \"git notes add\"\nthat would necessarily overwrite the old message (when using the -m/-F/-C/-c\noptions). However, when no options are given (meaning the notes are created\nfrom scratch in the editor) it is not very user-friendly to abort on existing\nnotes, and forcing the user to run \"git notes edit\".\n\nInstead, it is better to simply \"redirect\" to \"git notes edit\" automatically,\ni.e. open the existing notes in the editor and let the user edit them.\nThis patch does just that.\n\nThis changes the behavior of \"git notes add\" without options when notes\nalready exist for the given object, but I doubt that many users really depend\non the previous failure from \"git notes add\" in this case.\n\nSigned-off-by: Johan Herland <johan@herland.net>\n---\n\nOn Tuesday 29 March 2011, Junio C Hamano wrote:\n> Michael J Gruber <drmicha@warpmail.net> writes:\n> > and while at it rename \"add\" to \"edit\"\n> That one I think is older wart that may be harder to change.\n\nHere's one attempt at giving Michael a nicer \"git notes add\" without\nbreaking too many existing users. It's not very pretty, but I hope it\ngets the job done without inconveniencing current users too much.\n\nAfter all, current (script) users of \"git notes add\" that depend on it\nfailing to overwrite existing notes, should already use -m/-F/-C/-c\ninstead of the default interactive mode, anyway.\n\n\nHave fun! :)\n\n...Johan\n\n\n Documentation/git-notes.txt |    7 +++++--\n builtin/notes.c             |   19 ++++++++++++++++---\n t/t3301-notes.sh            |   29 +++++++++++++++++++++++++++--\n 3 files changed, 48 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 296f314..913ecd8 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -57,8 +57,11 @@ list::\n \n add::\n \tAdd notes for a given object (defaults to HEAD). Abort if the\n-\tobject already has notes (use `-f` to overwrite an\n-\texisting note).\n+\tobject already has notes (use `-f` to overwrite existing notes).\n+\tHowever, if you're using `add` interactively (using an editor\n+\tto supply the notes contents), then - instead of aborting -\n+\tthe existing notes will be opened in the editor (like the `edit`\n+\tsubcommand).\n \n copy::\n \tCopy the notes for the first object onto the second object.\ndiff --git a/builtin/notes.c b/builtin/notes.c\nindex 0aab150..4074ba1 100644\n--- a/builtin/notes.c\n+++ b/builtin/notes.c\n@@ -527,6 +527,8 @@ static int list(int argc, const char **argv, const char *prefix)\n \treturn retval;\n }\n \n+static int append_edit(int argc, const char **argv, const char *prefix);\n+\n static int add(int argc, const char **argv, const char *prefix)\n {\n \tint retval = 0, force = 0;\n@@ -554,14 +556,14 @@ static int add(int argc, const char **argv, const char *prefix)\n \t};\n \n \targc = parse_options(argc, argv, prefix, options, git_notes_add_usage,\n-\t\t\t     0);\n+\t\t\t     PARSE_OPT_KEEP_ARGV0);\n \n-\tif (1 < argc) {\n+\tif (2 < argc) {\n \t\terror(\"too many parameters\");\n \t\tusage_with_options(git_notes_add_usage, options);\n \t}\n \n-\tobject_ref = argc ? argv[0] : \"HEAD\";\n+\tobject_ref = argc > 1 ? argv[1] : \"HEAD\";\n \n \tif (get_sha1(object_ref, object))\n \t\tdie(\"Failed to resolve '%s' as a valid ref.\", object_ref);\n@@ -571,6 +573,17 @@ static int add(int argc, const char **argv, const char *prefix)\n \n \tif (note) {\n \t\tif (!force) {\n+\t\t\tif (!msg.given) /* redirect to \"edit\" subcommand */\n+\t\t\t{\n+\t\t\t\t/*\n+\t\t\t\t * We only end up here if none of -m/-F/-c/-C\n+\t\t\t\t * or -f are given. The original args are\n+\t\t\t\t * therefore still in argv[0-1]\n+\t\t\t\t */\n+\t\t\t\targv[0] = \"edit\";\n+\t\t\t\tfree_notes(t);\n+\t\t\t\treturn append_edit(argc, argv, prefix);\n+\t\t\t}\n \t\t\tretval = error(\"Cannot add notes. Found existing notes \"\n \t\t\t\t       \"for object %s. Use '-f' to overwrite \"\n \t\t\t\t       \"existing notes\", sha1_to_hex(object));\ndiff --git a/t/t3301-notes.sh b/t/t3301-notes.sh\nindex 1921ca3..3448c23 100755\n--- a/t/t3301-notes.sh\n+++ b/t/t3301-notes.sh\n@@ -101,8 +101,8 @@ test_expect_success 'edit existing notes' '\n \ttest_must_fail git notes show HEAD^\n '\n \n-test_expect_success 'cannot add note where one exists' '\n-\t! MSG=b2 git notes add &&\n+test_expect_success 'cannot \"git notes add -m\" where notes already exists' '\n+\ttest_must_fail git notes add -m \"b2\" &&\n \ttest ! -f .git/NOTES_EDITMSG &&\n \ttest 1 = $(git ls-tree refs/notes/commits | wc -l) &&\n \ttest b3 = $(git notes show) &&\n@@ -110,6 +110,24 @@ test_expect_success 'cannot add note where one exists' '\n \ttest_must_fail git notes show HEAD^\n '\n \n+test_expect_success 'can overwrite existing note with \"git notes add -f -m\"' '\n+\tgit notes add -f -m \"b1\" &&\n+\ttest ! -f .git/NOTES_EDITMSG &&\n+\ttest 1 = $(git ls-tree refs/notes/commits | wc -l) &&\n+\ttest b1 = $(git notes show) &&\n+\tgit show HEAD^ &&\n+\ttest_must_fail git notes show HEAD^\n+'\n+\n+test_expect_success 'add w/no options on existing note morphs into edit' '\n+\tMSG=b2 git notes add &&\n+\ttest ! -f .git/NOTES_EDITMSG &&\n+\ttest 1 = $(git ls-tree refs/notes/commits | wc -l) &&\n+\ttest b2 = $(git notes show) &&\n+\tgit show HEAD^ &&\n+\ttest_must_fail git notes show HEAD^\n+'\n+\n test_expect_success 'can overwrite existing note with \"git notes add -f\"' '\n \tMSG=b1 git notes add -f &&\n \ttest ! -f .git/NOTES_EDITMSG &&\n@@ -194,6 +212,13 @@ test_expect_success 'show -F notes' '\n \ttest_cmp expect-F output\n '\n \n+test_expect_success 'Re-adding -F notes without -f fails' '\n+\techo \"zyxxy\" > note5 &&\n+\ttest_must_fail git notes add -F note5 &&\n+\tgit log -3 > output &&\n+\ttest_cmp expect-F output\n+'\n+\n cat >expect << EOF\n commit 15023535574ded8b1a89052b32673f84cf9582b8\n tree e070e3af51011e47b183c33adf9736736a525709\n-- \n1.7.4\n"},{"id":"164664","messageId":"4D92D399.4090404@drmicha.warpmail.net","threadId":"26905","inReplyTo":"201103300202.55973.johan@herland.net","subject":"Re: [RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-03-30T06:54:17Z","receivedAt":"2011-03-30T06:54:17Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Johan Herland venit, vidit, dixit 30.03.2011 02:02:\n> Currently, \"notes add\" (without -f/--force) will abort when the given object\n> already has existing notes. This makes sense for the modes of \"git notes add\"\n> that would necessarily overwrite the old message (when using the -m/-F/-C/-c\n> options). However, when no options are given (meaning the notes are created\n> from scratch in the editor) it is not very user-friendly to abort on existing\n> notes, and forcing the user to run \"git notes edit\".\n> \n> Instead, it is better to simply \"redirect\" to \"git notes edit\" automatically,\n> i.e. open the existing notes in the editor and let the user edit them.\n> This patch does just that.\n> \n> This changes the behavior of \"git notes add\" without options when notes\n> already exist for the given object, but I doubt that many users really depend\n> on the previous failure from \"git notes add\" in this case.\n> \n> Signed-off-by: Johan Herland <johan@herland.net>\n> ---\n> \n> On Tuesday 29 March 2011, Junio C Hamano wrote:\n>> Michael J Gruber <drmicha@warpmail.net> writes:\n>>> and while at it rename \"add\" to \"edit\"\n>> That one I think is older wart that may be harder to change.\n> \n> Here's one attempt at giving Michael a nicer \"git notes add\" without\n> breaking too many existing users. It's not very pretty, but I hope it\n> gets the job done without inconveniencing current users too much.\n\nThat is certainly an improvement, though I'm still wondering how large a\nchange we're aiming at, given Junio's remarks. Things I would like to\nthrow in:\n\n* options vs. arguments:\n\n\"tag\", \"branch\" etc. use options for subcommands, e.g. \"tag -d\", \"branch\n-d\" etc. \"remote\", \"stash\" use arguments, e.g. \"remote add\", \"stash\nlist\". I don't see us unifying that, but we should decide about a\ndirection to go for \"new\" commands and stick to that. I feel that\noptions are the way to go. What I really feel strongly about is that we\nshould decide once and then stick to that for future commands (and may\nbe gradually revamping).\n\n* singular vs. plural:\n\nAll our porcelain commands are singular even when they deal with\nmultiple items (tag, branch, remote, submodule, ...). \"notes\" is the\nonly exception, why not have it be \"note\"? (That would also open up a\nmigration strategy, though the usual suspects may not even bother ;))\n\n* \"notes message\":\n\nThe term seems to be used to distinguish between the content of a note\nand the note object (blob content vs. blob object). A regular git user\nmay think it is the commit message in the notes log, i.e.:\n\ngit log $(git notes get-ref)\n\nI'm wondering whether we should actually expose those note commit\nmessages. If notes are shared then editing a note may require an\nexplanation just like other commits do, especially when they get used\nfor other things than \"notes\" in the proper sense.\n\nIf we do that, then -m,-c,-C etc. would need to be analogous to \"git\ncommit -m,-c,-C\", i.e. about note commit messages, not about the actual\nnote. If we completely discard the possibility that users will look at\nthe notes log and write note commit messages, we can use the \"regular\ncommit message <-> notes content\" analogy for the options that we\npartially have now (and adjust -c,-C).\n\nCheers,\nMichael\n"},{"id":"164678","messageId":"201103301159.55573.johan@herland.net","threadId":"26905","inReplyTo":"4D92D399.4090404@drmicha.warpmail.net","subject":"Re: [RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2011-03-30T09:59:55Z","receivedAt":"2011-03-30T09:59:55Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Wednesday 30 March 2011, Michael J Gruber wrote:\n> I'm still wondering how large a\n> change we're aiming at, given Junio's remarks. Things I would like to\n> throw in:\n> \n> * options vs. arguments:\n> \n> \"tag\", \"branch\" etc. use options for subcommands, e.g. \"tag -d\", \"branch\n> -d\" etc. \"remote\", \"stash\" use arguments, e.g. \"remote add\", \"stash\n> list\". I don't see us unifying that, but we should decide about a\n> direction to go for \"new\" commands and stick to that. I feel that\n> options are the way to go. What I really feel strongly about is that we\n> should decide once and then stick to that for future commands (and may\n> be gradually revamping).\n\nThis is a big discussion, and I don't really have a strong opinion either \nway (or on whether unification of options vs. arguments is really necessary \nat all). In general, I like separating the \"verb\" of the command (_what_ to \ndo) from the \"adverbs\" (_how_ to do it). For some git commands, the verb is \nright there in the name (e.g. \"checkout\", \"add\", \"rm\", etc.), so the options \nare usually all \"adverbs\". Other commands, however, refer to one of git's \n\"subsystems\" (for some very vague definition of \"subsystem\") as a \"noun\" \n(e.g. \"stash\", \"remote\", \"notes\"), and the verb needs to be specified \n(either as a subcommand, or as an option). In those cases, I personally \nprefer the subcommand approach (\"git noun verb --adverb\") better than the \noption approach (\"git noun --verb --adverb\"), so as to separate the verb \nfrom the adverbs.\n\nHowever, some commands (e.g. \"branch\", \"tag\") are _both_ \"verbs\" (\"I want to \ntag something\") and \"nouns\" (\"I want to add a tag\"). By now, I'm thoroughly \nused to \"branch -d\" and \"tag -d\", so e.g. \"branch rm\" and \"tag rm\" look a \nbit foreign to me, although they probably follow the above principle more \nclosely...\n\nThen you have weird cases that further complicate things: \"rebase\" is \nusually a verb, but in \"rebase --continue\" or \"rebase --abort\" another verb \ntakes the focus, and I would probably prefer them as subcommands (\"rebase \ncontinue\" and \"rebase abort\").\n\nWhat can I say? Habits are hard to break, and this might be a case where \nbreaking them is more harmful than a somewhat messy command-line interface.\n\n> * singular vs. plural:\n> \n> All our porcelain commands are singular even when they deal with\n> multiple items (tag, branch, remote, submodule, ...). \"notes\" is the\n> only exception, why not have it be \"note\"? (That would also open up a\n> migration strategy, though the usual suspects may not even bother ;))\n\nTrue, but would you want to use \"note\" as a verb or a noun?\n\n  Verb:\n  $ git note # to add/edit a note\n  $ git note -d # to remove a note\n  etc.\n\n  Noun:\n  $ git note add # to add/edit a note\n  $ git note rm # to remove a note\n  etc.\n\n> * \"notes message\":\n> \n> The term seems to be used to distinguish between the content of a note\n> and the note object (blob content vs. blob object). A regular git user\n> may think it is the commit message in the notes log, i.e.:\n> \n> git log $(git notes get-ref)\n> \n> I'm wondering whether we should actually expose those note commit\n> messages. If notes are shared then editing a note may require an\n> explanation just like other commits do, especially when they get used\n> for other things than \"notes\" in the proper sense.\n> \n> If we do that, then -m,-c,-C etc. would need to be analogous to \"git\n> commit -m,-c,-C\", i.e. about note commit messages, not about the actual\n> note. If we completely discard the possibility that users will look at\n> the notes log and write note commit messages, we can use the \"regular\n> commit message <-> notes content\" analogy for the options that we\n> partially have now (and adjust -c,-C).\n\nInteresting. Originally, I think \"notes message\" comes from the initial use \ncase of notes being an extension of the commit message. The \"notes message\" \nis therefore what is shown next to the commit message, i.e. the blob \ncontent. From that POV, the --reuse-message/--reedit-message options also \nmake some sense.\n\nBut it is apparent by now that simply extending the commit message will \nprobably not be the central use case for notes, and I agree that it makes \nsense to revisit the terminology (both in the documentation and the options \nthemselves.)\n\nAs you say, -m/-c/-C should probably change to affect the commit message of \nthe note commit (and not affect the note content). I'm unsure whether -F \nshould follow along, or if we should reserve that for supplying note content \n(binary-safely). I think I prefer the former, and would want a different \noption for getting note contents from a file.\n\nObviously, copying notes from one object to another is covered by \"git notes \ncopy\", but I wonder if it still makes sense to provide a way to get note \ncontents from an existing blob SHA1 (i.e. what -c/-C does today).\n\n\nHave fun! :)\n\n...Johan\n\n-- \nJohan Herland, <johan@herland.net>\nwww.herland.net\n"},{"id":"164716","messageId":"7vsju4mmjb.fsf@alter.siamese.dyndns.org","threadId":"26905","inReplyTo":"201103300202.55973.johan@herland.net","subject":"Re: [RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-03-30T19:32:56Z","receivedAt":"2011-03-30T19:32:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johan Herland <johan@herland.net> writes:\n\n> Currently, \"notes add\" (without -f/--force) will abort when the given object\n> already has existing notes. This makes sense for the modes of \"git notes add\"\n> that would necessarily overwrite the old message (when using the -m/-F/-C/-c\n> options). However, when no options are given (meaning the notes are created\n> from scratch in the editor) it is not very user-friendly to abort on existing\n> notes, and forcing the user to run \"git notes edit\".\n>\n> Instead, it is better to simply \"redirect\" to \"git notes edit\" automatically,\n> i.e. open the existing notes in the editor and let the user edit them.\n> This patch does just that.\n>\n> This changes the behavior of \"git notes add\" without options when notes\n> already exist for the given object, but I doubt that many users really depend\n> on the previous failure from \"git notes add\" in this case.\n>\n> Signed-off-by: Johan Herland <johan@herland.net>\n> ---\n>\n> On Tuesday 29 March 2011, Junio C Hamano wrote:\n>> Michael J Gruber <drmicha@warpmail.net> writes:\n>> > and while at it rename \"add\" to \"edit\"\n>> That one I think is older wart that may be harder to change.\n>\n> Here's one attempt at giving Michael a nicer \"git notes add\" without\n> breaking too many existing users. It's not very pretty, but I hope it\n> gets the job done without inconveniencing current users too much.\n>\n> After all, current (script) users of \"git notes add\" that depend on it\n> failing to overwrite existing notes, should already use -m/-F/-C/-c\n> instead of the default interactive mode, anyway.\n\nLooks sensible, by addressing the issue gently without going overboard.\n\nThanks; I like it.\n"},{"id":"165103","messageId":"BANLkTi=PHq=VVuh24S5-QZDXkdW4XVWWQA@mail.gmail.com","threadId":"26905","inReplyTo":"201103301159.55573.johan@herland.net","subject":"Re: [RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Lasse Makholm","fromEmail":"lasse.makholm@gmail.com","sentAt":"2011-04-04T11:35:38Z","receivedAt":"2011-04-04T11:35:38Z","isPatch":true,"sender":{"key":"lasse.makholm@gmail.com","avatar":"https://gravatar.com/avatar/5bc3a34e4fa8ba26b38c333f370b15c034351e18e09b056a2608f3904ae1a4c1?d=mp&s=160"},"body":"On 30 March 2011 11:59, Johan Herland <johan@herland.net> wrote:\n>> * options vs. arguments:\n>>\n>> \"tag\", \"branch\" etc. use options for subcommands, e.g. \"tag -d\", \"branch\n>> -d\" etc. \"remote\", \"stash\" use arguments, e.g. \"remote add\", \"stash\n>> list\". I don't see us unifying that, but we should decide about a\n>> direction to go for \"new\" commands and stick to that. I feel that\n>> options are the way to go. What I really feel strongly about is that we\n>> should decide once and then stick to that for future commands (and may\n>> be gradually revamping).\n>\n> This is a big discussion, and I don't really have a strong opinion either\n> way (or on whether unification of options vs. arguments is really necessary\n> at all). In general, I like separating the \"verb\" of the command (_what_ to\n> do) from the \"adverbs\" (_how_ to do it). For some git commands, the verb is\n> right there in the name (e.g. \"checkout\", \"add\", \"rm\", etc.), so the options\n> are usually all \"adverbs\". Other commands, however, refer to one of git's\n> \"subsystems\" (for some very vague definition of \"subsystem\") as a \"noun\"\n> (e.g. \"stash\", \"remote\", \"notes\"), and the verb needs to be specified\n> (either as a subcommand, or as an option). In those cases, I personally\n> prefer the subcommand approach (\"git noun verb --adverb\") better than the\n> option approach (\"git noun --verb --adverb\"), so as to separate the verb\n> from the adverbs.\n>\n> However, some commands (e.g. \"branch\", \"tag\") are _both_ \"verbs\" (\"I want to\n> tag something\") and \"nouns\" (\"I want to add a tag\"). By now, I'm thoroughly\n> used to \"branch -d\" and \"tag -d\", so e.g. \"branch rm\" and \"tag rm\" look a\n> bit foreign to me, although they probably follow the above principle more\n> closely...\n\nThink of it less as the (only) verb and more of it as a domain. In the\ndomain of a git remote, (add|rm|rename|...) is the action (verb) and\nthat's why it is and should be a sub-command.\n\ngit remote and git stash do it right in my opinion. The default action\ndiffers (list vs. create) but that's OK because so does the most\ncommon use case.\n\nThe canonical way to create a stash is to say \"git stash create\" but\nwe allow you to simply say \"git stash\" because that's probably what\nyou want. It seems then, that the canonical way to create a commit\nwould be by saying \"git commit create\" (again, allowing the \"git\ncommit\" shortcut).\n\nWe could even expand on the heresy and argue that git log should be an\nalias for \"git commit list\"... :-)\n\nMy fingers type git branch -d foo by habit as well, but were it to\nchange, I'd get over it and form new habits. We shouldn't let the\nforce of mere habits prevent us from doing The Right Thing.\n\nYou could argue that git branch -d is broken because -d is, in fact,\nnot an option at all. If it was, you would be able to say git branch\n-d junk feature master to delete junk and branch out feature from\nmaster. But you can't because -d really is a sub-command in disguise.\n\n> Then you have weird cases that further complicate things: \"rebase\" is\n> usually a verb, but in \"rebase --continue\" or \"rebase --abort\" another verb\n> takes the focus, and I would probably prefer them as subcommands (\"rebase\n> continue\" and \"rebase abort\").\n\nAbsolutely, yes. I don't see this as a weird case at all. In my view,\nthis is clearly broken just as git branch -d is. Again, in the domain\nof a rebase, abort and continue are clearly commands and should loose\nthe dashes.\n\n> What can I say? Habits are hard to break, and this might be a case where\n> breaking them is more harmful than a somewhat messy command-line interface.\n\nAs someone, standing on the edge of a 1000+ developer deployment of\ngit, the option-vs-sub-command issue is one of the many things\ncurrently keeping me up at night. I would take a break in habits any\nday to avoid a lifetime of pain teaching people to remember and accept\nthese inconsistencies...\n\n/Lasse\n"},{"id":"165110","messageId":"4D99BFA1.6090701@drmicha.warpmail.net","threadId":"26905","inReplyTo":"BANLkTi=PHq=VVuh24S5-QZDXkdW4XVWWQA@mail.gmail.com","subject":"Re: [RFC/PATCH] Make \"git notes add\" more user-friendly when there are existing notes","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-04-04T12:54:57Z","receivedAt":"2011-04-04T12:54:57Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Lasse Makholm venit, vidit, dixit 04.04.2011 13:35:\n> On 30 March 2011 11:59, Johan Herland <johan@herland.net> wrote:\n>>> * options vs. arguments:\n>>>\n>>> \"tag\", \"branch\" etc. use options for subcommands, e.g. \"tag -d\", \"branch\n>>> -d\" etc. \"remote\", \"stash\" use arguments, e.g. \"remote add\", \"stash\n>>> list\". I don't see us unifying that, but we should decide about a\n>>> direction to go for \"new\" commands and stick to that. I feel that\n>>> options are the way to go. What I really feel strongly about is that we\n>>> should decide once and then stick to that for future commands (and may\n>>> be gradually revamping).\n>>\n>> This is a big discussion, and I don't really have a strong opinion either\n>> way (or on whether unification of options vs. arguments is really necessary\n>> at all). In general, I like separating the \"verb\" of the command (_what_ to\n>> do) from the \"adverbs\" (_how_ to do it). For some git commands, the verb is\n>> right there in the name (e.g. \"checkout\", \"add\", \"rm\", etc.), so the options\n>> are usually all \"adverbs\". Other commands, however, refer to one of git's\n>> \"subsystems\" (for some very vague definition of \"subsystem\") as a \"noun\"\n>> (e.g. \"stash\", \"remote\", \"notes\"), and the verb needs to be specified\n>> (either as a subcommand, or as an option). In those cases, I personally\n>> prefer the subcommand approach (\"git noun verb --adverb\") better than the\n>> option approach (\"git noun --verb --adverb\"), so as to separate the verb\n>> from the adverbs.\n>>\n>> However, some commands (e.g. \"branch\", \"tag\") are _both_ \"verbs\" (\"I want to\n>> tag something\") and \"nouns\" (\"I want to add a tag\"). By now, I'm thoroughly\n>> used to \"branch -d\" and \"tag -d\", so e.g. \"branch rm\" and \"tag rm\" look a\n>> bit foreign to me, although they probably follow the above principle more\n>> closely...\n> \n> Think of it less as the (only) verb and more of it as a domain. In the\n> domain of a git remote, (add|rm|rename|...) is the action (verb) and\n> that's why it is and should be a sub-command.\n> \n> git remote and git stash do it right in my opinion. The default action\n> differs (list vs. create) but that's OK because so does the most\n> common use case.\n> \n> The canonical way to create a stash is to say \"git stash create\" but\n> we allow you to simply say \"git stash\" because that's probably what\n> you want. It seems then, that the canonical way to create a commit\n> would be by saying \"git commit create\" (again, allowing the \"git\n> commit\" shortcut).\n> \n> We could even expand on the heresy and argue that git log should be an\n> alias for \"git commit list\"... :-)\n> \n> My fingers type git branch -d foo by habit as well, but were it to\n> change, I'd get over it and form new habits. We shouldn't let the\n> force of mere habits prevent us from doing The Right Thing.\n> \n> You could argue that git branch -d is broken because -d is, in fact,\n> not an option at all. If it was, you would be able to say git branch\n> -d junk feature master to delete junk and branch out feature from\n> master. But you can't because -d really is a sub-command in disguise.\n> \n>> Then you have weird cases that further complicate things: \"rebase\" is\n>> usually a verb, but in \"rebase --continue\" or \"rebase --abort\" another verb\n>> takes the focus, and I would probably prefer them as subcommands (\"rebase\n>> continue\" and \"rebase abort\").\n> \n> Absolutely, yes. I don't see this as a weird case at all. In my view,\n> this is clearly broken just as git branch -d is. Again, in the domain\n> of a rebase, abort and continue are clearly commands and should loose\n> the dashes.\n> \n>> What can I say? Habits are hard to break, and this might be a case where\n>> breaking them is more harmful than a somewhat messy command-line interface.\n> \n> As someone, standing on the edge of a 1000+ developer deployment of\n> git, the option-vs-sub-command issue is one of the many things\n> currently keeping me up at night. I would take a break in habits any\n> day to avoid a lifetime of pain teaching people to remember and accept\n> these inconsistencies...\n> \n\nWell, I would like say that we should take this up as a long running\ntask then. The problem is, though, disambiguating things like \"git\nbranch list\" if we were to go for subcommands as arguments (not\noptions). I have no idea how to solve this (without having a complete\nswitch-over day).\n\nMichael\n"},{"id":"174223","messageId":"0b124a705cf63d7c531a3a097a158dbaeaf6d298.1314267281.git.git@drmicha.warpmail.net","threadId":"26905","inReplyTo":"7v1v1pr97x.fsf@alter.siamese.dyndns.org","subject":"[PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-08-25T10:26:37Z","receivedAt":"2011-08-25T10:26:37Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"The current description of '-C' together with the analogy to 'git commit\n-C' can lead to the wrong conclusion that '-C' copies notes between\nobjects. Make this clearer by rewording and pointing to 'copy'.\n\nThe example for attaching binary notes with 'git hash-object' followed\nby 'git notes add -C' immediately raises the question: \"Why not use 'git\nnotes add -F'?\". Answer it (the latter is not binary-safe).\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nThis one has been lying around and fell under the rugs of the discussion\nfor a ui redesign which never happened. So I think it's still worth it.\n---\n Documentation/git-notes.txt |    7 +++++--\n 1 files changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 6a187f2..e8319ea 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -142,8 +142,9 @@ OPTIONS\n \n -C <object>::\n --reuse-message=<object>::\n-\tTake the note message from the given blob object (for\n-\texample, another note).\n+\tTake the given blob object (for\texample, another note) as the\n+\tnote message. (Use `git notes copy <object>` instead to\n+\tcopy notes between objects.)\n \n -c <object>::\n --reedit-message=<object>::\n@@ -285,6 +286,8 @@ $ blob=$(git hash-object -w a.out)\n $ git notes --ref=built add -C \"$blob\" HEAD\n ------------\n \n+(You cannot simply use `git notes --ref=built add -F a.out HEAD`\n+because that is not binary-safe.)\n Of course, it doesn't make much sense to display non-text-format notes\n with 'git log', so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n-- \n1.7.6.845.gc3c05\n"},{"id":"174249","messageId":"1636229.DSRqu7vzHC@alpha","threadId":"26905","inReplyTo":"0b124a705cf63d7c531a3a097a158dbaeaf6d298.1314267281.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-notes.txt: clarify -C vs. copy and -F","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2011-08-25T18:50:42Z","receivedAt":"2011-08-25T18:50:42Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Thursday 25 August 2011 12:26:37 Michael J Gruber wrote:\n> The current description of '-C' together with the analogy to 'git commit\n> -C' can lead to the wrong conclusion that '-C' copies notes between\n> objects. Make this clearer by rewording and pointing to 'copy'.\n> \n> The example for attaching binary notes with 'git hash-object' followed\n> by 'git notes add -C' immediately raises the question: \"Why not use 'git\n> notes add -F'?\". Answer it (the latter is not binary-safe).\n> \n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n> This one has been lying around and fell under the rugs of the discussion\n> for a ui redesign which never happened. So I think it's still worth it.\n\nACK\n\n...Johan\n\n-- \nJohan Herland, <johan@herland.net>\nwww.herland.net\n"}]}