# [PATCH] make slash-rules more readable 7 messages from 2019-06-04 to 2019-07-04. Participants: Dr. Adam Nielsen, Philip Oakley, Junio C Hamano. Thread: https://gitlist.dev/t/51239 ## Dr. Adam Nielsen, 2019-06-04 17:34 Subject: [PATCH] make slash-rules more readable Message-ID: <20190604173446.2664-1-admin@in-ici.net> URL: https://gitlist.dev/e/20190604173446.2664-1-admin%40in-ici.net ``` 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 --- Documentation/gitignore.txt | 66 ++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index b5bc9dbff0..d47b1ae296 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -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 [...] -- 2.17.1 ``` ## Dr. Adam Nielsen, 2019-06-25 11:05 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/bd722415-1547-8db5-f88a-c35c8b48d8be%40in-ici.net In-Reply-To: <20190604173446.2664-1-admin@in-ici.net> ``` Hi everyone, any comments about the patch note from 04.06 ? All the best, Adam On 04.06.19 19:34, Dr. Adam Nielsen wrote: > 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 > > --- > Documentation/gitignore.txt | 66 ++++++++++++++++++++++++------------- > 1 file changed, 44 insertions(+), 22 deletions(-) > > diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt > index b5bc9dbff0..d47b1ae296 100644 > --- a/Documentation/gitignore.txt > +++ b/Documentation/gitignore.txt > @@ -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 > [...] > -- photograph *Dr. Adam Nielsen * Administrator | IN/ICI/WHO *IN:* nlp-institutes.net *ICI:* coaching-institutes.net *WHO:* world-hypnosis.org ``` ## Philip Oakley, 2019-06-25 11:31 Subject: Re: [PATCH] make slash-rules more readable Message-ID: <13f99ce6-f856-6554-5c14-1b1838d697d0@iee.org> URL: https://gitlist.dev/e/13f99ce6-f856-6554-5c14-1b1838d697d0%40iee.org In-Reply-To: ``` only one minor point... On 25/06/2019 12:05, Dr. Adam Nielsen wrote: > Hi everyone, > > any comments about the patch note from 04.06 ? > > All the best, > Adam > > On 04.06.19 19:34, Dr. Adam Nielsen wrote: >> 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 >> >> --- >>   Documentation/gitignore.txt | 66 ++++++++++++++++++++++++------------- >>   1 file changed, 44 insertions(+), 22 deletions(-) >> >> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt >> index b5bc9dbff0..d47b1ae296 100644 >> --- a/Documentation/gitignore.txt >> +++ b/Documentation/gitignore.txt >> @@ -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` 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). >> +   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 >>       [...] >> > Have you tried it out on any StackOverflow replies to see if those that inhabit that zone find it helpful? Philip ``` ## Dr. Adam Nielsen, 2019-06-27 17:10 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/d1d2ebec-a94a-0092-4a6d-8ae32db1573b%40in-ici.net In-Reply-To: <13f99ce6-f856-6554-5c14-1b1838d697d0@iee.org> ``` On 25.06.19 13:31, Philip Oakley wrote: > only one minor point... >>> + - 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). Yes we could change that. > 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? ``` ## Junio C Hamano, 2019-06-27 17:43 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/xmqqd0iyc4av.fsf%40gitster-ct.c.googlers.com In-Reply-To: ``` "Dr. Adam Nielsen" writes: > 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. ``` ## Philip Oakley, 2019-07-04 10:40 Subject: Re: [PATCH] make slash-rules more readable Message-ID: URL: https://gitlist.dev/e/b33e42c2-96a7-88d8-03b1-2da317dfa692%40iee.org In-Reply-To: ``` On 27/06/2019 18:10, Dr. Adam Nielsen wrote: > > On 25.06.19 13:31, Philip Oakley wrote: >> only one minor point... > > >>> + - 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). > > Yes we could change that. > >> 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. ``` ## Philip Oakley, 2019-07-04 10:46 Subject: Re: [PATCH] make slash-rules more readable Message-ID: <1104adb4-dd84-9e87-3c95-70a0088eadb0@iee.org> URL: https://gitlist.dev/e/1104adb4-dd84-9e87-3c95-70a0088eadb0%40iee.org In-Reply-To: ``` Oops, I missed Junio's message [1] while looking through my backlog. Sorry for the noise. Philip On 04/07/2019 11:40, Philip Oakley wrote: > 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. [1] ```