ls-files: document that pathspecs are supported

[adamchainz]

The command has taken pathspecs, not just filenames, since f0096c0 (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).

Signed-off-by: Adam Johnson me@adamj.eu

CC: Elijah Newren newren@gmail.com

[adamchainz]

/submit

[gitgitgadget-git]

Submitted as pull.1466.git.git.1678526355280.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-git-1466/adamchainz/doc-ls-files-pathspecs-v1

To fetch this version to local tag pr-git-1466/adamchainz/doc-ls-files-pathspecs-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-git-1466/adamchainz/doc-ls-files-pathspecs-v1

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Adam Johnson via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Adam Johnson <me@adamj.eu>
>
> The command has taken pathspecs, not just filenames, since f0096c06bcd
> (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).

Isn't that commit about ls-tree?  The commit does change how the
tree overlay (i.e. the --with-tree=<tree-ish> option) interacts with
the given pathspec arguments but that is only because that commit
changes how read_tree_recursive() has to be called.  The support of
pathspec matching in ls-files dates back to 56fc5108 ([PATCH]
git-ls-files: generalized pathspecs, 2005-08-21), arguably even
before the commit "generalized" the already existing path pattern
match feature.

> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 1abdd3c21c5..2f62374062c 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -21,7 +21,7 @@ SYNOPSIS
>  		[--exclude-standard]
>  		[--error-unmatch] [--with-tree=<tree-ish>]
>  		[--full-name] [--recurse-submodules]
> -		[--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
> +		[--abbrev[=<n>]] [--format=<format>] [--] [<pathspec>...]

Good.

>  DESCRIPTION
>  -----------
> @@ -127,12 +127,12 @@ OPTIONS
>  	in each directory, and the user's global exclusion file.
>  
>  --error-unmatch::
> -	If any <file> does not appear in the index, treat this as an
> +	If any <pathspec> does not appear in the index, treat this as an
>  	error (return 1).

This is no longer correct.  "If no path that matches <pathspec>
appears in the index".  When we are given <pathspec>, say '*.txt',
a path whose string is literally '*.txt' may not appear in the index,
but as long as there is a path that matches the pattern exists,
this option does not lead to an error.

> -<file>::
> +<pathspec>::
>  	Files to show. If no files are given all files which match the other

The description also needs to be updated.  "Limits the files to show
to only those that match the given pathspec" or something along that
line.

Thanks.

[adamchainz]

/submit

[gitgitgadget-git]

Submitted as pull.1466.v2.git.git.1678622116232.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-git-1466/adamchainz/doc-ls-files-pathspecs-v2

To fetch this version to local tag pr-git-1466/adamchainz/doc-ls-files-pathspecs-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-git-1466/adamchainz/doc-ls-files-pathspecs-v2

[gitgitgadget-git]

On the Git mailing list, Adam Johnson wrote (reply to this):

Thank you Junio, that's very good review feedback. Thank you for
finding the correct past commit. I am submitting an updated patch now.


On Sat, Mar 11, 2023 at 8:33 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Adam Johnson via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Adam Johnson <me@adamj.eu>
> >
> > The command has taken pathspecs, not just filenames, since f0096c06bcd
> > (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).
>
> Isn't that commit about ls-tree?  The commit does change how the
> tree overlay (i.e. the --with-tree=<tree-ish> option) interacts with
> the given pathspec arguments but that is only because that commit
> changes how read_tree_recursive() has to be called.  The support of
> pathspec matching in ls-files dates back to 56fc5108 ([PATCH]
> git-ls-files: generalized pathspecs, 2005-08-21), arguably even
> before the commit "generalized" the already existing path pattern
> match feature.
>
> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> > index 1abdd3c21c5..2f62374062c 100644
> > --- a/Documentation/git-ls-files.txt
> > +++ b/Documentation/git-ls-files.txt
> > @@ -21,7 +21,7 @@ SYNOPSIS
> >               [--exclude-standard]
> >               [--error-unmatch] [--with-tree=<tree-ish>]
> >               [--full-name] [--recurse-submodules]
> > -             [--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
> > +             [--abbrev[=<n>]] [--format=<format>] [--] [<pathspec>...]
>
> Good.
>
> >  DESCRIPTION
> >  -----------
> > @@ -127,12 +127,12 @@ OPTIONS
> >       in each directory, and the user's global exclusion file.
> >
> >  --error-unmatch::
> > -     If any <file> does not appear in the index, treat this as an
> > +     If any <pathspec> does not appear in the index, treat this as an
> >       error (return 1).
>
> This is no longer correct.  "If no path that matches <pathspec>
> appears in the index".  When we are given <pathspec>, say '*.txt',
> a path whose string is literally '*.txt' may not appear in the index,
> but as long as there is a path that matches the pattern exists,
> this option does not lead to an error.
>
> > -<file>::
> > +<pathspec>::
> >       Files to show. If no files are given all files which match the other
>
> The description also needs to be updated.  "Limits the files to show
> to only those that match the given pathspec" or something along that
> line.
>
> Thanks.