[PATCH] make slash-rules more readable

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

---
 Documentation/gitignore.txt | 37 ++++++++++++++++++++++++-------------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..3a6fb9117c 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,24 +89,35 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
    directory `foo` and paths underneath it, but will not match a
    regular file or a symbolic link `foo` (this is consistent
    with the way how pathspec works in general in Git).
 
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
+ - If the pattern contains no slash "`/`" (except an optional 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). 
+
+ - A pattern that contains a non-trailing slash 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). 
+   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`).
+
+ - 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.
+   The character "`?`" matches any one character except "`/`"
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the 
+   FNM_PATHNAME flag for a more detailed description.
 
  - A leading slash matches the beginning of the pathname.
    For example, "/{asterisk}.c" matches "cat-file.c" but not
-- 
2.17.1

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Make all paragraphs valid, even if they are not read
in strict order. Make paragraph better understandable
for pattern without slash. Add paragraph for pattern
with slash. Be precise whenever a trailing slashes
would make a difference. Add some examples.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 37 ++++++++++++++++++++++++-------------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..7d7fbd202e 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,24 +89,35 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
    directory `foo` and paths underneath it, but will not match a
    regular file or a symbolic link `foo` (this is consistent
    with the way how pathspec works in general in Git).
 
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
+ - If the pattern contains no slash "`/`" (except an optional 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).
+
+ - A pattern that contains a non-trailing slash 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).
+   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`).
+
+ - 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.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
  - A leading slash matches the beginning of the pathname.
    For example, "/{asterisk}.c" matches "cat-file.c" but not
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> + - A pattern that contains a non-trailing slash is matched
> +   For example, `doc/frotz/` matches `doc/frotz` directory, but not
> +   `a/doc/frotz` (relative from the `.gitignore` file).
> +   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`).

The "note" is not incorrect per-se.  The behaviour described is
because the leading slash is removed for the purpose of textual
matching against paths, but still counts as a non-trailing slash for
the purpose of anchoring the pattern to the level of recursion.

I am not sure if that is obvious to the readers, though.  Especially
because the "a leading slash matches the beginning of ..." which was
in the original is still left and appears two bullet points after
this one, the presentation order seem a bit suboptimal.

How about deleting that "A leading slash matches the beginning..."
bullet, and then splitting the above bullet into two?  That is

- A pattern that contains a non-trailing slash is matched
  For example, `doc/frotz/` matches `doc/frotz` directory, but not
  `a/doc/frotz` (relative from the `.gitignore` file).

- A leading slash, if any, is implicitly removed before matching the
  pattern with the pathname, but the pattern still counts as having
  a non-trailing slash for the purpose of the above rule.  For
  example, a pattern `{asterisk}.c` does not have any slash in it,
  so it would match a file or a directory whose name ends with `.c`
  anywhere in the directory that has `.gitignore` file in it
  (e.g. `sub/foo.c`, `bar.c`). By prefixing a slash to make it
  `/{asterisk}.c`, it can be limited to match only at the current
  level (i.e. `bar.c` but not `sub/foo.c`).

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

s/patter/&n/

> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>  
>   - A leading slash matches the beginning of the pathname.
>     For example, "/{asterisk}.c" matches "cat-file.c" but not

Then this last paragraph can be removed.

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

On 08.05.19 07:33, Junio C Hamano wrote:
> "Dr. Adam Nielsen" <admin@in-ici.net> writes:
> 
>> + - A pattern that contains a non-trailing slash 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).
>> +   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`).
> 
> The "note" is not incorrect per-se.  The behaviour described is
> because the leading slash is removed for the purpose of textual
> matching against paths, but still counts as a non-trailing slash for
> the purpose of anchoring the pattern to the level of recursion.
> 
> I am not sure if that is obvious to the readers, though.

Yes, its not explained to the reader that the leading slash is removed 
for the purpose of textual matching. But maybe this is not necessary in 
order to understand the effect of the pattern.

>  Especially
> because the "a leading slash matches the beginning of ..." which was
> in the original is still left and appears two bullet points after
> this one, the presentation order seem a bit suboptimal.

I agree. The paragraph "a leading slash matches the beginning of ..." 
should be deleted, because its already covered by the top rule plus an 
example.

> 
> How about deleting that "A leading slash matches the beginning..."
> bullet, and then splitting the above bullet into two?  That is
> 
> - A pattern that contains a non-trailing slash is matched
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 agree that the case of a leading slash is important and deserves its 
own paragraph, especially if we remove the last bullet.


> - A leading slash, if any, is implicitly removed before matching the
>    pattern with the pathname, but the pattern still counts as having
>    a non-trailing slash for the purpose of the above rule.  For

I would try to avoid ambiguous words like  `implicitly removed ` and 
`pathname` that have not been used before. Also I am not sure if 
explaining the reader how the algorithm works is the best approach.

>    example, a pattern `{asterisk}.c` does not have any slash in it,
>    so it would match a file or a directory whose name ends with `.c`
>    anywhere in the directory that has `.gitignore` file in it
>    (e.g. `sub/foo.c`, `bar.c`).

A similar example is already in the  "If the pattern contains no 
slash.." paragraph. I think it takes a bit too much space just to 
explain the difference when a leading slash appears.

> By prefixing a slash to make it
>    `/{asterisk}.c`, it can be limited to match only at the current
>    level (i.e. `bar.c` but not `sub/foo.c`).

How about we split it like this:

   - A pattern that contains a non-trailing slash 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; note that the
     example has a trailing and a non-trailing slash at the same time).

   - Note: A pattern with a leading slash has a non-trailing slash
     and is therefore effected by the previous paragraph.
     For example, the pattern `/bar` only matches the file or
     folder `bar` that is at the same location as the `gitignore` file.
     Whereas the pattern `bar` would also match in folders below the
     `gitignore`  file.
     On the other hand,  the pattern `doc/frotz` and `/doc/frotz`
     have the same effect in any `.gitignore` file, because both
     have a non-trailing slash.

> 
>> + - 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.
> 
> s/patter/&n/
> 
>> +   The character "`?`" matches any one character except "`/`".
>> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
>> +   one of the characters in a range. See fnmatch(3) and the
>> +   FNM_PATHNAME flag for a more detailed description.
>>   
>>    - A leading slash matches the beginning of the pathname.
>>      For example, "/{asterisk}.c" matches "cat-file.c" but not
> 
> Then this last paragraph can be removed.

Agree.
-

Another thing that I noticed is that its not mentioned anywhere that the 
pattern use a slash as a directory separator (instead of a backslash), 
its only clear from the examples. Maybe its worth to mention it in the 
"PATTERN FORMAT" section. Also its maybe worth to introduce the term 
"leading slash" and "trailing slash" because they will be of importance 
of the following paragraphs. Something like this after the paragraph of "!":

     [...] for example, "\!important!.txt".

     A slash `/` is used as a directory separator.
     A leading slash (that is if the pattern begins with a slash)
     or a trailing slash (that is if the pattern ends with a slash)
     have special meaning and are explained below.

     If the pattern contains a trailing slash, it would only find
     a match with a directory. [...]

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

