* Potential Issue with ls-tree documentation @ 2020-01-11 9:46 Kevin Bowersox 2020-01-13 22:33 ` Re* " Junio C Hamano 0 siblings, 1 reply; 3+ messages in thread From: Kevin Bowersox @ 2020-01-11 9:46 UTC (permalink / raw) To: git 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. I'm wondering if this statement is accurate. Here is my reasoning: When using this form of the command: git ls-tree <tree-ish> [<path>] the <tree-ish> (assuming this is typically a branch name) must be specified prior to the path, making the order of the arguments matter when issuing the command. If my reasoning is correct I would be glad to submit the changes for review/merge. Appreciate any insights. Kevin Bowersox ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re* Potential Issue with ls-tree documentation 2020-01-11 9:46 Potential Issue with ls-tree documentation Kevin Bowersox @ 2020-01-13 22:33 ` Junio C Hamano 2020-01-13 22:55 ` Elijah Newren 0 siblings, 1 reply; 3+ messages in thread From: Junio C Hamano @ 2020-01-13 22:33 UTC (permalink / raw) To: Kevin Bowersox; +Cc: git 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. 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 ^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: Re* Potential Issue with ls-tree documentation 2020-01-13 22:33 ` Re* " Junio C Hamano @ 2020-01-13 22:55 ` Elijah Newren 0 siblings, 0 replies; 3+ messages in thread From: Elijah Newren @ 2020-01-13 22:55 UTC (permalink / raw) To: Junio C Hamano; +Cc: Kevin Bowersox, Git Mailing List 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 > > ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-01-13 22:55 UTC | newest] Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-01-11 9:46 Potential Issue with ls-tree documentation Kevin Bowersox 2020-01-13 22:33 ` Re* " Junio C Hamano 2020-01-13 22:55 ` Elijah Newren
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).