[PATCH] improve documentation for some commands that use pathspecs

[PATCH] improve documentation for some commands that use pathspecs

[Joey Hess]

After being surprised that git-ls-files expands pathspecs, here's a patch
that would have saved me.
---
 Documentation/git-ls-files.txt | 9 +++++----
 Documentation/git-ls-tree.txt  | 8 ++++----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index e26f01f..f7a3039 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
 		[--exclude-per-directory=<file>]
 		[--exclude-standard]
 		[--error-unmatch] [--with-tree=<tree-ish>]
-		[--full-name] [--abbrev] [--] [<file>...]
+		[--full-name] [--abbrev] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -101,7 +101,7 @@ OPTIONS
 
 --with-tree=<tree-ish>::
 	When using --error-unmatch to expand the user supplied
-	<file> (i.e. path pattern) arguments to paths, pretend
+	<pathspec> arguments to paths, pretend
 	that paths which were removed in the index since the
 	named <tree-ish> are still present.  Using this option
 	with `-s` or `-u` options does not make any sense.
@@ -150,9 +150,10 @@ a space) at the start of each line:
 \--::
 	Do not interpret any more arguments as options.
 
-<file>::
+<pathspec>::
 	Files to show. If no files are given all files which match the other
-	specified criteria are shown.
+	specified criteria are shown. (Note that this isn't really raw
+	pathnames, but rather a list of patterns to match.)
 
 Output
 ------
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd..58e7f64 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git ls-tree' [-d] [-r] [-t] [-l] [-z]
 	    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
-	    <tree-ish> [<path>...]
+	    <tree-ish> [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does
 in the current working directory.  Note that:
 
  - the behaviour is slightly different from that of "/bin/ls" in that the
-   '<path>' denotes just a list of patterns to match, e.g. so specifying
+   '<pathspec>' denotes just a list of patterns to match, e.g. so specifying
    directory name (without '-r') will behave differently, and order of the
    arguments does not matter.
 
- - the behaviour is similar to that of "/bin/ls" in that the '<path>' is
+ - the behaviour is similar to that of "/bin/ls" in that the '<pathspec>' is
    taken as relative to the current working directory.  E.g. when you are
    in a directory 'sub' that has a directory 'dir', you can run 'git
    ls-tree -r HEAD dir' to list the contents of the tree (that is
@@ -72,7 +72,7 @@ OPTIONS
 	Do not limit the listing to the current working directory.
 	Implies --full-name.
 
-[<path>...]::
+[<pathspec>...]::
 	When paths are given, show them (note that this isn't really raw
 	pathnames, but rather a list of patterns to match).  Otherwise
 	implicitly uses the root level of the tree as the sole path argument.
-- 
2.1.4

Re: [PATCH] improve documentation for some commands that use pathspecs

[Junio C Hamano]

Joey Hess <joeyh@joeyh.name> writes:

> After being surprised that git-ls-files expands pathspecs, here's a patch
> that would have saved me.
> ---

I have a vague recollection that we originally wanted to
consistently say pathspec but some "user friendliness" folks wanted
to avoid the term as much as possible---blaming might reveal this
may be reverting the description to the original ;-).

I like the general direction, but please sign-off your patch.

> @@ -150,9 +150,10 @@ a space) at the start of each line:
>  \--::
>  	Do not interpret any more arguments as options.
>  
> -<file>::
> +<pathspec>::
>  	Files to show. If no files are given all files which match the other
> -	specified criteria are shown.
> +	specified criteria are shown. (Note that this isn't really raw
> +	pathnames, but rather a list of patterns to match.)

After updating the heading to <pathspec>, it would be clear that it
is not listing filename but a specification to choose path with.  I
do not see the need for this added "Note that".

Perhaps what you need to update is the first sentence "Files to
show".  It is more like "Limit the paths to show with." or
something, perhaps?  Then the "If no files are given" part (which is
wrong after your patch, because this is no longer talking about
giving any "file") can go.  By default we show everything, and
use of pathspecs is merely one of the ways to limit the output, and
you would not want to repeat "if this option is not given, all paths
that match the other specified criteria are shown" to all the other
options that limit what is shown.

Re: [PATCH] improve documentation for some commands that use pathspecs

[Duy Nguyen]

On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess <joeyh@joeyh.name> wrote:
> After being surprised that git-ls-files expands pathspecs, here's a patch
> that would have saved me.
> ---
>  Documentation/git-ls-files.txt | 9 +++++----
>  Documentation/git-ls-tree.txt  | 8 ++++----

ls-tree only supports straight file or directory paths, no globbing or
other magic (except ":/") so I'm not sure if we should change its man
page now.  On the bright side, if you use unsupported pathspec feature
on ls-tree, it'll reject, so not so bad.
-- 
Duy

Re: [PATCH] improve documentation for some commands that use pathspecs

[Duy Nguyen]

On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess <joeyh@joeyh.name> wrote:
> After being surprised that git-ls-files expands pathspecs, here's a patch
> that would have saved me.
> ---
>  Documentation/git-ls-files.txt | 9 +++++----
>  Documentation/git-ls-tree.txt  | 8 ++++----
>  2 files changed, 9 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index e26f01f..f7a3039 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -17,7 +17,7 @@ SYNOPSIS
>                 [--exclude-per-directory=<file>]
>                 [--exclude-standard]
>                 [--error-unmatch] [--with-tree=<tree-ish>]
> -               [--full-name] [--abbrev] [--] [<file>...]
> +               [--full-name] [--abbrev] [--] [<pathspec>...]

Just a note that "git ls-files -h" still says "<file>", from
ls_files_usage in builtin/ls-files.c
-- 
Duy