git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
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
>>
>>
> 
> 


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