* [PATCH] improve documentation for some commands that use pathspecs
@ 2015-03-31 15:22 Joey Hess
2015-03-31 16:38 ` Junio C Hamano
` (2 more replies)
0 siblings, 3 replies; 4+ messages in thread
From: Joey Hess @ 2015-03-31 15:22 UTC (permalink / raw)
To: Git Mailing List
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] improve documentation for some commands that use pathspecs
2015-03-31 15:22 [PATCH] improve documentation for some commands that use pathspecs Joey Hess
@ 2015-03-31 16:38 ` Junio C Hamano
2015-04-03 13:55 ` Duy Nguyen
2015-04-03 13:57 ` Duy Nguyen
2 siblings, 0 replies; 4+ messages in thread
From: Junio C Hamano @ 2015-03-31 16:38 UTC (permalink / raw)
To: Joey Hess; +Cc: Git Mailing List
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] improve documentation for some commands that use pathspecs
2015-03-31 15:22 [PATCH] improve documentation for some commands that use pathspecs Joey Hess
2015-03-31 16:38 ` Junio C Hamano
@ 2015-04-03 13:55 ` Duy Nguyen
2015-04-03 13:57 ` Duy Nguyen
2 siblings, 0 replies; 4+ messages in thread
From: Duy Nguyen @ 2015-04-03 13:55 UTC (permalink / raw)
To: Joey Hess; +Cc: Git Mailing List
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] improve documentation for some commands that use pathspecs
2015-03-31 15:22 [PATCH] improve documentation for some commands that use pathspecs Joey Hess
2015-03-31 16:38 ` Junio C Hamano
2015-04-03 13:55 ` Duy Nguyen
@ 2015-04-03 13:57 ` Duy Nguyen
2 siblings, 0 replies; 4+ messages in thread
From: Duy Nguyen @ 2015-04-03 13:57 UTC (permalink / raw)
To: Joey Hess; +Cc: Git Mailing List
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2015-04-03 13:58 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-03-31 15:22 [PATCH] improve documentation for some commands that use pathspecs Joey Hess
2015-03-31 16:38 ` Junio C Hamano
2015-04-03 13:55 ` Duy Nguyen
2015-04-03 13:57 ` Duy Nguyen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.