[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 11515 bytes --]

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@freedesktop.org>
---
 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@osdl.org>
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
 
 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Junio C Hamano]

Josh Triplett <josh@freedesktop.org> writes:

Thanks, but shouldn't all the in-text mention of "gitignore(5)"
and friends, not just in "See Also" section, use
"gitlink:gitignore[5]" instead?

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 346 bytes --]

Junio C Hamano wrote:
> Josh Triplett <josh@freedesktop.org> writes:
> 
> Thanks, but shouldn't all the in-text mention of "gitignore(5)"
> and friends, not just in "See Also" section, use
> "gitlink:gitignore[5]" instead?

Yes, thanks.  I followed some other example that didn't do that.

New patch momentarily.

- Josh Triplett



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 14302 bytes --]

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 and documentation.  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@freedesktop.org>
Signed-off-by: Josh Triplett <josh@freedesktop.org>
---
 Documentation/Makefile              |    2 +-
 Documentation/config.txt            |    3 +-
 Documentation/git-ls-files.txt      |   99 +++++-----------------------------
 Documentation/git-read-tree.txt     |    3 +-
 Documentation/git-status.txt        |    8 +--
 Documentation/gitignore.txt         |  100 +++++++++++++++++++++++++++++++++++
 Documentation/repository-layout.txt |    3 +-
 Documentation/user-manual.txt       |   12 ++--
 8 files changed, 129 insertions(+), 101 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/config.txt b/Documentation/config.txt
index 3d8f03d..bb4d6e0 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -259,7 +259,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
 core.excludeFile::
 	In addition to '.gitignore' (per-directory) and
 	'.git/info/exclude', git looks into this file for patterns
-	of files which are not meant to be tracked.
+	of files which are not meant to be tracked.  See
+	gitlink:gitignore[5].
 
 alias.*::
 	Command aliases for the gitlink:git[1] command wrapper - e.g.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 43e0d22..a78a9ff 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.  gitlink: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@osdl.org>
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
 
 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
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 0459bd9..15221b5 100644
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -155,8 +155,7 @@ info/exclude::
 	exclude pattern list. `.gitignore` is the per-directory
 	ignore file.  `git status`, `git add`, `git rm` and `git
 	clean` look at it but the core git commands do not look
-	at it.  See also: gitlink:git-ls-files[1] `--exclude-from`
-	and `--exclude-per-directory`.
+	at it.  See also: gitlink:gitignore[5].
 
 remotes::
 	Stores shorthands to be used to give URL and default
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 4fabb8e..7eaafa8 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc.
 
 Git therefore provides "exclude patterns" for telling git which files to
 actively ignore. Exclude patterns are thoroughly explained in the
-"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
-but the heart of the concept is simply a list of files which git should
-ignore. Entries in the list may contain globs to specify multiple files,
-or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
-excluded (ignored) file (i.e. later exclude patterns override earlier ones).
-The following example should illustrate such patterns:
+gitlink:gitignore[5] manual page, but the heart of the concept is simply
+a list of files which git should ignore. Entries in the list may contain
+globs to specify multiple files, or may be prefixed by "`!`" to
+explicitly include (un-ignore) a previously excluded (ignored) file
+(i.e. later exclude patterns override earlier ones).  The following
+example should illustrate such patterns:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
-- 
1.5.2



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Frank Lichtenheld]

Cool :)

Some remarks below.

On Fri, Jun 01, 2007 at 03:20:52PM -0700, Josh Triplett wrote:
> Signed-off-by: Josh Triplett <josh@freedesktop.org>
> Signed-off-by: Josh Triplett <josh@freedesktop.org>

:) (Wanted to make some funny remark, but its too late here to be funny
in a foreign language...)

>  Documentation
>  --------------
> -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
> +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.

No offence, but adding your name here for removing content? ;)

> +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.

Missing gitlink:

Also I don't like the paragraph. It should probably mention that
these programs actually implement the behaviour described, that
they aren't hardcoded to the mentioned filenames and that
all git porcelain just happens to call them with them.

But, as said, too late here for proper English ;)

> +Patterns have the following format:
> +
> + - A blank line matches no files, so it can serve as a separator
> +   for readability.
> +
> + - A line starting with # 

Is here missing something?

