ls-files: document that pathspecs are supported

PATCH Superseded Adam Johnson via GitGitGadget 3 participants 4 messages Mar 11, 2023 – Mar 12, 2023 Documentation

lore

Share & tools

lore

Adam Johnson via GitGitGadget

author

2023-03-11 09:20 UTC #0 lore raw

PATCH 1/1 ls-files: document that pathspecs are supported

From: Adam Johnson <[email protected]>

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

Signed-off-by Adam Johnson <[email protected]>

---
ls-files: document that pathspecs are supported

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

Signed-off-by Adam Johnson [email protected]

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1466%2Fadamchainz%2Fdoc-ls-files-pathspecs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1466/adamchainz/doc-ls-files-pathspecs-v1
Pull-Request: https://github.com/git/git/pull/1466

 Documentation/git-ls-files.txt | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

Documentation/git-ls-files.txt +7 -4

index 1abdd3c21c5..2f62374062c 100644
@@ -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>...]
 
 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).
 
 --with-tree=<tree-ish>::
 	When using --error-unmatch to expand the user supplied
-	<file> (i.e. path pattern) arguments to paths, pretend
+	<pathspec> (i.e. path pattern) arguments to paths, pretend
 	that paths which were removed in the index since the
 	named <tree-ish> are still present.  Using this option
 	with `-s` or `-u` options does not make any sense.

@@ -225,9 +225,12 @@ followed by the  ("attr/<eolattr>").
 \--::
 	Do not interpret any more arguments as options.
 
-<file>::
+<pathspec>::
 	Files to show. If no files are given all files which match the other
 	specified criteria are shown.
++
+For details on the <pathspec> syntax, see the 'pathspec' entry in
+linkgit:gitglossary[7].
 
 OUTPUT
 ------

base-commit: 725f57037d81e24eacfda6e59a19c60c0b4c8062

Signature · 1 line

gitgitgadget

Junio C Hamano

2023-03-11 20:34 UTC #1 lore raw

Quoted 4 lines · Adam Johnson via GitGitGadget

From: Adam Johnson <[email protected]>
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.

Documentation/git-ls-files.txt SYNOPSIS · line 24

Quoted 10 lines

Documentation/git-ls-files.txt +1 -1

index 1abdd3c21c5..2f62374062c 100644
@@ -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.

Documentation/git-ls-files.txt OPTIONS · line 131

Quoted 9 lines

Documentation/git-ls-files.txt +1 -1

 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.

Documentation/git-ls-files.txt followed by the ("attr/<eolattr>"). · line 229

Quoted 3 lines

Documentation/git-ls-files.txt +1 -1

-<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.

Adam Johnson

2023-03-12 11:53 UTC #2 lore raw

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

Quoted 55 lines · Junio C Hamano

Quoted 4 lines · Adam Johnson via GitGitGadget
From: Adam Johnson <[email protected]>
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.
Documentation/git-ls-files.txt SYNOPSIS · line 24
Quoted 10 lines
Documentation/git-ls-files.txt +1 -1
index 1abdd3c21c5..2f62374062c 100644
@@ -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.
Documentation/git-ls-files.txt OPTIONS · line 131
Quoted 9 lines
Documentation/git-ls-files.txt +1 -1
 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.
Documentation/git-ls-files.txt followed by the ("attr/<eolattr>"). · line 229
Quoted 3 lines
Documentation/git-ls-files.txt +1 -1
-<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.

Adam Johnson via GitGitGadget

author

2023-03-12 11:55 UTC #3 lore raw

PATCH v2 1/1 ls-files: document that pathspecs are supported

In reply to Adam Johnson via GitGitGadget

From: Adam Johnson <[email protected]>

The command has taken pathspecs, not just filenames, since at least 56fc5108 ([PATCH] git-ls-files: generalized pathspecs, 2005-08-21).

Signed-off-by Adam Johnson <[email protected]>

---
ls-files: document that pathspecs are supported

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

Signed-off-by Adam Johnson [email protected]

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1466%2Fadamchainz%2Fdoc-ls-files-pathspecs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1466/adamchainz/doc-ls-files-pathspecs-v2
Pull-Request: https://github.com/git/git/pull/1466

Range-diff vs v1:

1: 4a0417ba8e5 ! 1: 7c95f4f5a7d ls-files: document that pathspecs are supported
@@ Metadata
## Commit message ##
ls-files: document that pathspecs are supported

- The command has taken pathspecs, not just filenames, since f0096c06bcd
- (Convert read_tree{,_recursive} to support struct pathspec, 2011-03-25).
+ The command has taken pathspecs, not just filenames, since at least 56fc5108
+ ([PATCH] git-ls-files: generalized pathspecs, 2005-08-21).

Signed-off-by Adam Johnson <[email protected]>

@@ Documentation/git-ls-files.txt: OPTIONS

--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).
+- error (return 1).
++ If no path that matches <pathspec> appears in the index, treat this as
++ an error (return 1).

--with-tree=<tree-ish>::
When using --error-unmatch to expand the user supplied
@@ Documentation/git-ls-files.txt: followed by the ("attr/<eolattr>").
Do not interpret any more arguments as options.

-<file>::
+- Files to show. If no files are given all files which match the other
+<pathspec>::
- Files to show. If no files are given all files which match the other
++ Limits the files to show to only those that match any of the given
++ pathspecs. If no pathspecs are given, all files which match the other
specified criteria are shown.
++
+For details on the <pathspec> syntax, see the 'pathspec' entry in

 Documentation/git-ls-files.txt | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

Documentation/git-ls-files.txt +10 -6

index 1abdd3c21c5..d69a46f8a56 100644
@@ -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>...]
 
 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
-	error (return 1).
+	If no path that matches <pathspec> appears in the index, treat this as
+	an error (return 1).
 
 --with-tree=<tree-ish>::
 	When using --error-unmatch to expand the user supplied
-	<file> (i.e. path pattern) arguments to paths, pretend
+	<pathspec> (i.e. path pattern) arguments to paths, pretend
 	that paths which were removed in the index since the
 	named <tree-ish> are still present.  Using this option
 	with `-s` or `-u` options does not make any sense.

@@ -225,9 +225,13 @@ followed by the  ("attr/<eolattr>").
 \--::
 	Do not interpret any more arguments as options.
 
-<file>::
-	Files to show. If no files are given all files which match the other
+<pathspec>::
+	Limits the files to show to only those that match any of the given
+	pathspecs. If no pathspecs are given, all files which match the other
 	specified criteria are shown.
++
+For details on the <pathspec> syntax, see the 'pathspec' entry in
+linkgit:gitglossary[7].
 
 OUTPUT
 ------

base-commit: 725f57037d81e24eacfda6e59a19c60c0b4c8062

Signature · 1 line

gitgitgadget