From mboxrd@z Thu Jan 1 00:00:00 1970 From: Junio C Hamano Subject: Re: [PATCH] user-manual: Add section on ignoring files Date: Tue, 15 May 2007 16:30:29 -0700 Message-ID: <7v1whhis16.fsf@assigned-by-dhcp.cox.net> References: <200705160047.52717.johan@herland.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: git@vger.kernel.org, "Randal L. Schwartz" To: Johan Herland X-From: git-owner@vger.kernel.org Wed May 16 01:31:29 2007 Return-path: Envelope-to: gcvg-git@gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1Ho6UK-0003wY-8c for gcvg-git@gmane.org; Wed, 16 May 2007 01:31:28 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1760880AbXEOXad (ORCPT ); Tue, 15 May 2007 19:30:33 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1760206AbXEOXad (ORCPT ); Tue, 15 May 2007 19:30:33 -0400 Received: from fed1rmmtao105.cox.net ([68.230.241.41]:55050 "EHLO fed1rmmtao105.cox.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1760866AbXEOXab (ORCPT ); Tue, 15 May 2007 19:30:31 -0400 Received: from fed1rmimpo02.cox.net ([70.169.32.72]) by fed1rmmtao105.cox.net (InterMail vM.7.05.02.00 201-2174-114-20060621) with ESMTP id <20070515233031.JQK22040.fed1rmmtao105.cox.net@fed1rmimpo02.cox.net>; Tue, 15 May 2007 19:30:31 -0400 Received: from assigned-by-dhcp.cox.net ([68.5.247.80]) by fed1rmimpo02.cox.net with bizsmtp id zbWW1W0041kojtg0000000; Tue, 15 May 2007 19:30:30 -0400 In-Reply-To: <200705160047.52717.johan@herland.net> (Johan Herland's message of "Wed, 16 May 2007 00:47:52 +0200") User-Agent: Gnus/5.110006 (No Gnus v0.6) Emacs/21.4 (gnu/linux) Sender: git-owner@vger.kernel.org Precedence: bulk X-Mailing-List: git@vger.kernel.org Archived-At: Johan Herland 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.