> Another thing that I noticed is that its not mentioned anywhere that the 
> pattern use a slash as a directory separator (instead of a backslash), 
> its only clear from the examples. Maybe its worth to mention it in the 
> "PATTERN FORMAT" section. Also its maybe worth to introduce the term 
> "leading slash" and "trailing slash" because they will be of importance 
> of the following paragraphs. Something like this after the paragraph of 
> "!":
> 
>      [...] for example, "\!important!.txt".
> 
>      A slash `/` is used as a directory separator.
>      A leading slash (that is if the pattern begins with a slash)
>      or a trailing slash (that is if the pattern ends with a slash)
>      have special meaning and are explained below.
> 
>      If the pattern contains a trailing slash, it would only find
>      a match with a directory. [...]
> 


I changed my mind about this last addition. I think it is not very 
readable and there is no need to explain leading/trailing slash. Maybe 
one could just note it like this:

       [...] for example, "\!important!.txt".

       A slash `/` is used as a directory separator.
       A leading and trailing slash have special meaning
       and are explained in the following.

       If the pattern ends with a slash, it would only find
       a match with a directory. [...]

then I would also add:

      If the pattern does not end with a slash, it would find a match
      with a file or directory.


Two notes about two sentences that I proposed a while ago:

 > + - If the pattern contains no slash "`/`" (except an optional 
trailing slash),
 > +   the ...

I think that this sentence is not very readable. The exceptional case in 
the brackets makes it over complicated.

 > + - A pattern that contains a non-trailing slash is matched

And I don't like this phrase either. I think its too easy to confuse it 
with "A pattern that contains no trailing slash".

So I would suggest to replace both with the following:

     If the pattern contains no slash or only a trailing slash, [...].
     Otherwise (when it contains a non-trailing slash) the pattern
     is matched [...].

All the best,
Adam

Re: [PATCH] make slash-rules more readable

[Johannes Sixt]

Am 17.05.19 um 23:43 schrieb Dr. Adam Nielsen:
>> Another thing that I noticed is that its not mentioned anywhere that
>> the pattern use a slash as a directory separator (instead of a
>> backslash), its only clear from the examples. Maybe its worth to
>> mention it in the "PATTERN FORMAT" section. Also its maybe worth to
>> introduce the term "leading slash" and "trailing slash" because they
>> will be of importance of the following paragraphs. Something like this
>> after the paragraph of "!":
>>
>>      [...] for example, "\!important!.txt".
>>
>>      A slash `/` is used as a directory separator.
>>      A leading slash (that is if the pattern begins with a slash)
>>      or a trailing slash (that is if the pattern ends with a slash)
>>      have special meaning and are explained below.
>>
>>      If the pattern contains a trailing slash, it would only find
>>      a match with a directory. [...]
>>
> 
> 
> I changed my mind about this last addition. I think it is not very
> readable and there is no need to explain leading/trailing slash. Maybe
> one could just note it like this:
> 
>       [...] for example, "\!important!.txt".
> 
>       A slash `/` is used as a directory separator.
>       A leading and trailing slash have special meaning
>       and are explained in the following.
> 
>       If the pattern ends with a slash, it would only find
>       a match with a directory. [...]
> 
> then I would also add:
> 
>      If the pattern does not end with a slash, it would find a match
>      with a file or directory.
> 
> 
> Two notes about two sentences that I proposed a while ago:
> 
>> + - If the pattern contains no slash "`/`" (except an optional
> trailing slash),
>> +   the ...
> 
> I think that this sentence is not very readable. The exceptional case in
> the brackets makes it over complicated.
> 
>> + - A pattern that contains a non-trailing slash is matched
> 
> And I don't like this phrase either. I think its too easy to confuse it
> with "A pattern that contains no trailing slash".
> 
> So I would suggest to replace both with the following:
> 
>     If the pattern contains no slash or only a trailing slash, [...].
>     Otherwise (when it contains a non-trailing slash) the pattern
>     is matched [...].

With all those new "if"s, "but"s, "otherwise"s, "when"s, and "except"s,
I have a feeling that the current way to say

   If .... ends with a slash, then ... only directories... The trailing
   slash is removed for the purpose of the remaining rules.

is still the best way to go forward. I do understand that this is a
rather technical way to explain things than a colloquial one, but it
also does remove a lot of conditionals and, therefore, mental burden.

-- Hannes

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

On 18.05.19 08:42, Johannes Sixt wrote:
> Am 17.05.19 um 23:43 schrieb Dr. Adam Nielsen:
>>> Another thing that I noticed is that its not mentioned anywhere that
>>> the pattern use a slash as a directory separator (instead of a
>>> backslash), its only clear from the examples. Maybe its worth to
>>> mention it in the "PATTERN FORMAT" section. Also its maybe worth to
>>> introduce the term "leading slash" and "trailing slash" because they
>>> will be of importance of the following paragraphs. Something like this
>>> after the paragraph of "!":
>>>
>>>       [...] for example, "\!important!.txt".
>>>
>>>       A slash `/` is used as a directory separator.
>>>       A leading slash (that is if the pattern begins with a slash)
>>>       or a trailing slash (that is if the pattern ends with a slash)
>>>       have special meaning and are explained below.
>>>
>>>       If the pattern contains a trailing slash, it would only find
>>>       a match with a directory. [...]
>>>
>>
>>
>> I changed my mind about this last addition. I think it is not very
>> readable and there is no need to explain leading/trailing slash. Maybe
>> one could just note it like this:
>>
>>        [...] for example, "\!important!.txt".
>>
>>        A slash `/` is used as a directory separator.
>>        A leading and trailing slash have special meaning
>>        and are explained in the following.
>>
>>        If the pattern ends with a slash, it would only find
>>        a match with a directory. [...]
>>
>> then I would also add:
>>
>>       If the pattern does not end with a slash, it would find a match
>>       with a file or directory.
>>
>>
>> Two notes about two sentences that I proposed a while ago:
>>
>>> + - If the pattern contains no slash "`/`" (except an optional
>> trailing slash),
>>> +   the ...
>>
>> I think that this sentence is not very readable. The exceptional case in
>> the brackets makes it over complicated.
>>
>>> + - A pattern that contains a non-trailing slash is matched
>>
>> And I don't like this phrase either. I think its too easy to confuse it
>> with "A pattern that contains no trailing slash".
>>
>> So I would suggest to replace both with the following:
>>
>>      If the pattern contains no slash or only a trailing slash, [...].
>>      Otherwise (when it contains a non-trailing slash) the pattern
>>      is matched [...].
> 
> With all those new "if"s, "but"s, "otherwise"s, "when"s, and "except"s,
> I have a feeling that the current way to say
> 
>     If .... ends with a slash, then ... only directories... The trailing
>     slash is removed for the purpose of the remaining rules.
> 
> is still the best way to go forward >
 > I do understand that this is a
 > rather technical way to explain things than a colloquial one, but it
 > also does remove a lot of conditionals and, therefore, mental burden.
 >
 > -- Hannes
 >

If one compares the current version with the new proposed one (including 
the updates from my last mail) word by word, then one finds that there 
is no additional "when", "except" and "but" and that the number of 
"if's" and "otherwise" has remained the same. So the other alternative 
does not "remove a lot of conditionals".

 >     [...] The trailing
 >     slash is removed for the purpose of the remaining rules.

has many downsides that I have explained in detail in the mail from 
09.04.2019. The biggest issue is that the paragraphs do not stand for 
themselves alone anymore.

The only thing that would really change regarding the trailing slash is 
that we would say

     If the pattern contains no slash or only a trailing slash, [...}

