threads / discuss / 27001

[PATCHv3 2/2] Documentation: enhance gitignore whitelist example

Subject: [PATCHv3 2/2] Documentation: enhance gitignore whitelist example

## tl;dr

6 messages between Apr 5, 2011 and Apr 6, 2011.

replies: 5people: 3as markdown or json

Eric Blake· Apr 5, 2011, 22:17 UTC · lore

[PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore

Make it clear that in a .gitignore file,
  *ignore

matches (and therefore excludes) `.gitignore', even though the same glob does not match in the shell.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
v3: separate fnmatch wording cleanup into its own patch
 Documentation/gitignore.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 2e7328b..9b1e5e1 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -86,9 +86,10 @@ PATTERN FORMAT
    `.gitignore` file).

  - 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.
-   For example, "Documentation/{asterisk}.html" matches
+   for consumption by fnmatch(3) with the FNM_PATHNAME but not
+   FNM_PERIOD flags: wildcards in the pattern will match leading
+   . but not / in pathnames.  For example,
+   "Documentation/{asterisk}.html" matches "Documentation/.html" and
    "Documentation/git.html" but not "Documentation/ppc/ppc.html"
    or "tools/perf/Documentation/perf.html".

-- 
1.7.4
Eric Blake· Apr 5, 2011, 22:17 UTC · re: Eric Blake · lore

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.
CC: Jonathan Nieder <jrnieder@gmail.com>
CC: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Eric Blake <eblake@redhat.com>
---

v3: split out fnmatch tweaks, don't tweak specification of patterns or existing examples but instead add an entirely new example, make the example use a deeper hierarchy

 Documentation/gitignore.txt |   38 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 38 insertions(+), 0 deletions(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 9b1e5e1..e1ad234 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -139,6 +139,44 @@ EXAMPLES
     [...]
 --------------------------------------------------------------

+It is possible to ignore most of a hierarchy, while still
+white-listing a single file, by ignoring multiple files then using a
+negation pattern for the file in question.  However, this requires
+ignoring files and not directories, since no patterns are ever matched
+inside of an ignored directory.  For nested files, it requires several
+iterations of refined patterns.
+
+--------------------------------------------------------------
+    $ git status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/build/file
+    #       build/file
+    #       build/foo/baz
+    #       build/foo/other
+    [...]
+    $ cat .gitignore
+    # Use anchoring, since `build' would ignore Documentation/build.
+    # Do not ignore the directory itself, ...
+    # /build/
+    # rather ignore files in the top-level build directory, ...
+    /build/*
+    # but permit child directories, ...
+    !/build/*/
+    # then ignore all nested files, ...
+    /build/*/*
+    # and finally white-list the special file
+    !/build/foo/baz
+    $ git status
+    [...]
+    # Untracked files:
+    [...]
+    #       Documentation/build/file
+    #       build/foo/baz
+    [...]
+--------------------------------------------------------------
+
 Another example:

 --------------------------------------------------------------

-- 
1.7.4
Junio C Hamano· Apr 5, 2011, 22:43 UTC · re: Eric Blake · lore

Re: [PATCHv3 2/2] Documentation: enhance gitignore whitelist example

Eric Blake <eblake@redhat.com> writes:
> v3: split out fnmatch tweaks, don't tweak specification of patterns
> or existing examples but instead add an entirely new example, make
> the example use a deeper hierarchy

Somebody has to compare this vs making the existing example larger. Generally speaking, I prefer to keep the number of examples smaller (the less the beginner has to read, the better), but the end result might be more readable with a separate example, like this patch does.

> +    $ cat .gitignore
> +    # Use anchoring, since `build' would ignore Documentation/build.
> +    # Do not ignore the directory itself, ...
> +    # /build/
> +    # rather ignore files in the top-level build directory, ...

Do you _really_ need these three lines? I suspect that it is unclear to the first reader that the second one is a _bad_ example that is commented out. That is, how about starting like this, without the above three?

Show 7 quoted lines
> +    # Ignore files in the top-level build directory, ...
> +    /build/*
> +    # but permit child directories, ...
> +    !/build/*/
> +    # then ignore all nested files, ...
> +    /build/*/*
> +    # and finally white-list the special file
Nit; s/the special file/&./;
Show 8 quoted lines
> +    !/build/foo/baz
> +    $ git status
> +    [...]
> +    # Untracked files:
> +    [...]
> +    #       Documentation/build/file
> +    #       build/foo/baz
> +    [...]

Other than that, as a free-standing example this was very straightforward illustration. I didn't check the flow-of-learning though.

Thanks.
Junio C Hamano· Apr 5, 2011, 22:34 UTC · re: Eric Blake · lore

Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore

Eric Blake <eblake@redhat.com> writes:
Show 29 quoted lines
> Make it clear that in a .gitignore file,
>
>   *ignore
>
> matches (and therefore excludes) `.gitignore', even though the
> same glob does not match in the shell.
>
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>
> v3: separate fnmatch wording cleanup into its own patch
>
>  Documentation/gitignore.txt |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index 2e7328b..9b1e5e1 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -86,9 +86,10 @@ PATTERN FORMAT
>     `.gitignore` file).
>
>   - 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.
> -   For example, "Documentation/{asterisk}.html" matches
> +   for consumption by fnmatch(3) with the FNM_PATHNAME but not
> +   FNM_PERIOD flags: wildcards in the pattern will match leading
> +   . but not / in pathnames.  For example,
Does this format correctly with asciidoc?

Even if it does not get confused as a bullet or something, I think you would want to quote it (and the slash), perhaps like

	`.` (dot) and `/` (slash)

In any case, I tend to think that we would want to add FNM_PERIOD to tighten the match in the longer term, perhaps at the 1.8.0 boundary.

Eric Blake· Apr 5, 2011, 22:43 UTC · re: Junio C Hamano · lore

Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore

On 04/05/2011 04:34 PM, Junio C Hamano wrote:
Show 9 quoted lines
>>   - 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.
>> -   For example, "Documentation/{asterisk}.html" matches
>> +   for consumption by fnmatch(3) with the FNM_PATHNAME but not
>> +   FNM_PERIOD flags: wildcards in the pattern will match leading
>> +   . but not / in pathnames.  For example,
> 
> Does this format correctly with asciidoc?

No idea - I'm not an asciidoc whiz. How would I tell (or can someone else offer some advice)?

Show 8 quoted lines
> 
> Even if it does not get confused as a bullet or something, I think you
> would want to quote it (and the slash), perhaps like
> 
> 	`.` (dot) and `/` (slash)
> 
> In any case, I tend to think that we would want to add FNM_PERIOD to
> tighten the match in the longer term, perhaps at the 1.8.0 boundary.

POSIX requires that "find . -name '*'" not use FNM_PERIOD, and I actually like the consistency with find(1). In other words, I would complain (then go with group consensus, if my complaint is in the minority) that it is a step backwards to tighten the match, where the short:

  dir/*
would have to become the much longer
  dir/*
  dir/.[!.]
  dir/.??*
to properly exclude all except '.' and '..', or
  dir/*
  dir/.*
if '.' and '..' are already special to the pattern matching.
-- 
Eric Blake   eblake@redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org
Drew Northup· Apr 6, 2011, 12:48 UTC · re: Eric Blake · lore

Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore

On Tue, 2011-04-05 at 16:43 -0600, Eric Blake wrote:
Show 13 quoted lines
> On 04/05/2011 04:34 PM, Junio C Hamano wrote:
> >>   - 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.
> >> -   For example, "Documentation/{asterisk}.html" matches
> >> +   for consumption by fnmatch(3) with the FNM_PATHNAME but not
> >> +   FNM_PERIOD flags: wildcards in the pattern will match leading
> >> +   . but not / in pathnames.  For example,
> > 
> > Does this format correctly with asciidoc?
> 
> No idea - I'm not an asciidoc whiz.  How would I tell (or can someone
> else offer some advice)?

For my ongoing project of rearranging some of the Gitweb documentation I just went ahead and made a script based on the Documentation/Makefile and run that against my in-progress work. (In that case I'll get around to munging the local Makefile later if I decide I'm really that pleased with what I've [re-]written.) This way I can incrementally become an Asciidoc genius if I really need to and remain a mortal otherwise.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

← back to recent threads