{"thread":{"id":"51047","subject":"[PATCH] make slash-rules more readable","startedAt":"2019-05-07T10:45:46Z","lastAt":"2019-05-18T13:20:57Z","messageCount":6,"participants":["Dr. Adam Nielsen","Junio C Hamano","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"375011","messageId":"20190507104507.18735-1-admin@in-ici.net","threadId":"51047","inReplyTo":null,"subject":"[PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-07T10:45:07Z","receivedAt":"2019-05-07T10:45:46Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"gitignore.txt: make slash-rules more readable\n\nMake all paragraphs valid, even if they are not read\nin strict order. Make paragraph better understandable\nfor pattern without slash. Add paragraph for pattern\nwith slash. Be precise whenever a trailing slashes\nwould make a difference. Add some examples.\n\nSigned-off-by: Dr. Adam Nielsen <admin@in-ici.net>\n\n---\n Documentation/gitignore.txt | 37 ++++++++++++++++++++++++-------------\n 1 file changed, 24 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex b5bc9dbff0..7d7fbd202e 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -89,24 +89,35 @@ PATTERN FORMAT\n    Put a backslash (\"`\\`\") in front of the first \"`!`\" for patterns\n    that begin with a literal \"`!`\", for example, \"`\\!important!.txt`\".\n \n- - If the pattern ends with a slash, it is removed for the\n-   purpose of the following description, but it would only find\n+ - If the pattern ends with a slash, it would only find\n    a match with a directory.  In other words, `foo/` will match a\n    directory `foo` and paths underneath it, but will not match a\n    regular file or a symbolic link `foo` (this is consistent\n    with the way how pathspec works in general in Git).\n \n- - If the pattern does not contain a slash '/', Git treats it as\n-   a shell glob pattern and checks for a match against the\n-   pathname relative to the location of the `.gitignore` file\n-   (relative to the toplevel of the work tree if not from a\n-   `.gitignore` file).\n-\n- - Otherwise, Git treats the pattern as a shell glob: \"`*`\" matches\n-   anything except \"`/`\", \"`?`\" matches any one character except \"`/`\"\n-   and \"`[]`\" matches one character in a selected range. See\n-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed\n-   description.\n+ - If the pattern contains no slash \"`/`\" (except an optional trailing slash),\n+   the pattern is matched against all files and folders (recursively)\n+   from the location of the `.gitignore` file.\n+   For example, `frotz/` matches `frotz` and `a/frotz` that\n+   is a directory (relative from the `.gitignore` file).\n+\n+ - A pattern that contains a non-trailing slash is matched\n+   relative to the location of the `.gitignore` file.\n+   For example, `doc/frotz/` matches `doc/frotz` directory, but not\n+   `a/doc/frotz` (relative from the `.gitignore` file).\n+   Note that the pattern `doc/frotz` and `/doc/frotz` have the\n+   same effect in any `.gitignore` file, while `/bar` and `bar`\n+   have not the same effect (`/bar` will not match `foo/bar`).\n+\n+ - An asterisk \"`*`\" matches anything except a slash.\n+   A pattern \"foo/*\", for example, matches \"foo/test.json\"\n+   (a regular file), \"foo/bar\" (a diretory), but it does not match\n+   \"foo/bar/hello.c\" (a regular file), as the asterisk in the\n+   patter does not match \"bar/hello.c\" which has a slash in it.\n+   The character \"`?`\" matches any one character except \"`/`\".\n+   The range notation, e.g. `[a-zA-Z]`, can be used to match\n+   one of the characters in a range. See fnmatch(3) and the\n+   FNM_PATHNAME flag for a more detailed description.\n \n  - A leading slash matches the beginning of the pathname.\n    For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n-- \n2.17.1\n\n"},{"id":"375092","messageId":"xmqqzhnxh5nm.fsf@gitster-ct.c.googlers.com","threadId":"51047","inReplyTo":"20190507104507.18735-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-08T05:33:16Z","receivedAt":"2019-05-08T05:33:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Dr. Adam Nielsen\" <admin@in-ici.net> writes:\n\n> + - A pattern that contains a non-trailing slash is matched\n> +   For example, `doc/frotz/` matches `doc/frotz` directory, but not\n> +   `a/doc/frotz` (relative from the `.gitignore` file).\n> +   Note that the pattern `doc/frotz` and `/doc/frotz` have the\n> +   same effect in any `.gitignore` file, while `/bar` and `bar`\n> +   have not the same effect (`/bar` will not match `foo/bar`).\n\nThe \"note\" is not incorrect per-se.  The behaviour described is\nbecause the leading slash is removed for the purpose of textual\nmatching against paths, but still counts as a non-trailing slash for\nthe purpose of anchoring the pattern to the level of recursion.\n\nI am not sure if that is obvious to the readers, though.  Especially\nbecause the \"a leading slash matches the beginning of ...\" which was\nin the original is still left and appears two bullet points after\nthis one, the presentation order seem a bit suboptimal.\n\nHow about deleting that \"A leading slash matches the beginning...\"\nbullet, and then splitting the above bullet into two?  That is\n\n- A pattern that contains a non-trailing slash is matched\n  For example, `doc/frotz/` matches `doc/frotz` directory, but not\n  `a/doc/frotz` (relative from the `.gitignore` file).\n\n- A leading slash, if any, is implicitly removed before matching the\n  pattern with the pathname, but the pattern still counts as having\n  a non-trailing slash for the purpose of the above rule.  For\n  example, a pattern `{asterisk}.c` does not have any slash in it,\n  so it would match a file or a directory whose name ends with `.c`\n  anywhere in the directory that has `.gitignore` file in it\n  (e.g. `sub/foo.c`, `bar.c`). By prefixing a slash to make it\n  `/{asterisk}.c`, it can be limited to match only at the current\n  level (i.e. `bar.c` but not `sub/foo.c`).\n\n> + - An asterisk \"`*`\" matches anything except a slash.\n> +   A pattern \"foo/*\", for example, matches \"foo/test.json\"\n> +   (a regular file), \"foo/bar\" (a diretory), but it does not match\n> +   \"foo/bar/hello.c\" (a regular file), as the asterisk in the\n> +   patter does not match \"bar/hello.c\" which has a slash in it.\n\ns/patter/&n/\n\n> +   The character \"`?`\" matches any one character except \"`/`\".\n> +   The range notation, e.g. `[a-zA-Z]`, can be used to match\n> +   one of the characters in a range. See fnmatch(3) and the\n> +   FNM_PATHNAME flag for a more detailed description.\n>  \n>   - A leading slash matches the beginning of the pathname.\n>     For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n\nThen this last paragraph can be removed.\n\n"},{"id":"375351","messageId":"094f3746-67c9-0284-0593-eb6b24d5c4a3@in-ici.net","threadId":"51047","inReplyTo":"xmqqzhnxh5nm.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-12T09:56:15Z","receivedAt":"2019-05-12T09:56:19Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"\n\nOn 08.05.19 07:33, Junio C Hamano wrote:\n> \"Dr. Adam Nielsen\" <admin@in-ici.net> writes:\n> \n>> + - A pattern that contains a non-trailing slash is matched  relative to the location of the `.gitignore` file.\n>> +   For example, `doc/frotz/` matches `doc/frotz` directory, but not\n>> +   `a/doc/frotz` (relative from the `.gitignore` file).\n>> +   Note that the pattern `doc/frotz` and `/doc/frotz` have the\n>> +   same effect in any `.gitignore` file, while `/bar` and `bar`\n>> +   have not the same effect (`/bar` will not match `foo/bar`).\n> \n> The \"note\" is not incorrect per-se.  The behaviour described is\n> because the leading slash is removed for the purpose of textual\n> matching against paths, but still counts as a non-trailing slash for\n> the purpose of anchoring the pattern to the level of recursion.\n> \n> I am not sure if that is obvious to the readers, though.\n\nYes, its not explained to the reader that the leading slash is removed \nfor the purpose of textual matching. But maybe this is not necessary in \norder to understand the effect of the pattern.\n\n>  Especially\n> because the \"a leading slash matches the beginning of ...\" which was\n> in the original is still left and appears two bullet points after\n> this one, the presentation order seem a bit suboptimal.\n\nI agree. The paragraph \"a leading slash matches the beginning of ...\" \nshould be deleted, because its already covered by the top rule plus an \nexample.\n\n> \n> How about deleting that \"A leading slash matches the beginning...\"\n> bullet, and then splitting the above bullet into two?  That is\n> \n> - A pattern that contains a non-trailing slash is matched\nis matched relative to the location of the `.gitignore` file.\n>    For example, `doc/frotz/` matches `doc/frotz` directory, but not\n>    `a/doc/frotz` (relative from the `.gitignore` file).\n> \n\nI agree that the case of a leading slash is important and deserves its \nown paragraph, especially if we remove the last bullet.\n\n\n> - A leading slash, if any, is implicitly removed before matching the\n>    pattern with the pathname, but the pattern still counts as having\n>    a non-trailing slash for the purpose of the above rule.  For\n\nI would try to avoid ambiguous words like  `implicitly removed ` and \n`pathname` that have not been used before. Also I am not sure if \nexplaining the reader how the algorithm works is the best approach.\n\n>    example, a pattern `{asterisk}.c` does not have any slash in it,\n>    so it would match a file or a directory whose name ends with `.c`\n>    anywhere in the directory that has `.gitignore` file in it\n>    (e.g. `sub/foo.c`, `bar.c`).\n\nA similar example is already in the  \"If the pattern contains no \nslash..\" paragraph. I think it takes a bit too much space just to \nexplain the difference when a leading slash appears.\n\n> By prefixing a slash to make it\n>    `/{asterisk}.c`, it can be limited to match only at the current\n>    level (i.e. `bar.c` but not `sub/foo.c`).\n\nHow about we split it like this:\n\n   - A pattern that contains a non-trailing slash is matched\n     relative to the location of the `.gitignore` file.\n     For example, `doc/frotz/` matches `doc/frotz` directory, but not\n     `a/doc/frotz` (relative from the `.gitignore` file; note that the\n     example has a trailing and a non-trailing slash at the same time).\n\n   - Note: A pattern with a leading slash has a non-trailing slash\n     and is therefore effected by the previous paragraph.\n     For example, the pattern `/bar` only matches the file or\n     folder `bar` that is at the same location as the `gitignore` file.\n     Whereas the pattern `bar` would also match in folders below the\n     `gitignore`  file.\n     On the other hand,  the pattern `doc/frotz` and `/doc/frotz`\n     have the same effect in any `.gitignore` file, because both\n     have a non-trailing slash.\n\n> \n>> + - An asterisk \"`*`\" matches anything except a slash.\n>> +   A pattern \"foo/*\", for example, matches \"foo/test.json\"\n>> +   (a regular file), \"foo/bar\" (a diretory), but it does not match\n>> +   \"foo/bar/hello.c\" (a regular file), as the asterisk in the\n>> +   patter does not match \"bar/hello.c\" which has a slash in it.\n> \n> s/patter/&n/\n> \n>> +   The character \"`?`\" matches any one character except \"`/`\".\n>> +   The range notation, e.g. `[a-zA-Z]`, can be used to match\n>> +   one of the characters in a range. See fnmatch(3) and the\n>> +   FNM_PATHNAME flag for a more detailed description.\n>>   \n>>    - A leading slash matches the beginning of the pathname.\n>>      For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n> \n> Then this last paragraph can be removed.\n\nAgree.\n-\n\nAnother thing that I noticed is that its not mentioned anywhere that the \npattern use a slash as a directory separator (instead of a backslash), \nits only clear from the examples. Maybe its worth to mention it in the \n\"PATTERN FORMAT\" section. Also its maybe worth to introduce the term \n\"leading slash\" and \"trailing slash\" because they will be of importance \nof the following paragraphs. Something like this after the paragraph of \"!\":\n\n     [...] for example, \"\\!important!.txt\".\n\n     A slash `/` is used as a directory separator.\n     A leading slash (that is if the pattern begins with a slash)\n     or a trailing slash (that is if the pattern ends with a slash)\n     have special meaning and are explained below.\n\n     If the pattern contains a trailing slash, it would only find\n     a match with a directory. [...]\n\n\n\n\n\n"},{"id":"375831","messageId":"469c37d9-4491-9072-211f-d9d8614413e0@in-ici.net","threadId":"51047","inReplyTo":"094f3746-67c9-0284-0593-eb6b24d5c4a3@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-17T21:43:45Z","receivedAt":"2019-05-17T21:43:49Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"\n> Another thing that I noticed is that its not mentioned anywhere that the \n> pattern use a slash as a directory separator (instead of a backslash), \n> its only clear from the examples. Maybe its worth to mention it in the \n> \"PATTERN FORMAT\" section. Also its maybe worth to introduce the term \n> \"leading slash\" and \"trailing slash\" because they will be of importance \n> of the following paragraphs. Something like this after the paragraph of \n> \"!\":\n> \n>      [...] for example, \"\\!important!.txt\".\n> \n>      A slash `/` is used as a directory separator.\n>      A leading slash (that is if the pattern begins with a slash)\n>      or a trailing slash (that is if the pattern ends with a slash)\n>      have special meaning and are explained below.\n> \n>      If the pattern contains a trailing slash, it would only find\n>      a match with a directory. [...]\n> \n\n\nI changed my mind about this last addition. I think it is not very \nreadable and there is no need to explain leading/trailing slash. Maybe \none could just note it like this:\n\n       [...] for example, \"\\!important!.txt\".\n\n       A slash `/` is used as a directory separator.\n       A leading and trailing slash have special meaning\n       and are explained in the following.\n\n       If the pattern ends with a slash, it would only find\n       a match with a directory. [...]\n\nthen I would also add:\n\n      If the pattern does not end with a slash, it would find a match\n      with a file or directory.\n\n\nTwo notes about two sentences that I proposed a while ago:\n\n > + - If the pattern contains no slash \"`/`\" (except an optional \ntrailing slash),\n > +   the ...\n\nI think that this sentence is not very readable. The exceptional case in \nthe brackets makes it over complicated.\n\n > + - A pattern that contains a non-trailing slash is matched\n\nAnd I don't like this phrase either. I think its too easy to confuse it \nwith \"A pattern that contains no trailing slash\".\n\nSo I would suggest to replace both with the following:\n\n     If the pattern contains no slash or only a trailing slash, [...].\n     Otherwise (when it contains a non-trailing slash) the pattern\n     is matched [...].\n\nAll the best,\nAdam\n"},{"id":"375842","messageId":"f80eb2e5-3285-40bd-018d-ff0c7e5e9ff5@kdbg.org","threadId":"51047","inReplyTo":"469c37d9-4491-9072-211f-d9d8614413e0@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2019-05-18T06:42:52Z","receivedAt":"2019-05-18T06:42:57Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 17.05.19 um 23:43 schrieb Dr. Adam Nielsen:\n>> Another thing that I noticed is that its not mentioned anywhere that\n>> the pattern use a slash as a directory separator (instead of a\n>> backslash), its only clear from the examples. Maybe its worth to\n>> mention it in the \"PATTERN FORMAT\" section. Also its maybe worth to\n>> introduce the term \"leading slash\" and \"trailing slash\" because they\n>> will be of importance of the following paragraphs. Something like this\n>> after the paragraph of \"!\":\n>>\n>>      [...] for example, \"\\!important!.txt\".\n>>\n>>      A slash `/` is used as a directory separator.\n>>      A leading slash (that is if the pattern begins with a slash)\n>>      or a trailing slash (that is if the pattern ends with a slash)\n>>      have special meaning and are explained below.\n>>\n>>      If the pattern contains a trailing slash, it would only find\n>>      a match with a directory. [...]\n>>\n> \n> \n> I changed my mind about this last addition. I think it is not very\n> readable and there is no need to explain leading/trailing slash. Maybe\n> one could just note it like this:\n> \n>       [...] for example, \"\\!important!.txt\".\n> \n>       A slash `/` is used as a directory separator.\n>       A leading and trailing slash have special meaning\n>       and are explained in the following.\n> \n>       If the pattern ends with a slash, it would only find\n>       a match with a directory. [...]\n> \n> then I would also add:\n> \n>      If the pattern does not end with a slash, it would find a match\n>      with a file or directory.\n> \n> \n> Two notes about two sentences that I proposed a while ago:\n> \n>> + - If the pattern contains no slash \"`/`\" (except an optional\n> trailing slash),\n>> +   the ...\n> \n> I think that this sentence is not very readable. The exceptional case in\n> the brackets makes it over complicated.\n> \n>> + - A pattern that contains a non-trailing slash is matched\n> \n> And I don't like this phrase either. I think its too easy to confuse it\n> with \"A pattern that contains no trailing slash\".\n> \n> So I would suggest to replace both with the following:\n> \n>     If the pattern contains no slash or only a trailing slash, [...].\n>     Otherwise (when it contains a non-trailing slash) the pattern\n>     is matched [...].\n\nWith all those new \"if\"s, \"but\"s, \"otherwise\"s, \"when\"s, and \"except\"s,\nI have a feeling that the current way to say\n\n   If .... ends with a slash, then ... only directories... The trailing\n   slash is removed for the purpose of the remaining rules.\n\nis still the best way to go forward. I do understand that this is a\nrather technical way to explain things than a colloquial one, but it\nalso does remove a lot of conditionals and, therefore, mental burden.\n\n-- Hannes\n"},{"id":"375853","messageId":"ada99004-0d0d-b206-8d69-bcf522356629@in-ici.net","threadId":"51047","inReplyTo":"f80eb2e5-3285-40bd-018d-ff0c7e5e9ff5@kdbg.org","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-18T13:20:54Z","receivedAt":"2019-05-18T13:20:57Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"\n\nOn 18.05.19 08:42, Johannes Sixt wrote:\n> Am 17.05.19 um 23:43 schrieb Dr. Adam Nielsen:\n>>> Another thing that I noticed is that its not mentioned anywhere that\n>>> the pattern use a slash as a directory separator (instead of a\n>>> backslash), its only clear from the examples. Maybe its worth to\n>>> mention it in the \"PATTERN FORMAT\" section. Also its maybe worth to\n>>> introduce the term \"leading slash\" and \"trailing slash\" because they\n>>> will be of importance of the following paragraphs. Something like this\n>>> after the paragraph of \"!\":\n>>>\n>>>       [...] for example, \"\\!important!.txt\".\n>>>\n>>>       A slash `/` is used as a directory separator.\n>>>       A leading slash (that is if the pattern begins with a slash)\n>>>       or a trailing slash (that is if the pattern ends with a slash)\n>>>       have special meaning and are explained below.\n>>>\n>>>       If the pattern contains a trailing slash, it would only find\n>>>       a match with a directory. [...]\n>>>\n>>\n>>\n>> I changed my mind about this last addition. I think it is not very\n>> readable and there is no need to explain leading/trailing slash. Maybe\n>> one could just note it like this:\n>>\n>>        [...] for example, \"\\!important!.txt\".\n>>\n>>        A slash `/` is used as a directory separator.\n>>        A leading and trailing slash have special meaning\n>>        and are explained in the following.\n>>\n>>        If the pattern ends with a slash, it would only find\n>>        a match with a directory. [...]\n>>\n>> then I would also add:\n>>\n>>       If the pattern does not end with a slash, it would find a match\n>>       with a file or directory.\n>>\n>>\n>> Two notes about two sentences that I proposed a while ago:\n>>\n>>> + - If the pattern contains no slash \"`/`\" (except an optional\n>> trailing slash),\n>>> +   the ...\n>>\n>> I think that this sentence is not very readable. The exceptional case in\n>> the brackets makes it over complicated.\n>>\n>>> + - A pattern that contains a non-trailing slash is matched\n>>\n>> And I don't like this phrase either. I think its too easy to confuse it\n>> with \"A pattern that contains no trailing slash\".\n>>\n>> So I would suggest to replace both with the following:\n>>\n>>      If the pattern contains no slash or only a trailing slash, [...].\n>>      Otherwise (when it contains a non-trailing slash) the pattern\n>>      is matched [...].\n> \n> With all those new \"if\"s, \"but\"s, \"otherwise\"s, \"when\"s, and \"except\"s,\n> I have a feeling that the current way to say\n> \n>     If .... ends with a slash, then ... only directories... The trailing\n>     slash is removed for the purpose of the remaining rules.\n> \n> is still the best way to go forward >\n > I do understand that this is a\n > rather technical way to explain things than a colloquial one, but it\n > also does remove a lot of conditionals and, therefore, mental burden.\n >\n > -- Hannes\n >\n\nIf one compares the current version with the new proposed one (including \nthe updates from my last mail) word by word, then one finds that there \nis no additional \"when\", \"except\" and \"but\" and that the number of \n\"if's\" and \"otherwise\" has remained the same. So the other alternative \ndoes not \"remove a lot of conditionals\".\n\n >     [...] The trailing\n >     slash is removed for the purpose of the remaining rules.\n\nhas many downsides that I have explained in detail in the mail from \n09.04.2019. The biggest issue is that the paragraphs do not stand for \nthemselves alone anymore.\n\nThe only thing that would really change regarding the trailing slash is \nthat we would say\n\n     If the pattern contains no slash or only a trailing slash, [...}\n\ninstead of\n\n > - - If the pattern does not contain a slash '/',  [...]\n\n\nI will send the current version with its latest changes to make it more \nclear how readable the latest version is.\n\nBest regards\nAdam\n\n\n\n\n\n\n"}]}