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

[Junio C Hamano <gitster@pobox.com>]

Sitaram Chamarty <sitaramc@gmail.com> writes:

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

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