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

---

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:

'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
========================================================================

On Tue, 21 Nov 2017, Kevin Daudt wrote:

On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:

quoted

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

Signed-off-by: Robert P. J. Day <redacted>

---

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

On Tue, Nov 21, 2017 at 04:47:42PM -0500, Robert P. J. Day wrote:

On Tue, 21 Nov 2017, Kevin Daudt wrote:

quoted

On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:

quoted

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

Signed-off-by: Robert P. J. Day <redacted>

---

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

On Tue, 21 Nov 2017, Kevin Daudt wrote:

On Tue, Nov 21, 2017 at 04:47:42PM -0500, Robert P. J. Day wrote:

quoted

On Tue, 21 Nov 2017, Kevin Daudt wrote:

quoted

On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:

quoted

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

Signed-off-by: Robert P. J. Day <redacted>

---

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

On Tue, 21 Nov 2017, Kevin Daudt wrote:

On Tue, Nov 21, 2017 at 04:27:59PM -0500, Robert P. J. Day wrote:

quoted

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

Signed-off-by: Robert P. J. Day <redacted>

---

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

On Tue, Nov 21, 2017 at 10:45:52PM +0100, Kevin Daudt wrote:

quoted

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

On Wed, 22 Nov 2017, Jeff King wrote:

On Tue, Nov 21, 2017 at 10:45:52PM +0100, Kevin Daudt wrote:

quoted

quoted

- * 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
========================================================================

On Thu, Nov 23, 2017 at 02:45:44AM -0500, Robert P. J. Day wrote:

quoted

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

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:

quoted

quoted

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

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

quoted

quoted

quoted

  Without a disambiguating `--`, Git makes a reasonable guess. If it
  cannot guess (because your request is ambiguous), then it will error
  out.

[...]

quoted

quoted

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