[PATCHv2] Documentation: enhance gitignore whitelist example

[Eric Blake <eblake@redhat.com>]

I was trying to whitelist a single file pattern in a directory
that I was otherwise content to ignore, but when I tried:

  /m4/
  !/m4/virt-*.m4

then 'git add' kept warning me that I had to use -f.  I finally
figured out that ignoring a directory is much different than ignoring
all files in a directory, when it comes to later negation patterns:

  /m4/*
  !/m4/virt-*.m4

Improving the documentation will help others learn from my mistake.

Signed-off-by: Eric Blake <eblake@redhat.com>
Acked-by: Jonathan Nieder <jrnieder@gmail.com>
CC: Johannes Sixt <j6t@kdbg.org>
---

v2: incorporate helpful comments from Junio

 Documentation/gitignore.txt |   25 +++++++++++++++++++++----
 1 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 2e7328b..0955931 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -70,7 +70,11 @@ PATTERN FORMAT
  - An optional prefix '!' which negates the pattern; any
    matching file excluded by a previous pattern will become
    included again.  If a negated pattern matches, this will
-   override lower precedence patterns sources.
+   override lower precedence patterns sources.  However, since
+   directory patterns prevent searching for any files below
+   that directory, if it is desirable to whitelist a single
+   file in a directory, you should first exclude all files in
+   the directory rather than the directory itself.

  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find
@@ -87,7 +91,8 @@ PATTERN FORMAT

  - Otherwise, git treats the pattern as a shell glob suitable
    for consumption by fnmatch(3) with the FNM_PATHNAME flag:
-   wildcards in the pattern will not match a / in the pathname.
+   wildcards in the pattern will not match a / in the pathname,
+   and do not ignore files with a leading . in the pathname.
    For example, "Documentation/{asterisk}.html" matches
    "Documentation/git.html" but not "Documentation/ppc/ppc.html"
    or "tools/perf/Documentation/perf.html".
@@ -116,8 +121,11 @@ EXAMPLES
     [...]
     # Untracked files:
     [...]
+    #       Documentation/build
     #       Documentation/foo.html
     #       Documentation/gitignore.html
+    #       build/log
+    #       build/.file
     #       file.o
     #       lib.a
     #       src/internal.o
@@ -125,19 +133,28 @@ EXAMPLES
     $ cat .git/info/exclude
     # ignore objects and archives, anywhere in the tree.
     *.[oa]
+    # ignore files in the immediate child directory build,...
+    /build/*
+    # ... except for the log.
+    !/build/log
     $ cat Documentation/.gitignore
-    # ignore generated html files,
+    # ignore generated html files,...
     *.html
-    # except foo.html which is maintained by hand
+    # ... except foo.html which is maintained by hand
     !foo.html
     $ git status
     [...]
     # Untracked files:
     [...]
+    #       Documentation/build
     #       Documentation/foo.html
+    #       build/log
     [...]
 --------------------------------------------------------------

+Note that using `!/build/log' works with an earlier `/build/*' but
+would have no effect if there were an earlier `/build/'.
+
 Another example:

 --------------------------------------------------------------
-- 
1.7.4