From mboxrd@z Thu Jan 1 00:00:00 1970 From: Johan Herland Subject: [PATCH] user-manual: Add section on ignoring files Date: Wed, 16 May 2007 02:31:40 +0200 Message-ID: <200705160231.40486.johan@herland.net> References: <200705160047.52717.johan@herland.net> <7v1whhis16.fsf@assigned-by-dhcp.cox.net> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 7BIT Cc: Junio C Hamano , "Randal L. Schwartz" , Jakub Narebski To: git@vger.kernel.org X-From: git-owner@vger.kernel.org Wed May 16 02:31:53 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 1Ho7Qm-000487-BC for gcvg-git@gmane.org; Wed, 16 May 2007 02:31:52 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759349AbXEPAbq (ORCPT ); Tue, 15 May 2007 20:31:46 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1759439AbXEPAbq (ORCPT ); Tue, 15 May 2007 20:31:46 -0400 Received: from smtp.getmail.no ([84.208.20.33]:45656 "EHLO smtp.getmail.no" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759349AbXEPAbq (ORCPT ); Tue, 15 May 2007 20:31:46 -0400 Received: from pmxchannel-daemon.no-osl-m323-srv-009-z2.isp.get.no by no-osl-m323-srv-009-z2.isp.get.no (Sun Java System Messaging Server 6.2-7.05 (built Sep 5 2006)) id <0JI300603YSWYH00@no-osl-m323-srv-009-z2.isp.get.no> for git@vger.kernel.org; Wed, 16 May 2007 02:31:44 +0200 (CEST) Received: from smtp.getmail.no ([10.5.16.1]) by no-osl-m323-srv-009-z2.isp.get.no (Sun Java System Messaging Server 6.2-7.05 (built Sep 5 2006)) with ESMTP id <0JI300CORYSTY870@no-osl-m323-srv-009-z2.isp.get.no> for git@vger.kernel.org; Wed, 16 May 2007 02:31:41 +0200 (CEST) Received: from alpha.herland ([84.210.6.167]) by no-osl-m323-srv-009-z1.isp.get.no (Sun Java System Messaging Server 6.2-7.05 (built Sep 5 2006)) with ESMTP id <0JI30064SYSS2L10@no-osl-m323-srv-009-z1.isp.get.no> for git@vger.kernel.org; Wed, 16 May 2007 02:31:41 +0200 (CEST) In-reply-to: <7v1whhis16.fsf@assigned-by-dhcp.cox.net> Content-disposition: inline User-Agent: KMail/1.9.6 Sender: git-owner@vger.kernel.org Precedence: bulk X-Mailing-List: git@vger.kernel.org Archived-At: 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 --- Revised version with fixes from Junio and Jakub. Thanks. :) Documentation/user-manual.txt | 71 +++++++++++++++++++++++++++++++++++++++- 1 files changed, 69 insertions(+), 2 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index a7abeaa..750e55a 100644 --- 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 +-------------- + +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. + +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). +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 right place to put exclude patterns that are meant to + be shared between all project participants, 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 place to put exclude patterns that are local to your copy of the + repo (i.e. 'not' shared between project participants), such as + temporary backup files 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 remain + 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 +3253,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