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

[Junio C Hamano <junkio@cox.net>]

Johan Herland <johan@herland.net> 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.