instead of

 > - - If the pattern does not contain a slash '/',  [...]


I will send the current version with its latest changes to make it more 
clear how readable the latest version is.

Best regards
Adam

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Make all paragraphs valid, even if they are not read
in strict order. Make paragraph better understandable
for pattern without slash. Add sentece and example
for pattern with slash. Be precise whenever a trailing 
slashe would make a difference. Add some examples.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 58 +++++++++++++++++++++++--------------
 1 file changed, 37 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..584c82c7df 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,44 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing 
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a 
+   symbolic link `foo` (this is consistent with the way how 
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+   Otherwise 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). 
+
+ - The above pargraph also includes the case of a leading slash.
+   For example, the pattern `/bar` only matches the file or 
+   folder `bar` that is at the same location as the `gitignore` 
+   file. Whereas the pattern `bar` would also match in folders 
+   below the `gitignore`  file. Note that the pattern `doc/frotz` 
+   and `/doc/frotz` have the same effect in any `.gitignore` file. 
+
+ - 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.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
-- 
2.17.1

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Make all paragraphs valid, even if they are not read
in strict order. Make paragraph better understandable
for pattern without slash. Add sentece and example
for pattern with slash. Be precise whenever a trailing 
slashe would make a difference. Add some examples.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 57 +++++++++++++++++++++++--------------
 1 file changed, 36 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..925bf767b1 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,43 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a
+   symbolic link `foo` (this is consistent with the way how
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+   Otherwise 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).
+
+ - The above pargraph also includes the case of a leading slash.
+   For example, the pattern `/bar` only matches the file or
+   folder `bar` that is at the same location as the `gitignore`
+   file. Whereas the pattern `bar` would also match in folders
+   below the `gitignore`  file.
+
+ - 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.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

Hi Adam

On 18/05/2019 15:07, Dr. Adam Nielsen wrote:
> + - 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).
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'.

A blank line separator make make it more obvious.  Alternatively, make 
the "For example" parts flow as part of their previous lines.
If you go for an additional blank line then the next next para needs to 
clarify it's 'above' as their will be two paras, not one.
> +   Otherwise 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).

 > + - The above pargraph also includes the case of a leading slash.

s/pargraph/paragraph/
--
Philip

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> gitignore.txt: make slash-rules more readable
>
> 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 ;-)

> + - A slash `/` is used as a directory separator. A leading and trailing
> +   slash have special meaning and are explained in the following.
> +
> + - If the pattern ends with a slash, it would only find
> +   directory `foo`, but will not match a regular file or a
> +   symbolic link `foo` (this is consistent with the way how
> +   pathspec works in general in Git).
> +
> + - If the pattern does not end with a slash, it would find a match
> +   with a file or directory.
> +
> + - 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).
> +   Otherwise 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).

OK.

> + - The above pargraph also includes the case of a leading slash.

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 ;-) To put it differently, your reading of the above four
bullets are incomplete unless you read this too.

Typofix: "pargraph" -> "paragraph".

In any case, I cannot guess what 'also include the case of a leaning
slash' wants to say.  Perhaps

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

as the third point of the above paragraph (the first is about a
pattern without a slash, the second "Otherwise" is about a pattern
with one or more slashes, and the new "Note that" becomes the
third) may make it easier to follow and keep your "each bullet point
is independent".

> +   For example, the pattern `/bar` only matches the file or
> +   folder `bar` that is at the same location as the `gitignore`
> +   file. Whereas the pattern `bar` would also match in folders
> +   below the `gitignore`  file.
> +
> + - 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.
> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>  
>  Two consecutive asterisks ("`**`") in patterns matched against
>  full pathname may have special meaning:

Re: [PATCH] make slash-rules more readable

[Johannes Sixt]

Am 18.05.19 um 16:13 schrieb Dr. Adam Nielsen:
> - - If the pattern ends with a slash, it is removed for the
> -   purpose of the following description, but it would only find
> + - A slash `/` is used as a directory separator. A leading and trailing
> +   slash have special meaning and are explained in the following.
> +
> + - If the pattern ends with a slash, it would only find
>     a match with a directory.  In other words, `foo/` will match a
> -   directory `foo` and paths underneath it, but will not match a
> -   regular file or a symbolic link `foo` (this is consistent
> -   with the way how pathspec works in general in Git).
> -
> - - If the pattern does not contain a slash '/', Git treats it as
> -   a shell glob pattern and checks for a match against the
> -   pathname relative to the location of the `.gitignore` file
> -   (relative to the toplevel of the work tree if not from a
> -   `.gitignore` file).
> -
> - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
> -   anything except "`/`", "`?`" matches any one character except "`/`"
> -   and "`[]`" matches one character in a selected range. See
> -   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
> -   description.
> -
> - - A leading slash matches the beginning of the pathname.
> -   For example, "/{asterisk}.c" matches "cat-file.c" but not
> -   "mozilla-sha1/sha1.c".
> +   directory `foo`, but will not match a regular file or a
> +   symbolic link `foo` (this is consistent with the way how
> +   pathspec works in general in Git).
> +
> + - If the pattern does not end with a slash, it would find a match
> +   with a file or directory.
> +
> + - 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).
> +   Otherwise 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).
> +
> + - The above pargraph also includes the case of a leading slash.
> +   For example, the pattern `/bar` only matches the file or
> +   folder `bar` that is at the same location as the `gitignore`
> +   file. Whereas the pattern `bar` would also match in folders
> +   below the `gitignore`  file.
> +
> + - 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.
> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>  
>  Two consecutive asterisks ("`**`") in patterns matched against
>  full pathname may have special meaning:

All those examples unterrupt the flow of thought in a way that makes it
diffcult to follow the reasoning. 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.

Let's see how that works out.

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

-- Hannes

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

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

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

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

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Remove meta-rule in a paragraph for trailing-slash.
Be precise whenever a trailing slash would make a 
difference. Improve paragraph for pattern without slash. 
Remove rule for leading slash because its now redundant. 
Instead, add examples for leading slash and asterix in 
example section.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
 1 file changed, 50 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..a6c7807c74 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,32 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a
+   symbolic link `foo` (this is consistent with the way how
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+
+ - An asterisk "`*`" matches anything except a slash.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +156,31 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - 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). That is because the
+   pattern `/bar` contains a non-trailing slash and thus matches
+   relative to the location of the `.gitignore` file.
+   Since `bar` has no slash, it matches recursively.
+
+ - The pattern 'hello.*' is not sufficient for the following rule:
+   "ignore any file whose name begins with 'hello' and in this
+   directory only, not in its subdirectories." because the pattern
+   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'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. Both pattern contain a non-trailing
+   slash and thus match relative to the location of the
+   `.gitignore` file.
+
+ - The pattern "foo/*", 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.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> gitignore.txt: make slash-rules more readable
>
> Remove meta-rule in a paragraph for trailing-slash.
> Be precise whenever a trailing slash would make a 
> difference. Improve paragraph for pattern without slash. 
> Remove rule for leading slash because its now redundant. 
> Instead, add examples for leading slash and asterix in 
> example section.
>
> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
>
> ---
>  Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
>  1 file changed, 50 insertions(+), 21 deletions(-)

I think the updated text is readable, except for one nit.

Specifically, if you took my suggestion in an earlier review to
explicitly say that leading slash is merely a workaround for a
string without slash to anchor the pattern to the directory and
it should be treated as if it does not exist otherwise, then ...

> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
> +   in any `.gitignore` file. Both pattern contain a non-trailing
> +   slash and thus match relative to the location of the
> +   `.gitignore` file.

... this paragraph wouldn't have been necessary.  

Besides, one extra reason why these two have the same effect is not
given in the updated text to explain away "To which substring of
path 'doc/frotz' does that leading slash in /doc/frotz match?"

The updated text does not seem to explain that the leading slash is
merely to pretend that the pattern "contains a slash so it does not
apply in a subdirectory" and for the purpose of pattern matching the
slash does not participate in the textual match, which seems to have
been lost in the updated patch, relative to the suggestions raised
in the review of earlier rounds.

The updated description on trailing slash as type specifier
(i.e. directory-only) is much easier to follow compared to the
earlier rounds of this patch, I would think.

Thanks.

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

On 31.05.19 18:30, Junio C Hamano wrote:
> "Dr. Adam Nielsen" <admin@in-ici.net> writes:
> 
>> gitignore.txt: make slash-rules more readable
>>
>> Remove meta-rule in a paragraph for trailing-slash.
>> Be precise whenever a trailing slash would make a
>> difference. Improve paragraph for pattern without slash.
>> Remove rule for leading slash because its now redundant.
>> Instead, add examples for leading slash and asterix in
>> example section.
>>
>> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
>>
>> ---
>>   Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
>>   1 file changed, 50 insertions(+), 21 deletions(-)
> 
> I think the updated text is readable, except for one nit.
> 
> Specifically, if you took my suggestion in an earlier review to

I guess you are referencing on your review from 08.05.2019 to which I 
responded On 12.05.19 11:56,

 >> The "note" is not incorrect per-se.  The behaviour described is
 >> because the leading slash is removed for the purpose of textual
 >> matching against paths, but still counts as a non-trailing slash for
 >> the purpose of anchoring the pattern to the level of recursion.
 >>
 >> I am not sure if that is obvious to the readers, though.
 >
 > Yes, its not explained to the reader that the leading slash is removed
 > for the purpose of textual matching. But maybe this is not necessary in
 > order to understand the effect of the pattern.

> explicitly say that leading slash is merely a workaround for a
> string without slash to anchor the pattern to the directory and
> it should be treated as if it does not exist otherwise, then ...
> 
>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>> +   in any `.gitignore` file. Both pattern contain a non-trailing
>> +   slash and thus match relative to the location of the
>> +   `.gitignore` file.
> 
> ... this paragraph wouldn't have been necessary.

I think this above example follows from (and thus isn't necessary, but 
just a fine example)

     + - The pattern is matched relative to the location of
     +   the `.gitignore` file. Except if the pattern contains
     +   no slash [...]

Because a pattern with a leading slash has a slash, it "is matched 
relative to the location of the `.gitignore` file".

> 
> Besides, one extra reason why these two have the same effect is not
> given in the updated text to explain away "To which substring of
> path 'doc/frotz' does that leading slash in /doc/frotz match?"
 >
> The updated text does not seem to explain that the leading slash is
> merely to pretend that the pattern "contains a slash so it does not
> apply in a subdirectory" and for the purpose of pattern matching the
> slash does not participate in the textual match, which seems to have
> been lost in the updated patch, relative to the suggestions raised
> in the review of earlier rounds.

I believe its not said anywhere in the docs that the pattern is compared 
  by a textual match to a piece of the full path of a file\folder (where 
the path is represented as in a unix-like OS).

I feel like your proposal from

On 08.05.19 07:33, Junio C Hamano wrote:
 >  - A leading slash, if any, is implicitly removed before matching the
 >    pattern with the pathname, but the pattern still counts as having
 >    a non-trailing slash for the purpose of the above rule.

is great for everyone who knows about the algorithm in the background, 
but for others it might be unclear what is meant.

For example "pathname" is not explained anywhere. Its not clear if 
"pathname" itself contains a leading slash, or in which format the 
"pathname" is represented, or if its is absolute or relative.
And "implicitly removed before matching.." is maybe a bit confusing for 
people that see the matching algorithm as a black box. If its not 
explained anywhere in detail how the matching algorithm is conducted, 
why would it matter to tell that the leading slash is removed implicitly?

Thats why I think, the case with the leading slash is already covered by 
the paragraph

     + - The pattern is matched relative to the location of
     +   the `.gitignore` file. Except if the pattern contains
     +   no slash [...]

and why I put the further explanations (that are not necessary in my 
opinion, but also not obvious) in the example section.

Thus, I don't feel the need to add another paragraph, but if you want, I 
can add

 >  - A leading slash, if any, is implicitly removed before matching the
 >    pattern with the pathname, but the pattern still counts as having
 >    a non-trailing slash for the purpose of the above rule.

as another bullet to the patch.

All the best,
Adam

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>>> +   in any `.gitignore` file. Both pattern contain a non-trailing
>>> +   slash and thus match relative to the location of the
>>> +   `.gitignore` file.
>>
>> ... this paragraph wouldn't have been necessary.
>
> I think this above example follows from (and thus isn't necessary, but
> just a fine example)
>
>     + - The pattern is matched relative to the location of
>     +   the `.gitignore` file. Except if the pattern contains
>     +   no slash [...]
>
> Because a pattern with a leading slash has a slash, it "is matched
> relative to the location of the `.gitignore` file".

But that does not explain why the pattern /doc/frotz matches the
path doc/frotz.  A reader can understand 'd' (the second letter in
the patern) would match 'd' (the firstr letter in the path), 'o'
with 'o', etc., but nobody told the reader which substring of the
path consumes the leading '/' in the pattern as matched.

>>  - A leading slash, if any, is implicitly removed before matching the
>>    pattern with the pathname, but the pattern still counts as having
>>    a non-trailing slash for the purpose of the above rule.

Yeah, that would be an addition that makes the updated text
more complete.

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

---
 Documentation/gitignore.txt | 75 ++++++++++++++++++++++++++-----------
 1 file changed, 54 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..ce944779a5 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,36 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a
+   symbolic link `foo` (this is consistent with the way how
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+
+ - A leading slash, if any, is implicitly removed before matching the
+   pattern with the pathname, but the pattern still counts as having
+   a non-trailing slash for the purpose of the above rule.
+
+ - An asterisk "`*`" matches anything except a slash.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +160,31 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - 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). That is because the
+   pattern `/bar` contains a non-trailing slash and thus matches
+   relative to the location of the `.gitignore` file.
+   Since `bar` has no slash, it matches recursively.
+
+ - The pattern 'hello.*' is not sufficient for the following rule:
+   "ignore any file whose name begins with 'hello' and in this
+   directory only, not in its subdirectories." because the pattern
+   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'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. Both pattern contain a non-trailing
+   slash and thus match relative to the location of the
+   `.gitignore` file.
+
+ - The pattern "foo/*", 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.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Remove meta-rule in a paragraph for trailing-slash.
Be precise whenever a trailing slash would make a 
difference. Improve paragraph for pattern without slash. 
Remove rule for leading slash because its now redundant. 
Instead, add examples for leading slash and asterix in 
example section.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 75 ++++++++++++++++++++++++++-----------
 1 file changed, 54 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..ce944779a5 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,36 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a
