[PATCH v3] doc: tweak "man gitcli" for clarity

[PATCH v3] doc: tweak "man gitcli" for clarity

[Robert P. J. Day]

No major changes, just some rewording and showing some variations of
general Git commands.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 9f13266a6..b7f40bf78 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -13,7 +13,7 @@ gitcli
 DESCRIPTION
 -----------

-This manual describes the convention used throughout Git CLI.
+This manual describes the conventions used throughout Git CLI.

 Many commands take revisions (most often "commits", but sometimes
 "tree-ish", depending on the context and command) and paths as their
@@ -32,32 +32,35 @@ arguments.  Here are the rules:
    between the HEAD commit and the work tree as a whole".  You can say
    `git diff HEAD --` to ask for the latter.

- * Without disambiguating `--`, Git makes a reasonable guess, but errors
-   out and asking you to disambiguate when ambiguous.  E.g. if you have a
-   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
+ * In cases where a Git command is truly ambiguous, Git will error out
+   and ask you to disambiguate the command.  E.g. if you have a file
+   called HEAD in your work tree, `git diff HEAD` is ambiguous, and
    you have to say either `git diff HEAD --` or `git diff -- HEAD` to
    disambiguate.
 +
 When writing a script that is expected to handle random user-input, it is
 a good practice to make it explicit which arguments are which by placing
-disambiguating `--` at appropriate places.
+a disambiguating `--` at appropriate places.

  * Many commands allow wildcards in paths, but you need to protect
-   them from getting globbed by the shell.  These two mean different
-   things:
+   them from getting globbed by the shell.  The following commands have
+   two different meanings:
 +
 --------------------------------
 $ git checkout -- *.c
+
 $ git checkout -- \*.c
+$ git checkout -- "*.c"
+$ git checkout -- '*.c'
 --------------------------------
 +
-The former lets your shell expand the fileglob, and you are asking
-the dot-C files in your working tree to be overwritten with the version
-in the index.  The latter passes the `*.c` to Git, and you are asking
-the paths in the index that match the pattern to be checked out to your
-working tree.  After running `git add hello.c; rm hello.c`, you will _not_
-see `hello.c` in your working tree with the former, but with the latter
-you will.
+The first command lets your shell expand the fileglob, and you are asking
+the dot-C files in your working tree to be overwritten with the version in
+the index.  The latter three variations pass the `*.c` to Git, and you are
+asking the paths in the index that match the pattern to be checked out to
+your working tree.  After running `git add hello.c; rm hello.c`, you will
+_not_ see `hello.c` in your working tree with the first command, but with
+the latter three variations, you will.

  * Just as the filesystem '.' (period) refers to the current directory,
    using a '.' as a repository name in Git (a dot-repository) is a relative

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH v3] doc: tweak "man gitcli" for clarity

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

> -This manual describes the convention used throughout Git CLI.
> +This manual describes the conventions used throughout Git CLI.

OK.

>  Many commands take revisions (most often "commits", but sometimes
>  "tree-ish", depending on the context and command) and paths as their
> @@ -32,32 +32,35 @@ arguments.  Here are the rules:
>     between the HEAD commit and the work tree as a whole".  You can say
>     `git diff HEAD --` to ask for the latter.
>
> - * Without disambiguating `--`, Git makes a reasonable guess, but errors
> -   out and asking you to disambiguate when ambiguous.  E.g. if you have a
> -   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
> + * In cases where a Git command is truly ambiguous, Git will error out
> +   and ask you to disambiguate the command.  E.g. if you have a file
> +   called HEAD in your work tree, `git diff HEAD` is ambiguous, and
>     you have to say either `git diff HEAD --` or `git diff -- HEAD` to
>     disambiguate.
>  +
>  When writing a script that is expected to handle random user-input, it is
>  a good practice to make it explicit which arguments are which by placing
> -disambiguating `--` at appropriate places.
> +a disambiguating `--` at appropriate places.

The above "truly" is misleading by giving the information the other
way around.  We ask to disambiguate when we cannot readily say the
command line is *not* unambiguous.  That is different from asking
when we know it is truly ambiguous.

Also see <xmqq7eugqykq.fsf@gitster.mtv.corp.google.com> if you want
to know more.

>   * Many commands allow wildcards in paths, but you need to protect
> -   them from getting globbed by the shell.  These two mean different
> -   things:
> +   them from getting globbed by the shell.  The following commands have
> +   two different meanings:
>  +
>  --------------------------------
>  $ git checkout -- *.c
> +
>  $ git checkout -- \*.c
> +$ git checkout -- "*.c"
> +$ git checkout -- '*.c'

I do not think these two additional ones add any value.

And if you do not add these two, you do not need any of the change
we see before or after this example.  The changes you made to these
paragraphs are primarily there because you need to explain that the
latter three are equivalent to each other now because of these two
extra ones, while the original did not have to say anything like
that.

