# [PATCH] make slash-rules more readable 3 messages from 2019-05-18 to 2019-05-19. Participants: Dr. Adam Nielsen, Junio C Hamano, Johannes Sixt. Thread: https://gitlist.dev/t/51122 ## Dr. Adam Nielsen, 2019-05-18 14:13 Subject: [PATCH] make slash-rules more readable Message-ID: <20190518141337.14919-1-admin@in-ici.net> URL: https://gitlist.dev/e/20190518141337.14919-1-admin%40in-ici.net ``` gitignore.txt: make slash-rules more readable Make all paragraphs valid, even if they are not read in strict order. Make paragraph better understandable for pattern without slash. Add sentece and example for pattern with slash. Be precise whenever a trailing slashe would make a difference. Add some examples. Signed-off-by: Dr. Adam Nielsen --- Documentation/gitignore.txt | 57 +++++++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index b5bc9dbff0..925bf767b1 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -89,28 +89,43 @@ PATTERN FORMAT Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". - - If the pattern ends with a slash, it is removed for the - purpose of the following description, but it would only find + - A slash `/` is used as a directory separator. A leading and trailing + slash have special meaning and are explained in the following. + + - If the pattern ends with a slash, it would only find a match with a directory. In other words, `foo/` will match a - directory `foo` and paths underneath it, but will not match a - regular file or a symbolic link `foo` (this is consistent - with the way how pathspec works in general in Git). - - - If the pattern does not contain a slash '/', Git treats it as - a shell glob pattern and checks for a match against the - pathname relative to the location of the `.gitignore` file - (relative to the toplevel of the work tree if not from a - `.gitignore` file). - - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches - anything except "`/`", "`?`" matches any one character except "`/`" - and "`[]`" matches one character in a selected range. See - fnmatch(3) and the FNM_PATHNAME flag for a more detailed - description. - - - A leading slash matches the beginning of the pathname. - For example, "/{asterisk}.c" matches "cat-file.c" but not - "mozilla-sha1/sha1.c". + directory `foo`, but will not match a regular file or a + symbolic link `foo` (this is consistent with the way how + pathspec works in general in Git). + + - If the pattern does not end with a slash, it would find a match + with a file or directory. + + - If the pattern contains no slash or only a trailing slash, + the pattern is matched against all files and folders (recursively) + from the location of the `.gitignore` file. + For example, `frotz/` matches `frotz` and `a/frotz` that + is a directory (relative from the `.gitignore` file). + Otherwise the pattern is matched relative to the + location of the `.gitignore` file. + For example, `doc/frotz/` matches `doc/frotz` directory, but not + `a/doc/frotz` (relative from the `.gitignore` file). + + - The above pargraph also includes the case of a leading slash. + For example, the pattern `/bar` only matches the file or + folder `bar` that is at the same location as the `gitignore` + file. Whereas the pattern `bar` would also match in folders + below the `gitignore` file. + + - An asterisk "`*`" matches anything except a slash. + A pattern "foo/*", for example, matches "foo/test.json" + (a regular file), "foo/bar" (a diretory), but it does not match + "foo/bar/hello.c" (a regular file), as the asterisk in the + patter does not match "bar/hello.c" which has a slash in it. + The character "`?`" matches any one character except "`/`". + The range notation, e.g. `[a-zA-Z]`, can be used to match + one of the characters in a range. See fnmatch(3) and the + FNM_PATHNAME flag for a more detailed description. Two consecutive asterisks ("`**`") in patterns matched against full pathname may have special meaning: -- 2.17.1 ``` ## Junio C Hamano, 2019-05-19 01:59 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/xmqqo93z19wg.fsf%40gitster-ct.c.googlers.com In-Reply-To: <20190518141337.14919-1-admin@in-ici.net> ``` "Dr. Adam Nielsen" writes: > gitignore.txt: make slash-rules more readable > > Make all paragraphs valid, even if they are not read > in strict order. I think you are giving up on this, and I do not think that is particularly a bad thing ;-) > + - A slash `/` is used as a directory separator. A leading and trailing > + slash have special meaning and are explained in the following. > + > + - If the pattern ends with a slash, it would only find > + directory `foo`, but will not match a regular file or a > + symbolic link `foo` (this is consistent with the way how > + pathspec works in general in Git). > + > + - If the pattern does not end with a slash, it would find a match > + with a file or directory. > + > + - If the pattern contains no slash or only a trailing slash, > + the pattern is matched against all files and folders (recursively) > + from the location of the `.gitignore` file. > + For example, `frotz/` matches `frotz` and `a/frotz` that > + is a directory (relative from the `.gitignore` file). > + Otherwise the pattern is matched relative to the > + location of the `.gitignore` file. > + For example, `doc/frotz/` matches `doc/frotz` directory, but not > + `a/doc/frotz` (relative from the `.gitignore` file). OK. > + - The above pargraph also includes the case of a leading slash. Now you (not you the author of the document, but figuratively "any reader of this document") must have read all the four before this point ;-) To put it differently, your reading of the above four bullets are incomplete unless you read this too. Typofix: "pargraph" -> "paragraph". In any case, I cannot guess what 'also include the case of a leaning slash' wants to say. Perhaps Note that the above rule means you cannot easily say "a file whose name contains 'hello' and in this directory only, not in its subdirectories." because a pattern 'hello.*' does not have any slash. To work around this limitation, you can prepend your pattern with a slash, i.e. '/hello.*'; the pattern now matches 'hello.txt', 'hello.c' but not 'a/hello.java'. as the third point of the above paragraph (the first is about a pattern without a slash, the second "Otherwise" is about a pattern with one or more slashes, and the new "Note that" becomes the third) may make it easier to follow and keep your "each bullet point is independent". > + For example, the pattern `/bar` only matches the file or > + folder `bar` that is at the same location as the `gitignore` > + file. Whereas the pattern `bar` would also match in folders > + below the `gitignore` file. > + > + - An asterisk "`*`" matches anything except a slash. > + A pattern "foo/*", for example, matches "foo/test.json" > + (a regular file), "foo/bar" (a diretory), but it does not match > + "foo/bar/hello.c" (a regular file), as the asterisk in the > + patter does not match "bar/hello.c" which has a slash in it. > + The character "`?`" matches any one character except "`/`". > + The range notation, e.g. `[a-zA-Z]`, can be used to match > + one of the characters in a range. See fnmatch(3) and the > + FNM_PATHNAME flag for a more detailed description. > > Two consecutive asterisks ("`**`") in patterns matched against > full pathname may have special meaning: ``` ## Johannes Sixt, 2019-05-19 06:59 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/b98df9fc-384d-1d73-170c-691630454287%40kdbg.org In-Reply-To: <20190518141337.14919-1-admin@in-ici.net> ``` Am 18.05.19 um 16:13 schrieb Dr. Adam Nielsen: > - - If the pattern ends with a slash, it is removed for the > - purpose of the following description, but it would only find > + - A slash `/` is used as a directory separator. A leading and trailing > + slash have special meaning and are explained in the following. > + > + - If the pattern ends with a slash, it would only find > a match with a directory. In other words, `foo/` will match a > - directory `foo` and paths underneath it, but will not match a > - regular file or a symbolic link `foo` (this is consistent > - with the way how pathspec works in general in Git). > - > - - If the pattern does not contain a slash '/', Git treats it as > - a shell glob pattern and checks for a match against the > - pathname relative to the location of the `.gitignore` file > - (relative to the toplevel of the work tree if not from a > - `.gitignore` file). > - > - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches > - anything except "`/`", "`?`" matches any one character except "`/`" > - and "`[]`" matches one character in a selected range. See > - fnmatch(3) and the FNM_PATHNAME flag for a more detailed > - description. > - > - - A leading slash matches the beginning of the pathname. > - For example, "/{asterisk}.c" matches "cat-file.c" but not > - "mozilla-sha1/sha1.c". > + directory `foo`, but will not match a regular file or a > + symbolic link `foo` (this is consistent with the way how > + pathspec works in general in Git). > + > + - If the pattern does not end with a slash, it would find a match > + with a file or directory. > + > + - If the pattern contains no slash or only a trailing slash, > + the pattern is matched against all files and folders (recursively) > + from the location of the `.gitignore` file. > + For example, `frotz/` matches `frotz` and `a/frotz` that > + is a directory (relative from the `.gitignore` file). > + Otherwise the pattern is matched relative to the > + location of the `.gitignore` file. > + For example, `doc/frotz/` matches `doc/frotz` directory, but not > + `a/doc/frotz` (relative from the `.gitignore` file). > + > + - The above pargraph also includes the case of a leading slash. > + For example, the pattern `/bar` only matches the file or > + folder `bar` that is at the same location as the `gitignore` > + file. Whereas the pattern `bar` would also match in folders > + below the `gitignore` file. > + > + - An asterisk "`*`" matches anything except a slash. > + A pattern "foo/*", for example, matches "foo/test.json" > + (a regular file), "foo/bar" (a diretory), but it does not match > + "foo/bar/hello.c" (a regular file), as the asterisk in the > + patter does not match "bar/hello.c" which has a slash in it. > + The character "`?`" matches any one character except "`/`". > + The range notation, e.g. `[a-zA-Z]`, can be used to match > + one of the characters in a range. See fnmatch(3) and the > + FNM_PATHNAME flag for a more detailed description. > > Two consecutive asterisks ("`**`") in patterns matched against > full pathname may have special meaning: All those examples unterrupt the flow of thought in a way that makes it diffcult to follow the reasoning. May I suggest a different approach to upate this text? Provide two patches: - Patch 1/2 updates the Examples section such that it contains all examples that you provide in the text above, with explanation. Perhaps refer to the Examples section early above the rules. - Patch 2/2 updates the rules section without giving examples. Let's see how that works out. The examples in the Examples section are overly technical by saying $ cat .gitignore vmlinux* $ ls arch/foo/kernel/vm* arch/foo/kernel/vmlinux.lds.S $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore I think that this could be made more pleasent to read if one would not have to use a mental shell interpreter. ;) -- Hannes ```