+   symbolic link `foo` (this is consistent with the way how
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+
+ - A leading slash, if any, is implicitly removed before matching the
+   pattern with the pathname, but the pattern still counts as having
+   a non-trailing slash for the purpose of the above rule.
+
+ - An asterisk "`*`" matches anything except a slash.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +160,31 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - 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). That is because the
+   pattern `/bar` contains a non-trailing slash and thus matches
+   relative to the location of the `.gitignore` file.
+   Since `bar` has no slash, it matches recursively.
+
+ - The pattern 'hello.*' is not sufficient for the following rule:
+   "ignore any file whose name begins with 'hello' and in this
+   directory only, not in its subdirectories." because the pattern
+   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'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. Both pattern contain a non-trailing
+   slash and thus match relative to the location of the
+   `.gitignore` file.
+
+ - The pattern "foo/*", 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.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

Minor spelling mistake at end:
On 31/05/2019 08:44, Dr. Adam Nielsen wrote:
> +   (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.
s/patter/pattern/
> +
>   --------------------------------------------------------------
Philip

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

Hi Junio,
On 31/05/2019 17:30, Junio C Hamano wrote:
> I think the updated text is readable, except for one nit.
>
> Specifically, if you took my suggestion in an earlier review to
> explicitly say that leading slash is merely a workaround for a
> string without slash to anchor the pattern to the directory and
> it should be treated as if it does not exist otherwise, then ...
 From a user perspective, implementation issues shouldn't be part of the 
description unless absolutely essential.

Most user aren't aware of the implementation so don't grok/understand 
what the fuss is about and ignore it...
>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>> +   in any `.gitignore` file. Both pattern contain a non-trailing
>> +   slash and thus match relative to the location of the
>> +   `.gitignore` file.
> ... this paragraph wouldn't have been necessary.
...leading to that user mistake having to be explained in numerous Q&A 
threads - Why can't we an explicit explanation of this common user 
mistake? Arguably the issue is the special trailing slash rule getting 
users confused..

--
Philip

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

Hi Philip,

On 01.06.19 11:33, Philip Oakley wrote:
>  From a user perspective, implementation issues shouldn't be part of the 
> description unless absolutely essential.
> 
> Most user aren't aware of the implementation so don't grok/understand 
> what the fuss is about and ignore it...

I agree with that. I will send another patch where I add the leading 
slash rule without going into implementation details.

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Remove meta-rule in a paragraph for trailing-slash.
Be precise whenever a trailing slash would make a 
difference. Improve or add paragraphs relevant 
for pattern with slash. Add some slash examples 
in example section.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 69 ++++++++++++++++++++++++++-----------
 1 file changed, 48 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..46195649f1 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,39 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - If the pattern ends with a slash, it would only find
    a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, but will not match a regular file or a
+   symbolic link `foo` (this is consistent with the way how
+   pathspec works in general in Git).
+
+ - If the pattern does not end with a slash, it would find a match
+   with a file or directory.
+
+ - 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).
+
+ - If the pattern contains a leading slash, the pattern
+   is matched relative to the location of the
+   `.gitignore` file (this is actually a direct consequence
+   of the previous paragraph). For example, `/bar` only matches
+   the file or folder `bar` but not `a/bar`,
+   whereas the pattern `bar` would match both.
+
+ - An asterisk "`*`" matches anything except a slash.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +163,22 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - The pattern 'hello.*' matches any file or folder
+   whose name begins with 'hello'. If one wants to restrict
+   this only to the directory and not in its subdirectories,
+   one can prepend the pattern with a slash, i.e. '/hello.*';
+   the pattern now matches 'hello.txt', 'hello.c' but not
+   'a/hello.java'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. Both pattern match relative to the
+   location of the `.gitignore` file.
+
+ - The pattern "foo/*", matches "foo/test.json"
+   (a regular file), "foo/bar" (a directory), but it does not match
+   "foo/bar/hello.c" (a regular file), as the asterisk in the
+   pattern does not match "bar/hello.c" which has a slash in it.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

Philip Oakley <philipoakley@talktalk.net> writes:

> From a user perspective, implementation issues shouldn't be part of
> the description unless absolutely essential.
> Most user aren't aware of the implementation so don't grok/understand
> what the fuss is about and ignore it...

Oh, absolutely.  But unfortunately I do not see what that principle
has anything to do with the comments you made in your message.

>> Specifically, if you took my suggestion in an earlier review to
>> explicitly say that leading slash is merely a workaround for a
>> string without slash to anchor the pattern to the directory and
>> it should be treated as if it does not exist otherwise, then ...

