{"thread":{"id":"47158","subject":"[PATCH] bisect: mention \"view\" as an alternative to \"visualize\"","startedAt":"2017-11-10T16:32:59Z","lastAt":"2017-11-10T22:08:07Z","messageCount":4,"participants":["Robert P. J. Day","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"332189","messageId":"alpine.LFD.2.21.1711101123280.6717@DESKTOP-1GPMCEJ","threadId":"47158","inReplyTo":null,"subject":"[PATCH] bisect: mention \"view\" as an alternative to \"visualize\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-10T16:32:30Z","receivedAt":"2017-11-10T16:32:59Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"Tweak a number of files to mention \"view\" as an alternative to\n\"visualize\":\n\n Documentation/git-bisect.txt           | 9 ++++-----\n Documentation/user-manual.txt          | 3 ++-\n builtin/bisect--helper.c               | 2 +-\n contrib/completion/git-completion.bash | 2 +-\n git-bisect.sh                          | 4 ++--\n 5 files changed, 10 insertions(+), 10 deletions(-)\n\nSigned-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n\n---\n\n  here's hoping i have the right format for this patch ... are there\nany parts of this that are inappropriate, such as extending the bash\ncompletion?\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 6c42abf07..89e6f9667 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -23,7 +23,7 @@ on the subcommand:\n  git bisect terms [--term-good | --term-bad]\n  git bisect skip [(<rev>|<range>)...]\n  git bisect reset [<commit>]\n- git bisect visualize\n+ git bisect visualize|view\n  git bisect replay <logfile>\n  git bisect log\n  git bisect run <cmd>...\n@@ -196,15 +196,14 @@ of `git bisect good` and `git bisect bad` to mark commits.\n Bisect visualize\n ~~~~~~~~~~~~~~~~\n\n-To see the currently remaining suspects in 'gitk', issue the following\n-command during the bisection process:\n+To see the currently remaining suspects in 'gitk', issue either of the\n+following equivalent commands during the bisection process:\n\n ------------\n $ git bisect visualize\n+$ git bisect view\n ------------\n\n-`view` may also be used as a synonym for `visualize`.\n-\n If the `DISPLAY` environment variable is not set, 'git log' is used\n instead.  You can also give command-line options such as `-p` and\n `--stat`.\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 3a03e63eb..55ec58986 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -538,10 +538,11 @@ Note that the version which `git bisect` checks out for you at each\n point is just a suggestion, and you're free to try a different\n version if you think it would be a good idea.  For example,\n occasionally you may land on a commit that broke something unrelated;\n-run\n+run either of the equivalent commands\n\n -------------------------------------------------\n $ git bisect visualize\n+$ git bisect view\n -------------------------------------------------\n\n which will run gitk and label the commit it chose with a marker that\ndiff --git a/builtin/bisect--helper.c b/builtin/bisect--helper.c\nindex 35d2105f9..4b5fadcbe 100644\n--- a/builtin/bisect--helper.c\n+++ b/builtin/bisect--helper.c\n@@ -46,7 +46,7 @@ static int check_term_format(const char *term, const char *orig_term)\n \t\treturn error(_(\"'%s' is not a valid term\"), term);\n\n \tif (one_of(term, \"help\", \"start\", \"skip\", \"next\", \"reset\",\n-\t\t\t\"visualize\", \"replay\", \"log\", \"run\", \"terms\", NULL))\n+\t\t\t\"visualize\", \"view\", \"replay\", \"log\", \"run\", \"terms\", NULL))\n \t\treturn error(_(\"can't use the builtin command '%s' as a term\"), term);\n\n \t/*\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex fdd984d34..52f68c922 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -1162,7 +1162,7 @@ _git_bisect ()\n {\n \t__git_has_doubledash && return\n\n-\tlocal subcommands=\"start bad good skip reset visualize replay log run\"\n+\tlocal subcommands=\"start bad good skip reset visualize view replay log run\"\n \tlocal subcommand=\"$(__git_find_on_cmdline \"$subcommands\")\"\n \tif [ -z \"$subcommand\" ]; then\n \t\t__git_find_repo_path\ndiff --git a/git-bisect.sh b/git-bisect.sh\nindex 0138a8860..e8b622a47 100755\n--- a/git-bisect.sh\n+++ b/git-bisect.sh\n@@ -1,6 +1,6 @@\n #!/bin/sh\n\n-USAGE='[help|start|bad|good|new|old|terms|skip|next|reset|visualize|replay|log|run]'\n+USAGE='[help|start|bad|good|new|old|terms|skip|next|reset|visualize|view|replay|log|run]'\n LONG_USAGE='git bisect help\n \tprint this long help message.\n git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>]\n@@ -20,7 +20,7 @@ git bisect next\n \tfind next bisection to test and check it out.\n git bisect reset [<commit>]\n \tfinish bisection search and go back to commit.\n-git bisect visualize\n+git bisect visualize|view\n \tshow bisect status in gitk.\n git bisect replay <logfile>\n \treplay bisection log.\n\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"332248","messageId":"CAPig+cRtpmtD8XqhdXrn1iWOEf9Yx=TXQB=yvXBZ+uR_+XRcPg@mail.gmail.com","threadId":"47158","inReplyTo":"alpine.LFD.2.21.1711101123280.6717@DESKTOP-1GPMCEJ","subject":"Re: [PATCH] bisect: mention \"view\" as an alternative to \"visualize\"","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-10T21:06:08Z","receivedAt":"2017-11-10T21:06:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"Thanks for the patch. Some comments below...\n\nOn Fri, Nov 10, 2017 at 11:32 AM, Robert P. J. Day\n<rpjday@crashcourse.ca> wrote:\n> Tweak a number of files to mention \"view\" as an alternative to\n> \"visualize\":\n\nYou probably want to end this sentence with a period, not a colon.\n\n>  Documentation/git-bisect.txt           | 9 ++++-----\n>  Documentation/user-manual.txt          | 3 ++-\n>  builtin/bisect--helper.c               | 2 +-\n>  contrib/completion/git-completion.bash | 2 +-\n>  git-bisect.sh                          | 4 ++--\n>  5 files changed, 10 insertions(+), 10 deletions(-)\n\nThe diffstat belongs below the \"---\" separator, otherwise this text\nwill (undesirably) become part of the commit message proper.\n\n> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n>\n> ---\n>\n>   here's hoping i have the right format for this patch ... are there\n> any parts of this that are inappropriate, such as extending the bash\n> completion?\n\nThis is the correct place for your commentary. The diffstat should\nappear below your commentary.\n\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> @@ -23,7 +23,7 @@ on the subcommand:\n>   git bisect terms [--term-good | --term-bad]\n>   git bisect skip [(<rev>|<range>)...]\n>   git bisect reset [<commit>]\n> - git bisect visualize\n> + git bisect visualize|view\n\nI think you need parentheses around these terms (see \"git bisect\nskip\", for example):\n\n    git bisect (visualize | view)\n\nHowever, in this case, it might be easier for readers if each is\npresented on its own line (and subsequent discussion can make it clear\nthat they are synonyms).\n\n    git bisect visualize\n    git bisect view\n\nBut, that's a matter of taste...\n\n> @@ -196,15 +196,14 @@ of `git bisect good` and `git bisect bad` to mark commits.\n>  Bisect visualize\n>  ~~~~~~~~~~~~~~~~\n>\n> -To see the currently remaining suspects in 'gitk', issue the following\n> -command during the bisection process:\n> +To see the currently remaining suspects in 'gitk', issue either of the\n> +following equivalent commands during the bisection process:\n>\n>  ------------\n>  $ git bisect visualize\n> +$ git bisect view\n>  ------------\n>\n> -`view` may also be used as a synonym for `visualize`.\n\nHonestly, I think the original was clearer and placed a bit less\ncognitive load on the reader. Moreover, for someone scanning the\ndocumentation without reading it too deeply, the revised example makes\nit seem as if it is necessary to invoke both commands rather than one\nor the other.\n\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> @@ -538,10 +538,11 @@ Note that the version which `git bisect` checks out for you at each\n>  point is just a suggestion, and you're free to try a different\n>  version if you think it would be a good idea.  For example,\n>  occasionally you may land on a commit that broke something unrelated;\n> -run\n> +run either of the equivalent commands\n>\n>  -------------------------------------------------\n>  $ git bisect visualize\n> +$ git bisect view\n>  -------------------------------------------------\n\nSame observation as above. This has the potential to confuse someone\nquickly scanning the documentation into thinking that both commands\nmust be invoked. Merely stating in prose that one is the alias of the\nother might be better.\n\n>  which will run gitk and label the commit it chose with a marker that\n> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\n> index fdd984d34..52f68c922 100644\n> --- a/contrib/completion/git-completion.bash\n> +++ b/contrib/completion/git-completion.bash\n> @@ -1162,7 +1162,7 @@ _git_bisect ()\n>  {\n>         __git_has_doubledash && return\n>\n> -       local subcommands=\"start bad good skip reset visualize replay log run\"\n> +       local subcommands=\"start bad good skip reset visualize view replay log run\"\n\nPeople using muscle memory to type \"git bisect v<TAB>\"  or\n\"...vi<TAB>\" might find it annoying for this to suddenly become\nambiguous. Just an observation; no strong opinion on it...\n\n> diff --git a/git-bisect.sh b/git-bisect.sh\n> @@ -20,7 +20,7 @@ git bisect next\n>         find next bisection to test and check it out.\n>  git bisect reset [<commit>]\n>         finish bisection search and go back to commit.\n> -git bisect visualize\n> +git bisect visualize|view\n>         show bisect status in gitk.\n\nAgain, this might be easier to read if split over two lines:\n\n    git bisect visualize\n    git bisect view\n        show bisect status in gitk.\n\nin which case it's plenty clear that the commands are synonyms.\n"},{"id":"332249","messageId":"alpine.LFD.2.21.1711101609240.6187@localhost.localdomain","threadId":"47158","inReplyTo":"CAPig+cRtpmtD8XqhdXrn1iWOEf9Yx=TXQB=yvXBZ+uR_+XRcPg@mail.gmail.com","subject":"Re: [PATCH] bisect: mention \"view\" as an alternative to \"visualize\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-10T21:13:46Z","receivedAt":"2017-11-10T21:14:13Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 10 Nov 2017, Eric Sunshine wrote:\n\n> Thanks for the patch. Some comments below...\n>\n> On Fri, Nov 10, 2017 at 11:32 AM, Robert P. J. Day\n> <rpjday@crashcourse.ca> wrote:\n> > Tweak a number of files to mention \"view\" as an alternative to\n> > \"visualize\":\n>\n> You probably want to end this sentence with a period, not a colon.\n\n  not sure about that, what's the standard when you're introducing a\ncode snippet?\n\n> >  Documentation/git-bisect.txt           | 9 ++++-----\n> >  Documentation/user-manual.txt          | 3 ++-\n> >  builtin/bisect--helper.c               | 2 +-\n> >  contrib/completion/git-completion.bash | 2 +-\n> >  git-bisect.sh                          | 4 ++--\n> >  5 files changed, 10 insertions(+), 10 deletions(-)\n>\n> The diffstat belongs below the \"---\" separator, otherwise this text\n> will (undesirably) become part of the commit message proper.\n\n  no, i actually want that as part of the commit message. my standard\nis, if there are 5 or more files that get changed, i like to include a\ndiff --stat in the commit message so people viewing the log can get a\nquick idea of how much has changed. if that's not desired here, i can\nremove it.\n\n> > + git bisect visualize|view\n>\n> I think you need parentheses around these terms (see \"git bisect\n> skip\", for example):\n>\n>     git bisect (visualize | view)\n\n  ah, quite so.\n\n> However, in this case, it might be easier for readers if each is\n> presented on its own line (and subsequent discussion can make it clear\n> that they are synonyms).\n>\n>     git bisect visualize\n>     git bisect view\n>\n> But, that's a matter of taste...\n\n  given the precedent already established:\n\n   git bisect (bad|new|<term-new>) [<rev>]\n   git bisect (good|old|<term-old>) [<rev>...]\n\ni'll go with the parentheses and no intervening spaces. i'll let that\nposting simmer for a bit longer before posting \"v2\".\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"332250","messageId":"CAPig+cRYnwG4aTFh_5pgARbjoKPfzMBE12w4Boc6tzyKg54T1w@mail.gmail.com","threadId":"47158","inReplyTo":"alpine.LFD.2.21.1711101609240.6187@localhost.localdomain","subject":"Re: [PATCH] bisect: mention \"view\" as an alternative to \"visualize\"","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-10T22:08:00Z","receivedAt":"2017-11-10T22:08:07Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Nov 10, 2017 at 4:13 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n> On Fri, 10 Nov 2017, Eric Sunshine wrote:\n>\n>> Thanks for the patch. Some comments below...\n>>\n>> On Fri, Nov 10, 2017 at 11:32 AM, Robert P. J. Day\n>> <rpjday@crashcourse.ca> wrote:\n>> > Tweak a number of files to mention \"view\" as an alternative to\n>> > \"visualize\":\n>>\n>> You probably want to end this sentence with a period, not a colon.\n>\n>   not sure about that, what's the standard when you're introducing a\n> code snippet?\n\nIt wasn't clear that you were including a snippet since it's not\ncommon practice to include the diffstat in the commit message on this\nproject...\n\n>> >  Documentation/git-bisect.txt           | 9 ++++-----\n>> >  Documentation/user-manual.txt          | 3 ++-\n>> >  builtin/bisect--helper.c               | 2 +-\n>> >  contrib/completion/git-completion.bash | 2 +-\n>> >  git-bisect.sh                          | 4 ++--\n>> >  5 files changed, 10 insertions(+), 10 deletions(-)\n>>\n>> The diffstat belongs below the \"---\" separator, otherwise this text\n>> will (undesirably) become part of the commit message proper.\n>\n>   no, i actually want that as part of the commit message. my standard\n> is, if there are 5 or more files that get changed, i like to include a\n> diff --stat in the commit message so people viewing the log can get a\n> quick idea of how much has changed. if that's not desired here, i can\n> remove it.\n\nThe same information is available to anyone interested in it simply by\nasking for it:\n\n    git log --stat ...\n\nMore generally, commit messages should contain the really important\ninformation you want to convey to the reader which _isn't_ available\nsome other way (by, for instance, taking advantage of the tool itself\n-- such as the above --stat example).\n\nOn this project, the diffstat is never included as part of the commit\nmessage, and it's likely that the patch won't be accepted by Junio\nlike that (or he'll just edit it out if he does accept it).\n\nThanks.\n"}]}