Skip to contentSkip to conversation

make slash-rules more readable

PATCH In review Dr. Adam Nielsen 3 participants 7 messages Jun 4, 2019 – Jul 4, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

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
index b5bc9dbff0..d47b1ae296 100644
@@ -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
#1 lore raw

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.

---
  Documentation/gitignore.txt | 66 ++++++++++++++++++++++++-------------
  1 file changed, 44 insertions(+), 22 deletions(-)
Documentation/gitignore.txt +44 -22
index b5bc9dbff0..d47b1ae296 100644
@@ -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>
#2 lore raw

only one minor point...

Quoted 56 lines · Dr. Adam Nielsen

Hi everyone,

any comments about the patch note from 04.06 ?

All the best,
Adam

Quoted 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.

---
  Documentation/gitignore.txt | 66 ++++++++++++++++++++++++-------------

  1 file changed, 44 insertions(+), 22 deletions(-)
Documentation/gitignore.txt +0 -0
index b5bc9dbff0..d47b1ae296 100644
@@ -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).

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` 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

Quoted 8 lines

Documentation/gitignore.txt PATTERN FORMAT · line 105

Quoted 8 lines

+   match at any level below the .gitignore level.

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/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:

Documentation/gitignore.txt +0 -0
@@ -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.

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

#3 lore raw
Quoted 9 lines · Philip Oakley

only one minor point...

Quoted 2 lines
Quoted 2 lines

+ - 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.

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?

#4 lore raw
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/ matches doc/frotz

directory,

Quoted 5 lines
Quoted 1 line
Quoted 1 line

+   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

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.

#5 lore raw

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->master in the normal way, which should then show up in his 'What's cooking' emails.

[1] <[email protected]>