{"thread":{"id":"59377","subject":"[PATCH] ls-files: document that pathspecs are supported","startedAt":"2023-03-11T09:20:48Z","lastAt":"2023-03-12T11:55:23Z","messageCount":4,"participants":["Adam Johnson via GitGitGadget","Junio C Hamano","Adam Johnson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"473400","messageId":"pull.1466.git.git.1678526355280.gitgitgadget@gmail.com","threadId":"59377","inReplyTo":null,"subject":"[PATCH] ls-files: document that pathspecs are supported","fromName":"Adam Johnson via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-03-11T09:19:15Z","receivedAt":"2023-03-11T09:20:48Z","isPatch":true,"sender":{"key":"me@adamj.eu","avatar":"https://avatars.githubusercontent.com/u/857609?v=4"},"body":"From: Adam Johnson \n\nThe command has taken pathspecs, not just filenames, since f0096c06bcd\n(Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n\nSigned-off-by: Adam Johnson \n---\n ls-files: document that pathspecs are supported\n \n The command has taken pathspecs, not just filenames, since f0096c06bcd\n (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n \n Signed-off-by: Adam Johnson me@adamj.eu\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1466%2Fadamchainz%2Fdoc-ls-files-pathspecs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1466/adamchainz/doc-ls-files-pathspecs-v1\nPull-Request: https://github.com/git/git/pull/1466\n\n Documentation/git-ls-files.txt | 11 +++++++----\n 1 file changed, 7 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 1abdd3c21c5..2f62374062c 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -21,7 +21,7 @@ SYNOPSIS\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=]\n \t\t[--full-name] [--recurse-submodules]\n-\t\t[--abbrev[=]] [--format=] [--] [...]\n+\t\t[--abbrev[=]] [--format=] [--] [...]\n \n DESCRIPTION\n -----------\n@@ -127,12 +127,12 @@ OPTIONS\n \tin each directory, and the user's global exclusion file.\n \n --error-unmatch::\n-\tIf any does not appear in the index, treat this as an\n+\tIf any does not appear in the index, treat this as an\n \terror (return 1).\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 (i.e. path pattern) 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@@ -225,9 +225,12 @@ followed by the (\"attr/\").\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++\n+For details on the syntax, see the 'pathspec' entry in\n+linkgit:gitglossary[7].\n \n OUTPUT\n ------\n\nbase-commit: 725f57037d81e24eacfda6e59a19c60c0b4c8062\n-- \ngitgitgadget\n"},{"id":"473406","messageId":"xmqqzg8jxc2r.fsf@gitster.g","threadId":"59377","inReplyTo":"pull.1466.git.git.1678526355280.gitgitgadget@gmail.com","subject":"Re: [PATCH] ls-files: document that pathspecs are supported","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-11T20:33:32Z","receivedAt":"2023-03-11T20:34:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Adam Johnson via GitGitGadget\" writes:\n\n> From: Adam Johnson \n>\n> The command has taken pathspecs, not just filenames, since f0096c06bcd\n> (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n\nIsn't that commit about ls-tree? The commit does change how the\ntree overlay (i.e. the --with-tree= option) interacts with\nthe given pathspec arguments but that is only because that commit\nchanges how read_tree_recursive() has to be called. The support of\npathspec matching in ls-files dates back to 56fc5108 ([PATCH]\ngit-ls-files: generalized pathspecs, 2005-08-21), arguably even\nbefore the commit \"generalized\" the already existing path pattern\nmatch feature.\n\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index 1abdd3c21c5..2f62374062c 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -21,7 +21,7 @@ SYNOPSIS\n> \t\t[--exclude-standard]\n> \t\t[--error-unmatch] [--with-tree=]\n> \t\t[--full-name] [--recurse-submodules]\n> -\t\t[--abbrev[=]] [--format=] [--] [...]\n> +\t\t[--abbrev[=]] [--format=] [--] [...]\n\nGood.\n\n> DESCRIPTION\n> -----------\n> @@ -127,12 +127,12 @@ OPTIONS\n> \tin each directory, and the user's global exclusion file.\n> \n> --error-unmatch::\n> -\tIf any does not appear in the index, treat this as an\n> +\tIf any does not appear in the index, treat this as an\n> \terror (return 1).\n\nThis is no longer correct. \"If no path that matches \nappears in the index\". When we are given , say '*.txt',\na path whose string is literally '*.txt' may not appear in the index,\nbut as long as there is a path that matches the pattern exists,\nthis option does not lead to an error.\n\n> -::\n> +::\n> \tFiles to show. If no files are given all files which match the other\n\nThe description also needs to be updated. \"Limits the files to show\nto only those that match the given pathspec\" or something along that\nline.\n\nThanks.\n"},{"id":"473413","messageId":"CAMyDDM3VyCdwOLhay0PC8G6azoWCFpxoB1K76mvo5nd2C+sfCg@mail.gmail.com","threadId":"59377","inReplyTo":"xmqqzg8jxc2r.fsf@gitster.g","subject":"Re: [PATCH] ls-files: document that pathspecs are supported","fromName":"Adam Johnson","fromEmail":"me@adamj.eu","sentAt":"2023-03-12T11:52:54Z","receivedAt":"2023-03-12T11:53:12Z","isPatch":true,"sender":{"key":"me@adamj.eu","avatar":"https://avatars.githubusercontent.com/u/857609?v=4"},"body":"Thank you Junio, that's very good review feedback. Thank you for\nfinding the correct past commit. I am submitting an updated patch now.\n\n\nOn Sat, Mar 11, 2023 at 8:33 PM Junio C Hamano wrote:\n>\n> \"Adam Johnson via GitGitGadget\" writes:\n>\n> > From: Adam Johnson \n> >\n> > The command has taken pathspecs, not just filenames, since f0096c06bcd\n> > (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n>\n> Isn't that commit about ls-tree? The commit does change how the\n> tree overlay (i.e. the --with-tree= option) interacts with\n> the given pathspec arguments but that is only because that commit\n> changes how read_tree_recursive() has to be called. The support of\n> pathspec matching in ls-files dates back to 56fc5108 ([PATCH]\n> git-ls-files: generalized pathspecs, 2005-08-21), arguably even\n> before the commit \"generalized\" the already existing path pattern\n> match feature.\n>\n> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > index 1abdd3c21c5..2f62374062c 100644\n> > --- a/Documentation/git-ls-files.txt\n> > +++ b/Documentation/git-ls-files.txt\n> > @@ -21,7 +21,7 @@ SYNOPSIS\n> > [--exclude-standard]\n> > [--error-unmatch] [--with-tree=]\n> > [--full-name] [--recurse-submodules]\n> > - [--abbrev[=]] [--format=] [--] [...]\n> > + [--abbrev[=]] [--format=] [--] [...]\n>\n> Good.\n>\n> > DESCRIPTION\n> > -----------\n> > @@ -127,12 +127,12 @@ OPTIONS\n> > in each directory, and the user's global exclusion file.\n> >\n> > --error-unmatch::\n> > - If any does not appear in the index, treat this as an\n> > + If any does not appear in the index, treat this as an\n> > error (return 1).\n>\n> This is no longer correct. \"If no path that matches \n> appears in the index\". When we are given , say '*.txt',\n> a path whose string is literally '*.txt' may not appear in the index,\n> but as long as there is a path that matches the pattern exists,\n> this option does not lead to an error.\n>\n> > -::\n> > +::\n> > Files to show. If no files are given all files which match the other\n>\n> The description also needs to be updated. \"Limits the files to show\n> to only those that match the given pathspec\" or something along that\n> line.\n>\n> Thanks.\n"},{"id":"473414","messageId":"pull.1466.v2.git.git.1678622116232.gitgitgadget@gmail.com","threadId":"59377","inReplyTo":"pull.1466.git.git.1678526355280.gitgitgadget@gmail.com","subject":"[PATCH v2] ls-files: document that pathspecs are supported","fromName":"Adam Johnson via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-03-12T11:55:16Z","receivedAt":"2023-03-12T11:55:23Z","isPatch":true,"sender":{"key":"me@adamj.eu","avatar":"https://avatars.githubusercontent.com/u/857609?v=4"},"body":"From: Adam Johnson \n\nThe command has taken pathspecs, not just filenames, since at least 56fc5108\n([PATCH] git-ls-files: generalized pathspecs, 2005-08-21).\n\nSigned-off-by: Adam Johnson \n---\n ls-files: document that pathspecs are supported\n \n The command has taken pathspecs, not just filenames, since f0096c06bcd\n (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n \n Signed-off-by: Adam Johnson me@adamj.eu\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1466%2Fadamchainz%2Fdoc-ls-files-pathspecs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1466/adamchainz/doc-ls-files-pathspecs-v2\nPull-Request: https://github.com/git/git/pull/1466\n\nRange-diff vs v1:\n\n 1: 4a0417ba8e5 ! 1: 7c95f4f5a7d ls-files: document that pathspecs are supported\n @@ Metadata\n ## Commit message ##\n ls-files: document that pathspecs are supported\n \n - The command has taken pathspecs, not just filenames, since f0096c06bcd\n - (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).\n + The command has taken pathspecs, not just filenames, since at least 56fc5108\n + ([PATCH] git-ls-files: generalized pathspecs, 2005-08-21).\n \n Signed-off-by: Adam Johnson \n \n @@ Documentation/git-ls-files.txt: OPTIONS\n \n --error-unmatch::\n -\tIf any does not appear in the index, treat this as an\n -+\tIf any does not appear in the index, treat this as an\n - \terror (return 1).\n +-\terror (return 1).\n ++\tIf no path that matches appears in the index, treat this as\n ++\tan error (return 1).\n \n --with-tree=::\n \tWhen using --error-unmatch to expand the user supplied\n @@ Documentation/git-ls-files.txt: followed by the (\"attr/\").\n \tDo not interpret any more arguments as options.\n \n -::\n +-\tFiles to show. If no files are given all files which match the other\n +::\n - \tFiles to show. If no files are given all files which match the other\n ++\tLimits the files to show to only those that match any of the given\n ++\tpathspecs. If no pathspecs are given, all files which match the other\n \tspecified criteria are shown.\n ++\n +For details on the syntax, see the 'pathspec' entry in\n\n\n Documentation/git-ls-files.txt | 16 ++++++++++------\n 1 file changed, 10 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 1abdd3c21c5..d69a46f8a56 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -21,7 +21,7 @@ SYNOPSIS\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=]\n \t\t[--full-name] [--recurse-submodules]\n-\t\t[--abbrev[=]] [--format=] [--] [...]\n+\t\t[--abbrev[=]] [--format=] [--] [...]\n \n DESCRIPTION\n -----------\n@@ -127,12 +127,12 @@ OPTIONS\n \tin each directory, and the user's global exclusion file.\n \n --error-unmatch::\n-\tIf any does not appear in the index, treat this as an\n-\terror (return 1).\n+\tIf no path that matches appears in the index, treat this as\n+\tan error (return 1).\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 (i.e. path pattern) 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@@ -225,9 +225,13 @@ followed by the (\"attr/\").\n \\--::\n \tDo not interpret any more arguments as options.\n \n-::\n-\tFiles to show. If no files are given all files which match the other\n+::\n+\tLimits the files to show to only those that match any of the given\n+\tpathspecs. If no pathspecs are given, all files which match the other\n \tspecified criteria are shown.\n++\n+For details on the syntax, see the 'pathspec' entry in\n+linkgit:gitglossary[7].\n \n OUTPUT\n ------\n\nbase-commit: 725f57037d81e24eacfda6e59a19c60c0b4c8062\n-- \ngitgitgadget\n"}]}