Re: Q: .gitignore and asterisk "*"

[Junio C Hamano <gitster@pobox.com>]

"Windl, Ulrich" <u.windl@ukr.de> writes:

> I think the documentation for gitignore(5) could be improved regarding "*":
> It's nor clear whether "*" matches an empty string.
> So when I have
> foo.log
> foo.msg
> foo.sh
> foo-whatever.log
> foo-whetever.msg
> Would e.g. "foo*.log" cover all the logs?
>
> The manual says:
>        •   An asterisk "*" matches anything except a slash. The character "?"
>            matches any one character except "/". The range notation, e.g.
>            [a-zA-Z], can be used to match one of the characters in a range.
>            See fnmatch(3) and the FNM_PATHNAME flag for a more detailed
>            description.

Very good point.

The reference to fnmatch(3) may not make readers to consult the
documentation for the library function.  The system they are on may
not even have "man".  fnmatch(3) often refers to glob(7), which
typically would say that a '*' (not between brackets) matches any
string, including the empty string.  The reference to FNM_PATHNAME
we have there is an attempt to refer back to fnmatch(3) that would
typically say that the wildcard does not match a slash.

How about rewriting the entry like so to reduce external references?

----- >8 -----
Subject: gitignore: rewrite wildcard description

The documentation for '.gitignore' makes reference to fnmatch(3) and
FNM_PATHNAME to describe how an asterisk "*" and a question mark "?"
behave.  Even though it spells out that these wildcard characters
do not match a slash, it does not say if an asterisk matches an
empty string (it does).

Rewrite the section so that the readers would get a more complete
picture without requiring them to know what fnmatch(3) and glob(7)
says.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/gitignore.adoc | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git c/Documentation/gitignore.adoc w/Documentation/gitignore.adoc
index 7979e50f18..671a5a4c99 100644
--- c/Documentation/gitignore.adoc
+++ w/Documentation/gitignore.adoc
@@ -110,11 +110,16 @@ PATTERN FORMAT
    and `a/frotz` that is a directory (all paths are relative from
    the `.gitignore` file).
 
- - An asterisk "`*`" matches anything except a slash.
-   The character "`?`" matches any one character except "`/`".
-   The range notation, e.g. `[a-zA-Z]`, can be used to match
-   one of the characters in a range. See fnmatch(3) and the
-   FNM_PATHNAME flag for a more detailed description.
+ - An asterisk "`*`" matches string of any length, and a question mark
+   "`?`" matches any single character, but these wildcard characters
+   do not match a slash "`/`".
+
+ - A pair of brackets that enclose characters match one of the listed
+   characters, and a range notation inside them, e.g., "`[a-zA-Z]`",
+   would behave as if all the characters in the range were listed there
+   instead.  Wildcard characters "`*`" and "`?`" lose their special
+   meaning inside a pair of brackets, e.g., "`[*]`" would match an
+   asterisk and nothing else.
 
  - A backslash ("`\`") can be used to escape any character. E.g., "`\*`"
    matches a literal asterisk (and "`\a`" matches "`a`", even though