{"thread":{"id":"51122","subject":"[PATCH] make slash-rules more readable","startedAt":"2019-05-18T14:13:45Z","lastAt":"2019-05-19T16:58:12Z","messageCount":3,"participants":["Dr. Adam Nielsen","Junio C Hamano","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"375855","messageId":"20190518141337.14919-1-admin@in-ici.net","threadId":"51122","inReplyTo":null,"subject":"[PATCH] make slash-rules more readable","fromName":"Dr. Adam Nielsen","fromEmail":"admin@in-ici.net","sentAt":"2019-05-18T14:13:37Z","receivedAt":"2019-05-18T14:13:45Z","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 sentece and example\nfor pattern with slash. Be precise whenever a trailing \nslashe would make a difference. Add some examples.\n\nSigned-off-by: Dr. Adam Nielsen <admin@in-ici.net>\n\n---\n Documentation/gitignore.txt | 57 +++++++++++++++++++++++--------------\n 1 file changed, 36 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex b5bc9dbff0..925bf767b1 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -89,28 +89,43 @@ 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+ - If the pattern contains no slash or only a 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+   Otherwise the pattern is matched relative to the\n+   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+ - The above pargraph also includes the case of a leading slash.\n+   For example, the pattern `/bar` only matches the file or\n+   folder `bar` that is at the same location as the `gitignore`\n+   file. Whereas the pattern `bar` would also match in folders\n+   below the `gitignore`  file.\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 Two consecutive asterisks (\"`**`\") in patterns matched against\n full pathname may have special meaning:\n-- \n2.17.1\n\n"},{"id":"375869","messageId":"xmqqo93z19wg.fsf@gitster-ct.c.googlers.com","threadId":"51122","inReplyTo":"20190518141337.14919-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-19T01:59:59Z","receivedAt":"2019-05-19T02:00:07Z","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> gitignore.txt: make slash-rules more readable\n>\n> Make all paragraphs valid, even if they are not read\n> in strict order.\n\nI think you are giving up on this, and I do not think that is\nparticularly a bad thing ;-)\n\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> +   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> + - If the pattern contains no slash or only a 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> +   Otherwise the pattern is matched relative to the\n> +   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\nOK.\n\n> + - The above pargraph also includes the case of a leading slash.\n\nNow you (not you the author of the document, but figuratively \"any\nreader of this document\") must have read all the four before this\npoint ;-) To put it differently, your reading of the above four\nbullets are incomplete unless you read this too.\n\nTypofix: \"pargraph\" -> \"paragraph\".\n\nIn any case, I cannot guess what 'also include the case of a leaning\nslash' wants to say.  Perhaps\n\n      Note that the above rule means you cannot easily say \"a file\n      whose name contains 'hello' and in this directory only, not in\n      its subdirectories.\" because a pattern 'hello.*' does not have\n      any slash.  To work around this limitation, you can prepend\n      your pattern with a slash, i.e. '/hello.*'; the pattern now\n      matches 'hello.txt', 'hello.c' but not 'a/hello.java'.\n\nas the third point of the above paragraph (the first is about a\npattern without a slash, the second \"Otherwise\" is about a pattern\nwith one or more slashes, and the new \"Note that\" becomes the\nthird) may make it easier to follow and keep your \"each bullet point\nis independent\".\n\n> +   For example, the pattern `/bar` only matches the file or\n> +   folder `bar` that is at the same location as the `gitignore`\n> +   file. Whereas the pattern `bar` would also match in folders\n> +   below the `gitignore`  file.\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>  Two consecutive asterisks (\"`**`\") in patterns matched against\n>  full pathname may have special meaning:\n"},{"id":"375871","messageId":"b98df9fc-384d-1d73-170c-691630454287@kdbg.org","threadId":"51122","inReplyTo":"20190518141337.14919-1-admin@in-ici.net","subject":"Re: [PATCH] make slash-rules more readable","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2019-05-19T06:59:10Z","receivedAt":"2019-05-19T16:58:12Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 18.05.19 um 16:13 schrieb Dr. Adam Nielsen:\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> + - If the pattern contains no slash or only a 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> +   Otherwise the pattern is matched relative to the\n> +   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> + - The above pargraph also includes the case of a leading slash.\n> +   For example, the pattern `/bar` only matches the file or\n> +   folder `bar` that is at the same location as the `gitignore`\n> +   file. Whereas the pattern `bar` would also match in folders\n> +   below the `gitignore`  file.\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>  Two consecutive asterisks (\"`**`\") in patterns matched against\n>  full pathname may have special meaning:\n\nAll those examples unterrupt the flow of thought in a way that makes it\ndiffcult to follow the reasoning. May I suggest a different approach to\nupate this text? Provide two patches:\n\n- Patch 1/2 updates the Examples section such that it contains all\n  examples that you provide in the text above, with explanation.\n  Perhaps refer to the Examples section early above the rules.\n\n- Patch 2/2 updates the rules section without giving examples.\n\nLet's see how that works out.\n\nThe examples in the Examples section are overly technical by saying\n\n   $ cat .gitignore\n   vmlinux*\n   $ ls arch/foo/kernel/vm*\n   arch/foo/kernel/vmlinux.lds.S\n   $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore\n\nI think that this could be made more pleasent to read if one would not\nhave to use a mental shell interpreter. ;)\n\n-- Hannes\n"}]}