gitignore.txt: make slash-rules more readable
Remove meta-rule in a paragraph for trailing-slash.
Be precise whenever a trailing slash would make a
difference. Improve paragraph for pattern without slash.
Remove rule for leading slash because its now redundant.
Instead, add examples for leading slash and asterix in
example section.
Signed-off-by: Dr. Adam Nielsen <admin@xxxxxxxxxx>
---
Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
1 file changed, 50 insertions(+), 21 deletions(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..a6c7807c74 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,32 @@ 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.
+
+ - The pattern is matched relative to the location of
+ the `.gitignore` file. Except if the pattern contains
+ no slash (or no slash but a trailing slash), then the pattern is
+ matched against all files and folders (recursively)
+ from the location of the `.gitignore` file.
+ For example, `doc/frotz/` matches `doc/frotz` directory, but not
+ a/doc/frotz`; 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 +156,31 @@ To stop tracking a file that is currently tracked, use
EXAMPLES
--------
+ - The pattern `/bar` only matches the file or folder `bar`
+ but not `a/bar`, whereas the pattern `bar` would match both
+ (relative to the `.gitignore` file). That is because the
+ pattern `/bar` contains a non-trailing slash and thus matches
+ relative to the location of the `.gitignore` file.
+ Since `bar` has no slash, it matches recursively.
+
+ - The pattern 'hello.*' is not sufficient for the following rule:
+ "ignore any file whose name begins with 'hello' and in this
+ directory only, not in its subdirectories." because the pattern
+ 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'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+ in any `.gitignore` file. Both pattern contain a non-trailing
+ slash and thus match relative to the location of the
+ `.gitignore` file.
+
+ - The pattern "foo/*", 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.
+
--------------------------------------------------------------
$ git status
[...]
--
2.17.1