> + - 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".

I realise this is copy&paste but shouldn't that read:
"Documentation/\*.html" matches "Documentation/git.html"
but not "Documentation/ppc/ppc.html"
?

> +Documentation
> +-------------
> +Documentation by Josh Triplett.

No offence again, but given the amount of copy&paste, maybe the names from
git-ls-files should also be added here.

Gruesse,
-- 
Frank Lichtenheld <djpig@debian.org>
www: http://www.djpig.de/

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 2947 bytes --]

Frank Lichtenheld wrote:
> On Fri, Jun 01, 2007 at 03:20:52PM -0700, Josh Triplett wrote:
>> Signed-off-by: Josh Triplett <josh@freedesktop.org>
>> Signed-off-by: Josh Triplett <josh@freedesktop.org>
> 
> :) (Wanted to make some funny remark, but its too late here to be funny
> in a foreign language...)

Argh.  git-commit -s --amend signed a second time.  Sorry I missed this.

>>  Documentation
>>  --------------
>> -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
>> +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
> 
> No offence, but adding your name here for removing content? ;)

I intentionally avoided adding my name to the pages in which I only removed
content, or only added a reference to gitignore(5).  In the case of
git-ls-files, I rewrote some of the material.  However, I don't care that
strongly about the credit.

>> +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.
> 
> Missing gitlink:

Ah, good point.

> Also I don't like the paragraph. It should probably mention that
> these programs actually implement the behaviour described, that
> they aren't hardcoded to the mentioned filenames and that
> all git porcelain just happens to call them with them.

That seems like an implementation detail, only relevant to users of
git-ls-files and git-read-tree.

>> +Patterns have the following format:
>> +
>> + - A blank line matches no files, so it can serve as a separator
>> +   for readability.
>> +
>> + - A line starting with # 
> 
> Is here missing something?

Oops.  Yes, this should have said:

- A line starting with # serves as a comment.

>> + - 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".
> 
> I realise this is copy&paste but shouldn't that read:
> "Documentation/\*.html" matches "Documentation/git.html"
> but not "Documentation/ppc/ppc.html"
> ?

I don't know.  Neither file seems to exist in current Git.

>> +Documentation
>> +-------------
>> +Documentation by Josh Triplett.
> 
> No offence again, but given the amount of copy&paste, maybe the names from
> git-ls-files should also be added here.

Entirely correct; I don't know why I missed that, as I had intended to copy those
names. My apologies.

Expect an updated patch shortly, to fix the issues you pointed out.

- Josh Triplett


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 14580 bytes --]

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 and documentation.  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@freedesktop.org>
---

New version; fixes issues pointed out by Junio C Hamano and Frank Lichtenheld.

 Documentation/Makefile              |    2 +-
 Documentation/config.txt            |    3 +-
 Documentation/git-ls-files.txt      |   99 +++++-----------------------------
 Documentation/git-read-tree.txt     |    3 +-
 Documentation/git-status.txt        |    8 +--
 Documentation/gitignore.txt         |  102 +++++++++++++++++++++++++++++++++++
 Documentation/repository-layout.txt |    3 +-
 Documentation/user-manual.txt       |   12 ++--
 8 files changed, 131 insertions(+), 101 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/config.txt b/Documentation/config.txt
index 3d8f03d..bb4d6e0 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -259,7 +259,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
 core.excludeFile::
 	In addition to '.gitignore' (per-directory) and
 	'.git/info/exclude', git looks into this file for patterns
-	of files which are not meant to be tracked.
+	of files which are not meant to be tracked.  See
+	gitlink:gitignore[5].
 
 alias.*::
 	Command aliases for the gitlink:git[1] command wrapper - e.g.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 43e0d22..a78a9ff 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.  gitlink: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@osdl.org>
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
 
 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..c774ff0
--- /dev/null
+++ b/Documentation/gitignore.txt
@@ -0,0 +1,102 @@
+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.
+
+The underlying git plumbing tools, such as
+gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
+`gitignore` patterns specified by command-line options, or from
+files specified by command-line options.  Higher-level git
+tools, such as gitlink:git-status[1] and gitlink:git-add[1],
+use patterns from the sources specified above.
+
+Patterns have the following format:
+
+ - A blank line matches no files, so it can serve as a separator
+   for readability.
+
+ - A line starting with # serves as a comment.
+
+ - 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 David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 0459bd9..15221b5 100644
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -155,8 +155,7 @@ info/exclude::
 	exclude pattern list. `.gitignore` is the per-directory
 	ignore file.  `git status`, `git add`, `git rm` and `git
 	clean` look at it but the core git commands do not look
