make slash-rules more readable
PATCH 1/1 make slash-rules more readable
gitignore.txt: make slash-rules more readable
Renew paragraphs relevant for pattern with slash.
Aim to make it more clear and to avoid possible
pitfalls for the reader. Add some examples.
--- Documentation/gitignore.txt | 66 ++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 22 deletions(-)
Documentation/gitignore.txt +44 -22
@@ -89,28 +89,28 @@ 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 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". + - The slash '/' is used as the directory separator. Separators may + occur at the beginning, middle or end of the `.gitignore` search pattern. + + - If there is a separator at the beginning or middle (or both) of the + pattern, then the pattern is relative to the directory level of the + particular `.gitignore` file itself. Otherwise the pattern may also + match at any level below the `.gitignore` level. + + - If there is a separator at the end of the pattern then the pattern + will only match directories, otherwise the pattern can match both + files and directories. + + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, + but not `a/doc/frotz` directory; however `frotz/` matches `frotz` + and `a/frotz` that is a directory (all paths are relative from + the `.gitignore` file). + + - An asterisk "`*`" matches anything except a slash. + 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:
@@ -152,6 +152,28 @@ To stop tracking a file that is currently tracked, use EXAMPLES -------- + - The pattern `hello.*` matches any file or folder + whose name begins with `hello`. If one wants to restrict + this only to the directory and not in its subdirectories, + one can prepend the pattern with a slash, i.e. `/hello.*`; + the pattern now matches `hello.txt`, `hello.c` but not + `a/hello.java`. + + - The pattern `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) + + - The pattern `doc/frotz` and `/doc/frotz` have the same effect + in any `.gitignore` file. In other words, a leading slash + is not relevant if there is already a middle slash in + the pattern. + + - The pattern "foo/*", matches "foo/test.json" + (a regular file), "foo/bar" (a directory), but it does not match + "foo/bar/hello.c" (a regular file), as the asterisk in the + pattern does not match "bar/hello.c" which has a slash in it. + -------------------------------------------------------------- $ git status [...]
Signature · 1 line
2.17.1
Hi everyone,
any comments about the patch note from 04.06 ?
All the best,
Adam
Quoted 97 lines · Dr. Adam Nielsen
gitignore.txt: make slash-rules more readable
Renew paragraphs relevant for pattern with slash.
Aim to make it more clear and to avoid possible
pitfalls for the reader. Add some examples.Signed-off-by Dr. Adam Nielsen <[email protected]>--- Documentation/gitignore.txt | 66 ++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 22 deletions(-)Documentation/gitignore.txt +44
-22@@ -89,28 +89,28 @@ 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 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". + - The slash '/' is used as the directory separator. Separators may + occur at the beginning, middle or end of the `.gitignore` search pattern. + + - If there is a separator at the beginning or middle (or both) of the + pattern, then the pattern is relative to the directory level of the + particular `.gitignore` file itself. Otherwise the pattern may also + match at any level below the `.gitignore` level. + + - If there is a separator at the end of the pattern then the pattern + will only match directories, otherwise the pattern can match both + files and directories. + + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, + but not `a/doc/frotz` directory; however `frotz/` matches `frotz` + and `a/frotz` that is a directory (all paths are relative from + the `.gitignore` file). + + - An asterisk "`*`" matches anything except a slash. + 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:@@ -152,6 +152,28 @@ To stop tracking a file that is currently tracked, use EXAMPLES -------- + - The pattern `hello.*` matches any file or folder + whose name begins with `hello`. If one wants to restrict + this only to the directory and not in its subdirectories, + one can prepend the pattern with a slash, i.e. `/hello.*`; + the pattern now matches `hello.txt`, `hello.c` but not + `a/hello.java`. + + - The pattern `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) + + - The pattern `doc/frotz` and `/doc/frotz` have the same effect + in any `.gitignore` file. In other words, a leading slash + is not relevant if there is already a middle slash in + the pattern. + + - The pattern "foo/*", matches "foo/test.json" + (a regular file), "foo/bar" (a directory), but it does not match + "foo/bar/hello.c" (a regular file), as the asterisk in the + pattern does not match "bar/hello.c" which has a slash in it. + -------------------------------------------------------------- $ git status
Signature · 6 lines
photograph *Dr. Adam Nielsen * Administrator | IN/ICI/WHO *IN:* nlp-institutes.net <https://nlp-institutes.net> *ICI:* coaching-institutes.net <https://coaching-institutes.net> *WHO:* world-hypnosis.org <https://world-hypnosis.org>
only one minor point...
Quoted 56 lines · Dr. Adam Nielsen
Hi everyone,
any comments about the patch note from 04.06 ?
All the best,
AdamQuoted 48 lines · Dr. Adam Nielsen
gitignore.txt: make slash-rules more readable
Renew paragraphs relevant for pattern with slash.
Aim to make it more clear and to avoid possible
pitfalls for the reader. Add some examples.Signed-off-by Dr. Adam Nielsen <[email protected]>---
Documentation/gitignore.txt| 66 ++++++++++++++++++++++++-------------1 file changed, 44 insertions(+), 22 deletions(-)Documentation/gitignore.txt +0
-0@@ -89,28 +89,28 @@ PATTERN FORMATPut 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 match with a directory. In other words,foo/will match a - directoryfooand paths underneath it, but will not match a - regular file or a symbolic linkfoo(this is consistent - with the way how pathspec works in general in Git).Documentation/gitignore.txt +2
-16- - - 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". + - The slash '/' is used as the directory separator. Separators may + occur at the beginning, middle or end of the `.gitignore` searchpattern.
+
+ - If there is a separator at the beginning or middle (or both) of the + pattern, then the pattern is relative to the directory level of the + particular.gitignorefile itself. Otherwise the pattern may also
Quoted 8 lines
Documentation/gitignore.txt PATTERN FORMAT · line 105
Quoted 8 lines
+ match at any level below the
.gitignorelevel.Documentation/gitignore.txt +7
-0+ + - If there is a separator at the end of the pattern then the pattern + will only match directories, otherwise the pattern can match both + files and directories. + + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, + but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
her I misread this as: "but not a doc/frotz directory;"
i.e. the leading 'a' is too easy to skim over as is part of the sentence's prose, so maybe change to a 'baz' lead directory (bar already having been used below).
Quoted 32 lines
Quoted 32 lines
+ and
a/frotzthat is a directory (all paths are relative from + the.gitignorefile).
+
+ - An asterisk "*" matches anything except a slash. + 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_PATHNAMEflag for a more detailed description. Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:Documentation/gitignore.txt +0
-0@@ -152,6 +152,28 @@ To stop tracking a file that is currentlytracked, use
EXAMPLES
--------
+ - The patternhello.*matches any file or folder + whose name begins withhello. If one wants to restrict + this only to the directory and not in its subdirectories, + one can prepend the pattern with a slash, i.e./hello.*; + the pattern now matcheshello.txt,hello.cbut not +a/hello.java.Documentation/gitignore.txt +12
-0+ + - The pattern `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) + + - The pattern `doc/frotz` and `/doc/frotz` have the same effect + in any `.gitignore` file. In other words, a leading slash + is not relevant if there is already a middle slash in + the pattern. + + - The pattern "foo/*", matches "foo/test.json"
Quoted 9 lines
Quoted 8 lines
+ (a regular file), "foo/bar" (a directory), but it does not match + "
foo/bar/hello.c" (a regular file), as the asterisk in the + pattern does not match "bar/hello.c" which has a slash in it. +
--------------------------------------------------------------$ git status [...]
Have you tried it out on any StackOverflow replies to see if those that inhabit that zone find it helpful? Philip
Quoted 9 lines · Philip Oakley
only one minor point...
Quoted 2 lines
Quoted 2 lines
+ - For example, a pattern
doc/frotz/matchesdoc/frotzdirectory,
+ but nota/doc/frotzdirectory; howeverfrotz/matchesfrotzher I misread this as: "but not a
doc/frotzdirectory;" i.e. the leading 'a' is too easy to skim over as is part of the sentence's prose, so maybe change to a 'baz' lead directory (bar already having been used below).
Yes we could change that.
Quoted 2 lines
Have you tried it out on any StackOverflow replies to see if those that inhabit that zone find it helpful? Philip
I answered one person who had a hard time reading the docs at SO, but he didn't respond and the last time he was online was 2018, so I didn't made the effort to edit my answer with the current version.
-
What are the next steps? If there are no more responses, does it imply that everyone agrees with this patch? Can we publish it online?
Quoted 16 lines · Dr. Adam Nielsen
Quoted 3 lines · Philip Oakley
only one minor point...
Quoted 1 line
Quoted 1 line
+ - For example, a pattern
doc/frotz/matchesdoc/frotzdirectory,
Quoted 5 lines
Quoted 1 line
Quoted 1 line
+ but not
a/doc/frotzdirectory; howeverfrotz/matchesfrotzher I misread this as: "but not a
doc/frotzdirectory;" i.e. the leading 'a' is too easy to skim over as is part of the sentence's prose, so maybe change to a 'baz' lead directory (baralready
Quoted 1 line
having been used below).
Yes we could change that.
Quoted 8 lines
Quoted 2 lines
Have you tried it out on any StackOverflow replies to see if those that inhabit that zone find it helpful? Philip
I answered one person who had a hard time reading the docs at SO, but he didn't respond and the last time he was online was 2018, so I didn't made the effort to edit my answer with the current version.
-
What are the next steps? If there are no more responses, does it imply that everyone agrees with this patch? Can we publish it online?
If all the issues are cleared then I believe it is a case of providing a clean reroll (maybe identical to previous..) to Junio and the list to confirm that all issues have been resolved and it is ready for pu->next->master in the normal way, which should then show up in his 'What's cooking' emails.
Oops, I missed Junio's message [1] while looking through my backlog. Sorry for the noise. Philip
Quoted 1 line · Philip Oakley
If all the issues are cleared then I believe it is a case of providing a clean reroll (maybe identical to previous..) to Junio and the list to confirm that all issues have been resolved and it is ready for
pu->next->masterin the normal way, which should then show up in his 'What's cooking' emails.
[1] <[email protected]>
Quoted 3 lines · Dr. Adam Nielsen
Hi everyone,
any comments about the patch note from 04.06 ?
https://git.kernel.org/pub/scm/git/git.git/log/ shows that the topic holding the patch has already been merged to the 'master' branch about 6 days ago, at
https://git.kernel.org/pub/scm/git/git.git/commit/?id=e694ea5e04ea2cabc64ade337063b5562810b268
Thanks.