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: Tue, 09 Apr 2019 16:01:33 +0900 [thread overview]
Message-ID: <xmqqy34j7jci.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <CAKrvxcVgMLNEEY6U+ybm6n4WtUCdOaYRjBrDKFvRwzYbZyB2UQ@mail.gmail.com> (Adam Nielsen's message of "Mon, 8 Apr 2019 12:27:51 +0200")
"Dr. Adam Nielsen" <admin@in-ici.net> writes:
> I agree with you. How about we make up the word "intermediate slash" and
> explain it in an extra paragraph?
I am not sure if that is any better than "in the following, pretend
that a slash at the end of a pattern does not exist", which is how
the current description avoids repetition and aims for clarity. It
probably is worse than than the current one if we need to introduce
a new term that is otherwise not useful elsewhere---a new term adds
to the cognitive load of readers.
>> I also wonder if "in all directories" is clear enough that your
>> "all" is limited to below the level the ignore pattern is defined
>> for (i.e. "*.1" that appears in "Documentation/.gitignore" does not
>> ignore "foo.1" at the top-level of the tree).
>
> Its mentioned at the start of the page that the pattern is always
> relative to the location of the `.gitignore` file. However, I see that
> since its said "in all directories" its necessary to restrict it again.
> How about
>
> If the pattern contains no intermediate slash "`/`",
> the pattern will match in all directories at or below
> the `.gitignore` file, with infinite depth.
It is unclear what "with infinite depth" means in this sentence.
There is no depth-limit in the exclude mechanism, and I'd prefer
not to confuse readers by making a casual mention of "depth" to
imply as if there is some depth-based logic.
Also, as you defined "intermediate" as a slash that is neither
leading nor trailing, the above paragraph says "/foo" matches any
filesystem entity whose final path component is 'foo', e.g. a file
'foo' at the current level, a directory 'foo' in subdirectory 'dir'
(i.e. 'dir/foo'), etc. I do not think you meant to say that (and
this is why I do not like to introduce a new term---even its
inventor cannot get it right).
>> So I can tell that this patch is trying to address a problem in the
>> original that is worth fixing, but I cannot say the result is good.
>> At least not yet.
>> ...
>> Once you write consistently that a path for a directory foo/bar is
>> foo/bar, not foo/bar/, then this example would become much easier to
>> write and read, I suspect.
>>
>> An asterisk "`*`" matches anything except a slash. A
>> pattern "foo/*", for example, matches "foo/test.json" (a
>> regular file), "foo/bar" (a diretory), but it does not match
>> "foo/bar/hello.c" (a regular file), as the asterisk in the
>> patter does not match "bar/hello.c" which has a slash in it.
>>
>> perhaps.
>
> I agree, this is much better. Although I would leave out
>
>> "as the asterisk in the patter does not match "bar/hello.c"
>> which has a slash in it."
I happen to think that the part is the more important half of that
whole "example". By explaining why it does not match, it enforces
"matches anything except a slash" we gave upfront.
Thanks. I think we are making progress...
next prev parent reply other threads:[~2019-04-09 7:01 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 [this message]
2019-04-09 12:19 ` Dr. Adam Nielsen
2019-04-09 16:21 ` Junio C Hamano
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=xmqqy34j7jci.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).