-	at it.  See also: gitlink:git-ls-files[1] `--exclude-from`
-	and `--exclude-per-directory`.
+	at it.  See also: gitlink:gitignore[5].
 
 remotes::
 	Stores shorthands to be used to give URL and default
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 4fabb8e..7eaafa8 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc.
 
 Git therefore provides "exclude patterns" for telling git which files to
 actively ignore. Exclude patterns are thoroughly explained in the
-"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
-but the heart of the concept is simply a list of files which git should
-ignore. Entries in the list may contain globs to specify multiple files,
-or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
-excluded (ignored) file (i.e. later exclude patterns override earlier ones).
-The following example should illustrate such patterns:
+gitlink:gitignore[5] manual page, but the heart of the concept is simply
+a list of files which git should ignore. Entries in the list may contain
+globs to specify multiple files, or may be prefixed by "`!`" to
+explicitly include (un-ignore) a previously excluded (ignored) file
+(i.e. later exclude patterns override earlier ones).  The following
+example should illustrate such patterns:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
-- 
1.5.2



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Frank Lichtenheld]

On Fri, Jun 01, 2007 at 05:52:53PM -0700, Josh Triplett wrote:
> Frank Lichtenheld wrote:
> > On Fri, Jun 01, 2007 at 03:20:52PM -0700, Josh Triplett wrote:
> >> + - 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".
> > 
> > I realise this is copy&paste but shouldn't that read:
> > "Documentation/\*.html" matches "Documentation/git.html"
> > but not "Documentation/ppc/ppc.html"
> > ?
> 
> I don't know.  Neither file seems to exist in current Git.

The point I was trying to make is that "Documentation/*.html" _of
course_ doesn't match ppc/ppc.html. What we try to tell the user here
is that * doesn't match /
So I think it should definetly read Documentation/ppc/ppc.html
FWIW, I find the sentence
"any slash in the pattern must match a slash in the pathname"
very confusing too. The sentence in fnmatch(3) is much more precise:
"match a slash in string only with a slash in pattern and not by an
asterisk (*) or a question mark (?) metacharacter, nor by a bracket
expression ([]) containing a slash"

Anyway, if you prefer (and if it is okay with Junio) I can send a
patch of my own for this single issue to not hinder the commit of
your big patch as the issue is equally present in the old and the
new text.

Gruesse,
-- 
Frank Lichtenheld <djpig@debian.org>
www: http://www.djpig.de/

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 1912 bytes --]

Frank Lichtenheld wrote:
> On Fri, Jun 01, 2007 at 05:52:53PM -0700, Josh Triplett wrote:
>> Frank Lichtenheld wrote:
>>> On Fri, Jun 01, 2007 at 03:20:52PM -0700, Josh Triplett wrote:
>>>> + - 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".
>>> I realise this is copy&paste but shouldn't that read:
>>> "Documentation/\*.html" matches "Documentation/git.html"
>>> but not "Documentation/ppc/ppc.html"
>>> ?
>> I don't know.  Neither file seems to exist in current Git.
> 
> The point I was trying to make is that "Documentation/*.html" _of
> course_ doesn't match ppc/ppc.html. What we try to tell the user here
> is that * doesn't match /
> So I think it should definetly read Documentation/ppc/ppc.html

Ah, I understand your point now.

> FWIW, I find the sentence
> "any slash in the pattern must match a slash in the pathname"
> very confusing too. The sentence in fnmatch(3) is much more precise:
> "match a slash in string only with a slash in pattern and not by an
> asterisk (*) or a question mark (?) metacharacter, nor by a bracket
> expression ([]) containing a slash"

I like that better as well.

> Anyway, if you prefer (and if it is okay with Junio) I can send a
> patch of my own for this single issue to not hinder the commit of
> your big patch as the issue is equally present in the old and the
> new text.

