[PATCHv3 1/2] Documentation: clarify fnmatch...

[PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore

From: Eric Blake <hidden>
Date: 2016-06-15 22:50:59

Make it clear that in a .gitignore file,

  *ignore

matches (and therefore excludes) `.gitignore', even though the
same glob does not match in the shell.

Signed-off-by: Eric Blake <redacted>
---

v3: separate fnmatch wording cleanup into its own patch

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

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 2e7328b..9b1e5e1 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt

@@ -86,9 +86,10 @@ PATTERN FORMAT
    `.gitignore` file).

  - 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.
-   For example, "Documentation/{asterisk}.html" matches
+   for consumption by fnmatch(3) with the FNM_PATHNAME but not
+   FNM_PERIOD flags: wildcards in the pattern will match leading
+   . but not / in pathnames.  For example,
+   "Documentation/{asterisk}.html" matches "Documentation/.html" and
    "Documentation/git.html" but not "Documentation/ppc/ppc.html"
    or "tools/perf/Documentation/perf.html".

-- 
1.7.4

[PATCHv3 2/2] Documentation: enhance gitignore whitelist example

From: Eric Blake <hidden>
Date: 2016-06-15 22:50:59

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.

CC: Jonathan Nieder <redacted>
CC: Johannes Sixt <redacted>
Signed-off-by: Eric Blake <redacted>
---

v3: split out fnmatch tweaks, don't tweak specification of patterns
or existing examples but instead add an entirely new example, make
the example use a deeper hierarchy

 Documentation/gitignore.txt |   38 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 38 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 9b1e5e1..e1ad234 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt

@@ -139,6 +139,44 @@ EXAMPLES
     [...]
 --------------------------------------------------------------

+It is possible to ignore most of a hierarchy, while still
+white-listing a single file, by ignoring multiple files then using a
+negation pattern for the file in question.  However, this requires
+ignoring files and not directories, since no patterns are ever matched
+inside of an ignored directory.  For nested files, it requires several
+iterations of refined patterns.
+
+--------------------------------------------------------------
+    $ git status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/build/file
+    #       build/file
+    #       build/foo/baz
+    #       build/foo/other
+    [...]
+    $ cat .gitignore
+    # Use anchoring, since `build' would ignore Documentation/build.
+    # Do not ignore the directory itself, ...
+    # /build/
+    # rather ignore files in the top-level build directory, ...
+    /build/*
+    # but permit child directories, ...
+    !/build/*/
+    # then ignore all nested files, ...
+    /build/*/*
+    # and finally white-list the special file
+    !/build/foo/baz
+    $ git status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/build/file
+    #       build/foo/baz
+    [...]
+--------------------------------------------------------------
+
 Another example:

 --------------------------------------------------------------

-- 
1.7.4

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help