{"thread":{"id":"52614","subject":"Potential Issue with ls-tree documentation","startedAt":"2020-01-11T09:46:37Z","lastAt":"2020-01-13T22:55:47Z","messageCount":3,"participants":["Kevin Bowersox","Junio C Hamano","Elijah Newren"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"389605","messageId":"18b8b8fd-ee38-e1bf-8fae-b719b7b78a75@gmail.com","threadId":"52614","inReplyTo":null,"subject":"Potential Issue with ls-tree documentation","fromName":"Kevin Bowersox","fromEmail":"kevin.m.bowersox@gmail.com","sentAt":"2020-01-11T09:46:33Z","receivedAt":"2020-01-11T09:46:37Z","isPatch":false,"sender":{"key":"kevin.m.bowersox@gmail.com","avatar":null},"body":"Within the ls-tree documentation for Git found here: \nhttps://git-scm.com/docs/git-ls-tree <https://git-scm.com/docs/git-ls-tree>\n\nIt mentions the following:\n\nthe behaviour is slightly different from that of \"/bin/ls\" in that the \n<path> denotes just a list of patterns to match, e.g. so specifying \ndirectory name (without |-r|) will behave differently, and order of the \narguments does not matter.\n\nI'm wondering if this statement is accurate.  Here is my reasoning:\n\nWhen using this form of the command:\n\ngit ls-tree <tree-ish> [<path>]\n\nthe <tree-ish> (assuming this is typically a branch name) must be \nspecified prior to the path, making the order of the arguments matter \nwhen issuing the command.\n\nIf my reasoning is correct I would be glad to submit the changes for \nreview/merge.\n\nAppreciate any insights.\n\nKevin Bowersox\n"},{"id":"389729","messageId":"xmqqk15vj8aw.fsf@gitster-ct.c.googlers.com","threadId":"52614","inReplyTo":"18b8b8fd-ee38-e1bf-8fae-b719b7b78a75@gmail.com","subject":"Re* Potential Issue with ls-tree documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-13T22:33:27Z","receivedAt":"2020-01-13T22:33:37Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kevin Bowersox <kevin.m.bowersox@gmail.com> writes:\n\n> Within the ls-tree documentation for Git found here:\n> https://git-scm.com/docs/git-ls-tree\n> <https://git-scm.com/docs/git-ls-tree>\n>\n> It mentions the following:\n>\n> the behaviour is slightly different from that of \"/bin/ls\" in that the\n> <path> denotes just a list of patterns to match, e.g. so specifying\n> directory name (without |-r|) will behave differently, and order of\n> the arguments does not matter.\n\nThe above description is solely focused on the pathspec part of the\nargument list and the text needs to clarify that.  In other words,\nthe above paragraph only wants to say:\n\n    Among the paths in the given tree-ish, a subset of paths are\n    chosen to be shown by using pathspec, and the way these pathspec\n    arguments are used is different from how \"/bin/ls\" uses its\n    arguments.\n\nThe \"order of the arguments\" part is better read as if there is\nthe word \"pathspec\" before \"arguments\" for clarity.  As the synopsis\nmakes it clear, <tree-ish> must come before the pathspec, so the\norder of that part would not be flexible, obviously.\n\nThanks.\n\nPerhaps something like this?\n\n-- >8 --\nSubject: ls-tree doc: clarify and modernize pathspec description\n\nWe have been updating our docs to consistently say <pathspec> when\nan argument is one and not a path; \"ls-tree\" takes a tree-ish and\noptionally pathspec, so use the correct term.\n\nIt is correct that the order of pathspec arguments do not make a\ndifference in the output unlike the order of path arguments given to\n\"/bin/ls\", but the existing documentation can be misread to allow\nhaving even the <tree-ish> argument at a random place on the command\nline, which obviously was not what the original authors intended to\nsay.  Clarify it.\n\nNoticed-by: Kevin Bowersox <kevin.m.bowersox@gmail.com>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-ls-tree.txt | 17 ++++++++---------\n 1 file changed, 8 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex a7515714da..aa368a8d14 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -11,19 +11,20 @@ SYNOPSIS\n [verse]\n 'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n \t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]\n-\t    <tree-ish> [<path>...]\n+\t    <tree-ish> [<pathspec>...]\n \n DESCRIPTION\n -----------\n Lists the contents of a given tree object, like what \"/bin/ls -a\" does\n in the current working directory.  Note that:\n \n- - the behaviour is slightly different from that of \"/bin/ls\" in that the\n-   '<path>' denotes just a list of patterns to match, e.g. so specifying\n-   directory name (without `-r`) will behave differently, and order of the\n+ - The way <pathspec> is used is slightly different from how \"/bin/ls\" uses\n+   its paths arguments, in that '<pathspec>' denotes just a list of\n+   patterns to match, e.g. so specifying directory name (without\n+   `-r`) will behave differently, and the order of the pathspec\n    arguments does not matter.\n \n- - the behaviour is similar to that of \"/bin/ls\" in that the '<path>' is\n+ - the behaviour is similar to that of \"/bin/ls\" in that the '<pathspec>' is\t\n    taken as relative to the current working directory.  E.g. when you are\n    in a directory 'sub' that has a directory 'dir', you can run 'git\n    ls-tree -r HEAD dir' to list the contents of the tree (that is\n@@ -73,10 +74,8 @@ OPTIONS\n \tDo not limit the listing to the current working directory.\n \tImplies --full-name.\n \n-[<path>...]::\n-\tWhen paths are given, show them (note that this isn't really raw\n-\tpathnames, but rather a list of patterns to match).  Otherwise\n-\timplicitly uses the root level of the tree as the sole path argument.\n+[<pathspec>...]::\n+\tWhen pathspec is given, only show paths that match the pattern.\n \n \n Output Format\n\n\n"},{"id":"389730","messageId":"CABPp-BHgZdMnyiA_w-vCJTqj7aBcf4or0ABmSYui-HbMp=XVNw@mail.gmail.com","threadId":"52614","inReplyTo":"xmqqk15vj8aw.fsf@gitster-ct.c.googlers.com","subject":"Re: Re* Potential Issue with ls-tree documentation","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2020-01-13T22:55:33Z","receivedAt":"2020-01-13T22:55:47Z","isPatch":false,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Jan 13, 2020 at 2:37 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Kevin Bowersox <kevin.m.bowersox@gmail.com> writes:\n>\n> > Within the ls-tree documentation for Git found here:\n> > https://git-scm.com/docs/git-ls-tree\n> > <https://git-scm.com/docs/git-ls-tree>\n> >\n> > It mentions the following:\n> >\n> > the behaviour is slightly different from that of \"/bin/ls\" in that the\n> > <path> denotes just a list of patterns to match, e.g. so specifying\n> > directory name (without |-r|) will behave differently, and order of\n> > the arguments does not matter.\n\nThis is unreadable, IMO.  I don't understand what it's even trying to say.\n\n>\n> The above description is solely focused on the pathspec part of the\n> argument list and the text needs to clarify that.  In other words,\n> the above paragraph only wants to say:\n>\n>     Among the paths in the given tree-ish, a subset of paths are\n>     chosen to be shown by using pathspec, and the way these pathspec\n>     arguments are used is different from how \"/bin/ls\" uses its\n>     arguments.\n\nAh, much better.  But...\n\n>\n> The \"order of the arguments\" part is better read as if there is\n> the word \"pathspec\" before \"arguments\" for clarity.  As the synopsis\n> makes it clear, <tree-ish> must come before the pathspec, so the\n> order of that part would not be flexible, obviously.\n>\n> Thanks.\n>\n> Perhaps something like this?\n>\n> -- >8 --\n> Subject: ls-tree doc: clarify and modernize pathspec description\n>\n> We have been updating our docs to consistently say <pathspec> when\n> an argument is one and not a path; \"ls-tree\" takes a tree-ish and\n> optionally pathspec, so use the correct term.\n>\n> It is correct that the order of pathspec arguments do not make a\n> difference in the output unlike the order of path arguments given to\n> \"/bin/ls\", but the existing documentation can be misread to allow\n> having even the <tree-ish> argument at a random place on the command\n> line, which obviously was not what the original authors intended to\n> say.  Clarify it.\n>\n> Noticed-by: Kevin Bowersox <kevin.m.bowersox@gmail.com>\n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n>  Documentation/git-ls-tree.txt | 17 ++++++++---------\n>  1 file changed, 8 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\n> index a7515714da..aa368a8d14 100644\n> --- a/Documentation/git-ls-tree.txt\n> +++ b/Documentation/git-ls-tree.txt\n> @@ -11,19 +11,20 @@ SYNOPSIS\n>  [verse]\n>  'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n>             [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]\n> -           <tree-ish> [<path>...]\n> +           <tree-ish> [<pathspec>...]\n>\n>  DESCRIPTION\n>  -----------\n>  Lists the contents of a given tree object, like what \"/bin/ls -a\" does\n>  in the current working directory.  Note that:\n>\n> - - the behaviour is slightly different from that of \"/bin/ls\" in that the\n> -   '<path>' denotes just a list of patterns to match, e.g. so specifying\n> -   directory name (without `-r`) will behave differently, and order of the\n> + - The way <pathspec> is used is slightly different from how \"/bin/ls\" uses\n> +   its paths arguments, in that '<pathspec>' denotes just a list of\n> +   patterns to match, e.g. so specifying directory name (without\n> +   `-r`) will behave differently, and the order of the pathspec\n>     arguments does not matter.\n\nThis is much better; but it's still not parseable in my opinion.  Most\nof this long sentence is much improved but the phrase \"e.g. so\nspecifying directory name (without `-r`) will behave differently\"\nstill seems quite difficult to understand.  Possible permutations I\nrun through in my head while trying to read that:\n\nSpecifying a directory name behaves differently than specifying a\nfile?  But only if -r is not specified?  Or is ls-tree output for a\ndirectory different than /bin/ls output for a directory?  But I\nthought ls-tree output was different than /bin/ls in all cases, not\njust for directories??  Or maybe ls-tree output shows files\ndifferently if one of the pathspecs specified happens to be a\ndirectory, even if the files don't match that directory pathspec?\n\nBeing relatively familiar with git and ls-tree, so that I already know\nmy first five most natural interpretations of that sentence are\nincorrect, I think that sentence fragment is trying to say that\nls-trees won't recurse into a specified directory (making it somewhat\nlike the -d option of ls), but what a convoluted way of saying it.\nAnd I'm still not sure that is what it is actually trying to say.\n\n> - - the behaviour is similar to that of \"/bin/ls\" in that the '<path>' is\n> + - the behaviour is similar to that of \"/bin/ls\" in that the '<pathspec>' is\n>     taken as relative to the current working directory.  E.g. when you are\n>     in a directory 'sub' that has a directory 'dir', you can run 'git\n>     ls-tree -r HEAD dir' to list the contents of the tree (that is\n> @@ -73,10 +74,8 @@ OPTIONS\n>         Do not limit the listing to the current working directory.\n>         Implies --full-name.\n>\n> -[<path>...]::\n> -       When paths are given, show them (note that this isn't really raw\n> -       pathnames, but rather a list of patterns to match).  Otherwise\n> -       implicitly uses the root level of the tree as the sole path argument.\n> +[<pathspec>...]::\n> +       When pathspec is given, only show paths that match the pattern.\n>\n>\n>  Output Format\n>\n>\n"}]}