Re: [PATCH/docs] make slash-rules more readable
- Date: Tue, 09 Apr 2019 16:01:33 +0900
- From: Junio C Hamano <gitster@xxxxxxxxx>
- Subject: Re: [PATCH/docs] make slash-rules more readable
"Dr. Adam Nielsen" <admin@xxxxxxxxxx> 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.
> 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...