From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 25 Jul 2019 21:27:13 +0000 (-0700)
Subject: Merge branch 'an/ignore-doc-update' into maint
X-Git-Tag: v2.23.0-rc0~6^2~8
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/167d02aa5841cfc820c668efb3cb9d382c311767?hp=-c

Merge branch 'an/ignore-doc-update' into maint

The description about slashes in gitignore patterns (used to
indicate things like "anchored to this level only" and "only
matches directories") has been revamped.

* an/ignore-doc-update:
gitignore.txt: make slash-rules more readable
---

167d02aa5841cfc820c668efb3cb9d382c311767
diff --combined Documentation/gitignore.txt
index b5bc9dbff0,7dff340e4e..d47b1ae296
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@@ -89,28 -89,28 +89,28 @@@ PATTERN FORMA
     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:
@@@ -132,14 -132,6 +132,14 @@@
   - Other consecutive asterisks are considered regular asterisks and
     will match according to the previous rules.
  
 +CONFIGURATION
 +-------------
 +
 +The optional configuration variable `core.excludesFile` indicates a path to a
 +file containing patterns of file names to exclude, similar to
 +`$GIT_DIR/info/exclude`.  Patterns in the exclude file are used in addition to
 +those in `$GIT_DIR/info/exclude`.
 +
  NOTES
  -----
  
@@@ -152,6 -144,28 +152,28 @@@ To stop tracking a file that is current
  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
      [...]