>> At any rate, would it at least be a good idea to make the "trailing
>> slash halts recursion, won't consider nested .gitignore files"
>> explicit in the `.gitignore` doc? Unless I'm missing it, I don't think
>> that behavior is called out (or at least not called out concisely/in
>> one place). It looks like this is all there is:
>
> Yeah, it's definitely come up multiple times over the years. I don't
> know what all is in gitignore(5), but if it's not mentioned it probably
> should be.
>
>> "If the pattern ends with a slash, it is removed for the purpose
>> of the following description, but it would only find a match with a
>> directory. In other words, foo/ will match a directory foo and paths
>> underneath it, but will not match a regular file or a symbolic link
>> foo (this is consistent with the way how pathspec works in general in
>> Git)."
>>
>> Also, I'm not sure what the "following description" is in "it is
>> removed for the purpose of the following description". Is that trying
>> to imply "excluded from the rest of the doc"?
>
> I think it means "for the rest of the description of how the patterns
> work". I.e., "foo/" matches as "foo" when the rest of the matching rules
> are applied. I agree it's a bit awkward. Patches welcome. :)
I hope this is correct. I tried to follow the instructions. Please let
me know if I need to fix something with how I'm sending this!
-- >8 --
Subject: [PATCH] doc: clarify non-recursion for ignore paths like `foo/`
The behavior of .gitignore patterns ending with trailing slashes is
unclear. The user may expect subsequent matching patterns to matter, while
they do not. For example:
foo/ # Ignores `foo` directories and everything inside of them
!foo/*.txt # Does nothing
Explain this behavior (and its implications) more explicitly.
Signed-off-by: Dakota Hawkins <daktoahawkins@xxxxxxxxx>
---
Documentation/gitignore.txt | 17 +++++++++++------
1 file changed, 11 insertions(+), 6 deletions(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index ff5d7f9ed..e9c34c1d5 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,12 +89,17 @@ PATTERN FORMAT
Put a backslash ("`\`") in front of the first "`!`" for patterns
that begin with a literal "`!`", for example, "`\!important!.txt`".
- - If the pattern ends with a slash, it is removed for the
- purpose of the following description, but it would only find
- a match with a directory. In other words, `foo/` will match a
- directory `foo` and paths underneath it, but will not match a
- regular file or a symbolic link `foo` (this is consistent
- with the way how pathspec works in general in Git).
+ - If the pattern ends with a slash it will match directories but prevent
+ further recursion into subdirectories. In other words, `foo/` will match a
+ directory `foo`, excluding files and paths underneath it, but will not match
+ a regular file or a symbolic link `foo` (this is consistent with the way
+ that pathspec works in general in Git). Consequently, `foo/` will prevent
+ consideration of subsequent matches, including exclusions (for example,
+ `!foo/*.noignore`). In order to match `foo/` directories while allowing for
+ possible later exclusions, consider using a trailing wildcard (`foo/*`).
+ Note that matching directories with a trailing wildcard incurs some
+ additional performance cost, since it requires recursion into
+ subdirectories.
- If the pattern does not contain a slash '/', Git treats it as
a shell glob pattern and checks for a match against the
--
2.16.2.windows.1
