{"thread":{"id":"47292","subject":"[PATCH v3] doc: tweak \"man gitcli\" for clarity","startedAt":"2017-11-22T12:04:43Z","lastAt":"2017-11-24T10:40:50Z","messageCount":4,"participants":["Robert P. J. Day","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"333268","messageId":"alpine.LFD.2.21.1711220701070.12544@DESKTOP-1GPMCEJ","threadId":"47292","inReplyTo":null,"subject":"[PATCH v3] doc: tweak \"man gitcli\" for clarity","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-22T12:03:09Z","receivedAt":"2017-11-22T12:04:43Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"No major changes, just some rewording and showing some variations of\ngeneral Git commands.\n\nSigned-off-by: Robert P. J. Day \n\n---\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 9f13266a6..b7f40bf78 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -13,7 +13,7 @@ gitcli\n DESCRIPTION\n -----------\n\n-This manual describes the convention used throughout Git CLI.\n+This manual describes the conventions used throughout Git CLI.\n\n Many commands take revisions (most often \"commits\", but sometimes\n \"tree-ish\", depending on the context and command) and paths as their\n@@ -32,32 +32,35 @@ arguments. Here are the rules:\n between the HEAD commit and the work tree as a whole\". You can say\n `git diff HEAD --` to ask for the latter.\n\n- * Without disambiguating `--`, Git makes a reasonable guess, but errors\n- out and asking you to disambiguate when ambiguous. E.g. if you have a\n- file called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n+ * In cases where a Git command is truly ambiguous, Git will error out\n+ and ask you to disambiguate the command. E.g. if you have a file\n+ called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n disambiguate.\n +\n When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n-disambiguating `--` at appropriate places.\n+a disambiguating `--` at appropriate places.\n\n * Many commands allow wildcards in paths, but you need to protect\n- them from getting globbed by the shell. These two mean different\n- things:\n+ them from getting globbed by the shell. The following commands have\n+ two different meanings:\n +\n --------------------------------\n $ git checkout -- *.c\n+\n $ git checkout -- \\*.c\n+$ git checkout -- \"*.c\"\n+$ git checkout -- '*.c'\n --------------------------------\n +\n-The former lets your shell expand the fileglob, and you are asking\n-the dot-C files in your working tree to be overwritten with the version\n-in the index. The latter passes the `*.c` to Git, and you are asking\n-the paths in the index that match the pattern to be checked out to your\n-working tree. After running `git add hello.c; rm hello.c`, you will _not_\n-see `hello.c` in your working tree with the former, but with the latter\n-you will.\n+The first command lets your shell expand the fileglob, and you are asking\n+the dot-C files in your working tree to be overwritten with the version in\n+the index. The latter three variations pass the `*.c` to Git, and you are\n+asking the paths in the index that match the pattern to be checked out to\n+your working tree. After running `git add hello.c; rm hello.c`, you will\n+_not_ see `hello.c` in your working tree with the first command, but with\n+the latter three variations, you will.\n\n * Just as the filesystem '.' (period) refers to the current directory,\n using a '.' as a repository name in Git (a dot-repository) is a relative\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":"333407","messageId":"xmqqd148p8v4.fsf@gitster.mtv.corp.google.com","threadId":"47292","inReplyTo":"alpine.LFD.2.21.1711220701070.12544@DESKTOP-1GPMCEJ","subject":"Re: [PATCH v3] doc: tweak \"man gitcli\" for clarity","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-24T05:02:23Z","receivedAt":"2017-11-24T05:02:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" writes:\n\n> -This manual describes the convention used throughout Git CLI.\n> +This manual describes the conventions used throughout Git CLI.\n\nOK.\n\n> Many commands take revisions (most often \"commits\", but sometimes\n> \"tree-ish\", depending on the context and command) and paths as their\n> @@ -32,32 +32,35 @@ arguments. Here are the rules:\n> between the HEAD commit and the work tree as a whole\". You can say\n> `git diff HEAD --` to ask for the latter.\n>\n> - * Without disambiguating `--`, Git makes a reasonable guess, but errors\n> - out and asking you to disambiguate when ambiguous. E.g. if you have a\n> - file called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n> + * In cases where a Git command is truly ambiguous, Git will error out\n> + and ask you to disambiguate the command. E.g. if you have a file\n> + called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n> you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n> disambiguate.\n> +\n> When writing a script that is expected to handle random user-input, it is\n> a good practice to make it explicit which arguments are which by placing\n> -disambiguating `--` at appropriate places.\n> +a disambiguating `--` at appropriate places.\n\nThe above \"truly\" is misleading by giving the information the other\nway around. We ask to disambiguate when we cannot readily say the\ncommand line is *not* unambiguous. That is different from asking\nwhen we know it is truly ambiguous.\n\nAlso see if you want\nto know more.\n\n> * Many commands allow wildcards in paths, but you need to protect\n> - them from getting globbed by the shell. These two mean different\n> - things:\n> + them from getting globbed by the shell. The following commands have\n> + two different meanings:\n> +\n> --------------------------------\n> $ git checkout -- *.c\n> +\n> $ git checkout -- \\*.c\n> +$ git checkout -- \"*.c\"\n> +$ git checkout -- '*.c'\n\nI do not think these two additional ones add any value.\n\nAnd if you do not add these two, you do not need any of the change\nwe see before or after this example. The changes you made to these\nparagraphs are primarily there because you need to explain that the\nlatter three are equivalent to each other now because of these two\nextra ones, while the original did not have to say anything like\nthat.\n\nBecause this is not a tutorial for shell scripting and its quoting\nrules, highlighting the difference between the case where Git sees\nthe asterisk and you let shell to expand asterisk and do not let Git\nsee the asterisk _is_ important, but the fact that you can quote the\nasterisk in different ways from the shell is *not* important. We\nshouldn't clutter the description with the latter, I would think.\n\nI would however be receptive if the change were to only replace the\nbackslash quoting of asterisk with the one that uses a single quote\npair (and with no changes in the surrounding paragraphs). That\nchange could be justified by saying that a pair of single (or\ndouble) quotes would be more familiar for people new to the shell.\n\nThanks.\n"},{"id":"333413","messageId":"xmqqo9nsnqk7.fsf@gitster.mtv.corp.google.com","threadId":"47292","inReplyTo":"xmqqd148p8v4.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3] doc: tweak \"man gitcli\" for clarity","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-24T06:23:04Z","receivedAt":"2017-11-24T06:23:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> - * Without disambiguating `--`, Git makes a reasonable guess, but errors\n>> - out and asking you to disambiguate when ambiguous. E.g. if you have a\n>> - file called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n>> + * In cases where a Git command is truly ambiguous, Git will error out\n>> + and ask you to disambiguate the command. E.g. if you have a file\n>> + called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n>> you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n>> disambiguate.\n>> ...\n>\n> The above \"truly\" is misleading by giving the information the other\n> way around. We ask to disambiguate when we cannot readily say the\n> command line is *not* unambiguous. That is different from asking\n> when we know it is truly ambiguous.\n>\n> Also see if you want\n> to know more.\n\nSo, here is my attempt (other than \"the original reads clear enough\nto me, so I am not sure what's there to improve\"):\n\n When the command line does not have the disambiguating `--`, Git\n needs to find where the revisions end and paths begin. In order\n to make sure it does not guess incorrectly, Git errors out when\n it cannot cheaply determine that there is no ambiguity, and asks\n you to disambiguate with `--`. If you have a file whose name is\n HEAD, \"git diff HEAD\" gets an error for this reason; you need to\n say \"git diff -- HEAD\" or \"git diff HEAD --\" to disambiguate.\n\n Also, if you do not have a file whose name is Nakefile and it is\n not a branch or tag name, \"git log Nakefile\" is flagged as an\n error. If you know there used to be a file called Nakefile but\n not in the current working tree, \"git log -- Nakefile\" is how\n you tell Git that you did not make a typo and you mean to find\n commits that touch the path.\n\nI briefly considered the following as a more technically correct\ndescription for \"cheaply determine\", but I am not sure if we want to\ngo down to that level of detail:\n\n ... when it cannot determine that every argument before one\n point on the command line names a revision and does not have a\n file with that name in the working tree, and every argument\n after that point does have a file with that name and cannot be\n interpreted as a valid revision.\n\n>> When writing a script that is expected to handle random user-input, it is\n>> a good practice to make it explicit which arguments are which by placing\n>> -disambiguating `--` at appropriate places.\n>> +a disambiguating `--` at appropriate places.\n\nI forgot to mention in my earlier message, but this part of the\npatch is obviously good ;-)\n"},{"id":"333429","messageId":"alpine.LFD.2.21.1711240536390.4054@DESKTOP-1GPMCEJ","threadId":"47292","inReplyTo":"xmqqd148p8v4.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3] doc: tweak \"man gitcli\" for clarity","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-24T10:39:14Z","receivedAt":"2017-11-24T10:40:50Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 24 Nov 2017, Junio C Hamano wrote:\n\n> \"Robert P. J. Day\" writes:\n>\n> > -This manual describes the convention used throughout Git CLI.\n> > +This manual describes the conventions used throughout Git CLI.\n>\n> OK.\n>\n> > Many commands take revisions (most often \"commits\", but sometimes\n> > \"tree-ish\", depending on the context and command) and paths as their\n> > @@ -32,32 +32,35 @@ arguments. Here are the rules:\n> > between the HEAD commit and the work tree as a whole\". You can say\n> > `git diff HEAD --` to ask for the latter.\n> >\n> > - * Without disambiguating `--`, Git makes a reasonable guess, but errors\n> > - out and asking you to disambiguate when ambiguous. E.g. if you have a\n> > - file called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n> > + * In cases where a Git command is truly ambiguous, Git will error out\n> > + and ask you to disambiguate the command. E.g. if you have a file\n> > + called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n> > you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n> > disambiguate.\n> > +\n> > When writing a script that is expected to handle random user-input, it is\n> > a good practice to make it explicit which arguments are which by placing\n> > -disambiguating `--` at appropriate places.\n> > +a disambiguating `--` at appropriate places.\n>\n> The above \"truly\" is misleading by giving the information the other\n> way around. We ask to disambiguate when we cannot readily say the\n> command line is *not* unambiguous. That is different from asking\n> when we know it is truly ambiguous.\n>\n> Also see if you want\n> to know more.\n\n ... snip ...\n\n at this point, i would throw out *all* of this and, rather than try\nto cram disambiguation into the bullet lists currently in that man\npage, just break it out into its own section, where it can be\nexplained properly and comprehensively.\n\n the reason this has gotten so chaotic is that we're trying to\npreserve the structure that is in that man page, when it should just\nbe tossed and rewritten to give \"--\" and disambiguation the section it\ndeserves.\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"}]}