Re: How do I qualify paths in the .gitignore file w.r.t. the repo root directory?

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 24, 2009, 17:33 UTC
Message-ID: <7vzlgbhh95.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <slrngq7e6c.iti.sitaramc@sitaramc.homelinux.net>

Sitaram Chamarty <sitaramc@gmail.com> writes:

Show 11 quoted lines

> On 2009-02-24, Junio C Hamano <gitster@pobox.com> wrote:
>> I think you are looking for "/foo/".  From Documentation/gitignore.txt:
>
> [lots of very clear and detailed explanation snipped for
> brevity...]
>
> I'd been sort of struggling with the part of 'man gitignore'
> that describes the rules for the exclusion patterns; it just
> didn't seem as clear as it could have been.  It's very
> accurate, but I (and I noticed a few others on irc) had to
> read very carefully to do anything moderately complex.

The existing documentation has an unfortunate history behind it and the "if it ends with a slash it matches only directories" was bolted on as an afterthought; see d6b8fc3 (gitignore(5): Allow "foo/" in ignore list to match directory "foo", 2008-01-31).

Show 24 quoted lines

> A few days ago, 'doener' (BjÃ¶rn Steinbrink) came up with
> some much simpler rules that said the same thing, and --
> building on the insight that his rules gave me -- I came up
> with these:
>
> ----->8-----
>
> Note that rule 1 merely *modifies* rules 2 and 3, it does not
> supercede or preclude them.
>
> 1.  If you pattern ends with a slash, it matches only
>     directories (and their contents)
> 2.  If there is no slash otherwise, it matches that name, at
>     any depth in the tree
> 3.  If there is a slash anywhere else, it matches that name,
>     relative to the .gitignore (or $GIT_WORK_TREE if the
>     pattern is from one of the other pattern sources like
>     `.git/info/exclude` etc)
>
> The wildcards (`*` and `?`) do not match slashes, but otherwise
> the patterns are normal shell globs as defined by fnmatch(3) with
> the FNM_PATHNAME flag set.
>
> ----->8-----

Nicely written, except that as a non-native speaker I fear "otherwise" and "anywhere else" _might_ leave ambiguity for a pattern that has slash only at the end [*1*], but I dunno. It certainly is much better than what I wrote in the current documentation.

Please send it in a patch form (possibly addressing my ambiguity concern if it is real for other people) with a one-liner log message that says "The existing documentation is unreadable even though it may be precise", and I'll apply.

Thanks.

[Footnote]

*1* That is why I wrote "it is removed for the purpose of..." in the description, even though I do agree that paragraph is hard to read. Perhaps I should have said "it only matches directories. The slash at the end is ignored for the purpose of the following rules." which probably would have flowed a bit more naturally.