[PATCH v2] gitcli: tweak "man gitcli" for clarity

[PATCH v2] gitcli: 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..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
========================================================================

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Kevin Daudt]

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?

>     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 v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

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

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Kevin Daudt]

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.

Kevin

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

On Tue, 21 Nov 2017, Kevin Daudt wrote:

> 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.

  all right, i will ponder this ... open to suggestions. i would have
to examine the heuristic itself, wondering if it can make the wrong
decision on occasion.

rday

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

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?

  even if there is ambiguity, will git actually "error out"? i have a
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?

rday

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Junio C Hamano]

"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.

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

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

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Kevin Daudt]

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
 

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

On Wed, 22 Nov 2017, Kevin Daudt wrote:

> 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

  fair enough, i'll go back and reword to refer to actual
disambiguation errors.

rday

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Jeff King]

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.

-Peff

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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.

Splitting it into two sentences like you did makes it even clearer,
I would think.

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Robert P. J. Day]

On Wed, 22 Nov 2017, Jeff King wrote:

> 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.

  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?

rday

-- 

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

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Jeff King]

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

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Kevin Daudt]

On Thu, Nov 23, 2017 at 08:51:55AM -0500, Jeff King wrote:
> 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.

Might be worth documenting this.

Kevin

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Junio C Hamano]

Kevin Daudt <me@ikke.info> writes:

> 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.

I know you understand all of this, but your "git could" needs to be
examined carefully.

The same can be said for "git log master deleted_file.txt" whose
intention is to refer to a file that the user _thinks_ existed once
in the past but may never have been there.

Surely, "git could" know if it runs "git log master" to the root of
the history to see if it ever existed.  Also, against "git log
master next deleted_file.txt", "git could" do the same traversal from
two tips of the history to check that.  But it requires us to do the
same work twice to materialize that "git could".

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".

The message "unknown revision or path not in the working tree."
clearly shows why we decided to ask.  Even if deleted_file.txt could
have been a valid path somewhere in the history, "not in the working
tree" is the condition we check to see if it is unambiguous.  And we
stop and ask when it cannot be proven cheaply that it is not.

"git stops and asks when ambiguous" is a white lie to explain the
safety feature in a way that is easier to understand.  If somebody
wants to make the documentation more "technically correct", the
condition is not "when ambiguous", but "when git cannot prove it is
not unambiguous with inexpensive tests".

IIRC, I think Peff mentioned in this or nearby thread that we do not
want to spell out the implementation details and leave the exact
conditions vague on purpose, and that principle probably would apply
here, too.  We might later discover that checking not just the working
tree but also for the index to see if user meant by deleted_file.txt
a path and not a revision is not overly expensive, for example, and
at that point, we are still trying to prove that it is unambiguously
a path and not a rev with inexpensive tests.

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Jeff King]

On Fri, Nov 24, 2017 at 10:01:41AM +0900, Junio C Hamano wrote:

> 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".

I just sent a similar response before reading this, and agree with
everything you said.

But I wanted to point out this "we must also look for ambiguities"
argument, because I totally missed it in my response. And it's much more
damning, I think, because it means you can never short-cut the easy
cases and say "OK, we found the path, therefore we can stop our
traversal early". To behave consistently, you have to always do the
whole traversal twice.

-Peff

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Jeff King]

On Thu, Nov 23, 2017 at 09:55:03PM +0100, Kevin Daudt wrote:

> > > >   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:

Right, I was focused on what the sentence _currently_ said, and didn't
think about other cases. The "cannot guess" case is not just due to
ambiguity, but may be due to other heuristics.

I _think_ the only one is the "does it exist in the working tree" rule
you found, but I'm not sure we'd want to commit ourselves to never
changing that.

You could make my suggestion correct by putting "e.g.," or "for example"
at the front of the parentheses. ;)

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.

>   $ 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.

For that command, yes. But when the command is "git log", do we really
want to dig through all of history to see if anybody ever mentions
"deleted_file"?

I'm not sure if we want to get into having different rules for different
contexts. Not to mention that this really mixes up the layers; you
cannot know what the whole command line means until you decide what
abc123 means and examine it, which may in turn be influenced by other
options. E.g., given:

  git log --no-merges A..B deleted_file.txt

we have to actually do the no-merges log of A..B to see if
deleted_file.txt is in there.

-Peff

Re: [PATCH v2] gitcli: tweak "man gitcli" for clarity

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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.

Yes, taken with "git log master" example where if we want to say
"this truly cannot be ambiguous" and end up digging "git log HEAD --"
to ensure there is no path that match 'master' ever existed, I would
prefer not to say a lot more about "black magic" and yet still going
into the precise details.

On the other hand, of course we do not want to cast in stone the
precise details of the current "black magic" implementation that is
subject to change.

A description of "black magic" that is without details, i.e. the one
that focuses on the spirit and not the exact design, would be...

    Without "--", Git tries to find a point between two arguments on
    (or at the beginning or the end of) the command line, where
    every argument before it are likely to be a revision (and
    unlikely to be a path) and every argument after it are likely to
    be a path (and unlikely to be a revision) with "black magic".
    If there is no such point, you'd be asked to disambiguate.

    The "black magic" would use 4 combinations that results from
    two tests.  

    A. Is it likely to be a revision (yes/no)?
    B. Is it likely to be a path (yes/no)?

    If both are true, it is am ambigous command line.  If neither is
    true, it is likely a typo (e.g. "git log naster" when the user
    meant 'master', or "git log Nakefile" when the user meant
    'Makefile').  If only one is true, Git thinks that the command
    line is unambigous and goes ahead with its decision.

    Git will not spend excess amount of cycles to make these two
    tests, so there can be misidentification.  Two easy to
    understand examples are:

    - If you have a file 'naster' in your working tree and said "git
      log naster", test A _could_ notice that there is a slightly
      different name 'master' that could be a revision that you
      meant, and ask you to disambiguate in case you made a typo.
      Because test A (deliberately) is not overly thorough, Git does
      not flag it as a possible ambiguity.

    - If you had a file whose name is "Nakefile" in HEAD but you
      just removed it, "git log Nakefile" may actually be a valid
      and unambigous request to use Nakefile as a path, but in order
      to notice that possibility, Git has to not just check if the
      working tree has such a path, but also in the index and HEAD
      (and if the removal was older, then it has to do an internal
      "git log" to see what paths ever existed in the past, which is
      ridiculous).  Because test B (deliberately) is not overly
      thorough, Git would refuse to use it as either a revision or a
      path without disambiguation.