Re: [PATCH] Documentation: enhance gitignore whitelist example

[Johannes Sixt <j6t@kdbg.org>]

On Dienstag, 5. April 2011, Jonathan Nieder wrote:
> Eric Blake wrote:
> > @@ -70,7 +70,9 @@ PATTERN FORMAT
> >   - An optional prefix '!' which negates the pattern; any
> >     matching file excluded by a previous pattern will become
> >     included again.  If a negated pattern matches, this will
> > -   override lower precedence patterns sources.
> > +   override lower precedence patterns sources.  However, a
> > +   file negation does not override a path that has already
> > +   been excluded by a directory match.

I don't think this is the right place to explain this caveat. Here we describe 
the format and behavior of the patterns in a rather formal manner.

> > @@ -87,7 +89,8 @@ PATTERN FORMAT
> >
> >   - Otherwise, git treats the pattern as a shell glob suitable
> >     for consumption by fnmatch(3) with the FNM_PATHNAME flag:
> > -   wildcards in the pattern will not match a / in the pathname.
> > +   wildcards in the pattern will not match a / in the pathname,
> > +   and do not ignore files with a leading . in the pathname.

I don't think this is correct. * matches .gitignore. I tried it.

> > @@ -116,8 +119,11 @@ EXAMPLES
> >      [...]
> >      # Untracked files:
> >      [...]
> > +    #       Documentation/build
> >      #       Documentation/foo.html
> >      #       Documentation/gitignore.html
> > +    #       build/log
> > +    #       build/.file
> >      #       file.o
> >      #       lib.a
> >      #       src/internal.o
> > @@ -125,6 +131,10 @@ EXAMPLES
> >      $ cat .git/info/exclude
> >      # ignore objects and archives, anywhere in the tree.
> >      *.[oa]
> > +    # ignore files in the immediate child directory build,
> > +    /build/*
> > +    # except for the log.
> > +    !/build/log

Doesn't this example give the false impression that you could do

	/foo/*
	!/foo/bar/baz

and have foo/bar/baz not ignored? But it is still ignored.

I propose a paragraph like this in the NOTES section:

--- 8< ---
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.
--- 8< ---

-- Hannes