git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
From: "Dr. Adam Nielsen" <admin@in-ici.net>
To: git@vger.kernel.org
Subject: Re: [PATCH] make slash-rules more readable
Date: Sun, 19 May 2019 17:33:29 +0200
Message-ID: <1730c168-c4fb-0e04-dd20-c267ce510fd1@in-ici.net> (raw)
In-Reply-To: <7b062fd1-c793-b8b9-c997-90f53f958e2c@iee.org>

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



  reply index

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-18 14:07 Dr. Adam Nielsen
2019-05-18 19:34 ` Philip Oakley
2019-05-19 15:33   ` Dr. Adam Nielsen [this message]
     [not found]     ` <0c2894ce-7eab-8207-9af8-7ce5e779d4ec@iee.org>
2019-05-29  8:28       ` Dr. Adam Nielsen
  -- 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=1730c168-c4fb-0e04-dd20-c267ce510fd1@in-ici.net \
    --to=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

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror http://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Example config snippet for mirrors

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git