v2gitcli: tweak "man gitcli" for clarity

> 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..d690d1ff0 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
> + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> +   error out, 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
>     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
> ========================================================================

> On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:
> > 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..d690d1ff0 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
> > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
>
> 'Can' error out implies that it sometimes would not error out when
> there is ambiguity. Are there situation where git does not error out
> in that case?

> On Tue, 21 Nov 2017, Kevin Daudt wrote:
> 
> > On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:
> > > 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..d690d1ff0 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
> > > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
> >
> > 'Can' error out implies that it sometimes would not error out when
> > there is ambiguity. Are there situation where git does not error out
> > in that case?
> 
>   i would say (based on my limited knowledge) that if the heuristic
> kicks in and works fine, then things will work. i think it's fair to
> say that git "can" error out if the heuristic fails.
> 
> rday

> On Tue, Nov 21, 2017 at 04:47:42PM -0500, Robert P. J. Day wrote:
> > On Tue, 21 Nov 2017, Kevin Daudt wrote:
> >
> > > On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:
> > > > 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..d690d1ff0 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
> > > > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > > > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
> > >
> > > 'Can' error out implies that it sometimes would not error out when
> > > there is ambiguity. Are there situation where git does not error out
> > > in that case?
> >
> >   i would say (based on my limited knowledge) that if the heuristic
> > kicks in and works fine, then things will work. i think it's fair to
> > say that git "can" error out if the heuristic fails.
> >
> > rday
>
> In most cases that I'm aware of, you have to be explicit. If for
> example you want to refer to a file that's not in the working tree,
> you have to use '--'.  Even with heuristics, it would still have to
> error out when it's ambiguous what the user meant.
>
> So the way you worded it implies that there are situations where git
> knows there are multiple things the user could have meant, but it
> would not error out in that case.

> On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:
> > 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..d690d1ff0 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
> > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
>
> 'Can' error out implies that it sometimes would not error out when
> there is ambiguity. Are there situation where git does not error out
> in that case?

> git repo with a file called "Gemfile", so i created a branch called
> "Gemfile", and when i ran:
>
>   $ git checkout Gemfile
>
> git switched to the branch. so even with the ambiguity, git obviously
> has some sort of precedence order it checks. so what are the rules
> here?

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > git repo with a file called "Gemfile", so i created a branch called
> > "Gemfile", and when i ran:
> >
> >   $ git checkout Gemfile
> >
> > git switched to the branch. so even with the ambiguity, git
> > obviously has some sort of precedence order it checks. so what are
> > the rules here?
>
> 31b83f36 ("Merge branch 'nd/checkout-disambiguation'", 2016-09-26)
> should have made it clear that the "checkout" command has a
> convenience special case.

> On Wed, 22 Nov 2017, Junio C Hamano wrote:
> 
> > "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
> >
> > > git repo with a file called "Gemfile", so i created a branch called
> > > "Gemfile", and when i ran:
> > >
> > >   $ git checkout Gemfile
> > >
> > > git switched to the branch. so even with the ambiguity, git
> > > obviously has some sort of precedence order it checks. so what are
> > > the rules here?
> >
> > 31b83f36 ("Merge branch 'nd/checkout-disambiguation'", 2016-09-26)
> > should have made it clear that the "checkout" command has a
> > convenience special case.
> 
>   ok, then i'm still curious about git examples that actually fail due
> to an inability to disambiguate.
> 
> rday

> On Wed, Nov 22, 2017 at 06:19:23AM -0500, Robert P. J. Day wrote:
> > On Wed, 22 Nov 2017, Junio C Hamano wrote:
> >
> > > "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
> > >
> > > > git repo with a file called "Gemfile", so i created a branch called
> > > > "Gemfile", and when i ran:
> > > >
> > > >   $ git checkout Gemfile
> > > >
> > > > git switched to the branch. so even with the ambiguity, git
> > > > obviously has some sort of precedence order it checks. so what are
> > > > the rules here?
> > >
> > > 31b83f36 ("Merge branch 'nd/checkout-disambiguation'", 2016-09-26)
> > > should have made it clear that the "checkout" command has a
> > > convenience special case.
> >
> >   ok, then i'm still curious about git examples that actually fail due
> > to an inability to disambiguate.
> >
> > rday
>
> Here is an example with git diff
>
>     $ git init git-disambiguate
>     $ cd git-disambiguate
>     $ echo 1 >foo && git add foo && git commit -m foo
>     $ git branch foo
>     $ echo 2 >>foo && git add foo && git commit -m foo2
>     $ echo 3 >>foo
>
>     $ git diff foo
>     fatal: ambiguous argument 'foo': both revision and filename
>     Use '--' to separate paths from revisions, like this:
>     'git <command> [<revision>...] -- [<file>...]'
>
>     $ git diff HEAD foo
>     fatal: ambiguous argument 'foo': both revision and filename
>     Use '--' to separate paths from revisions, like this:
>     'git <command> [<revision>...] -- [<file>...]'
>
>     $ git diff HEAD -- foo
>     diff --git a/foo b/foo
>     index 1191247..01e79c3 100644
>     --- a/foo
>     +++ b/foo
>     @@ -1,2 +1,3 @@
>      1
>      2
>     +3
>
>     $ git diff HEAD foo --
>     diff --git a/foo b/foo
>     index 1191247..d00491f 100644
>     --- a/foo
>     +++ b/foo
>     @@ -1,2 +1 @@
>      1
>     -2

> > - * Without disambiguating `--`, Git makes a reasonable guess, but errors
> > -   out and asking you to disambiguate when ambiguous.  E.g. if you have a
> > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
> 
> 'Can' error out implies that it sometimes would not error out when there
> is ambiguity. Are there situation where git does not error out in that
> case?