Perhaps you thought "workaround" refers to some implementation
glitch?  That is not what the word means in that sentence.  It is a
technique to work around "you need a slash somewhere in the pattern
to anchor it to a specific directory" that is a very user visible
design.  The user absolutely need to be aware of it, if s/he wants
to anchor a pattern that does not have a slash (e.g. "I need a
pattern to name/match the README file at this level but not in any
of the subdirectories"), and an extra leading slash is a way to mark
such a pattern that otherwise does not have a slash as anchored.

The fact that the leading slash is such a syntactic marking of a
pattern *and* is not a part of the pattern itself, would not help
you understand the implementation, but you need to know it in order
to use that feature effectively.

>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>>> +   in any `.gitignore` file. Both pattern contain a non-trailing
>>> +   slash and thus match relative to the location of the
>>> +   `.gitignore` file.
>> ... this paragraph wouldn't have been necessary.
> ...leading to that user mistake having to be explained in numerous Q&A
> threads - Why can't we an explicit explanation of this common user
> mistake?
> Arguably the issue is the special trailing slash rule getting
> users confused..

What common user mistake?  The above is about leading slash rule, by
the way, so perhaps you are getting confused?

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

On 03/06/2019 19:01, Junio C Hamano wrote:
> Philip Oakley <philipoakley@talktalk.net> writes:
>
>>  From a user perspective, implementation issues shouldn't be part of
>> the description unless absolutely essential.
>> Most user aren't aware of the implementation so don't grok/understand
>> what the fuss is about and ignore it...
> Oh, absolutely.  But unfortunately I do not see what that principle
> has anything to do with the comments you made in your message.
>
>>> Specifically, if you took my suggestion in an earlier review to
>>> explicitly say that leading slash is merely a workaround for a
>>> string without slash to anchor the pattern to the directory and
>>> it should be treated as if it does not exist otherwise, then ...
> Perhaps you thought "workaround" refers to some implementation
> glitch?  That is not what the word means in that sentence.  It is a
> technique to work around "you need a slash somewhere in the pattern
> to anchor it to a specific directory" that is a very user visible
> design.
It is the fact that we have ended up describing what needs to be done 
from having had the implementation problem. Thus we (accidentally) lock 
ourselves into a 'difficult to explain' situation.
>    The user absolutely need to be aware of it, if s/he wants
> to anchor a pattern that does not have a slash
No. That (as I read it, regarding the need for an initial slash) is the 
lock-in.

We should explain it from the other end  - to anchor the pattern one 
needs a slash either at the beginning or middle.

> (e.g. "I need a
> pattern to name/match the README file at this level but not in any
> of the subdirectories"), and an extra leading slash is a way to mark
> such a pattern that otherwise does not have a slash as anchored.
>
> The fact that the leading slash is such a syntactic marking of a
> pattern *and* is not a part of the pattern itself, would not help
> you understand the implementation, but you need to know it in order
> to use that feature effectively.
>
>>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>>>> +   in any `.gitignore` file. Both pattern contain a non-trailing
>>>> +   slash and thus match relative to the location of the
>>>> +   `.gitignore` file.
>>> ... this paragraph wouldn't have been necessary.
>> ...leading to that user mistake having to be explained in numerous Q&A
>> threads - Why can't we an explicit explanation of this common user
>> mistake?
>> Arguably the issue is the special trailing slash rule getting
>> users confused..
> What common user mistake?  The above is about leading slash rule, by
> the way, so perhaps you are getting confused?
We do get a reasonable number of queries to the list regarding 
.gitignore patterns which generally indicate that user have been 
confused and failed to understand the overall man page description (both 
leading and training slashes being somehow special but exactly how they 
haven't fully fathomed..) (and plenty on StackOverflow)

I'll ad some more feedback to Adam's side of the thread, and a possible 
alternate suggestion.

Philip

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

Hi Adam,
On 31/05/2019 08:44, Dr. Adam Nielsen wrote:
> gitignore.txt: make slash-rules more readable
>
> Remove meta-rule in a paragraph for trailing-slash.
> Be precise whenever a trailing slash would make a
> difference. Improve paragraph for pattern without slash.
> Remove rule for leading slash because its now redundant.
> Instead, add examples for leading slash and asterix in
> example section.
>
> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
I think the rules end up being difficult because we describe them from a 
coders implementation viewpoint, rather than a users descriptive 
viewpoint. Thus we avoided things like the difficult to code slashes in 
the front/middle, and we get caught on the equivalent of neither/nor 
phrases, which can even be difficult for native English speakers.

Later on there is a recursively/respectively issue (latter not 
explicitly mentioned).  There is also an "Except if" not-a-proper 
sentence. (mentioned off-line)

I think this is the truth table for the slash..
Lead/  | mid/  | end/  |
yes    |yes    |yes    | Directory, directly at .gitignore
no     |yes    |yes    | Directory, directly at .gitignore
yes    |no     |yes    | Directory, directly at .gitignore
no     |no     |yes    | Directory, anywhere at, or below, .gitignore   
<the tricky one ;-)

yes    |yes    |no     | file or Directory, directly at .gitignore
no     |yes    |no     | file or Directory, directly at .gitignore
yes    |no     |no     | file or Directory, directly at .gitignore
no     |no     |no     | file or Directory, anywhere at, or below, 
.gitignore

After sleeping on it, I came up with:

    The slash '/' is used as the directory separator. Separators may
    occur at the beginning, middle or end of the .gitignore search pattern.

    If there is a separator at the beginning or middle (or both) of the
    pattern, then the pattern is relative to the directory level of the
    particular .gitignore file itself. Otherwise the pattern may also
    match at any level below the .gitignore level.

    If there is a separator at the end of the pattern then the pattern
    will only match directories, otherwise the pattern can match both
    files and directories.

    Examples text..

    The special '*' ...

    The special '**' ...

-- 
The key (for me) was to add in the sentence that says we have 
beginning/middle/end slashes as a prompt ready for later, and use the 
plural for 'separator'.

I then also used 'otherwise' and an occasional 'also'  to avoid any 
and/or/neither/nor logic problems. I removed all 'it/they/them' style 
indirect references as it is easy to pick the wrong indirection.

I have been explicit (pedantic) about '.gitignore search pattern' to 
avoid the reader accidentally changing focus and thinking of the path 
string.

One could also add "Likewise the directory(?) pattern will not match a 
symbolic link, as is normal for pathspecs in Git." as this isn't 
mentioned elsewhere.
--
Philip

> ---
>   Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
>   1 file changed, 50 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index b5bc9dbff0..a6c7807c74 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -89,28 +89,32 @@ PATTERN FORMAT
>      Put a backslash ("`\`") in front of the first "`!`" for patterns
>      that begin with a literal "`!`", for example, "`\!important!.txt`".
>   
> - - If the pattern ends with a slash, it is removed for the
> -   purpose of the following description, but it would only find
> + - A slash `/` is used as a directory separator. A leading and trailing
> +   slash have special meaning and are explained in the following.
> +
> + - If the pattern ends with a slash, it would only find
>      a match with a directory.  In other words, `foo/` will match a
> -   directory `foo` and paths underneath it, but will not match a
> -   regular file or a symbolic link `foo` (this is consistent
> -   with the way how pathspec works in general in Git).
> -
> - - If the pattern does not contain a slash '/', Git treats it as
> -   a shell glob pattern and checks for a match against the
> -   pathname relative to the location of the `.gitignore` file
> -   (relative to the toplevel of the work tree if not from a
> -   `.gitignore` file).
> -
> - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
> -   anything except "`/`", "`?`" matches any one character except "`/`"
> -   and "`[]`" matches one character in a selected range. See
> -   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
> -   description.
> -
> - - A leading slash matches the beginning of the pathname.
> -   For example, "/{asterisk}.c" matches "cat-file.c" but not
> -   "mozilla-sha1/sha1.c".
> +   directory `foo`, but will not match a regular file or a
> +   symbolic link `foo` (this is consistent with the way how
> +   pathspec works in general in Git).
> +
> + - If the pattern does not end with a slash, it would find a match
> +   with a file or directory.
> +
> + - 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).
> +
> + - An asterisk "`*`" matches anything except a slash.
> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>   
>   Two consecutive asterisks ("`**`") in patterns matched against
>   full pathname may have special meaning:
> @@ -152,6 +156,31 @@ To stop tracking a file that is currently tracked, use
>   EXAMPLES
>   --------
>   
> + - 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). That is because the
> +   pattern `/bar` contains a non-trailing slash and thus matches
> +   relative to the location of the `.gitignore` file.
> +   Since `bar` has no slash, it matches recursively.
> +
> + - The pattern 'hello.*' is not sufficient for the following rule:
> +   "ignore any file whose name begins with 'hello' and in this
> +   directory only, not in its subdirectories." because the pattern
> +   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'.
> +
> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
> +   in any `.gitignore` file. Both pattern contain a non-trailing
> +   slash and thus match relative to the location of the
> +   `.gitignore` file.
> +
> + - The pattern "foo/*", 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.
> +
>   --------------------------------------------------------------
>       $ git status
>       [...]

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

Hi Philip

On 04.06.19 14:34, Philip Oakley wrote:
> I think the rules end up being difficult because we describe them from a 
> coders implementation viewpoint, rather than a users descriptive 
> viewpoint. Thus we avoided things like the difficult to code slashes in 
> the front/middle, and we get caught on the equivalent of neither/nor 
> phrases, which can even be difficult for native English speakers.
> 
> Later on there is a recursively/respectively issue (latter not 
> explicitly mentioned).  There is also an "Except if" not-a-proper 
> sentence. (mentioned off-line)
> 
> After sleeping on it, I came up with:
> 
>     The slash '/' is used as the directory separator. Separators may
>     occur at the beginning, middle or end of the .gitignore search pattern.
> 
>     If there is a separator at the beginning or middle (or both) of the
>     pattern, then the pattern is relative to the directory level of the
>     particular .gitignore file itself. Otherwise the pattern may also
>     match at any level below the .gitignore level.
> 
>     If there is a separator at the end of the pattern then the pattern
>     will only match directories, otherwise the pattern can match both
>     files and directories.
> 
>     Examples text..
> 
>     The special '*' ...
> 
>     The special '**' ...
> 

