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

[Johan Herland <johan@herland.net>]

On Wednesday 16 May 2007, J. Bruce Fields wrote:
> On Wed, May 16, 2007 at 02:31:40AM +0200, Johan Herland wrote:
> > 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.).
> 
> Thanks for doing this!
> 
> > --- a/Documentation/user-manual.txt
> > +++ b/Documentation/user-manual.txt
> > @@ -1188,6 +1188,75 @@ 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
> > +--------------
> 
> This looks like a sensible place to add it....
> 
> > +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 quickly becomes
> > +annoying to have these untracked files lying around; e.g. they make
> > +"`git add .`" and "`git commit -a`" practically useless, and they keep
> > +showing up in the output of "`git status`", etc.
> 
> It might be cute to introduce this with an example; "suppose you just
> imported a new project into git, build it, and run git-status.  The
> output you get might look like:..." etc.

This would of course work as well, but I was trying to keep it as short as possible. 
Ignoring files isn't a big part of what git is really about, so I'd like for this
section to stay as short and to-the-point as possible.

> > +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).
> 
> It might simplify things just to start off by talking about .gitignore
> exclusively, rather than talking about exclude patterns in general;
> something like: "Git therefore allows you to provide .gitignore files,
> which consist of a list of entries, processed in order from top to
> bottom, each telling git about some files to ignore...."
> 
> Then introduce the other options at the end: "for exclude patterns that
> you want to be used just by one repo, or by a group of repos on one
> computer, you can use .git/info/exclude or core.excludesfile."  In fact,
> I'd be *almost* tempted just to leave the discussion of these local
> exclude files at that, and refer elsewhere for the details.  Do people
> really find them useful?

Sounds like a good idea. Feel free to rewrite. But the original impetus for 
the section was Randal's question on the difference between the various 
ignore files, so make sure that's still in there somewhere.

> But those are nits.  I'll happily take it as is and then revise
> later....

Thanks :)


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net