{"thread":{"id":"38960","subject":"[PATCH] improve documentation for some commands that use pathspecs","startedAt":"2015-03-31T15:22:24Z","lastAt":"2015-04-03T13:57:45Z","messageCount":4,"participants":["Joey Hess","Junio C Hamano","Duy Nguyen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"258745","messageId":"20150331152224.GA16617@kitenet.net","threadId":"38960","inReplyTo":null,"subject":"[PATCH] improve documentation for some commands that use pathspecs","fromName":"Joey Hess","fromEmail":"joeyh@joeyh.name","sentAt":"2015-03-31T15:22:24Z","receivedAt":"2015-03-31T15:22:24Z","isPatch":true,"sender":{"key":"joeyh@joeyh.name","avatar":"https://avatars.githubusercontent.com/u/16392?v=4"},"body":"After being surprised that git-ls-files expands pathspecs, here's a patch\nthat would have saved me.\n---\n Documentation/git-ls-files.txt | 9 +++++----\n Documentation/git-ls-tree.txt | 8 ++++----\n 2 files changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex e26f01f..f7a3039 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -17,7 +17,7 @@ SYNOPSIS\n \t\t[--exclude-per-directory=]\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=]\n-\t\t[--full-name] [--abbrev] [--] [...]\n+\t\t[--full-name] [--abbrev] [--] [...]\n \n DESCRIPTION\n -----------\n@@ -101,7 +101,7 @@ OPTIONS\n \n --with-tree=::\n \tWhen using --error-unmatch to expand the user supplied\n-\t (i.e. path pattern) arguments to paths, pretend\n+\t arguments to paths, pretend\n \tthat paths which were removed in the index since the\n \tnamed are still present. Using this option\n \twith `-s` or `-u` options does not make any sense.\n@@ -150,9 +150,10 @@ a space) at the start of each line:\n \\--::\n \tDo not interpret any more arguments as options.\n \n-::\n+::\n \tFiles to show. If no files are given all files which match the other\n-\tspecified criteria are shown.\n+\tspecified criteria are shown. (Note that this isn't really raw\n+\tpathnames, but rather a list of patterns to match.)\n \n Output\n ------\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex 16e87fd..58e7f64 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n \t [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=]]\n-\t [...]\n+\t [...]\n \n DESCRIPTION\n -----------\n@@ -19,11 +19,11 @@ 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- '' denotes just a list of patterns to match, e.g. so specifying\n+ '' 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 arguments does not matter.\n \n- - the behaviour is similar to that of \"/bin/ls\" in that the '' is\n+ - the behaviour is similar to that of \"/bin/ls\" in that the '' 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@@ -72,7 +72,7 @@ OPTIONS\n \tDo not limit the listing to the current working directory.\n \tImplies --full-name.\n \n-[...]::\n+[...]::\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-- \n2.1.4\n"},{"id":"258747","messageId":"xmqqd23prukg.fsf@gitster.dls.corp.google.com","threadId":"38960","inReplyTo":"20150331152224.GA16617@kitenet.net","subject":"Re: [PATCH] improve documentation for some commands that use pathspecs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-31T16:38:23Z","receivedAt":"2015-03-31T16:38:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Joey Hess writes:\n\n> After being surprised that git-ls-files expands pathspecs, here's a patch\n> that would have saved me.\n> ---\n\nI have a vague recollection that we originally wanted to\nconsistently say pathspec but some \"user friendliness\" folks wanted\nto avoid the term as much as possible---blaming might reveal this\nmay be reverting the description to the original ;-).\n\nI like the general direction, but please sign-off your patch.\n\n> @@ -150,9 +150,10 @@ a space) at the start of each line:\n> \\--::\n> \tDo not interpret any more arguments as options.\n> \n> -::\n> +::\n> \tFiles to show. If no files are given all files which match the other\n> -\tspecified criteria are shown.\n> +\tspecified criteria are shown. (Note that this isn't really raw\n> +\tpathnames, but rather a list of patterns to match.)\n\nAfter updating the heading to , it would be clear that it\nis not listing filename but a specification to choose path with. I\ndo not see the need for this added \"Note that\".\n\nPerhaps what you need to update is the first sentence \"Files to\nshow\". It is more like \"Limit the paths to show with.\" or\nsomething, perhaps? Then the \"If no files are given\" part (which is\nwrong after your patch, because this is no longer talking about\ngiving any \"file\") can go. By default we show everything, and\nuse of pathspecs is merely one of the ways to limit the output, and\nyou would not want to repeat \"if this option is not given, all paths\nthat match the other specified criteria are shown\" to all the other\noptions that limit what is shown.\n"},{"id":"258922","messageId":"CACsJy8ADrWAuCXXA92FdF6YCMwVUPrWi42tf-qD0re6xnYvHtg@mail.gmail.com","threadId":"38960","inReplyTo":"20150331152224.GA16617@kitenet.net","subject":"Re: [PATCH] improve documentation for some commands that use pathspecs","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2015-04-03T13:55:48Z","receivedAt":"2015-04-03T13:55:48Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess wrote:\n> After being surprised that git-ls-files expands pathspecs, here's a patch\n> that would have saved me.\n> ---\n> Documentation/git-ls-files.txt | 9 +++++----\n> Documentation/git-ls-tree.txt | 8 ++++----\n\nls-tree only supports straight file or directory paths, no globbing or\nother magic (except \":/\") so I'm not sure if we should change its man\npage now. On the bright side, if you use unsupported pathspec feature\non ls-tree, it'll reject, so not so bad.\n-- \nDuy\n"},{"id":"258923","messageId":"CACsJy8AW0vj2SWpzocJpXkrgJB93x8Zb1p9YVQZE1SVh4G7COg@mail.gmail.com","threadId":"38960","inReplyTo":"20150331152224.GA16617@kitenet.net","subject":"Re: [PATCH] improve documentation for some commands that use pathspecs","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2015-04-03T13:57:45Z","receivedAt":"2015-04-03T13:57:45Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Mar 31, 2015 at 10:22 PM, Joey Hess wrote:\n> After being surprised that git-ls-files expands pathspecs, here's a patch\n> that would have saved me.\n> ---\n> Documentation/git-ls-files.txt | 9 +++++----\n> Documentation/git-ls-tree.txt | 8 ++++----\n> 2 files changed, 9 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index e26f01f..f7a3039 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -17,7 +17,7 @@ SYNOPSIS\n> [--exclude-per-directory=]\n> [--exclude-standard]\n> [--error-unmatch] [--with-tree=]\n> - [--full-name] [--abbrev] [--] [...]\n> + [--full-name] [--abbrev] [--] [...]\n\nJust a note that \"git ls-files -h\" still says \"\", from\nls_files_usage in builtin/ls-files.c\n-- \nDuy\n"}]}