"Dr. Adam Nielsen" <admin@xxxxxxxxxx> writes:
> If the pattern contains no slash "`/`"
> (except an optional trailing slash),
That's perfect.
> the pattern will match in all directories relative to
> the `.gitignore` file, with infinite depth.
Maybe it is just me but "in all directories relative to the file"
does not say the same thing as
the pattern is matched against paths in the directory where the
`.gitignore` file that has the pattern in it is in, and any of
its subdirectories (recursively).
which I think is what we want to say. Especially, I do not think
the phrasing implies the match is limited to the directory and its
subdirectories, as it is unclear what the words "relative to" wanted
to mean in that sentence.
> For example, `frotz/` matches `frotz` and `a/frotz` that
> is a directory, but does not match if these are files.
> A pattern `frotz` on the other hand matches these paths
> whether they are files or directories.
Yeah this is good.
> For the next paragraph I would suggest this:
>
> If the pattern contains a non-trailing slash "`/`",
> it matches the beginning of the pathname.
The reference of "it" in "it matches" is fuzzy; first I was confused
as I thoguht it refers to the slash (which one? if the pattern has
two or more slashes a/b/c).
A pattern with a non-trailing slash matches the beginning of
the pathname
would mean the same thing without ambiguity, but I am not sure
"matches the beginning of" is quite right.
A pattern doc/frotz that appears in v1.0/.gitignore file would match
a file or directory v1.0/doc/frotz (pathnames in these example are
all from the top level of the repository).
I think woe most important messages we need to deliver are
- a pattern without slash applies in a directory the pattern
"appears in", or any of its subdirectories (recursively).
- a pattern with slash on the other hand is anchored at the
directory the pattern "appears in" and does not apply to any of
its subdirectories.
So with that in mind, perhaps
Unlike a pattern without a slash, a pattern with a
non-trailing slash is matched against paths immediately in
the directory the `.gitignore` file the pattern appears in
is stored in, and does not get used in its subdirectories..
or something?
> For example, the pattern `doc/frotz/` matches
> `doc/frotz` that is a directory
> but does not match `a/doc/frotz`.
Correct, almost.
For example, the pattern `doc/frotz/` that appears in
`.gitignore` at the top-level of the project matches
`doc/frotz` directory (again, seen from the top-level), but
not `a/doc/frotz`.
Also, a pattern "/doc" matches doc at the current level (i.e. the
directory in which .gitignore file that the pattern was taken from
is found) and not in any subdirectories. Is that clear in the
proposed update?
Procedurally (I am writing to make sure we are on the same page for
the technical correctness, so that I can let you take care of the
ease of understanding of the end result---it is of no use if an easy
to understand document describes incorrect behaviour ;-)
* A trailing slash is used *only* to mark that a pattern matches
only against directories, and it is ignored by the actual pattern
mac.thing logic. It also is ignored by the logic to determine if
the pattern is anchored.
e.g. /foo-bar/ becomes /foo-bar but "must match dir" (aka "ends
with a slash") is remembered.
* A leading slash is used *only* to mark that a pattern is
"anchored" at the current level, and otherwise it is ignored by
the actual pattern matching logic.
e.g. /foo-bar that used to be /foo-bar/ then becomes foo-bar but
we also remember "must match here" (aka "had a slash in it").
* A slash in a pattern that is not ignored by the above two rules
(i.e. your "intermediate slash") marks a pattern as "anchored",
i.e. used to match against the paths relative to the current
level only.
e.g. foo-bar that used to be /foo-bar that used to be /foo-bar/
thru the above processing, as well as foo/bar that was ignored by
the above two rules, are both anchored to the current level, and
they do not match a/foo-bar or a/foo/bar in our immediate
subdirectory 'a'
