From: Junio C Hamano <gitster@pobox.com>
To: "Dr. Adam Nielsen" <admin@in-ici.net>
Cc: Git Mailing List <git@vger.kernel.org>
Subject: Re: [PATCH/docs] make slash-rules more readable
Date: Wed, 10 Apr 2019 01:21:36 +0900 [thread overview]
Message-ID: <xmqqzhoz2lpr.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <CAKrvxcW1hKUjMsCGUz7GothxbEKiQek2J5CkjhuiSKoGrArjbQ@mail.gmail.com> (Adam Nielsen's message of "Tue, 9 Apr 2019 14:19:14 +0200")
"Dr. Adam Nielsen" <admin@in-ici.net> 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'
next prev parent reply other threads:[~2019-04-09 16:21 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-05 20:00 [PATCH/docs] make slash-rules more readable Dr. Adam Nielsen
2019-04-08 7:51 ` Junio C Hamano
2019-04-08 10:27 ` Dr. Adam Nielsen
2019-04-09 7:01 ` Junio C Hamano
2019-04-09 12:19 ` Dr. Adam Nielsen
2019-04-09 16:21 ` Junio C Hamano [this message]
2019-04-10 7:39 ` Dr. Adam Nielsen
2019-04-17 15:49 ` Dr. Adam Nielsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqzhoz2lpr.fsf@gitster-ct.c.googlers.com \
--to=gitster@pobox.com \
--cc=admin@in-ici.net \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).