Documentation: describe git-ls-files --exclude patterns.

Signed-off-by: Junio C Hamano <junkio@cox.net>

1 files changed, 92 insertions, 4 deletions

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index be83ab12fe..7ac6c7d84a 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -14,6 +14,7 @@ SYNOPSIS
 		(-[c|d|o|i|s|u|k])\*
 		[-x <pattern>|--exclude=<pattern>]
 		[-X <file>|--exclude-from=<file>]
+		[--exclude-per-directory=<file>]
 
 DESCRIPTION
 -----------
@@ -59,10 +60,10 @@ OPTIONS
 
 -X|--exclude-from=<file>::
 	exclude patterns are read from <file>; 1 per line.
-	Allows the use of the famous dontdiff file as follows to find
-	out about uncommitted files just as dontdiff is used with
-	the diff command:
-	     git-ls-files --others --exclude-from=dontdiff
+
+--exclude-per-directory=<file>::
+	read additional exclude patterns that apply only to the
+	directory and its subdirectories in <file>.
 
 -t::
 	Identify the file status with the following tags (followed by
@@ -89,6 +90,93 @@ the dircache records up to three such pairs; one from tree O in stage
 the user (or Cogito) to see what should eventually be recorded at the
 path. (see read-cache for more information on state)
 
+
+Exclude Patterns
+----------------
+
+'git-ls-files' can use a list of "exclude patterns" when
+traversing the directory tree and finding files to show when the
+flags --others or --ignored are specified.
+
+These exclude patterns come from these places:
+
+ (1) command line flag --exclude=<pattern> specifies a single
+     pattern.
+
+ (2) command line flag --exclude-from=<file> specifies a list of
+     patterns stored in a file.
+
+ (3) command line flag --exclude-per-directory=<name> specifies
+     a name of the file in each directory 'git-ls-files'
+     examines, and if exists, its contents are used as an
+     additional list of patterns.
+
+An exclude pattern file used by (2) and (3) contains one pattern
+per line.  A line that starts with a '#' can be used as comment
+for readability.
+
+The list of patterns that is in effect at a given time is
+built and ordered in the following way:
+
+ * --exclude=<pattern> and lines read from --exclude-from=<file>
+   come at the beginning of the list of patterns, in the order
+   given on the command line.  Patterns that come from the file
+   specified with --exclude-from are ordered in the same order
+   as they appear in the file.
+
+ * When --exclude-per-directory=<name> is specified, upon
+   entering a directory that has such a file, its contents are
+   appended at the end of the current "list of patterns".  They
+   are popped off when leaving the directory.
+
+Each pattern in the pattern list specifies "a match pattern" and
+optionally the fate --- either a file that matches the pattern
+is considered excluded or included.  By default, this being
+"exclude" mechanism, the fate is "excluded".  A filename is
+examined against the patterns in the list, and the first match
+determines its fate.
+
+A pattern specified on the command line with --exclude or read
+from the file specified with --exclude-from is relative to the
+top of the directory tree.  A pattern read from a file specified
+by --exclude-per-directory is relative to the directory that the
+pattern file appears in.
+
+An exclude pattern is of the following format:
+
+ - an optional prefix '!' which means that the fate this pattern
+   specifies is "include", not the usual "exclude"; the
+   remainder of the pattern string is interpreted according to
+   the following rules.
+
+ - if it does not contain a slash '/', it is a shell glob
+   pattern and used to match against the filename without
+   leading directories (i.e. the same way as the current
+   implementation).
+
+ - otherwise, it is a shell glob pattern, suitable for
+   consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
+   slash in the pattern must match a slash in the pathname.
+   "Documentation/*.html" matches "Documentation/git.html" but
+   not "ppc/ppc.html".  As a natural exception, "/*.c" matches
+   "cat-file.c" but not "mozilla-sha1/sha1.c".
+
+An example:
+
+    $ cat .git/ignore
+    # ignore objects and archives, anywhere in the tree.
+    *.[oa]
+    $ cat Documentation/.gitignore
+    # ignore generated html files,
+    # except foo.html which is maintained by hand
+    !foo.html
+    *.html
+    $ git-ls-files --ignored \
+        --exclude='Documentation/*.[0-9]' \
+        --exclude-from=.git/ignore \
+        --exclude-per-directory=.gitignore
+
+
 See Also
 --------
 link:read-cache.html[read-cache]