On Wed, Mar 21 2018, Dakota Hawkins jotted:
>>> 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
Just before the context your patch quotes, we have this in gitignore(5)
already:
[...]It is not possible to re-include a file if a parent directory
of that file is excluded. Git doesn’t list excluded directories for
performance reasons, so any patterns on contained files have no
effect, no matter where they are defined.[...]
I can't see how your change to the documentation doesn't just re-state
what we already have documented, which is not to say the docs can't be
improved, but then we should clearly state this in one place, not
re-state it within the span of a few paragraphs.
