| Message ID | xmqqk15vj8aw.fsf@gitster-ct.c.googlers.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Re* Potential Issue with ls-tree documentation | expand |
On Mon, Jan 13, 2020 at 2:37 PM Junio C Hamano <gitster@pobox.com> wrote: > > Kevin Bowersox <kevin.m.bowersox@gmail.com> writes: > > > 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. This is unreadable, IMO. I don't understand what it's even trying to say. > > 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. Ah, much better. But... > > 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. This is much better; but it's still not parseable in my opinion. Most of this long sentence is much improved but the phrase "e.g. so specifying directory name (without `-r`) will behave differently" still seems quite difficult to understand. Possible permutations I run through in my head while trying to read that: Specifying a directory name behaves differently than specifying a file? But only if -r is not specified? Or is ls-tree output for a directory different than /bin/ls output for a directory? But I thought ls-tree output was different than /bin/ls in all cases, not just for directories?? Or maybe ls-tree output shows files differently if one of the pathspecs specified happens to be a directory, even if the files don't match that directory pathspec? Being relatively familiar with git and ls-tree, so that I already know my first five most natural interpretations of that sentence are incorrect, I think that sentence fragment is trying to say that ls-trees won't recurse into a specified directory (making it somewhat like the -d option of ls), but what a convoluted way of saying it. And I'm still not sure that is what it is actually trying to say. > - - 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 > >
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