[PATCH] user-manual: Add section on ignoring files

[Johan Herland <johan@herland.net>]

The todo list at the end of the user manual says that something must be
said about .gitignore. Also, there seems to be a lack of documentation
on how to choose between the various types of ignore files (.gitignore
vs. .git/info/exclude, etc.).

This patch adds a section on ignoring files which try to introduce how
to tell git about ignored files, and how the different strategies
complement eachother.

The syntax of exclude patterns is explained in a simplified manner, with
a reference to git-ls-files(1) which already contains a more thorough
explanation.

Signed-off-by: Johan Herland <johan@herland.net>
---
Writing this section was triggered by Randal L. Schwartz on #git lamenting
the lack of documentation on the difference between .gitignore and
.git/info/exclude. Hope this is what you're looking for, Randal. :)

 Documentation/user-manual.txt |   69 +++++++++++++++++++++++++++++++++++++++-
 1 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a7abeaa..4ca30dd 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1188,6 +1188,73 @@ description.  Tools that turn commits into email, for example, use
 the first line on the Subject line and the rest of the commit in the
 body.
 
+[[ignoring-files]]
+Ignoring files
+--------------
+
+A project will often generate files that you do 'not' want to track with git.
+This typically includes files generated by a build process or temporary
+backup files made by your editor. Of course, 'not' tracking files with git
+is just a matter of 'not' calling "git add" on them. But it might be
+annoying to have these untracked files automatically showing up in the
+output of "git status", in the commit message template, 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 file.
+The following example should illustrate such patterns:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]
+-------------------------------------------------
+
+The next question is where to put these exclude patterns so that git can
+find them. Git looks for exclude patterns in the following files:
+
+`.gitignore` files in your working tree:::
+	   You may store multiple `.gitignore` files at various locations in your
+	   working tree. Each `.gitignore` file is applied to the directory where
+	   it's located, including its subdirectories. Furthermore, the
+	   `.gitignore` files can be tracked like any other files in your working
+	   tree; just do a `git add .gitignore` and commit. `.gitignore` is
+	   therefore the perfect place to put exclude patterns that match
+	   ignored files that pop up in every copy of your project, such as
+	   build output files (e.g. `\*.o`), etc.
+`.git/info/exclude` in your repo:::
+	   Exclude patterns in this file are applied to the working tree as a
+	   whole. Since the file is not located in your working tree, it does
+	   not follow push/pull/clone like `.gitignore` can do. This is therefore
+	   the best place to put exclude patterns that you want to keep local
+	   to your copy of the repo, such as temporary backups made by your
+	   editor (e.g. `\*~`), etc.
+The file specified by the `core.excludesfile` config directive:::
+	   By setting the `core.excludesfile` config directive you can tell git
+	   where to find more exclude patterns (see gitlink:git-config[1] for
+	   more information on configuration options). This config directive
+	   can be set in the per-repo `.git/config` file, in which case the
+	   exclude patterns will apply to that repo only. Alternatively, you
+	   can set the directive in the global `~/.gitconfig` file to apply
+	   the exclude pattern to all your git repos. As with the above
+	   `.git/info/exclude` (and, indeed, with git config directives in
+	   general), this directive does not follow push/pull/clone, but stays
+	   local to your repo(s).
+
+[NOTE]
+In addition to the above alternatives, there are git commands that can take
+exclude patterns directly on the command line. See gitlink:git-ls-files[1]
+for an example of this.
+
 [[how-to-merge]]
 How to merge
 ------------
@@ -3184,8 +3251,6 @@ Think about how to create a clear chapter dependency graph that will
 allow people to get to important topics without necessarily reading
 everything in between.
 
-Say something about .gitignore.
-
 Scan Documentation/ for other stuff left out; in particular:
 	howto's
 	some of technical/?
-- 
1.5.1.4