Only git-ls-files(1) describes the gitignore format in detail, and it does so
with reference to git-ls-files options. Most users don't use the plumbing
command git-ls-files directly, and shouldn't have to look in its manpage for
information on the gitignore format.
Create a new manpage gitignore(5) (Documentation/gitignore.txt), and factor
out the gitignore documentation into that file, changing it to refer to
.gitignore and $GIT_DIR/info/exclude as used by porcelain commands. Reference
gitignore(5) from other relevant manpages. Remove now-redundant information
on exclude patterns from git-ls-files(1), leaving only information on how
git-ls-files options specify exclude patterns and what precedence they have.
Signed-off-by: Josh Triplett <josh@xxxxxxxxxxxxxxx>
---
Documentation/Makefile | 2 +-
Documentation/git-ls-files.txt | 99 +++++---------------------------------
Documentation/git-read-tree.txt | 3 +-
Documentation/git-status.txt | 8 +--
Documentation/gitignore.txt | 100 +++++++++++++++++++++++++++++++++++++++
5 files changed, 120 insertions(+), 92 deletions(-)
create mode 100644 Documentation/gitignore.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3f92783..ef4425c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -2,7 +2,7 @@ MAN1_TXT= \
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
$(wildcard git-*.txt)) \
gitk.txt
-MAN5_TXT=gitattributes.txt
+MAN5_TXT=gitattributes.txt gitignore.txt
MAN7_TXT=git.txt
DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 43e0d22..62d8739 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -139,46 +139,24 @@ 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.
+flags --others or --ignored are specified. gitignore(5)
+specifies the format of exclude patterns.
-These exclude patterns come from these places:
+These exclude patterns come from these places, in order:
- 1. command line flag --exclude=<pattern> specifies a single
- pattern.
+ 1. The command line flag --exclude=<pattern> specifies a
+ single pattern. Patterns are ordered in the same order
+ they appear in the command line.
- 2. command line flag --exclude-from=<file> specifies a list of
- patterns stored in a file.
+ 2. The command line flag --exclude-from=<file> specifies a
+ file containing a list of patterns. Patterns are ordered
+ in the same order they appear in the 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.
-
-There are three lists of patterns that are in effect at a given
-time. They are built and ordered in the following way:
-
- * --exclude=<pattern> from the command line; patterns are
- ordered in the same order as they appear on the command line.
-
- * lines read from --exclude-from=<file>; patterns 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. A filename is matched against
-the patterns in the three lists; the --exclude-from list is
-checked first, then the --exclude-per-directory list, and then
-finally the --exclude list. The last match determines its fate.
-If there is no match in the three lists, the fate is "included".
+ examines, normally `.gitignore`. Files in deeper
+ directories take precedence. Patterns are ordered in the
+ same order they appear in the files.
A pattern specified on the command line with --exclude or read
from the file specified with --exclude-from is relative to the
@@ -186,58 +164,9 @@ 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.
-
- - 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/info/exclude
- # ignore objects and archives, anywhere in the tree.
- *.[oa]
- $ cat Documentation/.gitignore
- # ignore generated html files,
- *.html
- # except foo.html which is maintained by hand
- !foo.html
- $ git-ls-files --ignored \
- --exclude='Documentation/*.[0-9]' \
- --exclude-from=.git/info/exclude \
- --exclude-per-directory=.gitignore
---------------------------------------------------------------
-
-Another example:
-
---------------------------------------------------------------
- $ cat .gitignore
- vmlinux*
- $ ls arch/foo/kernel/vm*
- arch/foo/kernel/vmlinux.lds.S
- $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
---------------------------------------------------------------
-
-The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file
-from getting ignored.
-
-
See Also
--------
-gitlink:git-read-tree[1]
+gitlink:git-read-tree[1], gitlink:gitignore[5]
Author
@@ -246,7 +175,7 @@ Written by Linus Torvalds <torvalds@xxxxxxxx>
Documentation
--------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@xxxxxxxxxxxxxxx>.
+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@xxxxxxxxxxxxxxx>.
GIT
---
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 019c8be..acb5744 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -341,7 +341,8 @@ have finished your work-in-progress), attempt the merge again.
See Also
--------
-gitlink:git-write-tree[1]; gitlink:git-ls-files[1]
+gitlink:git-write-tree[1]; gitlink:git-ls-files[1];
+gitlink:gitignore[5]
Author
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index d701538..1fd1af1 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward
compatibility) and `color.status.<slot>` configuration variables
to colorize its output.
-As for gitlink:git-add[1], the configuration variable
-'core.excludesfile' can indicate a path to a file containing patterns
-of file names to exclude, in addition to patterns given in
-'info/exclude' and '.gitignore'.
-
+See Also
+--------
+gitlink:gitignore[5]
Author
------
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
new file mode 100644
index 0000000..190bd9f
--- /dev/null
+++ b/Documentation/gitignore.txt
@@ -0,0 +1,100 @@
+gitignore(5)
+============
+
+NAME
+----
+gitignore - Specifies intentionally untracked files to ignore
+
+SYNOPSIS
+--------
+$GIT_DIR/info/exclude, .gitignore
+
+DESCRIPTION
+-----------
+
+A `gitignore` file specifies intentionally untracked files that
+git should ignore. Each line in a `gitignore` file specifies a
+pattern.
+
+When deciding whether to ignore a path, git normally checks
+`gitignore` patterns from multiple sources, with the following
+order of precedence:
+
+ * Patterns read from the file specified by the configuration
+ variable 'core.excludesfile'.
+
+ * Patterns read from `$GIT_DIR/info/exclude`.
+
+ * Patterns read from a `.gitignore` file in the same directory
+ as the path, or in any parent directory, ordered from the
+ deepest such file to a file in the root of the repository.
+ These patterns match relative to the location of the
+ `.gitignore` file. A project normally includes such
+ `.gitignore` files in its repository, containing patterns for
+ files generated as part of the project build.
+
+Some git plumbing tools, such as git-ls-files(1) and
+git-read-tree(1), read `gitignore` patterns specified by
+command-line options, or from files specified by command-line
+options.
+
+Patterns have the following format:
+
+ - A blank line matches no files, so it can serve as a separator
+ for readability.
+
+ - A line starting with #
+
+ - An optional prefix '!' which negates the pattern; any
+ matching file excluded by a previous pattern will become
+ included again.
+
+ - If the pattern does not contain a slash '/', git treats it as
+ a shell glob pattern and checks for a match against the
+ pathname without leading directories.
+
+ - Otherwise, git treats the pattern as a shell glob suitable
+ for consumption by fnmatch(3) with the FNM_PATHNAME flag: any
+ slash in the pattern must match a slash in the pathname. For
+ example, "Documentation/\*.html" matches
+ "Documentation/git.html" but not "ppc/ppc.html". A leading
+ slash matches the beginning of the pathname; for example,
+ "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".
+
+An example:
+
+--------------------------------------------------------------
+ $ cat .git/info/exclude
+ # ignore objects and archives, anywhere in the tree.
+ *.[oa]
+ $ cat Documentation/.gitignore
+ # ignore generated html files,
+ *.html
+ # except foo.html which is maintained by hand
+ !foo.html
+ $ git-ls-files --ignored \
+ --exclude='Documentation/*.[0-9]' \
+ --exclude-from=.git/info/exclude \
+ --exclude-per-directory=.gitignore
+--------------------------------------------------------------
+
+Another example:
+
+--------------------------------------------------------------
+ $ cat .gitignore
+ vmlinux*
+ $ ls arch/foo/kernel/vm*
+ arch/foo/kernel/vmlinux.lds.S
+ $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
+--------------------------------------------------------------
+
+The second .gitignore prevents git from ignoring
+`arch/foo/kernel/vmlinux.lds.S`.
+
+Documentation
+-------------
+Documentation by Josh Triplett.
+
+GIT
+---
+Part of the gitlink:git[7] suite
--
1.5.2
Attachment:
signature.asc
Description: OpenPGP digital signature
