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

Johan Herland [off-list ref] writes:

+[[ignoring-files]]
+Ignoring files
+--------------

Looks good ;-).

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

Another point about this annoyance factor is that "git-add ."
does not add files that are excluded.

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

I think you can safely teach the reader that later entries
override the earlier ones here, as you are about to give such an
example just below.

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

... and more importantly, the patterns that are _meant_ to be
shared by all the project participants.  I think it is probably
easier to follow if you explain that in-tree .gitignore is not
about personal preference upfront in this section, rather than
saying it in .git/info/exclude section.