{"thread":{"id":"50880","subject":"[PATCH/docs] make slash-rules more readable","startedAt":"2019-04-05T20:42:36Z","lastAt":"2019-04-17T15:49:59Z","messageCount":8,"participants":["Dr. Adam Nielsen","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"373258","messageId":"20190405200045.10063-1-admin@in-ici.net","threadId":"50880","inReplyTo":null,"subject":"[PATCH/docs] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-04-05T20:00:45Z","receivedAt":"2019-04-05T20:42:36Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"From: Adam Nielsen <admin@in-ici.net>\n\ngitignore.txt: make slash-rules more readable\n\nRemove the addition `it is removed for the purpose of the following description` and \nmake clear in which situations a trailing slash is used or not. Increase readability\nand make all paragraphs valid, even if they are not read in strict order.\nReplace `otherwise` with the the concrete pattern that is considered in the paragraph to avoid\nconfusion. \nAdd simple examples to point out the significant difference between using or not using a trailing slash.\n\nSigned-off-by: Adam J. N. Nielsen <info@drnielsen.de>\n\n---\n Documentation/gitignore.txt | 23 +++++++++++++----------\n 1 file changed, 13 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex 1c94f08ff4..c6720b0ac4 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -89,22 +89,25 @@ 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+ - If the pattern contains no slash \"`/`\" other then a trailing slash,\n+   then the pattern will match in all directories. In other words,\n+   `foo/` will match `/bar/foo/` and `foo` will match `/bar/bar/foo`.\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+ - If the pattern contains a slash \"`/`\" other then a trailing slash, then\n+   the pattern is always considered from the `.gitignore` file location.\n+   In other words, `foo/bar` will match `/foo/bar` but not `/bar/foo/bar`.\n+\n+ - The character \"`*`\" matches anything except a non trailing slash \"`/`\".\n+   For example, \"foo/*\" matches \"foo/test.json\" and \"foo/bar/\"\n+   but not \"foo/bar/test.json\".\n+   The character \"`?`\" matches any one character except \"`/`\".\n+   The character \"`[]`\" matches one character in a selected range. See\n    fnmatch(3) and the FNM_PATHNAME flag for a more detailed\n    description.\n \n-- \n2.17.1\n\n"},{"id":"373403","messageId":"xmqqftqt7x49.fsf@gitster-ct.c.googlers.com","threadId":"50880","inReplyTo":"20190405200045.10063-1-admin@in-ici.net","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-08T07:51:50Z","receivedAt":"2019-04-08T07:51:57Z","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\nA few notes on the form.\n\n> From: Adam Nielsen <admin@in-ici.net>\n\nThis \"author\" identity and the name-email on the Signed-off-by: line\nshould match, at least for this project.  I cannot tell which one is\nyour preference, and I do not have any preference over your name\neither ;-), but please pick one and use it consistently.\n\n>\n> gitignore.txt: make slash-rules more readable\n>\n> Remove the addition `it is removed for the purpose of the following description` and \n> make clear in which situations a trailing slash is used or not. Increase readability\n> and make all paragraphs valid, even if they are not read in strict order.\n> Replace `otherwise` with the the concrete pattern that is considered in the paragraph to avoid\n> confusion. \n> Add simple examples to point out the significant difference between using or not using a trailing slash.\n\nThese are overly long lines; we tend to fold long lines at around\n70 char or so.\n\n> Signed-off-by: Adam J. N. Nielsen <info@drnielsen.de>\n>\n> ---\n>  Documentation/gitignore.txt | 23 +++++++++++++----------\n>  1 file changed, 13 insertions(+), 10 deletions(-)\n>\n> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\n> index 1c94f08ff4..c6720b0ac4 100644\n> --- a/Documentation/gitignore.txt\n> +++ b/Documentation/gitignore.txt\n> @@ -89,22 +89,25 @@ 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\nI do like this change, even though I cannot bring myself backing it\n100% immediately.  The reason why I wrote it the way in the original\nwas because I did not want to repeat \"... but a slash at end, if\nexists, is exempt from this rule\" over and over in the later bullet\npoints, as it would be a maintenance burden when we have more bullet\npoints and when we find a better phrasing to say \"... but a slash at\nend if exists, is exempt from this rule\".\n\nThe patch I am responding to bites the bullet and repeats the \"the\none at the end does not count\", which may be slightly harder to\nmaintain, but certainly makes it easier to read.\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> + - If the pattern contains no slash \"`/`\" other then a trailing slash,\n\nWhile pretending to be a fresh reader and reading only this line\nmade me wonder if the rule described in this bullet point applies\nonly to a pattern that has a single slash at the end.  I wonder if\nit is just me, or we can improve the phrasing so that it is clear\nthat a pattern without any slash also is covered by this rule, not\njust a pattern that has all non-slash chars followed by a single\nslash.\n\n> +   then the pattern will match in all directories. In other words,\n> +   `foo/` will match `/bar/foo/` and `foo` will match `/bar/bar/foo`.\n\nThe half-technical \"treats it as a shell glob pattern\" from the\noriginal is gone, which I think is a good change.  The examples may\nneed to be improved, as it may not be clear to naive readers that\nwith /bar/foo/, you meant that it is limited to a directory but not\na file, and with /bar/bar/foo you meant both a directory and a file\nis fine.  Perhaps\n\n\tFor example, 'frotz/' matches 'frotz', 'a/frotz', etc. that\n\tis a directory, but does not match if these are files.\n\tA pattern 'frotz' on the other hand matches these paths\n\twhether they are files or directories.\n\nI also wonder if \"in all directories\" is clear enough that your\n\"all\" is limited to below the level the ignore pattern is defined\nfor (i.e. \"*.1\" that appears in \"Documentation/.gitignore\" does not\nignore \"foo.1\" at the top-level of the tree).\n\nSo I can tell that this patch is trying to address a problem in the\noriginal that is worth fixing, but I cannot say the result is good.\nAt least not yet.\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> + - If the pattern contains a slash \"`/`\" other then a trailing slash, then\n\nThe same comment applies to this first line about the ambiguity of a\npattern without any slash anywhere.\n\n> +   the pattern is always considered from the `.gitignore` file location.\n> +   In other words, `foo/bar` will match `/foo/bar` but not `/bar/foo/bar`.\n\nAgain, loss of the mention of \"shell glob\" is a good thing, as we\nstill have a clue for those \"in the know\" at the end by mentioning\nfnmatch(3).\n\nThe example lacks one crucial description to be useful.  The reader\nmust be told where foo/bar came from.  Was it in the .gitignore file\nat the top-level?  A per-directory exclude file bar/.gitignore?\nWithout making that clear, none of the \"In other words\" example\nmakes much sense.\n\nAlso another issue common to previous example is that you are using\nabsolute path notation \"/bar/foo/\", \"/bar/foo/bar\", etc. without\nexplaining what you want it mean.  I can guess that it does not\nrefer to the root of the filesystem but you meant to refer to the\ntop level of the working tree, but you are not writing documentation\nto help _me_ understand Git, so we should not rely on that \"I can\nguess\".  I do not think an average first-time reader can.\n\n> + - The character \"`*`\" matches anything except a non trailing slash \"`/`\".\n> +   For example, \"foo/*\" matches \"foo/test.json\" and \"foo/bar/\"\n> +   but not \"foo/bar/test.json\".\n\nI think your writing out the trailing slash on the filesystem-entity\nside (i.e. things that are matched by patterns) is making the\nresulting description more distracting than necessary.  Being able\nto mark a pattern with a trailing slash to \"match only to directory\"\nis one thing, but when the example talks about paths foo/test.json\n(presumably a regular file and not a directory) and foo/bar\n(presumably a directory), it shouldn't force users to mistakenly\nthink that the matching engine first appends a slash after a\ndirectory we read from the filesystem before applying the pattern\nmatching logic, which has a compensating hack to ignore trailing\nslash from the path when matching.\n\nOnce you write consistently that a path for a directory foo/bar is\nfoo/bar, not foo/bar/, then this example would become much easier to\nwrite and read, I suspect.\n\n\tAn asterisk \"`*`\" matches anything except a slash.  A\n\tpattern \"foo/*\", for example, matches \"foo/test.json\" (a\n\tregular file), \"foo/bar\" (a diretory), but it does not match\n\t\"foo/bar/hello.c\" (a regular file), as the asterisk in the\n\tpatter does not match \"bar/hello.c\" which has a slash in it.\n\nperhaps.\n\n> +   The character \"`?`\" matches any one character except \"`/`\".\n> +   The character \"`[]`\" matches one character in a selected range. See\n\nCalling `[]` construct \"the character\" is blatantly wrong.\n\n\tThe range notation, e.g. `[a-zA-Z]`, can be used to match\n\tone of the characters in a range.\n\nperhaps.  It still omits negation [!0-9] but it probably is OK to\nleave that for fnmatch(3), and you've done so by leaving these two\nlines from the original intact, which is good.\n\n>     fnmatch(3) and the FNM_PATHNAME flag for a more detailed\n>     description.\n\n\nThanks.\n"},{"id":"373410","messageId":"CAKrvxcVgMLNEEY6U+ybm6n4WtUCdOaYRjBrDKFvRwzYbZyB2UQ@mail.gmail.com","threadId":"50880","inReplyTo":"xmqqftqt7x49.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-04-08T10:27:51Z","receivedAt":"2019-04-08T10:28:09Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"Am Mo., 8. Apr. 2019 um 09:51 Uhr schrieb Junio C Hamano <gitster@pobox.com>:\n>\n> \"Adam Nielsen\" <admin@in-ici.net> writes:\n>\n> A few notes on the form.\n>\n> > From: Adam Nielsen <admin@in-ici.net>\n>\n> This \"author\" identity and the name-email on the Signed-off-by: line\n> should match, at least for this project.  I cannot tell which one is\n> your preference, and I do not have any preference over your name\n> either ;-), but please pick one and use it consistently.\n>\n\nHaha yes sorry. I had my struggles with this patch procedure and I\nwill do better next time.\n\n\n> >\n> > gitignore.txt: make slash-rules more readable\n> >\n> > Remove the addition `it is removed for the purpose of the following description` and\n> > make clear in which situations a trailing slash is used or not. Increase readability\n> > and make all paragraphs valid, even if they are not read in strict order.\n> > Replace `otherwise` with the the concrete pattern that is considered in the paragraph to avoid\n> > confusion.\n> > Add simple examples to point out the significant difference between using or not using a trailing slash.\n>\n> These are overly long lines; we tend to fold long lines at around\n> 70 char or so.\n\nOkay.\n\n>\n> > Signed-off-by: Adam J. N. Nielsen <info@drnielsen.de>\n> >\n> > ---\n> >  Documentation/gitignore.txt | 23 +++++++++++++----------\n> >  1 file changed, 13 insertions(+), 10 deletions(-)\n> >\n> > diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\n> > index 1c94f08ff4..c6720b0ac4 100644\n> > --- a/Documentation/gitignore.txt\n> > +++ b/Documentation/gitignore.txt\n> > @@ -89,22 +89,25 @@ 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> I do like this change, even though I cannot bring myself backing it\n> 100% immediately.\n\n> The reason why I wrote it the way in the original\n> was because I did not want to repeat \"... but a slash at end, if\n> exists, is exempt from this rule\"\n\nYes, I can see why this makes sense. However, I find that this exception\nmakes this paragraph hard to read. Also I think its ambiguous if \"it\" refers\nto the pattern or the slash. The first few times I read it,\nI just didn't get it and was very intimidated by the paragraph.\n\n> over and over in the later bullet\n> points, as it would be a maintenance burden when we have more bullet\n> points and when we find a better phrasing to say \"... but a slash at\n> end if exists, is exempt from this rule\".\n\nYes, I agree. One should not repeat such a bloated exception rule over and over\nagain.\n\n>\n> The patch I am responding to bites the bullet and repeats the \"the\n> one at the end does not count\", which may be slightly harder to\n> maintain, but certainly makes it easier to read.\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> > + - If the pattern contains no slash \"`/`\" other then a trailing slash,\n>\n> While pretending to be a fresh reader and reading only this line\n> made me wonder if the rule described in this bullet point applies\n> only to a pattern that has a single slash at the end.  I wonder if\n> it is just me, or we can improve the phrasing so that it is clear\n> that a pattern without any slash also is covered by this rule, not\n> just a pattern that has all non-slash chars followed by a single\n> slash.\n\nI agree with you. How about we make up the word \"intermediate slash\" and\nexplain it in an extra paragraph? This would make it less repetitive.\nAlso it makes clear that the case without any slash is also covered.\nPerhaps\n\n         In the following we use the term **intermediate slash** to\n         denote a slash \"`/`\" in a pattern that is not a trailing slash\n         nor a leading slash.\n         For example the pattern `/foo/bar`, `foo/bar` and `/foo/bar/`\nall contain\n         only one intermediate slash. The pattern `foo/` does not contain an\n         intermediate slash.\n\nThen, instead of:\n\n         If the pattern contains no slash \"`/`\" other then a trailing slash,\"\n\none could say:\n\n         If the pattern contains no intermediate slash \"`/`\",\n\n\n>\n> > +   then the pattern will match in all directories. In other words,\n> > +   `foo/` will match `/bar/foo/` and `foo` will match `/bar/bar/foo`.\n>\n> The half-technical \"treats it as a shell glob pattern\" from the\n> original is gone, which I think is a good change.  The examples may\n> need to be improved, as it may not be clear to naive readers that\n> with /bar/foo/, you meant that it is limited to a directory but not\n> a file, and with /bar/bar/foo you meant both a directory and a file\n> is fine.  Perhaps\n>\n>         For example, 'frotz/' matches 'frotz', 'a/frotz', etc. that\n>         is a directory, but does not match if these are files.\n>         A pattern 'frotz' on the other hand matches these paths\n>         whether they are files or directories.\n>\n\nYes. This is so much better.\n\n> I also wonder if \"in all directories\" is clear enough that your\n> \"all\" is limited to below the level the ignore pattern is defined\n> for (i.e. \"*.1\" that appears in \"Documentation/.gitignore\" does not\n> ignore \"foo.1\" at the top-level of the tree).\n\nIts mentioned at the start of the page that the pattern is always\nrelative to the location of the `.gitignore` file. However, I see that\nsince its said \"in all directories\" its necessary to restrict it again.\nHow about\n\n         If the pattern contains no intermediate slash \"`/`\",\n         the pattern will match in all directories at or below\n         the `.gitignore` file, with infinite depth.\n\n>\n> So I can tell that this patch is trying to address a problem in the\n> original that is worth fixing, but I cannot say the result is good.\n> At least not yet.\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> > + - If the pattern contains a slash \"`/`\" other then a trailing slash, then\n>\n> The same comment applies to this first line about the ambiguity of a\n> pattern without any slash anywhere.\n\nThis would now change with the above remarks to:\n\n         If the pattern contains an intermediate slash \"`/`\",\n\n>\n> > +   the pattern is always considered from the `.gitignore` file location.\n> > +   In other words, `foo/bar` will match `/foo/bar` but not `/bar/foo/bar`.\n>\n> Again, loss of the mention of \"shell glob\" is a good thing, as we\n> still have a clue for those \"in the know\" at the end by mentioning\n> fnmatch(3).\n>\n> The example lacks one crucial description to be useful.  The reader\n> must be told where foo/bar came from.  Was it in the .gitignore file\n> at the top-level?  A per-directory exclude file bar/.gitignore?\n> Without making that clear, none of the \"In other words\" example\n> makes much sense.\n>\n> Also another issue common to previous example is that you are using\n> absolute path notation \"/bar/foo/\", \"/bar/foo/bar\", etc. without\n> explaining what you want it mean.  I can guess that it does not\n> refer to the root of the filesystem but you meant to refer to the\n> top level of the working tree, but you are not writing documentation\n> to help _me_ understand Git, so we should not rely on that \"I can\n> guess\".  I do not think an average first-time reader can.\n\nMaybe its shorter and clearer to write it like this:\n\n         If the pattern contains an intermediate slash \"`/`\",\n         its equivalent to the same pattern starting with a leading slash.\n         For example the pattern `doc/read.txt` is equivalent to\n         `/doc/read.txt`.\n\nIf we do this, one would need to lift the \"leading slash\" paragraph up\n(The one starting with \"A leading slash matches the beginning of the\npathname. For example,...\").\n\nNote that since an intermediate slash is explicitly not a leading\nslash, it is not said that\n`/bar/` and `//bar/` are equivalent.\n\n\n\n>\n> > + - The character \"`*`\" matches anything except a non trailing slash \"`/`\".\n> > +   For example, \"foo/*\" matches \"foo/test.json\" and \"foo/bar/\"\n> > +   but not \"foo/bar/test.json\".\n>\n> I think your writing out the trailing slash on the filesystem-entity\n> side (i.e. things that are matched by patterns) is making the\n> resulting description more distracting than necessary.  Being able\n> to mark a pattern with a trailing slash to \"match only to directory\"\n> is one thing, but when the example talks about paths foo/test.json\n> (presumably a regular file and not a directory) and foo/bar\n> (presumably a directory), it shouldn't force users to mistakenly\n> think that the matching engine first appends a slash after a\n> directory we read from the filesystem before applying the pattern\n> matching logic, which has a compensating hack to ignore trailing\n> slash from the path when matching.\n>\n> Once you write consistently that a path for a directory foo/bar is\n> foo/bar, not foo/bar/, then this example would become much easier to\n> write and read, I suspect.\n>\n>         An asterisk \"`*`\" matches anything except a slash.  A\n>         pattern \"foo/*\", for example, matches \"foo/test.json\" (a\n>         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> perhaps.\n\nI agree, this is much better. Although I would leave out\n\n>  \"as the asterisk in the patter does not match \"bar/hello.c\"\n>   which has a slash in it.\"\n\n>\n> > +   The character \"`?`\" matches any one character except \"`/`\".\n> > +   The character \"`[]`\" matches one character in a selected range. See\n>\n> Calling `[]` construct \"the character\" is blatantly wrong.\n\nYes, my bad.\n\n>\n>         The range notation, e.g. `[a-zA-Z]`, can be used to match\n>         one of the characters in a range.\n>\n> perhaps.\n\nThat is much better too.\n\n> It still omits negation [!0-9] but it probably is OK to\n> leave that for fnmatch(3), and you've done so by leaving these two\n> lines from the original intact, which is good.\n>\n> >     fnmatch(3) and the FNM_PATHNAME flag for a more detailed\n> >     description.\n>\n>\n> Thanks.\n\nThank you for all your input. If you agree with my proposed changes, I would\ncreate a new patch merging all this together.\n\n\nAm Mo., 8. Apr. 2019 um 09:51 Uhr schrieb Junio C Hamano <gitster@pobox.com>:\n>\n> \"Dr. Adam Nielsen\" <admin@in-ici.net> writes:\n>\n> A few notes on the form.\n>\n> > From: Adam Nielsen <admin@in-ici.net>\n>\n> This \"author\" identity and the name-email on the Signed-off-by: line\n> should match, at least for this project.  I cannot tell which one is\n> your preference, and I do not have any preference over your name\n> either ;-), but please pick one and use it consistently.\n>\n> >\n> > gitignore.txt: make slash-rules more readable\n> >\n> > Remove the addition `it is removed for the purpose of the following description` and\n> > make clear in which situations a trailing slash is used or not. Increase readability\n> > and make all paragraphs valid, even if they are not read in strict order.\n> > Replace `otherwise` with the the concrete pattern that is considered in the paragraph to avoid\n> > confusion.\n> > Add simple examples to point out the significant difference between using or not using a trailing slash.\n>\n> These are overly long lines; we tend to fold long lines at around\n> 70 char or so.\n>\n> > Signed-off-by: Adam J. N. Nielsen <info@drnielsen.de>\n> >\n> > ---\n> >  Documentation/gitignore.txt | 23 +++++++++++++----------\n> >  1 file changed, 13 insertions(+), 10 deletions(-)\n> >\n> > diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\n> > index 1c94f08ff4..c6720b0ac4 100644\n> > --- a/Documentation/gitignore.txt\n> > +++ b/Documentation/gitignore.txt\n> > @@ -89,22 +89,25 @@ 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> I do like this change, even though I cannot bring myself backing it\n> 100% immediately.  The reason why I wrote it the way in the original\n> was because I did not want to repeat \"... but a slash at end, if\n> exists, is exempt from this rule\" over and over in the later bullet\n> points, as it would be a maintenance burden when we have more bullet\n> points and when we find a better phrasing to say \"... but a slash at\n> end if exists, is exempt from this rule\".\n>\n> The patch I am responding to bites the bullet and repeats the \"the\n> one at the end does not count\", which may be slightly harder to\n> maintain, but certainly makes it easier to read.\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> > + - If the pattern contains no slash \"`/`\" other then a trailing slash,\n>\n> While pretending to be a fresh reader and reading only this line\n> made me wonder if the rule described in this bullet point applies\n> only to a pattern that has a single slash at the end.  I wonder if\n> it is just me, or we can improve the phrasing so that it is clear\n> that a pattern without any slash also is covered by this rule, not\n> just a pattern that has all non-slash chars followed by a single\n> slash.\n>\n> > +   then the pattern will match in all directories. In other words,\n> > +   `foo/` will match `/bar/foo/` and `foo` will match `/bar/bar/foo`.\n>\n> The half-technical \"treats it as a shell glob pattern\" from the\n> original is gone, which I think is a good change.  The examples may\n> need to be improved, as it may not be clear to naive readers that\n> with /bar/foo/, you meant that it is limited to a directory but not\n> a file, and with /bar/bar/foo you meant both a directory and a file\n> is fine.  Perhaps\n>\n>         For example, 'frotz/' matches 'frotz', 'a/frotz', etc. that\n>         is a directory, but does not match if these are files.\n>         A pattern 'frotz' on the other hand matches these paths\n>         whether they are files or directories.\n>\n> I also wonder if \"in all directories\" is clear enough that your\n> \"all\" is limited to below the level the ignore pattern is defined\n> for (i.e. \"*.1\" that appears in \"Documentation/.gitignore\" does not\n> ignore \"foo.1\" at the top-level of the tree).\n>\n> So I can tell that this patch is trying to address a problem in the\n> original that is worth fixing, but I cannot say the result is good.\n> At least not yet.\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> > + - If the pattern contains a slash \"`/`\" other then a trailing slash, then\n>\n> The same comment applies to this first line about the ambiguity of a\n> pattern without any slash anywhere.\n>\n> > +   the pattern is always considered from the `.gitignore` file location.\n> > +   In other words, `foo/bar` will match `/foo/bar` but not `/bar/foo/bar`.\n>\n> Again, loss of the mention of \"shell glob\" is a good thing, as we\n> still have a clue for those \"in the know\" at the end by mentioning\n> fnmatch(3).\n>\n> The example lacks one crucial description to be useful.  The reader\n> must be told where foo/bar came from.  Was it in the .gitignore file\n> at the top-level?  A per-directory exclude file bar/.gitignore?\n> Without making that clear, none of the \"In other words\" example\n> makes much sense.\n>\n> Also another issue common to previous example is that you are using\n> absolute path notation \"/bar/foo/\", \"/bar/foo/bar\", etc. without\n> explaining what you want it mean.  I can guess that it does not\n> refer to the root of the filesystem but you meant to refer to the\n> top level of the working tree, but you are not writing documentation\n> to help _me_ understand Git, so we should not rely on that \"I can\n> guess\".  I do not think an average first-time reader can.\n>\n> > + - The character \"`*`\" matches anything except a non trailing slash \"`/`\".\n> > +   For example, \"foo/*\" matches \"foo/test.json\" and \"foo/bar/\"\n> > +   but not \"foo/bar/test.json\".\n>\n> I think your writing out the trailing slash on the filesystem-entity\n> side (i.e. things that are matched by patterns) is making the\n> resulting description more distracting than necessary.  Being able\n> to mark a pattern with a trailing slash to \"match only to directory\"\n> is one thing, but when the example talks about paths foo/test.json\n> (presumably a regular file and not a directory) and foo/bar\n> (presumably a directory), it shouldn't force users to mistakenly\n> think that the matching engine first appends a slash after a\n> directory we read from the filesystem before applying the pattern\n> matching logic, which has a compensating hack to ignore trailing\n> slash from the path when matching.\n>\n> Once you write consistently that a path for a directory foo/bar is\n> foo/bar, not foo/bar/, then this example would become much easier to\n> write and read, I suspect.\n>\n>         An asterisk \"`*`\" matches anything except a slash.  A\n>         pattern \"foo/*\", for example, matches \"foo/test.json\" (a\n>         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> perhaps.\n>\n> > +   The character \"`?`\" matches any one character except \"`/`\".\n> > +   The character \"`[]`\" matches one character in a selected range. See\n>\n> Calling `[]` construct \"the character\" is blatantly wrong.\n>\n>         The range notation, e.g. `[a-zA-Z]`, can be used to match\n>         one of the characters in a range.\n>\n> perhaps.  It still omits negation [!0-9] but it probably is OK to\n> leave that for fnmatch(3), and you've done so by leaving these two\n> lines from the original intact, which is good.\n>\n> >     fnmatch(3) and the FNM_PATHNAME flag for a more detailed\n> >     description.\n>\n>\n> Thanks.\n\n\n\n-- \n\n\nDr. Adam Nielsen\n\n\nAdministrator for IN/ICI/WHO\n\n\nIN:\n\nwww.nlp-institutes.net\n\n\nICI:\n\nwww.coaching-institutes.net\n\n\nWHO:\n\nwww.world-hypnosis.org\n"},{"id":"373460","messageId":"xmqqy34j7jci.fsf@gitster-ct.c.googlers.com","threadId":"50880","inReplyTo":"CAKrvxcVgMLNEEY6U+ybm6n4WtUCdOaYRjBrDKFvRwzYbZyB2UQ@mail.gmail.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-09T07:01:33Z","receivedAt":"2019-04-09T07:01:39Z","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> I agree with you. How about we make up the word \"intermediate slash\" and\n> explain it in an extra paragraph?\n\nI am not sure if that is any better than \"in the following, pretend\nthat a slash at the end of a pattern does not exist\", which is how\nthe current description avoids repetition and aims for clarity.  It\nprobably is worse than than the current one if we need to introduce\na new term that is otherwise not useful elsewhere---a new term adds\nto the cognitive load of readers.\n\n>> I also wonder if \"in all directories\" is clear enough that your\n>> \"all\" is limited to below the level the ignore pattern is defined\n>> for (i.e. \"*.1\" that appears in \"Documentation/.gitignore\" does not\n>> ignore \"foo.1\" at the top-level of the tree).\n>\n> Its mentioned at the start of the page that the pattern is always\n> relative to the location of the `.gitignore` file. However, I see that\n> since its said \"in all directories\" its necessary to restrict it again.\n> How about\n>\n>          If the pattern contains no intermediate slash \"`/`\",\n>          the pattern will match in all directories at or below\n>          the `.gitignore` file, with infinite depth.\n\nIt is unclear what \"with infinite depth\" means in this sentence.\nThere is no depth-limit in the exclude mechanism, and I'd prefer\nnot to confuse readers by making a casual mention of \"depth\" to\nimply as if there is some depth-based logic.\n\nAlso, as you defined \"intermediate\" as a slash that is neither\nleading nor trailing, the above paragraph says \"/foo\" matches any\nfilesystem entity whose final path component is 'foo', e.g. a file\n'foo' at the current level, a directory 'foo' in subdirectory 'dir'\n(i.e. 'dir/foo'), etc.  I do not think you meant to say that (and\nthis is why I do not like to introduce a new term---even its\ninventor cannot get it right).\n\n>> So I can tell that this patch is trying to address a problem in the\n>> original that is worth fixing, but I cannot say the result is good.\n>> At least not yet.\n>> ...\n>> Once you write consistently that a path for a directory foo/bar is\n>> foo/bar, not foo/bar/, then this example would become much easier to\n>> write and read, I suspect.\n>>\n>>         An asterisk \"`*`\" matches anything except a slash.  A\n>>         pattern \"foo/*\", for example, matches \"foo/test.json\" (a\n>>         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>> perhaps.\n>\n> I agree, this is much better. Although I would leave out\n>\n>>  \"as the asterisk in the patter does not match \"bar/hello.c\"\n>>   which has a slash in it.\"\n\nI happen to think that the part is the more important half of that\nwhole \"example\".  By explaining why it does not match, it enforces\n\"matches anything except a slash\" we gave upfront.\n\nThanks.  I think we are making progress...\n"},{"id":"373487","messageId":"CAKrvxcW1hKUjMsCGUz7GothxbEKiQek2J5CkjhuiSKoGrArjbQ@mail.gmail.com","threadId":"50880","inReplyTo":"xmqqy34j7jci.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-04-09T12:19:14Z","receivedAt":"2019-04-09T12:19:31Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":">> I agree with you. How about we make up the word \"intermediate slash\" and\n>> explain it in an extra paragraph?\n\n> I am not sure if that is any better than \"in the following, pretend\n> that a slash at the end of a pattern does not exist\", which is how\n> the current description avoids repetition and aims for clarity.\n> It probably is worse than than the current one if we need to introduce\n> a new term that is otherwise not useful elsewhere---a new term adds\n> to the cognitive load of readers.\n\nThe description \"in the following, pretend that a slash at the end of\na pattern does not exist\"\nis much better understandable then \"it is removed for the purpose of\nthe following description\"\nto me. However, I still think its better not to use it:\n\n  1. The following paragraphs may not be valid if you do not keep this\nrule in mind.\n      This could happen, because one may not read the paragraphs in order,\n      or its unclear if \"in the following\" is meant for all following\nparagraphs or just this\n      paragraph, or one simply forgets it if one happens to check up a\nspecific paragraph\n      after some months or when returning from a break.\n  2. Forcing the user to be aware that \"in the following pretend that\na slash at the end does not exist\"\n      is at least for me a harder cognitive load then introducing a new term.\n      Because for every new paragraph that I read, I have to check if\nthis rule applies.\n  3. If you jump between paragraphs, you always need to locate the rule\n      and then check if the current paragraph is below or after that rule.\n  4. There are 7 paragraphs following this \"specific rule\" but only\nthe next paragraph\n      is using it. I think its also not needed for the paragraph where\nit appears.\n      For the other 6 paragraphs one needs to unnecessary check\n      if the rule is implicitly used anywhere.\n  5. For every paragraph that one may add in the future below that\nrule, one needs to double check\n      if its compatible with this rule. So in terms of maintenance I\nthink its rather a downside.\n\nIf something is cumbersome to explain and appears often, I think its\nbest to explain it once in detail\nand refer to that instead of a bloated description. However, since\nthis scenario only appears in two paragraphs,\na new term is maybe not justifiable. Thus, a cumbersome but complete\ndescription might be preferable.\n\n> > Its mentioned at the start of the page that the pattern is always\n> > relative to the location of the `.gitignore` file. However, I see that\n> > since its said \"in all directories\" its necessary to restrict it again.\n> > How about\n> >\n> >          If the pattern contains no intermediate slash \"`/`\",\n> >          the pattern will match in all directories at or below\n> >          the `.gitignore` file, with infinite depth.\n>\n> It is unclear what \"with infinite depth\" means in this sentence.\n> There is no depth-limit in the exclude mechanism, and I'd prefer\n> not to confuse readers by making a casual mention of \"depth\" to\n> imply as if there is some depth-based logic.\n\nThe description \"infinite depth\" is used in the current documentation\nin the paragraph\nfor `/**`. I thought its good to reuse something that has already been\napproved by the community.\nI think it points out very well that we are not only looking at\nfolders at the level of the `.gitignore`\nfile but all the folders below.\n\n> Also, as you defined \"intermediate\" as a slash that is neither\n> leading nor trailing, the above paragraph says \"/foo\" matches any\n> filesystem entity whose final path component is 'foo', e.g. a file\n> 'foo' at the current level, a directory 'foo' in subdirectory 'dir'\n> (i.e. 'dir/foo'), etc.  I do not think you meant to say that (and\n\nWe could fix it by defining an intermediate slash as any slash that is\nnot a trailing one.\nBut then one may just call it a \"non-trailing\" slash which is maybe\nself-explanatory enough.\n\n> this is why I do not like to introduce a new term---even its\n> inventor cannot get it right).\n\nEspecially if someone invents a new thing, I would not expect that its\nperfect right from scratch.\n\nHowever, I have to admit, the introduced term \"intermediate\" has its\nflaws. Maybe using \"non-trailing\" or a description is better.\n\n> > I agree, this is much better. Although I would leave out\n> >\n> >>  \"as the asterisk in the patter does not match \"bar/hello.c\"\n> >>   which has a slash in it.\"\n>\n> I happen to think that the part is the more important half of that\n> whole \"example\".\n\nAlright.\n\n\n\nTo summarize: I would suggest to drop \"it is removed for the purpose\nof the following description\" because of the points\nI made at the top and instead mention the necessary exceptions in the\ntwo relevant paragraphs. Here my new updated proposals:\n\n          If the pattern contains no slash \"`/`\"\n          (except an optional trailing slash),\n          the pattern will match in all directories relative to\n          the `.gitignore` file, with infinite depth.\n          For example, `frotz/` matches `frotz` and `a/frotz` that\n          is a directory, but does not match if these are files.\n          A pattern `frotz` on the other hand matches these paths\n          whether they are files or directories.\n\nI think this is better then my first proposal:\n\n>> + - If the pattern contains no slash \"`/`\" other then a trailing slash,\n\n>While pretending to be a fresh reader and reading only this line\n>made me wonder if the rule described in this bullet point applies\n>only to a pattern that has a single slash at the end.  I wonder if\n>it is just me, or we can improve the phrasing so that it is clear\n>that a pattern without any slash also is covered by this rule, not\n>just a pattern that has all non-slash chars followed by a single\n>slash.\n\nThe phrase \"except an optional\" and the example both point out that\nthis rule works with and without trailing slash.\nI kept \"infinite depth\" for the reasons explained above.\n\nFor the next paragraph I would suggest this:\n\n        If the pattern contains a non-trailing slash \"`/`\",\n        it matches the beginning of the pathname.\n        For example, the pattern `doc/frotz/` matches\n        `doc/frotz` that is a directory\n        but does not match `a/doc/frotz`.\n\nWhere I have taken `it matches the beginning of the pathname` from the\nparagraph of a leading slash.\nThe example uses a trailing slash, to emphasize that this rule works\nalso with trailing slash, for the case\nthat the reader confuses the line with \"If the pattern contains no\ntrailing slash\". Alternatively I would suggest:\n\n        If the pattern contains a slash \"`/`\"\n        that is not a trailing slash,\n        it matches the beginning of the pathname.\n        For example, the pattern `doc/frotz/` matches\n        `doc/frotz` that is a directory\n        but does not match `a/doc/frotz`.\n\nThis might be addressing the problem of my first proposal:\n\n>> + - If the pattern contains a slash \"`/`\" other then a trailing slash, then\n\n>The same comment applies to this first line about the ambiguity of a\n>pattern without any slash anywhere.\n\n\n\nAll the best,\nAdam\n"},{"id":"373520","messageId":"xmqqzhoz2lpr.fsf@gitster-ct.c.googlers.com","threadId":"50880","inReplyTo":"CAKrvxcW1hKUjMsCGUz7GothxbEKiQek2J5CkjhuiSKoGrArjbQ@mail.gmail.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-09T16:21:36Z","receivedAt":"2019-04-09T16:21:41Z","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>           If the pattern contains no slash \"`/`\"\n>           (except an optional trailing slash),\n\nThat's perfect.\n\n>           the pattern will match in all directories relative to\n>           the `.gitignore` file, with infinite depth.\n\nMaybe it is just me but \"in all directories relative to the file\"\ndoes not say the same thing as\n\n    the pattern is matched against paths in the directory where the\n    `.gitignore` file that has the pattern in it is in, and any of\n    its subdirectories (recursively).\n\nwhich I think is what we want to say.  Especially, I do not think\nthe phrasing implies the match is limited to the directory and its\nsubdirectories, as it is unclear what the words \"relative to\" wanted\nto mean in that sentence.\n\n>           For example, `frotz/` matches `frotz` and `a/frotz` that\n>           is a directory, but does not match if these are files.\n>           A pattern `frotz` on the other hand matches these paths\n>           whether they are files or directories.\n\nYeah this is good.\n\n> For the next paragraph I would suggest this:\n>\n>         If the pattern contains a non-trailing slash \"`/`\",\n>         it matches the beginning of the pathname.\n\nThe reference of \"it\" in \"it matches\" is fuzzy; first I was confused\nas I thoguht it refers to the slash (which one?  if the pattern has\ntwo or more slashes a/b/c).\n\n\tA pattern with a non-trailing slash matches the beginning of\n\tthe pathname\n\nwould mean the same thing without ambiguity, but I am not sure\n\"matches the beginning of\" is quite right.  \n\nA pattern doc/frotz that appears in v1.0/.gitignore file would match\na file or directory v1.0/doc/frotz (pathnames in these example are\nall from the top level of the repository).  \n\nI think woe most important messages we need to deliver are\n\n - a pattern without slash applies in a directory the pattern\n   \"appears in\", or any of its subdirectories (recursively).\n\n - a pattern with slash on the other hand is anchored at the\n   directory the pattern \"appears in\" and does not apply to any of\n   its subdirectories.\n\nSo with that in mind, perhaps\n\n\tUnlike a pattern without a slash, a pattern with a\n\tnon-trailing slash is matched against paths immediately in\n\tthe directory the `.gitignore` file the pattern appears in\n\tis stored in, and does not get used in its subdirectories..\n\nor something?\n\n>         For example, the pattern `doc/frotz/` matches\n>         `doc/frotz` that is a directory\n>         but does not match `a/doc/frotz`.\n\nCorrect, almost.  \n\n\tFor example, the pattern `doc/frotz/` that appears in\n\t`.gitignore` at the top-level of the project matches\n\t`doc/frotz` directory (again, seen from the top-level), but\n\tnot `a/doc/frotz`.\n\nAlso, a pattern \"/doc\" matches doc at the current level (i.e. the\ndirectory in which .gitignore file that the pattern was taken from\nis found) and not in any subdirectories.  Is that clear in the\nproposed update?\n\nProcedurally (I am writing to make sure we are on the same page for\nthe technical correctness, so that I can let you take care of the\nease of understanding of the end result---it is of no use if an easy\nto understand document describes incorrect behaviour ;-)\n\n * A trailing slash is used *only* to mark that a pattern matches\n   only against directories, and it is ignored by the actual pattern\n   mac.thing logic.  It also is ignored by the logic to determine if\n   the pattern is anchored.\n\n   e.g. /foo-bar/ becomes /foo-bar but \"must match dir\" (aka \"ends\n   with a slash\") is remembered.\n\n\n * A leading slash is used *only* to mark that a pattern is\n   \"anchored\" at the current level, and otherwise it is ignored by\n   the actual pattern matching logic.\n\n   e.g. /foo-bar that used to be /foo-bar/ then becomes foo-bar but\n   we also remember \"must match here\" (aka \"had a slash in it\").\n\n\n * A slash in a pattern that is not ignored by the above two rules\n   (i.e. your \"intermediate slash\") marks a pattern as \"anchored\",\n   i.e. used to match against the paths relative to the current\n   level only.\n\n   e.g. foo-bar that used to be /foo-bar that used to be /foo-bar/\n   thru the above processing, as well as foo/bar that was ignored by\n   the above two rules, are both anchored to the current level, and\n   they do not match a/foo-bar or a/foo/bar in our immediate\n   subdirectory 'a'\n\n"},{"id":"373573","messageId":"CAKrvxcX+Fi1U4NcH5Mqf0cR8QQc9FWtVQ-uuj0Dhd3qEu5o6XA@mail.gmail.com","threadId":"50880","inReplyTo":"xmqqzhoz2lpr.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-04-10T07:39:13Z","receivedAt":"2019-04-10T07:39:28Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"> the pattern is matched against paths in the directory where the\n> `.gitignore` file that has the pattern in it is in, and any of\n> its subdirectories (recursively).\n\n> the pattern will match in all directories relative to\n> the `.gitignore` file, with infinite depth.\n\nI could not catch the difference between the meaning of both.\nHowever, I think \"paths in the directory\" and \"directories relative to\"\nare maybe both ambiguous.\n\nSince a pattern without a non-trailing slash must always be a file name or a\nfolder name, and does not have a leading slash, we could maybe just\nsay it like this:\n\n        the pattern is matched against all files and folders (recursively)\n        from the location of the `.gitignore` file.\n---------\n\n\n> Unlike a pattern without a slash, a pattern with a\n> non-trailing slash is matched against paths immediately in\n> the directory the `.gitignore` file the pattern appears in\n> is stored in, and does not get used in its subdirectories..\n\nI think one can always assume that we talking about the relevant\n`.gitignore` file (where the pattern appears in).\n\nPerhaps this covers it all?\n\n        A pattern with a non-trailing slash is always considered\n        to begin at the `.gitignore` file location.\n\nfollowed by your example\n\n> For example, the pattern `doc/frotz/` that appears in\n> `.gitignore` at the top-level of the project matches\n> `doc/frotz` directory (again, seen from the top-level), but\n> not `a/doc/frotz`.\n\nand maybe one more example\n\n        Note that the pattern `doc/frotz` and `/doc/frotz` are\n        equivalent.\n        However `/bar` and `bar` are different. They both match the\n        `bar` file or folder at the top level, but only the latter\nwill also match `foo/bar`\n        (when `foo` is at the top level).\n\nThis avoids the hustle with the ambiguous path, where it starts, and\ntrailing or leading slashes. Together with the\ntwo examples it seems to be a good compromise between accuracy and\nunderstandable.\n\nThe alternative would be to say\n\n        A pattern with a non-trailing slash is only matched against any\n        path that begins in the directory of the `.gitignore` file.\n\nWhile this is maybe clearer then saying \"pattern [...] always\nconsidered to begin at` it is ambiguous about the slashes.\nSo a very accuracy but maybe less understandable version would be\nsomething like this:\n\n        A pattern with a non-trailing slash is only matched against any\n        path that begins in the directory of the `.gitignore` file.\n        For example, if the `.gitignore` file is in folder `doc`\n        the path to file  `bar/doc/a/foo` that begins in `doc` is `a/foo`.\n        A pattern that matches a path except for a leading slash or\ntrailing slash\n        is still considered a match. It is still valid however,\n        that when a pattern ends with a slash, it would only find a\nmatch with a directory.\n\n---------\n\n> Also, a pattern \"/doc\" matches doc at the current level (i.e. the\n> directory in which .gitignore file that the pattern was taken from\n> is found) and not in any subdirectories.  Is that clear in the\n> proposed update?\n\nYes.\n\nHowever, in the docs is already one paragraph solely dedicated for this case:\n\n> A leading slash matches the beginning of the pathname. For example, \"/*.c\" matches\n> \"cat-file.c\" but not \"mozilla-sha1/sha1.c\".\n\nHowever, we have already a better and more in detail explained example\nin the new\nproposal `*` paragraph and and the case with the leading slash is\nnow a sub-case of `A pattern with a non-trailing slash`\nso we might just get rid of the above paragraph?\n----------\n\n\nThank you for explaining me how the algorithm works procedurally.\nIt gave some inside of the origin of \"If the pattern ends with a slash, it is\nremoved for the purpose of the following description..\"\n---------\n\nAll the best,\nAdam\n"},{"id":"374052","messageId":"CAKrvxcXrnEdVFHxrEhhcFB5knXF1V=Jtf0psVVaK-Q=KVEztTg@mail.gmail.com","threadId":"50880","inReplyTo":"CAKrvxcX+Fi1U4NcH5Mqf0cR8QQc9FWtVQ-uuj0Dhd3qEu5o6XA@mail.gmail.com","subject":"Re: [PATCH/docs] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-04-17T15:49:42Z","receivedAt":"2019-04-17T15:49:59Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"I think its maybe hard to track all the changes that we have discussed\nso far. Should I create a new PATCH request including all the changes\nfrom the recent mails and then we continue the discussion from there?\n\nBest regards,\nAdam\n\nAm Mi., 10. Apr. 2019 um 09:39 Uhr schrieb Dr. Adam Nielsen <admin@in-ici.net>:\n>\n> > the pattern is matched against paths in the directory where the\n> > `.gitignore` file that has the pattern in it is in, and any of\n> > its subdirectories (recursively).\n>\n> > the pattern will match in all directories relative to\n> > the `.gitignore` file, with infinite depth.\n>\n> I could not catch the difference between the meaning of both.\n> However, I think \"paths in the directory\" and \"directories relative to\"\n> are maybe both ambiguous.\n>\n> Since a pattern without a non-trailing slash must always be a file name or a\n> folder name, and does not have a leading slash, we could maybe just\n> say it like this:\n>\n>         the pattern is matched against all files and folders (recursively)\n>         from the location of the `.gitignore` file.\n> ---------\n>\n>\n> > Unlike a pattern without a slash, a pattern with a\n> > non-trailing slash is matched against paths immediately in\n> > the directory the `.gitignore` file the pattern appears in\n> > is stored in, and does not get used in its subdirectories..\n>\n> I think one can always assume that we talking about the relevant\n> `.gitignore` file (where the pattern appears in).\n>\n> Perhaps this covers it all?\n>\n>         A pattern with a non-trailing slash is always considered\n>         to begin at the `.gitignore` file location.\n>\n> followed by your example\n>\n> > For example, the pattern `doc/frotz/` that appears in\n> > `.gitignore` at the top-level of the project matches\n> > `doc/frotz` directory (again, seen from the top-level), but\n> > not `a/doc/frotz`.\n>\n> and maybe one more example\n>\n>         Note that the pattern `doc/frotz` and `/doc/frotz` are\n>         equivalent.\n>         However `/bar` and `bar` are different. They both match the\n>         `bar` file or folder at the top level, but only the latter\n> will also match `foo/bar`\n>         (when `foo` is at the top level).\n>\n> This avoids the hustle with the ambiguous path, where it starts, and\n> trailing or leading slashes. Together with the\n> two examples it seems to be a good compromise between accuracy and\n> understandable.\n>\n> The alternative would be to say\n>\n>         A pattern with a non-trailing slash is only matched against any\n>         path that begins in the directory of the `.gitignore` file.\n>\n> While this is maybe clearer then saying \"pattern [...] always\n> considered to begin at` it is ambiguous about the slashes.\n> So a very accuracy but maybe less understandable version would be\n> something like this:\n>\n>         A pattern with a non-trailing slash is only matched against any\n>         path that begins in the directory of the `.gitignore` file.\n>         For example, if the `.gitignore` file is in folder `doc`\n>         the path to file  `bar/doc/a/foo` that begins in `doc` is `a/foo`.\n>         A pattern that matches a path except for a leading slash or\n> trailing slash\n>         is still considered a match. It is still valid however,\n>         that when a pattern ends with a slash, it would only find a\n> match with a directory.\n>\n> ---------\n>\n> > Also, a pattern \"/doc\" matches doc at the current level (i.e. the\n> > directory in which .gitignore file that the pattern was taken from\n> > is found) and not in any subdirectories.  Is that clear in the\n> > proposed update?\n>\n> Yes.\n>\n> However, in the docs is already one paragraph solely dedicated for this case:\n>\n> > A leading slash matches the beginning of the pathname. For example, \"/*.c\" matches\n> > \"cat-file.c\" but not \"mozilla-sha1/sha1.c\".\n>\n> However, we have already a better and more in detail explained example\n> in the new\n> proposal `*` paragraph and and the case with the leading slash is\n> now a sub-case of `A pattern with a non-trailing slash`\n> so we might just get rid of the above paragraph?\n> ----------\n>\n>\n> Thank you for explaining me how the algorithm works procedurally.\n> It gave some inside of the origin of \"If the pattern ends with a slash, it is\n> removed for the purpose of the following description..\"\n> ---------\n>\n> All the best,\n> Adam\n"}]}