From: "Dr. Adam Nielsen" <admin@in-ici.net>
To: Philip Oakley <philipoakley@iee.org>
Cc: git@vger.kernel.org
Subject: Re: [PATCH] make slash-rules more readable
Date: Wed, 29 May 2019 10:28:33 +0200 [thread overview]
Message-ID: <4a939040-b0d2-5914-f800-26903e4ec829@in-ici.net> (raw)
In-Reply-To: <0c2894ce-7eab-8207-9af8-7ce5e779d4ec@iee.org>
On 19.05.19 19:42, Philip Oakley wrote:
> Hi Adam,
>
Hi Philip
> a) keep going. the documentation does need improving!
Thank you for the encouragement!
> b) also have a look at the `git help glossary` for 'glob' pattern
> descriptions for other ideas.
The glob entry looks very familiar to some entries from the gitignore
docs. But thanks for the reference.
> c) maybe swap the order for considering the slashes (first slash vs last
> slash). It appears as if the 'trailing slash rule' == 'always a
> directory' could be said first, or is that last? dunno..
The first paragraph about slashes is already that a "trailing slash" ==
"always a directory".
However I was also thinking of swapping the order of
If the pattern contains no slash or only a trailing slash,
the pattern is matched against all files and folders (recursively)
from the location of the `.gitignore` file.
For example, `frotz/` matches `frotz` and `a/frotz` that
is a directory (relative from the `.gitignore` file).
and
Otherwise, if the pattern contains a non-trailing slash,
the pattern is matched relative to the location
of the `.gitignore` file.
For example, `doc/frotz/` matches `doc/frotz` directory, but not
`a/doc/frotz` (relative from the `.gitignore` file).
I am wondering if it would be an improvement to state it like this:
The pattern is matched relative to the location of
the `.gitignore` file. Except if the pattern contains
no slash (or no slash but a trailing slash), then the pattern is
matched against all files and folders (recursively)
from the location of the `.gitignore` file.
For example, `doc/frotz/` matches `doc/frotz` directory, but not
`a/doc/frotz`; however `frotz/` matches `frotz` and `a/frotz` that
is a directory (all paths are relative from the `.gitignore` file).
> d) It looks like its the counting of slashes that gets everyone!
>
Yes the trailing slash is the reason we can't say, if there is any slash
[...]. If there is no slash [...]. So counting is not enough, one also
needs to consider the type of the slash.
> Philip
>
All the best,
Adam
> On 19/05/2019 16:33, Dr. Adam Nielsen wrote:
>> On 18.05.19 21:34, Philip Oakley wrote:
>>> Hi Adam
>>>
>>
>> Hi Philip
>>
>>> On 18/05/2019 15:07, Dr. Adam Nielsen wrote:
>>> This "Otherwise" below could be the complement to the initial "If",
>>> or could be part of a "matches" pair of example sentences. At least
>>> on my initial reading I paired it via the 'matches'.
>>
>> Now that you said it, I can see the ambiguity. Maybe its better to
>> create a blank line separator, the mentioned paragraph is already very
>> big. Perhaps like this:
>>
>> If the pattern contains no slash or only a trailing slash, [..].
>> For example, `frotz/` matches `frotz` and `a/frotz` that
>> is a directory (relative from the `.gitignore` file).
>>
>> Otherwise, if the pattern contains a non-trailing slash,
>> the pattern is matched relative to the location
>> of the `.gitignore` file.
>>
>>
>> On 19.05.19 03:59, Junio C Hamano wrote:
>> >> Make all paragraphs valid, even if they are not read
>> >> in strict order.
>> >
>> > I think you are giving up on this, and I do not think that is
>> > particularly a bad thing ;-)
>>
>> You are right. The paragraph below
>>
>> >> + - The above pargraph also includes the case of a leading slash.
>>
>> can of course not be read in any order. Maybe its more precise to say:
>>
>> Remove meta-rules in a paragraph that effect the way one
>> has to read upcoming paragraphs.
>>
>> > Now you (not you the author of the document, but figuratively "any
>> > reader of this document") must have read all the four before this
>> > point ;-)
>>
>> This paragraph references to the immediate forerunner. Why do you
>> think it references to all four paragraphs?
>>
>> > To put it differently, your reading of the above four
>> > bullets are incomplete unless you read this too.
>>
>> I would say the paragraph
>>
>> >> + - The above pargraph also includes the case of a leading slash.
>> [...]
>>
>> is redundant. Its purpose is to point out that the previous paragraph
>> also included the rule about the leading slash.
>> So the above four paragraphs are valid in my opinion without this
>> paragraph.
>>
>> >
>> > Typofix: "pargraph" -> "paragraph".
>> >
>> > In any case, I cannot guess what 'also include the case of a leaning
>> > slash' wants to say.
>>
>> Maybe this is better understandable(?):
>>
>> Note that any pattern that starts with a leading slash contains
>> a non-trailing slash and is therefore effected by the
>> previous paragraph.
>>
>> This might be even better after creating a new paragraph for the
>> "Otherwise.." part as suggested by Philip.
>>
>> > Note that the above rule means you cannot easily say "a file
>> > whose name contains 'hello' and in this directory only, not in
>> > its subdirectories." because a pattern 'hello.*' does not have
>> > any slash. To work around this limitation, you can prepend
>> > your pattern with a slash, i.e. '/hello.*'; the pattern now
>> > matches 'hello.txt', 'hello.c' but not 'a/hello.java'.
>>
>> I think examples that are as descriptive as this should rather belong
>> to the "Example" section. For the rules section I would like to keep
>> the examples as short and clean as possible (I think Johannes agrees
>> with me here?).
>>
>> If understand you correctly, then you find my example too abstract?
>> Maybe this is better(?):
>>
>> For example, the pattern `/bar` only matches the file or
>> folder `bar` but not `a/bar`, whereas the pattern `bar` would
>> match both (relative to the `.gitignore` file).
>>
>>
>> On 19.05.19 08:59, Johannes Sixt wrote:
>> > All those examples unterrupt the flow of thought in a way that makes it
>> > diffcult to follow the reasoning.
>>
>> I agree with you that complex examples make it harder to read.
>> However, I find that if a complex rule is accompanied by a simple
>> example, it improves readability a lot. I find that for example the
>> four paragraphs about the `**` have a perfect balance between rules
>> and examples.
>>
>> >May I suggest a different approach to
>> > upate this text? Provide two patches:
>> >
>> > - Patch 1/2 updates the Examples section such that it contains all
>> > examples that you provide in the text above, with explanation.
>> > Perhaps refer to the Examples section early above the rules.
>> >
>> > - Patch 2/2 updates the rules section without giving examples.
>>
>> Maybe its best if discuss this for each changed/new paragraph if the
>> example should be moved into the example section.
>>
>> 1.
>>
>> >> + - If the pattern contains no slash or only a trailing slash,
>> >> + the pattern is matched against all files and folders (recursively)
>> >> + from the location of the `.gitignore` file.
>> >> + For example, `frotz/` matches `frotz` and `a/frotz` that
>> >> + is a directory (relative from the `.gitignore` file).
>>
>> I think the example very short and important, and it should stay.
>>
>> 2.
>> - Otherwise, if the pattern contains a non-trailing slash,
>> the pattern is matched relative to the
>> location of the `.gitignore` file.
>> For example, `doc/frotz/` matches `doc/frotz` directory, but not
>> `a/doc/frotz` (relative from the `.gitignore` file).
>>
>> Same here. Its a short and important. I would like to keep it there.
>>
>>
>> 3.
>>
>> Note that any pattern that starts with a leading slash contains
>> a non-trailing slash and is therefore effected by the
>> previous paragraph.
>> For example, the pattern `/bar` only matches the file or
>> folder `bar` but not `a/bar`, whereas the pattern `bar` would
>> match both (relative to the `.gitignore` file).
>>
>> I would agree to put this entire paragraph in the example section.
>>
>>
>> 4.
>>
>> >> + - 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 would also agree to put the 4-line example into the example section.
>>
>> We could also put this in the example section:
>>
>> Note that the pattern `doc/frotz` and `/doc/frotz` have the
>> same effect in any `.gitignore` file, while `/bar` and `bar`
>> have not the same effect (`/bar` will not match `foo/bar`).
>>
>>
>> If we do all this, I could imagine the following procedure:
>>
>> - Patch 1/2 updates all the changes but do not include
>> the examples from 3. and 4.
>>
>> - Patch 2/2 improving the example section and including the
>> examples from 3. and 4.
>>
>> I have actually some ideas for the example section that you may see in
>> my blog post in the section examples:
>> https://dr-nielsen.com/git/gitignore-pattern-explained
>>
>> I would like to put all of those in the example section of the docs.
>> But this is clearly out of scope of patch 1/2.
>>
>> > The examples in the Examples section are overly technical by saying
>> >
>> > $ cat .gitignore
>> > vmlinux*
>> > $ ls arch/foo/kernel/vm*
>> > arch/foo/kernel/vmlinux.lds.S
>> > $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
>> >
>> > I think that this could be made more pleasent to read if one would not
>> > have to use a mental shell interpreter. ;)
>>
>> I agree, I would also vote to remove this one.
>>
>>
>> All the best,
>> Adam
>>
>>
>
>
next prev parent reply other threads:[~2019-05-29 8:28 UTC|newest]
Thread overview: 36+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-18 14:07 [PATCH] make slash-rules more readable Dr. Adam Nielsen
2019-05-18 19:34 ` Philip Oakley
2019-05-19 15:33 ` Dr. Adam Nielsen
[not found] ` <0c2894ce-7eab-8207-9af8-7ce5e779d4ec@iee.org>
2019-05-29 8:28 ` Dr. Adam Nielsen [this message]
-- strict thread matches above, loose matches on Subject: below --
2020-02-15 3:08 Pavel Ivashkov
2019-06-04 17:34 Dr. Adam Nielsen
2019-06-25 11:05 ` Dr. Adam Nielsen
2019-06-25 11:31 ` Philip Oakley
2019-06-27 17:10 ` Dr. Adam Nielsen
2019-07-04 10:40 ` Philip Oakley
2019-07-04 10:46 ` Philip Oakley
2019-06-27 17:43 ` Junio C Hamano
2019-06-02 9:04 Dr. Adam Nielsen
2019-05-31 18:17 Dr. Adam Nielsen
2019-05-31 18:16 Dr. Adam Nielsen
2019-05-31 7:44 Dr. Adam Nielsen
2019-05-31 16:30 ` Junio C Hamano
2019-05-31 17:24 ` Dr. Adam Nielsen
2019-05-31 17:40 ` Junio C Hamano
2019-06-01 9:33 ` Philip Oakley
2019-06-02 9:01 ` Dr. Adam Nielsen
2019-06-03 18:01 ` Junio C Hamano
2019-06-04 10:40 ` Philip Oakley
2019-06-01 9:23 ` Philip Oakley
2019-06-04 12:34 ` Philip Oakley
2019-06-04 17:22 ` Dr. Adam Nielsen
2019-05-18 14:13 Dr. Adam Nielsen
2019-05-19 1:59 ` Junio C Hamano
2019-05-19 6:59 ` Johannes Sixt
2019-05-07 10:45 Dr. Adam Nielsen
2019-05-08 5:33 ` Junio C Hamano
2019-05-12 9:56 ` Dr. Adam Nielsen
2019-05-17 21:43 ` Dr. Adam Nielsen
2019-05-18 6:42 ` Johannes Sixt
2019-05-18 13:20 ` Dr. Adam Nielsen
2019-04-26 14:32 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=4a939040-b0d2-5914-f800-26903e4ec829@in-ici.net \
--to=admin@in-ici.net \
--cc=git@vger.kernel.org \
--cc=philipoakley@iee.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).