> I read the rest of the thread, and I think the question here is not
> about Git's behavior, but about parsing this sentence.
>
> Without a "--" Git can sometimes do what you want. Or it may error out,
> if what you asked for is ambiguous. And that sentence is trying to cover
> those cases separately, and the "can" only applies to the ambiguous
> case.
>
> It's pretty clear to me as it is, but maybe we can write it differently.
> Like:
>
>   Without a disambiguating `--`, Git makes a reasonable guess. If it
>   cannot guess (because your request is ambiguous), then it will error
>   out.

> On Tue, Nov 21, 2017 at 10:45:52PM +0100, Kevin Daudt wrote:
>
> > > - * Without disambiguating `--`, Git makes a reasonable guess, but errors
> > > -   out and asking you to disambiguate when ambiguous.  E.g. if you have a
> > > + * Without a disambiguating `--`, Git makes a reasonable guess, but can
> > > +   error out, asking you to disambiguate when ambiguous.  E.g. if you have a
> >
> > 'Can' error out implies that it sometimes would not error out when there
> > is ambiguity. Are there situation where git does not error out in that
> > case?
>
> I read the rest of the thread, and I think the question here is not
> about Git's behavior, but about parsing this sentence.
>
> Without a "--" Git can sometimes do what you want. Or it may error out,
> if what you asked for is ambiguous. And that sentence is trying to cover
> those cases separately, and the "can" only applies to the ambiguous
> case.
>
> It's pretty clear to me as it is, but maybe we can write it differently.
> Like:
>
>   Without a disambiguating `--`, Git makes a reasonable guess. If it
>   cannot guess (because your request is ambiguous), then it will error
>   out.

> > It's pretty clear to me as it is, but maybe we can write it differently.
> > Like:
> >
> >   Without a disambiguating `--`, Git makes a reasonable guess. If it
> >   cannot guess (because your request is ambiguous), then it will error
> >   out.
> 
>   ok, i'll give this another try, given that there are two independent
> points to be made here:
> 
> 1) even without the "--", git can generally parse the command and do
> the right thing (or do a *valid* thing, given its heuristics)
> 
> 2) occasionally, without the "--", the command is really and truly
> ambiguous, at which point git will fail and tell you to disambiguate
> 
>   not the wording i will use, but can we agree that those are the two
> points to be made here?

> On Thu, Nov 23, 2017 at 02:45:44AM -0500, Robert P. J. Day wrote:
> 
> > > It's pretty clear to me as it is, but maybe we can write it differently.
> > > Like:
> > >
> > >   Without a disambiguating `--`, Git makes a reasonable guess. If it
> > >   cannot guess (because your request is ambiguous), then it will error
> > >   out.
> > 
> >   ok, i'll give this another try, given that there are two independent
> > points to be made here:
> > 
> > 1) even without the "--", git can generally parse the command and do
> > the right thing (or do a *valid* thing, given its heuristics)
> > 
> > 2) occasionally, without the "--", the command is really and truly
> > ambiguous, at which point git will fail and tell you to disambiguate
> > 
> >   not the wording i will use, but can we agree that those are the two
> > points to be made here?
> 
> Yep, I think so.
> 
> -Peff

> Just for completeness, as it is somewhat covered by point 1 already, but
> there are cases where there is no real ambiguity but you are required to
> add '--' to tell git that it should not look for the file in the working
> tree:
>
>   $ git show abc123 deleted_file.txt
>   fatal: ambiguous argument 'deleted_file.txt':
>   unknown revision or path not in the working tree.
>   Use '--' to separate paths from revisions, like this:
>   'git <command> [<revision>...] -- [<file>...]'
>
> There might be good reasons why this is, but I don't consider this to be
> actually ambiguous: there is no branch called 'deleted_file.txt' and git
> could know that the files exists in the mentioned commit, so it should
> be pretty clear what is meant.

> Actually the second example is a lot worse (and that is why I am
> bringing it up).  If git does spend cycles to realize that "git
> could", for consistency, it must also check if "next" is unambiguous
> between a path or a rev, i.e. it must dig history from "master" and
> see if "next" appears as a path ever in the history, and if so, die
> with "ambiguous argument".

> > > >   Without a disambiguating `--`, Git makes a reasonable guess. If it
> > > >   cannot guess (because your request is ambiguous), then it will error
> > > >   out.
> [...]
> > > 1) even without the "--", git can generally parse the command and do
> > > the right thing (or do a *valid* thing, given its heuristics)
> > > 
> > > 2) occasionally, without the "--", the command is really and truly
> > > ambiguous, at which point git will fail and tell you to disambiguate
> [...]
> 
> Just for completeness, as it is somewhat covered by point 1 already, but
> there are cases where there is no real ambiguity but you are required to
> add '--' to tell git that it should not look for the file in the working
> tree:

>   $ git show abc123 deleted_file.txt
>   fatal: ambiguous argument 'deleted_file.txt':
>   unknown revision or path not in the working tree.
>   Use '--' to separate paths from revisions, like this:
>   'git <command> [<revision>...] -- [<file>...]'
> 
> There might be good reasons why this is, but I don't consider this to be
> actually ambiguous: there is no branch called 'deleted_file.txt' and git
> could know that the files exists in the mentioned commit, so it should
> be pretty clear what is meant.

> There is an open question of how carefully we want to document it, but I
> think the strategy so far has been:
>
>  - if you want to be careful, use "--"
>
>  - if you don't, git will use black magic to guess, but that magic is
>    subject to change, so don't rely on it
>
> I don't mind documenting the current magic as long as the "don't rely on
> it" part is made clear.