Re: [PATCH] Documentation: enhance gitignore whitelist example

[Jonathan Nieder <jrnieder@gmail.com>]

Eric Blake wrote:

> I was trying to whitelist a single file pattern in a directory
> that I was otherwise content to ignore, but when I tried:
> 
> /m4/
> !/m4/virt-*.m4
> 
> then 'git add' kept warning me that I had to use -f.  I finally
> figured out that ignoring a directory is much different than ignoring
> all files in a directory, when it comes to later negation patterns:
> 
> /m4/*
> !/m4/virt-*.m4
> 
> Improving the documentation will help others learn from my mistake.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>

Yes.

Acked-by: Jonathan Nieder <jrnieder@gmail.com>

Cc-ing Hannes, in case he has thoughts on how to explain this more
intuitively.

> ---
>  Documentation/gitignore.txt |   19 +++++++++++++++++--
>  1 files changed, 17 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index 2e7328b..2f49989 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -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.
> 
>   - If the pattern ends with a slash, it is removed for the
>     purpose of the following description, but it would only find
> @@ -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.
>     For example, "Documentation/{asterisk}.html" matches
>     "Documentation/git.html" but not "Documentation/ppc/ppc.html"
>     or "tools/perf/Documentation/perf.html".
> @@ -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
>      $ cat Documentation/.gitignore
>      # ignore generated html files,
>      *.html
> @@ -134,10 +144,15 @@ EXAMPLES
>      [...]
>      # Untracked files:
>      [...]
> +    #       Documentation/build
>      #       Documentation/foo.html
> +    #       build/log
>      [...]
>  --------------------------------------------------------------
> 
> +Note that using `!/build/log' works with an earlier `/build/*' but
> +would have no effect if there were an earlier `/build/'.
> +
>  Another example:
> 
>  --------------------------------------------------------------
> -- 
> 1.7.4
>