I am really happy about this improvement (or rather this new creation). 
In my opinion it is really easy to understand now, and it solves a ton 
of other issues we had with the preceding proposals.

I will create a new patch.

All the best,
Adam

[PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

gitignore.txt: make slash-rules more readable

Renew paragraphs relevant for pattern with slash. 
Aim to make it more clear and to avoid possible
pitfalls for the reader. Add some examples.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 66 ++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 22 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..d47b1ae296 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,28 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
-   a match with a directory.  In other words, `foo/` will match a
-   directory `foo` and paths underneath it, but will not match a
-   regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in Git).
-
- - If the pattern does not contain a slash '/', Git treats it as
-   a shell glob pattern and checks for a match against the
-   pathname relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+ - The slash '/' is used as the directory separator. Separators may
+   occur at the beginning, middle or end of the `.gitignore` search pattern.
+
+ - If there is a separator at the beginning or middle (or both) of the
+   pattern, then the pattern is relative to the directory level of the
+   particular `.gitignore` file itself. Otherwise the pattern may also
+   match at any level below the `.gitignore` level.
+
+ - If there is a separator at the end of the pattern then the pattern
+   will only match directories, otherwise the pattern can match both
+   files and directories.
+
+ - For example, a pattern `doc/frotz/` matches `doc/frotz` directory,
+   but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
+   and `a/frotz` that is a directory (all paths are relative from
+   the `.gitignore` file).
+
+ - An asterisk "`*`" matches anything except a slash.
+   The character "`?`" matches any one character except "`/`".
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the
+   FNM_PATHNAME flag for a more detailed description.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +152,28 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - The pattern `hello.*` matches any file or folder
+   whose name begins with `hello`. If one wants to restrict
+   this only to the directory and not in its subdirectories,
+   one can prepend the pattern with a slash, i.e. `/hello.*`;
+   the pattern now matches `hello.txt`, `hello.c` but not
+   `a/hello.java`.
+
+ - The pattern `foo/` will match a directory `foo` and
+   paths underneath it, but will not match a regular file
+   or a symbolic link `foo` (this is consistent with the
+   way how pathspec works in general in Git)
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. In other words, a leading slash
+   is not relevant  if there is already a middle slash in
+   the pattern.
+
+ - The pattern "foo/*", matches "foo/test.json"
+   (a regular file), "foo/bar" (a directory), but it does not match
+   "foo/bar/hello.c" (a regular file), as the asterisk in the
+   pattern does not match "bar/hello.c" which has a slash in it.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

Hi everyone,

any comments about the patch note from 04.06 ?

All the best,
Adam

On 04.06.19 19:34, Dr. Adam Nielsen wrote:
> gitignore.txt: make slash-rules more readable
> 
> Renew paragraphs relevant for pattern with slash.
> Aim to make it more clear and to avoid possible
> pitfalls for the reader. Add some examples.
> 
> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
> 
> ---
>   Documentation/gitignore.txt | 66 ++++++++++++++++++++++++-------------
>   1 file changed, 44 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index b5bc9dbff0..d47b1ae296 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -89,28 +89,28 @@ PATTERN FORMAT
>      Put a backslash ("`\`") in front of the first "`!`" for patterns
>      that begin with a literal "`!`", for example, "`\!important!.txt`".
>   
> - - If the pattern ends with a slash, it is removed for the
> -   purpose of the following description, but it would only find
> -   a match with a directory.  In other words, `foo/` will match a
> -   directory `foo` and paths underneath it, but will not match a
> -   regular file or a symbolic link `foo` (this is consistent
> -   with the way how pathspec works in general in Git).
> -
> - - If the pattern does not contain a slash '/', Git treats it as
> -   a shell glob pattern and checks for a match against the
> -   pathname relative to the location of the `.gitignore` file
> -   (relative to the toplevel of the work tree if not from a
> -   `.gitignore` file).
> -
> - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
> -   anything except "`/`", "`?`" matches any one character except "`/`"
> -   and "`[]`" matches one character in a selected range. See
> -   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
> -   description.
> -
> - - A leading slash matches the beginning of the pathname.
> -   For example, "/{asterisk}.c" matches "cat-file.c" but not
> -   "mozilla-sha1/sha1.c".
> + - The slash '/' is used as the directory separator. Separators may
> +   occur at the beginning, middle or end of the `.gitignore` search pattern.
> +
> + - If there is a separator at the beginning or middle (or both) of the
> +   pattern, then the pattern is relative to the directory level of the
> +   particular `.gitignore` file itself. Otherwise the pattern may also
> +   match at any level below the `.gitignore` level.
> +
> + - If there is a separator at the end of the pattern then the pattern
> +   will only match directories, otherwise the pattern can match both
> +   files and directories.
> +
> + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory,
> +   but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
> +   and `a/frotz` that is a directory (all paths are relative from
> +   the `.gitignore` file).
> +
> + - An asterisk "`*`" matches anything except a slash.
> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>   
>   Two consecutive asterisks ("`**`") in patterns matched against
>   full pathname may have special meaning:
> @@ -152,6 +152,28 @@ To stop tracking a file that is currently tracked, use
>   EXAMPLES
>   --------
>   
> + - The pattern `hello.*` matches any file or folder
> +   whose name begins with `hello`. If one wants to restrict
> +   this only to the directory and not in its subdirectories,
> +   one can prepend the pattern with a slash, i.e. `/hello.*`;
> +   the pattern now matches `hello.txt`, `hello.c` but not
> +   `a/hello.java`.
> +
> + - The pattern `foo/` will match a directory `foo` and
> +   paths underneath it, but will not match a regular file
> +   or a symbolic link `foo` (this is consistent with the
> +   way how pathspec works in general in Git)
> +
> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
> +   in any `.gitignore` file. In other words, a leading slash
> +   is not relevant  if there is already a middle slash in
> +   the pattern.
> +
> + - The pattern "foo/*", matches "foo/test.json"
> +   (a regular file), "foo/bar" (a directory), but it does not match
> +   "foo/bar/hello.c" (a regular file), as the asterisk in the
> +   pattern does not match "bar/hello.c" which has a slash in it.
> +
>   --------------------------------------------------------------
>       $ git status
>       [...]
> 

-- 
photograph 	
*Dr. Adam Nielsen
* Administrator | IN/ICI/WHO
*IN:* 	nlp-institutes.net <https://nlp-institutes.net>
*ICI:* 	coaching-institutes.net <https://coaching-institutes.net>
*WHO:* 	world-hypnosis.org <https://world-hypnosis.org>

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

only one minor point...

