threads / patch / 38960

patchimprove documentation for some commands that use pathspecs

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

## tl;dr

4 messages between Mar 31, 2015 and Apr 3, 2015. Diffs are folded; open one to read it.

replies: 3people: 3as markdown or json

Joey Hess· Mar 31, 2015, 15:22 UTC · lore

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(-)

Show changes to 2 files +9 −8

Documentation/git-ls-files.txt, Documentation/git-ls-tree.txt

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

Junio C Hamano· Mar 31, 2015, 16:38 UTC · re: Joey Hess · lore

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

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.

Show 10 quoted lines

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

Duy Nguyen· Apr 3, 2015, 13:55 UTC · re: Joey Hess · lore

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

On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess <joeyh@joeyh.name> wrote:

Show 5 quoted lines

> 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

Duy Nguyen· Apr 3, 2015, 13:57 UTC · re: Joey Hess · lore

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

On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess <joeyh@joeyh.name> wrote:

Show 17 quoted lines

> 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