Now that I understand the issue you raised, I can easily fix it and
send a revised patch.  Expect one momentarily.

- Josh Triplett


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Josh Triplett]

[-- Attachment #1: Type: text/plain, Size: 14957 bytes --]

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 and documentation.  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@freedesktop.org>
---

In this new version, I've modified the explanation and example for patterns
containing a slash based on additional comments by Frank Lichtenheld.

I also updated the first example in gitignore(5) to use git-status rather than
git-ls-files.

 Documentation/Makefile              |    2 +-
 Documentation/config.txt            |    3 +-
 Documentation/git-ls-files.txt      |   99 ++++-------------------------
 Documentation/git-read-tree.txt     |    3 +-
 Documentation/git-status.txt        |    8 +--
 Documentation/gitignore.txt         |  116 +++++++++++++++++++++++++++++++++++
 Documentation/repository-layout.txt |    3 +-
 Documentation/user-manual.txt       |   12 ++--
 8 files changed, 145 insertions(+), 101 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/config.txt b/Documentation/config.txt
index 3d8f03d..bb4d6e0 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -259,7 +259,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
 core.excludeFile::
 	In addition to '.gitignore' (per-directory) and
 	'.git/info/exclude', git looks into this file for patterns
-	of files which are not meant to be tracked.
+	of files which are not meant to be tracked.  See
+	gitlink:gitignore[5].
 
 alias.*::
 	Command aliases for the gitlink:git[1] command wrapper - e.g.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 43e0d22..a78a9ff 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.  gitlink: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@osdl.org>
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
 
 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..ea79d74
--- /dev/null
+++ b/Documentation/gitignore.txt
@@ -0,0 +1,116 @@
+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.
+
+The underlying git plumbing tools, such as
+gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
+`gitignore` patterns specified by command-line options, or from
+files specified by command-line options.  Higher-level git
+tools, such as gitlink:git-status[1] and gitlink:git-add[1],
+use patterns from the sources specified above.
+
+Patterns have the following format:
+
+ - A blank line matches no files, so it can serve as a separator
+   for readability.
+
+ - A line starting with # serves as a comment.
+
+ - 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:
+   wildcards in the pattern will not match a / in the pathname.
+   For example, "Documentation/\*.html" matches
+   "Documentation/git.html" but not
+   "Documentation/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:
+
+--------------------------------------------------------------
+    $ git-status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/foo.html
+    #       Documentation/gitignore.html
+    #       file.o
+    #       lib.a
+    #       src/internal.o
+    [...]
+    $ 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-status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/foo.html
+    [...]
+--------------------------------------------------------------
+
+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 David Greaves, Junio C Hamano, Josh Triplett,
+Frank Lichtenheld, and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 0459bd9..15221b5 100644
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -155,8 +155,7 @@ info/exclude::
 	exclude pattern list. `.gitignore` is the per-directory
 	ignore file.  `git status`, `git add`, `git rm` and `git
 	clean` look at it but the core git commands do not look
-	at it.  See also: gitlink:git-ls-files[1] `--exclude-from`
-	and `--exclude-per-directory`.
+	at it.  See also: gitlink:gitignore[5].
 
 remotes::
 	Stores shorthands to be used to give URL and default
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 4fabb8e..7eaafa8 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc.
 
 Git therefore provides "exclude patterns" for telling git which files to
 actively ignore. Exclude patterns are thoroughly explained in the
-"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
-but the heart of the concept is simply a list of files which git should
-ignore. Entries in the list may contain globs to specify multiple files,
-or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
-excluded (ignored) file (i.e. later exclude patterns override earlier ones).
-The following example should illustrate such patterns:
+gitlink:gitignore[5] manual page, but the heart of the concept is simply
+a list of files which git should ignore. Entries in the list may contain
+globs to specify multiple files, or may be prefixed by "`!`" to
+explicitly include (un-ignore) a previously excluded (ignored) file
+(i.e. later exclude patterns override earlier ones).  The following
+example should illustrate such patterns:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
-- 
1.5.2



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere

[Junio C Hamano]

Josh Triplett <josh@freedesktop.org> writes:

> Now that I understand the issue you raised, I can easily fix it and
> send a revised patch.  Expect one momentarily.

Thanks both.  Yes the original description showed my
incompetence in wording.