On 25/06/2019 12:05, Dr. Adam Nielsen wrote:
> Hi everyone,
>
> any comments about the patch note from 04.06 ?
>
> All the best,
> Adam
>
> On 04.06.19 19:34, Dr. Adam Nielsen wrote:
>> gitignore.txt: make slash-rules more readable
>>
>> Renew paragraphs relevant for pattern with slash.
>> Aim to make it more clear and to avoid possible
>> pitfalls for the reader. Add some examples.
>>
>> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
>>
>> ---
>>   Documentation/gitignore.txt | 66 ++++++++++++++++++++++++-------------
>>   1 file changed, 44 insertions(+), 22 deletions(-)
>>
>> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
>> index b5bc9dbff0..d47b1ae296 100644
>> --- a/Documentation/gitignore.txt
>> +++ b/Documentation/gitignore.txt
>> @@ -89,28 +89,28 @@ PATTERN FORMAT
>>      Put a backslash ("`\`") in front of the first "`!`" for patterns
>>      that begin with a literal "`!`", for example, "`\!important!.txt`".
>>   - - If the pattern ends with a slash, it is removed for the
>> -   purpose of the following description, but it would only find
>> -   a match with a directory.  In other words, `foo/` will match a
>> -   directory `foo` and paths underneath it, but will not match a
>> -   regular file or a symbolic link `foo` (this is consistent
>> -   with the way how pathspec works in general in Git).
>> -
>> - - If the pattern does not contain a slash '/', Git treats it as
>> -   a shell glob pattern and checks for a match against the
>> -   pathname relative to the location of the `.gitignore` file
>> -   (relative to the toplevel of the work tree if not from a
>> -   `.gitignore` file).
>> -
>> - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
>> -   anything except "`/`", "`?`" matches any one character except "`/`"
>> -   and "`[]`" matches one character in a selected range. See
>> -   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
>> -   description.
>> -
>> - - A leading slash matches the beginning of the pathname.
>> -   For example, "/{asterisk}.c" matches "cat-file.c" but not
>> -   "mozilla-sha1/sha1.c".
>> + - The slash '/' is used as the directory separator. Separators may
>> +   occur at the beginning, middle or end of the `.gitignore` search 
>> pattern.
>> +
>> + - If there is a separator at the beginning or middle (or both) of the
>> +   pattern, then the pattern is relative to the directory level of the
>> +   particular `.gitignore` file itself. Otherwise the pattern may also
>> +   match at any level below the `.gitignore` level.
>> +
>> + - If there is a separator at the end of the pattern then the pattern
>> +   will only match directories, otherwise the pattern can match both
>> +   files and directories.
>> +
>> + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory,
>> +   but not `a/doc/frotz` directory; however `frotz/` matches `frotz`

her I misread this as:  "but not a `doc/frotz` directory;"
i.e. the leading 'a' is too easy to skim over as is part of the 
sentence's prose, so maybe change to a 'baz' lead directory (bar already 
having been used below).

>> +   and `a/frotz` that is a directory (all paths are relative from
>> +   the `.gitignore` file).
>> +
>> + - An asterisk "`*`" matches anything except a slash.
>> +   The character "`?`" matches any one character except "`/`".
>> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
>> +   one of the characters in a range. See fnmatch(3) and the
>> +   FNM_PATHNAME flag for a more detailed description.
>>     Two consecutive asterisks ("`**`") in patterns matched against
>>   full pathname may have special meaning:
>> @@ -152,6 +152,28 @@ To stop tracking a file that is currently 
>> tracked, use
>>   EXAMPLES
>>   --------
>>   + - The pattern `hello.*` matches any file or folder
>> +   whose name begins with `hello`. If one wants to restrict
>> +   this only to the directory and not in its subdirectories,
>> +   one can prepend the pattern with a slash, i.e. `/hello.*`;
>> +   the pattern now matches `hello.txt`, `hello.c` but not
>> +   `a/hello.java`.
>> +
>> + - The pattern `foo/` will match a directory `foo` and
>> +   paths underneath it, but will not match a regular file
>> +   or a symbolic link `foo` (this is consistent with the
>> +   way how pathspec works in general in Git)
>> +
>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
>> +   in any `.gitignore` file. In other words, a leading slash
>> +   is not relevant  if there is already a middle slash in
>> +   the pattern.
>> +
>> + - The pattern "foo/*", matches "foo/test.json"
>> +   (a regular file), "foo/bar" (a directory), but it does not match
>> +   "foo/bar/hello.c" (a regular file), as the asterisk in the
>> +   pattern does not match "bar/hello.c" which has a slash in it.
>> +
>>   --------------------------------------------------------------
>>       $ git status
>>       [...]
>>
>
Have you tried it out on any StackOverflow replies to see if those that 
inhabit that zone find it helpful?
Philip

Re: [PATCH] make slash-rules more readable

[Dr. Adam Nielsen]

On 25.06.19 13:31, Philip Oakley wrote:
> only one minor point...

 >>> + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory,
 >>> +   but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
 >
 > her I misread this as:  "but not a `doc/frotz` directory;"
 > i.e. the leading 'a' is too easy to skim over as is part of the
 > sentence's prose, so maybe change to a 'baz' lead directory (bar already
 > having been used below).

Yes we could change that.

> Have you tried it out on any StackOverflow replies to see if those that 
> inhabit that zone find it helpful?
> Philip
I answered one person who had a hard time reading the docs at SO, but he 
didn't respond and the last time he was online was 2018, so I didn't 
made the effort to edit my answer with the current version.

-

What are the next steps? If there are no more responses, does it imply 
that everyone agrees with this patch? Can we publish it online?

Re: [PATCH] make slash-rules more readable

[Junio C Hamano]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> Hi everyone,
>
> any comments about the patch note from 04.06 ?

https://git.kernel.org/pub/scm/git/git.git/log/ shows that the topic
holding the patch has already been merged to the 'master' branch
about 6 days ago, at

https://git.kernel.org/pub/scm/git/git.git/commit/?id=e694ea5e04ea2cabc64ade337063b5562810b268

Thanks.

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

On 27/06/2019 18:10, Dr. Adam Nielsen wrote:
>
> On 25.06.19 13:31, Philip Oakley wrote:
>> only one minor point...
>
> >>> + - For example, a pattern `doc/frotz/` matches `doc/frotz` 
> directory,
> >>> +   but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
> >
> > her I misread this as:  "but not a `doc/frotz` directory;"
> > i.e. the leading 'a' is too easy to skim over as is part of the
> > sentence's prose, so maybe change to a 'baz' lead directory (bar 
> already
> > having been used below).
>
> Yes we could change that.
>
>> Have you tried it out on any StackOverflow replies to see if those 
>> that inhabit that zone find it helpful?
>> Philip
> I answered one person who had a hard time reading the docs at SO, but 
> he didn't respond and the last time he was online was 2018, so I 
> didn't made the effort to edit my answer with the current version.
>
> -
>
> What are the next steps? If there are no more responses, does it imply 
> that everyone agrees with this patch? Can we publish it online?
>
If all the issues are cleared then I believe it is a case of providing a 
clean reroll (maybe identical to previous..) to Junio and the list to 
confirm that all issues have been resolved and it is ready for 
pu->next->master in the normal way, which should then show up in his 
'What's cooking' emails.

Re: [PATCH] make slash-rules more readable

[Philip Oakley]

Oops, I missed Junio's message [1] while looking through my backlog. 
Sorry for the noise.
Philip

On 04/07/2019 11:40, Philip Oakley wrote:
> If all the issues are cleared then I believe it is a case of providing 
> a clean reroll (maybe identical to previous..) to Junio and the list 
> to confirm that all issues have been resolved and it is ready for 
> pu->next->master in the normal way, which should then show up in his 
> 'What's cooking' emails. 
[1] <xmqqd0iyc4av.fsf@gitster-ct.c.googlers.com>

Re: [PATCH] make slash-rules more readable

[Pavel Ivashkov]

There is a typo: `hello.*` in .gitignore will require dot in file name.

- - The pattern `hello.*` matches any file or folder
+ - The pattern `hello*` matches any file or folder