Because this is not a tutorial for shell scripting and its quoting
rules, highlighting the difference between the case where Git sees
the asterisk and you let shell to expand asterisk and do not let Git
see the asterisk _is_ important, but the fact that you can quote the
asterisk in different ways from the shell is *not* important.  We
shouldn't clutter the description with the latter, I would think.

I would however be receptive if the change were to only replace the
backslash quoting of asterisk with the one that uses a single quote
pair (and with no changes in the surrounding paragraphs).  That
change could be justified by saying that a pair of single (or
double) quotes would be more familiar for people new to the shell.

Thanks.

Re: [PATCH v3] doc: tweak "man gitcli" for clarity

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> - * Without disambiguating `--`, Git makes a reasonable guess, but errors
>> -   out and asking you to disambiguate when ambiguous.  E.g. if you have a
>> -   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
>> + * In cases where a Git command is truly ambiguous, Git will error out
>> +   and ask you to disambiguate the command.  E.g. if you have a file
>> +   called HEAD in your work tree, `git diff HEAD` is ambiguous, and
>>     you have to say either `git diff HEAD --` or `git diff -- HEAD` to
>>     disambiguate.
>>  ...
>
> The above "truly" is misleading by giving the information the other
> way around.  We ask to disambiguate when we cannot readily say the
> command line is *not* unambiguous.  That is different from asking
> when we know it is truly ambiguous.
>
> Also see <xmqq7eugqykq.fsf@gitster.mtv.corp.google.com> if you want
> to know more.

So, here is my attempt (other than "the original reads clear enough
to me, so I am not sure what's there to improve"):

    When the command line does not have the disambiguating `--`, Git
    needs to find where the revisions end and paths begin.  In order
    to make sure it does not guess incorrectly, Git errors out when
    it cannot cheaply determine that there is no ambiguity, and asks
    you to disambiguate with `--`.  If you have a file whose name is
    HEAD, "git diff HEAD" gets an error for this reason; you need to
    say "git diff -- HEAD" or "git diff HEAD --" to disambiguate.

    Also, if you do not have a file whose name is Nakefile and it is
    not a branch or tag name, "git log Nakefile" is flagged as an
    error.  If you know there used to be a file called Nakefile but
    not in the current working tree, "git log -- Nakefile" is how
    you tell Git that you did not make a typo and you mean to find
    commits that touch the path.

I briefly considered the following as a more technically correct
description for "cheaply determine", but I am not sure if we want to
go down to that level of detail:

    ... when it cannot determine that every argument before one
    point on the command line names a revision and does not have a
    file with that name in the working tree, and every argument
    after that point does have a file with that name and cannot be
    interpreted as a valid revision.

>>  When writing a script that is expected to handle random user-input, it is
>>  a good practice to make it explicit which arguments are which by placing
>> -disambiguating `--` at appropriate places.
>> +a disambiguating `--` at appropriate places.

I forgot to mention in my earlier message, but this part of the
patch is obviously good ;-)

Re: [PATCH v3] doc: tweak "man gitcli" for clarity

[Robert P. J. Day]

On Fri, 24 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > -This manual describes the convention used throughout Git CLI.
> > +This manual describes the conventions used throughout Git CLI.
>
> OK.
>
> >  Many commands take revisions (most often "commits", but sometimes
> >  "tree-ish", depending on the context and command) and paths as their
> > @@ -32,32 +32,35 @@ arguments.  Here are the rules:
> >     between the HEAD commit and the work tree as a whole".  You can say
> >     `git diff HEAD --` to ask for the latter.
> >
> > - * Without disambiguating `--`, Git makes a reasonable guess, but errors
> > -   out and asking you to disambiguate when ambiguous.  E.g. if you have a
> > -   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
> > + * In cases where a Git command is truly ambiguous, Git will error out
> > +   and ask you to disambiguate the command.  E.g. if you have a file
> > +   called HEAD in your work tree, `git diff HEAD` is ambiguous, and
> >     you have to say either `git diff HEAD --` or `git diff -- HEAD` to
> >     disambiguate.
> >  +
> >  When writing a script that is expected to handle random user-input, it is
> >  a good practice to make it explicit which arguments are which by placing
> > -disambiguating `--` at appropriate places.
> > +a disambiguating `--` at appropriate places.
>
> The above "truly" is misleading by giving the information the other
> way around.  We ask to disambiguate when we cannot readily say the
> command line is *not* unambiguous.  That is different from asking
> when we know it is truly ambiguous.
>
> Also see <xmqq7eugqykq.fsf@gitster.mtv.corp.google.com> if you want
> to know more.

  ... snip ...

  at this point, i would throw out *all* of this and, rather than try
to cram disambiguation into the bullet lists currently in that man
page, just break it out into its own section, where it can be
explained properly and comprehensively.

  the reason this has gotten so chaotic is that we're trying to
preserve the structure that is in that man page, when it should just
be tossed and rewritten to give "--" and disambiguation the section it
deserves.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================