{"thread":{"id":"51206","subject":"[PATCH] make slash-rules more readable","startedAt":"2019-05-31T07:44:38Z","lastAt":"2019-06-04T17:22:47Z","messageCount":11,"participants":["Dr. Adam Nielsen","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"376469","messageId":"20190531074426.6810-1-admin@in-ici.net","threadId":"51206","inReplyTo":null,"subject":"[PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-31T07:44:26Z","receivedAt":"2019-05-31T07:44:38Z","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\nRemove meta-rule in a paragraph for trailing-slash.\nBe precise whenever a trailing slash would make a \ndifference. Improve paragraph for pattern without slash. \nRemove rule for leading slash because its now redundant. \nInstead, add examples for leading slash and asterix in \nexample section.\n\nSigned-off-by: Dr. Adam Nielsen \n\n---\n Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------\n 1 file changed, 50 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex b5bc9dbff0..a6c7807c74 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -89,28 +89,32 @@ 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+ - A slash `/` is used as a directory separator. A leading and trailing\n+ slash have special meaning 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. 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-\n- - A leading slash matches the beginning of the pathname.\n- For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n- \"mozilla-sha1/sha1.c\".\n+ directory `foo`, but will not match a regular file or a\n+ symbolic link `foo` (this is consistent with the way how\n+ pathspec works in general in Git).\n+\n+ - If the pattern does not end with a slash, it would find a match\n+ with a file or directory.\n+\n+ - The pattern is matched relative to the location of\n+ the `.gitignore` file. Except if the pattern contains\n+ no slash (or no slash but a trailing slash), then the pattern is\n+ matched against all files and folders (recursively)\n+ from the location of the `.gitignore` file.\n+ For example, `doc/frotz/` matches `doc/frotz` directory, but not\n+ a/doc/frotz`; however `frotz/` matches `frotz` and `a/frotz` that\n+ is a directory (all paths are relative from the `.gitignore` file).\n+\n+ - An asterisk \"`*`\" matches anything except a slash.\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 Two consecutive asterisks (\"`**`\") in patterns matched against\n full pathname may have special meaning:\n@@ -152,6 +156,31 @@ To stop tracking a file that is currently tracked, use\n EXAMPLES\n --------\n \n+ - The pattern `/bar` only matches the file or folder `bar`\n+ but not `a/bar`, whereas the pattern `bar` would match both\n+ (relative to the `.gitignore` file). That is because the\n+ pattern `/bar` contains a non-trailing slash and thus matches\n+ relative to the location of the `.gitignore` file.\n+ Since `bar` has no slash, it matches recursively.\n+\n+ - The pattern 'hello.*' is not sufficient for the following rule:\n+ \"ignore any file whose name begins with 'hello' and in this\n+ directory only, not in its subdirectories.\" because the pattern\n+ does not have any slash. To work around this limitation,\n+ you can prepend your pattern with a slash, i.e. '/hello.*';\n+ the pattern now matches 'hello.txt', 'hello.c' but not\n+ 'a/hello.java'.\n+\n+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n+ in any `.gitignore` file. Both pattern contain a non-trailing\n+ slash and thus match relative to the location of the\n+ `.gitignore` file.\n+\n+ - The pattern \"foo/*\", 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 --------------------------------------------------------------\n $ git status\n [...]\n-- \n2.17.1\n\n"},{"id":"376484","messageId":"xmqqh89awprl.fsf@gitster-ct.c.googlers.com","threadId":"51206","inReplyTo":"20190531074426.6810-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-31T16:30:06Z","receivedAt":"2019-05-31T16:30:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Dr. Adam Nielsen\" writes:\n\n> gitignore.txt: make slash-rules more readable\n>\n> Remove meta-rule in a paragraph for trailing-slash.\n> Be precise whenever a trailing slash would make a \n> difference. Improve paragraph for pattern without slash. \n> Remove rule for leading slash because its now redundant. \n> Instead, add examples for leading slash and asterix in \n> example section.\n>\n> Signed-off-by: Dr. Adam Nielsen \n>\n> ---\n> Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------\n> 1 file changed, 50 insertions(+), 21 deletions(-)\n\nI think the updated text is readable, except for one nit.\n\nSpecifically, if you took my suggestion in an earlier review to\nexplicitly say that leading slash is merely a workaround for a\nstring without slash to anchor the pattern to the directory and\nit should be treated as if it does not exist otherwise, then ...\n\n> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n> + in any `.gitignore` file. Both pattern contain a non-trailing\n> + slash and thus match relative to the location of the\n> + `.gitignore` file.\n\n... this paragraph wouldn't have been necessary. \n\nBesides, one extra reason why these two have the same effect is not\ngiven in the updated text to explain away \"To which substring of\npath 'doc/frotz' does that leading slash in /doc/frotz match?\"\n\nThe updated text does not seem to explain that the leading slash is\nmerely to pretend that the pattern \"contains a slash so it does not\napply in a subdirectory\" and for the purpose of pattern matching the\nslash does not participate in the textual match, which seems to have\nbeen lost in the updated patch, relative to the suggestions raised\nin the review of earlier rounds.\n\nThe updated description on trailing slash as type specifier\n(i.e. directory-only) is much easier to follow compared to the\nearlier rounds of this patch, I would think.\n\nThanks.\n"},{"id":"376488","messageId":"88c6cf45-3908-6561-c3bf-11adf628f8af@in-ici.net","threadId":"51206","inReplyTo":"xmqqh89awprl.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-31T17:24:25Z","receivedAt":"2019-05-31T17:24:31Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"\nOn 31.05.19 18:30, Junio C Hamano wrote:\n> \"Dr. Adam Nielsen\" writes:\n> \n>> gitignore.txt: make slash-rules more readable\n>>\n>> Remove meta-rule in a paragraph for trailing-slash.\n>> Be precise whenever a trailing slash would make a\n>> difference. Improve paragraph for pattern without slash.\n>> Remove rule for leading slash because its now redundant.\n>> Instead, add examples for leading slash and asterix in\n>> example section.\n>>\n>> Signed-off-by: Dr. Adam Nielsen \n>>\n>> ---\n>> Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------\n>> 1 file changed, 50 insertions(+), 21 deletions(-)\n> \n> I think the updated text is readable, except for one nit.\n> \n> Specifically, if you took my suggestion in an earlier review to\n\nI guess you are referencing on your review from 08.05.2019 to which I \nresponded On 12.05.19 11:56,\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 >\n > Yes, its not explained to the reader that the leading slash is removed\n > for the purpose of textual matching. But maybe this is not necessary in\n > order to understand the effect of the pattern.\n\n> explicitly say that leading slash is merely a workaround for a\n> string without slash to anchor the pattern to the directory and\n> it should be treated as if it does not exist otherwise, then ...\n> \n>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n>> + in any `.gitignore` file. Both pattern contain a non-trailing\n>> + slash and thus match relative to the location of the\n>> + `.gitignore` file.\n> \n> ... this paragraph wouldn't have been necessary.\n\nI think this above example follows from (and thus isn't necessary, but \njust a fine example)\n\n + - The pattern is matched relative to the location of\n + the `.gitignore` file. Except if the pattern contains\n + no slash [...]\n\nBecause a pattern with a leading slash has a slash, it \"is matched \nrelative to the location of the `.gitignore` file\".\n\n> \n> Besides, one extra reason why these two have the same effect is not\n> given in the updated text to explain away \"To which substring of\n> path 'doc/frotz' does that leading slash in /doc/frotz match?\"\n >\n> The updated text does not seem to explain that the leading slash is\n> merely to pretend that the pattern \"contains a slash so it does not\n> apply in a subdirectory\" and for the purpose of pattern matching the\n> slash does not participate in the textual match, which seems to have\n> been lost in the updated patch, relative to the suggestions raised\n> in the review of earlier rounds.\n\nI believe its not said anywhere in the docs that the pattern is compared \n by a textual match to a piece of the full path of a file\\folder (where \nthe path is represented as in a unix-like OS).\n\nI feel like your proposal from\n\nOn 08.05.19 07:33, Junio C Hamano wrote:\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.\n\nis great for everyone who knows about the algorithm in the background, \nbut for others it might be unclear what is meant.\n\nFor example \"pathname\" is not explained anywhere. Its not clear if \n\"pathname\" itself contains a leading slash, or in which format the \n\"pathname\" is represented, or if its is absolute or relative.\nAnd \"implicitly removed before matching..\" is maybe a bit confusing for \npeople that see the matching algorithm as a black box. If its not \nexplained anywhere in detail how the matching algorithm is conducted, \nwhy would it matter to tell that the leading slash is removed implicitly?\n\nThats why I think, the case with the leading slash is already covered by \nthe paragraph\n\n + - The pattern is matched relative to the location of\n + the `.gitignore` file. Except if the pattern contains\n + no slash [...]\n\nand why I put the further explanations (that are not necessary in my \nopinion, but also not obvious) in the example section.\n\nThus, I don't feel the need to add another paragraph, but if you want, I \ncan add\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.\n\nas another bullet to the patch.\n\nAll the best,\nAdam\n"},{"id":"376490","messageId":"xmqq1s0ewmin.fsf@gitster-ct.c.googlers.com","threadId":"51206","inReplyTo":"88c6cf45-3908-6561-c3bf-11adf628f8af@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-31T17:40:16Z","receivedAt":"2019-05-31T17:40:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Dr. Adam Nielsen\" writes:\n\n>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n>>> + in any `.gitignore` file. Both pattern contain a non-trailing\n>>> + slash and thus match relative to the location of the\n>>> + `.gitignore` file.\n>>\n>> ... this paragraph wouldn't have been necessary.\n>\n> I think this above example follows from (and thus isn't necessary, but\n> just a fine example)\n>\n> + - The pattern is matched relative to the location of\n> + the `.gitignore` file. Except if the pattern contains\n> + no slash [...]\n>\n> Because a pattern with a leading slash has a slash, it \"is matched\n> relative to the location of the `.gitignore` file\".\n\nBut that does not explain why the pattern /doc/frotz matches the\npath doc/frotz. A reader can understand 'd' (the second letter in\nthe patern) would match 'd' (the firstr letter in the path), 'o'\nwith 'o', etc., but nobody told the reader which substring of the\npath consumes the leading '/' in the pattern as matched.\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.\n\nYeah, that would be an addition that makes the updated text\nmore complete.\n"},{"id":"376529","messageId":"979f6497-5e26-4a93-c345-f61b31c736c6@talktalk.net","threadId":"51206","inReplyTo":"xmqqh89awprl.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Philip Oakley","fromEmail":"philipoakley@talktalk.net","sentAt":"2019-06-01T09:33:33Z","receivedAt":"2019-06-01T10:30:57Z","isPatch":true,"sender":{"key":"philipoakley@talktalk.net","avatar":null},"body":"Hi Junio,\nOn 31/05/2019 17:30, Junio C Hamano wrote:\n> I think the updated text is readable, except for one nit.\n>\n> Specifically, if you took my suggestion in an earlier review to\n> explicitly say that leading slash is merely a workaround for a\n> string without slash to anchor the pattern to the directory and\n> it should be treated as if it does not exist otherwise, then ...\n From a user perspective, implementation issues shouldn't be part of the \ndescription unless absolutely essential.\n\nMost user aren't aware of the implementation so don't grok/understand \nwhat the fuss is about and ignore it...\n>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n>> + in any `.gitignore` file. Both pattern contain a non-trailing\n>> + slash and thus match relative to the location of the\n>> + `.gitignore` file.\n> ... this paragraph wouldn't have been necessary.\n...leading to that user mistake having to be explained in numerous Q&A \nthreads - Why can't we an explicit explanation of this common user \nmistake? Arguably the issue is the special trailing slash rule getting \nusers confused..\n\n--\nPhilip\n"},{"id":"376530","messageId":"6f633212-7ea8-0d26-3476-fa5a2142ef06@iee.org","threadId":"51206","inReplyTo":"20190531074426.6810-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-06-01T09:23:15Z","receivedAt":"2019-06-01T10:47:19Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Minor spelling mistake at end:\nOn 31/05/2019 08:44, Dr. Adam Nielsen wrote:\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.\ns/patter/pattern/\n> +\n> --------------------------------------------------------------\nPhilip\n"},{"id":"376539","messageId":"37f3d5d3-80b0-c37d-23e6-d05e77fc498a@in-ici.net","threadId":"51206","inReplyTo":"979f6497-5e26-4a93-c345-f61b31c736c6@talktalk.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-06-02T09:01:34Z","receivedAt":"2019-06-02T09:04:38Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"Hi Philip,\n\nOn 01.06.19 11:33, Philip Oakley wrote:\n> From a user perspective, implementation issues shouldn't be part of the \n> description unless absolutely essential.\n> \n> Most user aren't aware of the implementation so don't grok/understand \n> what the fuss is about and ignore it...\n\nI agree with that. I will send another patch where I add the leading \nslash rule without going into implementation details.\n\n\n\n\n"},{"id":"376590","messageId":"xmqqsgsqv98w.fsf@gitster-ct.c.googlers.com","threadId":"51206","inReplyTo":"979f6497-5e26-4a93-c345-f61b31c736c6@talktalk.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-06-03T18:01:19Z","receivedAt":"2019-06-03T18:01:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> From a user perspective, implementation issues shouldn't be part of\n> the description unless absolutely essential.\n> Most user aren't aware of the implementation so don't grok/understand\n> what the fuss is about and ignore it...\n\nOh, absolutely. But unfortunately I do not see what that principle\nhas anything to do with the comments you made in your message.\n\n>> Specifically, if you took my suggestion in an earlier review to\n>> explicitly say that leading slash is merely a workaround for a\n>> string without slash to anchor the pattern to the directory and\n>> it should be treated as if it does not exist otherwise, then ...\n\nPerhaps you thought \"workaround\" refers to some implementation\nglitch? That is not what the word means in that sentence. It is a\ntechnique to work around \"you need a slash somewhere in the pattern\nto anchor it to a specific directory\" that is a very user visible\ndesign. The user absolutely need to be aware of it, if s/he wants\nto anchor a pattern that does not have a slash (e.g. \"I need a\npattern to name/match the README file at this level but not in any\nof the subdirectories\"), and an extra leading slash is a way to mark\nsuch a pattern that otherwise does not have a slash as anchored.\n\nThe fact that the leading slash is such a syntactic marking of a\npattern *and* is not a part of the pattern itself, would not help\nyou understand the implementation, but you need to know it in order\nto use that feature effectively.\n\n>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n>>> + in any `.gitignore` file. Both pattern contain a non-trailing\n>>> + slash and thus match relative to the location of the\n>>> + `.gitignore` file.\n>> ... this paragraph wouldn't have been necessary.\n> ...leading to that user mistake having to be explained in numerous Q&A\n> threads - Why can't we an explicit explanation of this common user\n> mistake?\n> Arguably the issue is the special trailing slash rule getting\n> users confused..\n\nWhat common user mistake? The above is about leading slash rule, by\nthe way, so perhaps you are getting confused?\n"},{"id":"376648","messageId":"221eab3b-75a1-c108-79a4-e2654c844d91@iee.org","threadId":"51206","inReplyTo":"xmqqsgsqv98w.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-06-04T10:40:49Z","receivedAt":"2019-06-04T10:40:51Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 03/06/2019 19:01, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n>> From a user perspective, implementation issues shouldn't be part of\n>> the description unless absolutely essential.\n>> Most user aren't aware of the implementation so don't grok/understand\n>> what the fuss is about and ignore it...\n> Oh, absolutely. But unfortunately I do not see what that principle\n> has anything to do with the comments you made in your message.\n>\n>>> Specifically, if you took my suggestion in an earlier review to\n>>> explicitly say that leading slash is merely a workaround for a\n>>> string without slash to anchor the pattern to the directory and\n>>> it should be treated as if it does not exist otherwise, then ...\n> Perhaps you thought \"workaround\" refers to some implementation\n> glitch? That is not what the word means in that sentence. It is a\n> technique to work around \"you need a slash somewhere in the pattern\n> to anchor it to a specific directory\" that is a very user visible\n> design.\nIt is the fact that we have ended up describing what needs to be done \nfrom having had the implementation problem. Thus we (accidentally) lock \nourselves into a 'difficult to explain' situation.\n> The user absolutely need to be aware of it, if s/he wants\n> to anchor a pattern that does not have a slash\nNo. That (as I read it, regarding the need for an initial slash) is the \nlock-in.\n\nWe should explain it from the other end  - to anchor the pattern one \nneeds a slash either at the beginning or middle.\n\n> (e.g. \"I need a\n> pattern to name/match the README file at this level but not in any\n> of the subdirectories\"), and an extra leading slash is a way to mark\n> such a pattern that otherwise does not have a slash as anchored.\n>\n> The fact that the leading slash is such a syntactic marking of a\n> pattern *and* is not a part of the pattern itself, would not help\n> you understand the implementation, but you need to know it in order\n> to use that feature effectively.\n>\n>>>> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n>>>> + in any `.gitignore` file. Both pattern contain a non-trailing\n>>>> + slash and thus match relative to the location of the\n>>>> + `.gitignore` file.\n>>> ... this paragraph wouldn't have been necessary.\n>> ...leading to that user mistake having to be explained in numerous Q&A\n>> threads - Why can't we an explicit explanation of this common user\n>> mistake?\n>> Arguably the issue is the special trailing slash rule getting\n>> users confused..\n> What common user mistake? The above is about leading slash rule, by\n> the way, so perhaps you are getting confused?\nWe do get a reasonable number of queries to the list regarding \n.gitignore patterns which generally indicate that user have been \nconfused and failed to understand the overall man page description (both \nleading and training slashes being somehow special but exactly how they \nhaven't fully fathomed..) (and plenty on StackOverflow)\n\nI'll ad some more feedback to Adam's side of the thread, and a possible \nalternate suggestion.\n\nPhilip\n"},{"id":"376651","messageId":"0c9f79f3-b43b-5f32-d217-ff92531c5da7@iee.org","threadId":"51206","inReplyTo":"20190531074426.6810-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-06-04T12:34:25Z","receivedAt":"2019-06-04T12:34:26Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Adam,\nOn 31/05/2019 08:44, Dr. Adam Nielsen wrote:\n> gitignore.txt: make slash-rules more readable\n>\n> Remove meta-rule in a paragraph for trailing-slash.\n> Be precise whenever a trailing slash would make a\n> difference. Improve paragraph for pattern without slash.\n> Remove rule for leading slash because its now redundant.\n> Instead, add examples for leading slash and asterix in\n> example section.\n>\n> Signed-off-by: Dr. Adam Nielsen \nI think the rules end up being difficult because we describe them from a \ncoders implementation viewpoint, rather than a users descriptive \nviewpoint. Thus we avoided things like the difficult to code slashes in \nthe front/middle, and we get caught on the equivalent of neither/nor \nphrases, which can even be difficult for native English speakers.\n\nLater on there is a recursively/respectively issue (latter not \nexplicitly mentioned).  There is also an \"Except if\" not-a-proper \nsentence. (mentioned off-line)\n\nI think this is the truth table for the slash..\nLead/  | mid/  | end/  |\nyes    |yes    |yes    | Directory, directly at .gitignore\nno     |yes    |yes    | Directory, directly at .gitignore\nyes    |no     |yes    | Directory, directly at .gitignore\nno     |no     |yes    | Directory, anywhere at, or below, .gitignore   \n ---\n> Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------\n> 1 file changed, 50 insertions(+), 21 deletions(-)\n>\n> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\n> index b5bc9dbff0..a6c7807c74 100644\n> --- a/Documentation/gitignore.txt\n> +++ b/Documentation/gitignore.txt\n> @@ -89,28 +89,32 @@ 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> + - A slash `/` is used as a directory separator. A leading and trailing\n> + slash have special meaning 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. 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> -\n> - - A leading slash matches the beginning of the pathname.\n> - For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n> - \"mozilla-sha1/sha1.c\".\n> + directory `foo`, but will not match a regular file or a\n> + symbolic link `foo` (this is consistent with the way how\n> + pathspec works in general in Git).\n> +\n> + - If the pattern does not end with a slash, it would find a match\n> + with a file or directory.\n> +\n> + - The pattern is matched relative to the location of\n> + the `.gitignore` file. Except if the pattern contains\n> + no slash (or no slash but a trailing slash), then the pattern is\n> + matched against all files and folders (recursively)\n> + from the location of the `.gitignore` file.\n> + For example, `doc/frotz/` matches `doc/frotz` directory, but not\n> + a/doc/frotz`; however `frotz/` matches `frotz` and `a/frotz` that\n> + is a directory (all paths are relative from the `.gitignore` file).\n> +\n> + - An asterisk \"`*`\" matches anything except a slash.\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> Two consecutive asterisks (\"`**`\") in patterns matched against\n> full pathname may have special meaning:\n> @@ -152,6 +156,31 @@ To stop tracking a file that is currently tracked, use\n> EXAMPLES\n> --------\n> \n> + - The pattern `/bar` only matches the file or folder `bar`\n> + but not `a/bar`, whereas the pattern `bar` would match both\n> + (relative to the `.gitignore` file). That is because the\n> + pattern `/bar` contains a non-trailing slash and thus matches\n> + relative to the location of the `.gitignore` file.\n> + Since `bar` has no slash, it matches recursively.\n> +\n> + - The pattern 'hello.*' is not sufficient for the following rule:\n> + \"ignore any file whose name begins with 'hello' and in this\n> + directory only, not in its subdirectories.\" because the pattern\n> + does not have any slash. To work around this limitation,\n> + you can prepend your pattern with a slash, i.e. '/hello.*';\n> + the pattern now matches 'hello.txt', 'hello.c' but not\n> + 'a/hello.java'.\n> +\n> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect\n> + in any `.gitignore` file. Both pattern contain a non-trailing\n> + slash and thus match relative to the location of the\n> + `.gitignore` file.\n> +\n> + - The pattern \"foo/*\", 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> --------------------------------------------------------------\n> $ git status\n> [...]\n\n"},{"id":"376676","messageId":"8984a44f-b80c-9d04-3094-c17bb4e17d20@in-ici.net","threadId":"51206","inReplyTo":"0c9f79f3-b43b-5f32-d217-ff92531c5da7@iee.org","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-06-04T17:22:43Z","receivedAt":"2019-06-04T17:22:47Z","isPatch":true,"sender":{"key":"admin@in-ici.net","avatar":"https://avatars.githubusercontent.com/u/1765602?v=4"},"body":"Hi Philip\n\nOn 04.06.19 14:34, Philip Oakley wrote:\n> I think the rules end up being difficult because we describe them from a \n> coders implementation viewpoint, rather than a users descriptive \n> viewpoint. Thus we avoided things like the difficult to code slashes in \n> the front/middle, and we get caught on the equivalent of neither/nor \n> phrases, which can even be difficult for native English speakers.\n> \n> Later on there is a recursively/respectively issue (latter not \n> explicitly mentioned).  There is also an \"Except if\" not-a-proper \n> sentence. (mentioned off-line)\n> \n> After sleeping on it, I came up with:\n> \n>    The slash '/' is used as the directory separator. Separators may\n>    occur at the beginning, middle or end of the .gitignore search pattern.\n> \n>    If there is a separator at the beginning or middle (or both) of the\n>    pattern, then the pattern is relative to the directory level of the\n>    particular .gitignore file itself. Otherwise the pattern may also\n>    match at any level below the .gitignore level.\n> \n>    If there is a separator at the end of the pattern then the pattern\n>    will only match directories, otherwise the pattern can match both\n>    files and directories.\n> \n>    Examples text..\n> \n>    The special '*' ...\n> \n>    The special '**' ...\n> \n\nI am really happy about this improvement (or rather this new creation). \nIn my opinion it is really easy to understand now, and it solves a ton \nof other issues we had with the preceding proposals.\n\nI will create a new patch.\n\nAll the best,\nAdam\n\n"}]}