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 <admin@in-ici.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Dr. Adam Nielsen committed
Jun 4, 2019 at 19:34 UTC
1a58bad0144dedd59eeef29b7ba7791aed19106f
1 file changed
+44
-22
Documentation/gitignore.txt
+44
-22
@@ -89,28 +89,28 @@ PATTERN FORMAT
89
Put a backslash ("`\`") in front of the first "`!`" for patterns
90
that begin with a literal "`!`", for example, "`\!important!.txt`".
91
92
- - If the pattern ends with a slash, it is removed for the
93
- purpose of the following description, but it would only find
94
- a match with a directory. In other words, `foo/` will match a
95
- directory `foo` and paths underneath it, but will not match a
96
- regular file or a symbolic link `foo` (this is consistent
97
- with the way how pathspec works in general in Git).
98
-
99
- - If the pattern does not contain a slash '/', Git treats it as
100
- a shell glob pattern and checks for a match against the
101
- pathname relative to the location of the `.gitignore` file
102
- (relative to the toplevel of the work tree if not from a
103
- `.gitignore` file).
104
-
105
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
106
- anything except "`/`", "`?`" matches any one character except "`/`"
107
- and "`[]`" matches one character in a selected range. See
108
- fnmatch(3) and the FNM_PATHNAME flag for a more detailed
109
- description.
110
-
111
- - A leading slash matches the beginning of the pathname.
112
- For example, "/{asterisk}.c" matches "cat-file.c" but not
113
- "mozilla-sha1/sha1.c".
92
+ - The slash '/' is used as the directory separator. Separators may
93
+ occur at the beginning, middle or end of the `.gitignore` search pattern.
94
+
95
+ - If there is a separator at the beginning or middle (or both) of the
96
+ pattern, then the pattern is relative to the directory level of the
97
+ particular `.gitignore` file itself. Otherwise the pattern may also
98
+ match at any level below the `.gitignore` level.
99
+
100
+ - If there is a separator at the end of the pattern then the pattern
101
+ will only match directories, otherwise the pattern can match both
102
+ files and directories.
103
+
104
+ - For example, a pattern `doc/frotz/` matches `doc/frotz` directory,
105
+ but not `a/doc/frotz` directory; however `frotz/` matches `frotz`
106
+ and `a/frotz` that is a directory (all paths are relative from
107
+ the `.gitignore` file).
108
+
109
+ - An asterisk "`*`" matches anything except a slash.
110
+ The character "`?`" matches any one character except "`/`".
111
+ The range notation, e.g. `[a-zA-Z]`, can be used to match
112
+ one of the characters in a range. See fnmatch(3) and the
113
+ FNM_PATHNAME flag for a more detailed description.
114
115
Two consecutive asterisks ("`**`") in patterns matched against
116
full pathname may have special meaning:
@@ -144,6 +144,28 @@ To stop tracking a file that is currently tracked, use
144
EXAMPLES
145
--------
146
147
+ - The pattern `hello.*` matches any file or folder
148
+ whose name begins with `hello`. If one wants to restrict
149
+ this only to the directory and not in its subdirectories,
150
+ one can prepend the pattern with a slash, i.e. `/hello.*`;
151
+ the pattern now matches `hello.txt`, `hello.c` but not
152
+ `a/hello.java`.
153
+
154
+ - The pattern `foo/` will match a directory `foo` and
155
+ paths underneath it, but will not match a regular file
156
+ or a symbolic link `foo` (this is consistent with the
157
+ way how pathspec works in general in Git)
158
+
159
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
160
+ in any `.gitignore` file. In other words, a leading slash
161
+ is not relevant if there is already a middle slash in
162
+ the pattern.
163
+
164
+ - The pattern "foo/*", matches "foo/test.json"
165
+ (a regular file), "foo/bar" (a directory), but it does not match
166
+ "foo/bar/hello.c" (a regular file), as the asterisk in the
167
+ pattern does not match "bar/hello.c" which has a slash in it.
168
+
169
--------------------------------------------------------------
170
$ git status
171
[...]