Re: [PATCH] Documentation: enhance gitignore whitelist example

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 5, 2011, 20:56 UTC
Message-ID: <7vfwpwmn8d.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1302032214-11438-1-git-send-email-eblake@redhat.com>

Eric Blake <eblake@redhat.com> writes:

Show 5 quoted lines

> 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

Please always indent displayed examples in commit log messages for readability.

Show 26 quoted lines

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

It may be better to say "However X doesn't do Y" than not saying anything, but can't we phrase this more like "If you want to do Y, you need to do Z also/instead"? It would be much more useful for people who are looking for a way to do Y if you didn't stop at saying "X is not the way to do it", and said "Do X and Z if you want to achieve Y", no?

On the other hand, if you are trying to explain why X doesn't do Y, the above would need a bit more explanation (e.g. "when a directory matches an ignore pattern, it tells git not to descend into the directory to find ignored or unignored paths in it" or something like that).

Show 8 quoted lines

> @@ -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

In the patch form it is clear these two lines go together, but the correspondence does not stand out in the text after the patch is applied.

Perhaps doing it like this would make it clearer?

> +    # ignore files in the immediate child directory build, ...
> +    /build/*
> +    # ... except for the log.
> +    !/build/log