Re: [PATCH/docs] make slash-rules more readable

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 9, 2019, 07:01 UTC
Message-ID: <xmqqy34j7jci.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <CAKrvxcVgMLNEEY6U+ybm6n4WtUCdOaYRjBrDKFvRwzYbZyB2UQ@mail.gmail.com>

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

Show 13 quoted lines

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

Show 20 quoted lines

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