Re* Potential Issue with ls-tree documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jan 13, 2020, 22:33 UTC
- Message-ID
- <xmqqk15vj8aw.fsf@gitster-ct.c.googlers.com>
- In-Reply-To
- <18b8b8fd-ee38-e1bf-8fae-b719b7b78a75@gmail.com>
Kevin Bowersox <kevin.m.bowersox@gmail.com> writes:
Show 10 quoted lines
> Within the ls-tree documentation for Git found here: > https://git-scm.com/docs/git-ls-tree > <https://git-scm.com/docs/git-ls-tree> > > It mentions the following: > > 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 > directory name (without |-r|) will behave differently, and order of > the arguments does not matter.
The above description is solely focused on the pathspec part of the argument list and the text needs to clarify that. In other words, the above paragraph only wants to say:
Among the paths in the given tree-ish, a subset of paths are
chosen to be shown by using pathspec, and the way these pathspec
arguments are used is different from how "/bin/ls" uses its
arguments.The "order of the arguments" part is better read as if there is the word "pathspec" before "arguments" for clarity. As the synopsis makes it clear, <tree-ish> must come before the pathspec, so the order of that part would not be flexible, obviously.
Thanks.
Perhaps something like this?
-- >8 -- Subject: ls-tree doc: clarify and modernize pathspec description
We have been updating our docs to consistently say <pathspec> when an argument is one and not a path; "ls-tree" takes a tree-ish and optionally pathspec, so use the correct term.
It is correct that the order of pathspec arguments do not make a difference in the output unlike the order of path arguments given to "/bin/ls", but the existing documentation can be misread to allow having even the <tree-ish> argument at a random place on the command line, which obviously was not what the original authors intended to say. Clarify it.
Noticed-by: Kevin Bowersox <kevin.m.bowersox@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-ls-tree.txt | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index a7515714da..aa368a8d14 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -11,19 +11,20 @@ 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 ----------- 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 - directory name (without `-r`) will behave differently, and order of the + - The way <pathspec> is used is slightly different from how "/bin/ls" uses + its paths arguments, in that '<pathspec>' denotes just a list of + patterns to match, e.g. so specifying directory name (without + `-r`) will behave differently, and the order of the pathspec 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 @@ -73,10 +74,8 @@ OPTIONS Do not limit the listing to the current working directory. Implies --full-name. -[<path>...]:: - 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. +[<pathspec>...]:: + When pathspec is given, only show paths that match the pattern. Output Format