[PATCH 4/4] Documentation/gitignore: explain how to un-ignore part of a directory

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Nov 7, 2011, 08:11 UTC
Message-ID: <20111107081132.GD30486@elie.hsd1.il.comcast.net>
In-Reply-To: <20111107080449.GA30448@elie.hsd1.il.comcast.net>

From: Johannes Sixt <j6t@kdbg.org>
Date: Tue, 5 Apr 2011 23:15:54 +0200

Trying to whitelist a single file pattern in a directory that I was otherwise content to ignore, if I try

	/m4/
	!/m4/virt-*.m4

then 'git add' will keep warning me that I have to use -f. That is because ignoring a directory is much different than ignoring all files in a directory, when it comes to later negation patterns:

	/m4/*
	!/m4/virt-*.m4

However, this example is misleading because it gives the false impression that you could do

	/foo/*
	!/foo/bar/baz

and have foo/bar/baz not ignored, and it is still ignored. Add a paragraph in the NOTES section explaining the general rule and suggesting ignoring the directory and using "git add -f" to track exceptions to cope with it.

[jn: change description distilled from messages by Eric and Hannes to the mailing list.

As Eric noticed, while the "git add -f" trick works well with commands like "git status" and "git add -u", plain "git add subdir/<path>" refuses to update the index with changes from an ignored subdirectory. When describing the trick, explicitly list a few commands that already behave appropriately to avoid confusion.]

Reported-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
That's the end of the series.  Thoughts?

 Documentation/gitignore.txt |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index e5715a27..8b6f601e 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -113,6 +113,21 @@ use 'git update-index {litdd}assume-unchanged'.
 To stop tracking a file that is currently tracked, use
 'git rm --cached'.
 
+When a directory is ignored, it is not possible to un-ignore a single file
+somewhere in the directory using another pattern. E.g., with the patterns
+
+--------------
+/build/
+!/build/tests/results
+--------------
+
+the file "build/tests/results" is still ignored because when a directory is
+ignored, its contents are never investigated. In a situation where a few
+exceptions in an otherwise ignored hierarchy are needed, the recommended
+procedure is to specify to ignore the root of the hierarchy and then to 'git
+add -f' the exceptional files. Subsequent changes to the files will not be
+ignored by 'git status', 'git add .', 'git add -u', or 'git commit -a'.
+
 EXAMPLES
 --------

-- 
1.7.8.rc0