Missing ? wildcard character in gitignore documentation

Missing ? wildcard character in gitignore documentation

[Jack F]

Hello,

I have just noticed that the documentation for gitignore is missing
documentation on using the ? to match any single character. I have
included a example below with git version 2.14.1.

|11:05:09 j ~/Development/ls-ignore [master] $ git status On branch
master Your branch is up-to-date with 'origin/master'. nothing to
commit, working tree clean 11:05:11 j ~/Development/ls-ignore [master] $
cat .gitignore *~ node_modules yarn* 11:05:21 j ~/Development/ls-ignore
[master] $ touch test.swo 11:05:31 j ~/Development/ls-ignore [master]?1
$ git status On branch master Your branch is up-to-date with
'origin/master'. Untracked files: (use "git add <file>..." to include in
what will be committed) test.swo nothing added to commit but untracked
files present (use "git add" to track) 11:05:35 j
~/Development/ls-ignore [master]?1 $ echo "*.sw?" >> .gitignore 11:05:40
j ~/Development/ls-ignore [master]≠1 $ cat .gitignore *~ node_modules
yarn* *.sw? 11:05:51 j ~/Development/ls-ignore [master]≠1 $ git status
On branch master Your branch is up-to-date with 'origin/master'. Changes
not staged for commit: (use "git add <file>..." to update what will be
committed) (use "git checkout -- <file>..." to discard changes in
working directory) modified: .gitignore no changes added to commit (use
"git add" and/or "git commit -a")|



Noticed it when checking an npm package (ignore) that uses the
documentation (https://git-scm.com/docs/gitignore) to determine its
functionality. It is documented in
https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files

Cheers.

From,
Jack

https://bytes.nz
https://keybase.io/bytesnz

RE: Missing ? wildcard character in gitignore documentation

[Randall S. Becker]

On January 29, 2018 6:30 AM, Jack F wrote:
> I have just noticed that the documentation for gitignore is missing
> documentation on using the ? to match any single character. I have included
> a example below with git version 2.14.1.
> 
> |11:05:09 j ~/Development/ls-ignore [master] $ git status On branch
> master Your branch is up-to-date with 'origin/master'. nothing to commit,
> working tree clean 11:05:11 j ~/Development/ls-ignore [master] $ cat
> .gitignore *~ node_modules yarn* 11:05:21 j ~/Development/ls-ignore
> [master] $ touch test.swo 11:05:31 j ~/Development/ls-ignore [master]?1 $
> git status On branch master Your branch is up-to-date with 'origin/master'.
> Untracked files: (use "git add <file>..." to include in what will be committed)
> test.swo nothing added to commit but untracked files present (use "git add"
> to track) 11:05:35 j ~/Development/ls-ignore [master]?1 $ echo "*.sw?" >>
> .gitignore 11:05:40 j ~/Development/ls-ignore [master]≠1 $ cat .gitignore *~
> node_modules
> yarn* *.sw? 11:05:51 j ~/Development/ls-ignore [master]≠1 $ git status On
> branch master Your branch is up-to-date with 'origin/master'. Changes not
> staged for commit: (use "git add <file>..." to update what will be
> committed) (use "git checkout -- <file>..." to discard changes in working
> directory) modified: .gitignore no changes added to commit (use "git add"
> and/or "git commit -a")|
> 
> 
> 
> Noticed it when checking an npm package (ignore) that uses the
> documentation (https://git-scm.com/docs/gitignore) to determine its
> functionality. It is documented in https://git-scm.com/book/en/v2/Git-
> Basics-Recording-Changes-to-the-Repository#Ignoring-Files

The implication of support for ? is there through the following paragraph from the gitignore documentation:

    "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/*.html" matches "Documentation/git.html"
    but not "Documentation/ppc/ppc.html" or "tools/perf/Documentation/perf.html"."

Of course you have to go read fnmatch(3), so it might be good for expand on this here :).

Cheers,
Randall

-- Brief whoami:
 NonStop developer since approximately 211288444200000000
 UNIX developer since approximately 421664400
-- In my real life, I talk too much.

Re: Missing ? wildcard character in gitignore documentation

[Jack F]

Ah. Yes it does. Apologies. Maybe a "See glob(7) for more pattern
matching options, including ! ? [] *"

Thank you very much.

Cheers.

From,
Jack

On 29/01/18 15:47, Randall S. Becker wrote:
> On January 29, 2018 6:30 AM, Jack F wrote:
>> I have just noticed that the documentation for gitignore is missing
>> documentation on using the ? to match any single character. I have included
>> a example below with git version 2.14.1.
>>
>> |11:05:09 j ~/Development/ls-ignore [master] $ git status On branch
>> master Your branch is up-to-date with 'origin/master'. nothing to commit,
>> working tree clean 11:05:11 j ~/Development/ls-ignore [master] $ cat
>> .gitignore *~ node_modules yarn* 11:05:21 j ~/Development/ls-ignore
>> [master] $ touch test.swo 11:05:31 j ~/Development/ls-ignore [master]?1 $
>> git status On branch master Your branch is up-to-date with 'origin/master'.
>> Untracked files: (use "git add <file>..." to include in what will be committed)
>> test.swo nothing added to commit but untracked files present (use "git add"
>> to track) 11:05:35 j ~/Development/ls-ignore [master]?1 $ echo "*.sw?" >>
>> .gitignore 11:05:40 j ~/Development/ls-ignore [master]≠1 $ cat .gitignore *~
>> node_modules
>> yarn* *.sw? 11:05:51 j ~/Development/ls-ignore [master]≠1 $ git status On
>> branch master Your branch is up-to-date with 'origin/master'. Changes not
>> staged for commit: (use "git add <file>..." to update what will be
>> committed) (use "git checkout -- <file>..." to discard changes in working
>> directory) modified: .gitignore no changes added to commit (use "git add"
>> and/or "git commit -a")|
>>
>>
>>
>> Noticed it when checking an npm package (ignore) that uses the
>> documentation (https://git-scm.com/docs/gitignore) to determine its
>> functionality. It is documented in https://git-scm.com/book/en/v2/Git-
>> Basics-Recording-Changes-to-the-Repository#Ignoring-Files
> The implication of support for ? is there through the following paragraph from the gitignore documentation:
>
>     "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/*.html" matches "Documentation/git.html"
>     but not "Documentation/ppc/ppc.html" or "tools/perf/Documentation/perf.html"."
>
> Of course you have to go read fnmatch(3), so it might be good for expand on this here :).
>
> Cheers,
> Randall
>
> -- Brief whoami:
>  NonStop developer since approximately 211288444200000000
>  UNIX developer since approximately 421664400
> -- In my real life, I talk too much.
>
>
>

-- 
https://bytes.nz
https://keybase.io/bytesnz

Re: Missing ? wildcard character in gitignore documentation

[Duy Nguyen]

On Mon, Jan 29, 2018 at 10:47:10AM -0500, Randall S. Becker wrote:
> The implication of support for ? is there through the following paragraph from the gitignore documentation:
> 
>     "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/*.html" matches "Documentation/git.html" but not
>     "Documentation/ppc/ppc.html" or
>     "tools/perf/Documentation/perf.html"."
> 
> Of course you have to go read fnmatch(3), so it might be good for
> expand on this here :).

I agree. How about something like this?

-- 8< --
Subject: [PATCH] gitignore.txt: elaborate shell glob syntax

`fnmatch(3)` is a great mention if the intended audience is
programmers. For normal users it's probably better to spell out what
a shell glob is.

This paragraph is updated to roughly tell (or remind) what the main
wildcards are supposed to do. All the details are still hidden away
behind the `fnmatch(3)` wall because bringing the whole specification
here may be too much.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Documentation/gitignore.txt | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 63260f0056..0f4b1360bd 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -102,12 +102,11 @@ PATTERN FORMAT
    (relative to the toplevel of the work tree if not from a
    `.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
-   "Documentation/git.html" but not "Documentation/ppc/ppc.html"
-   or "tools/perf/Documentation/perf.html".
+ - Otherwise, Git treats the pattern as a shell glob: '{asterisk}'
+   matches anything except '/', '?' matches any one character except
+   '/' and '[]' matches one character in a selected range. See
+   fnmatch(3) and the FNM_PATHNAME flag for a more accurate
+   description.
 
  - A leading slash matches the beginning of the pathname.
    For example, "/{asterisk}.c" matches "cat-file.c" but not
-- 
2.16.1.205.g271f633410

-- 8< --

Re: Missing ? wildcard character in gitignore documentation

[Ævar Arnfjörð Bjarmason]

On Tue, Jan 30 2018, Duy Nguyen jotted:

> On Mon, Jan 29, 2018 at 10:47:10AM -0500, Randall S. Becker wrote:
>> The implication of support for ? is there through the following paragraph from the gitignore documentation:
>>
>>     "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/*.html" matches "Documentation/git.html" but not
>>     "Documentation/ppc/ppc.html" or
>>     "tools/perf/Documentation/perf.html"."
>>
>> Of course you have to go read fnmatch(3), so it might be good for
>> expand on this here :).
>
> I agree. How about something like this?
>
> -- 8< --
> Subject: [PATCH] gitignore.txt: elaborate shell glob syntax
>
> `fnmatch(3)` is a great mention if the intended audience is
> programmers. For normal users it's probably better to spell out what
> a shell glob is.
>
> This paragraph is updated to roughly tell (or remind) what the main
> wildcards are supposed to do. All the details are still hidden away
> behind the `fnmatch(3)` wall because bringing the whole specification
> here may be too much.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
>  Documentation/gitignore.txt | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index 63260f0056..0f4b1360bd 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -102,12 +102,11 @@ PATTERN FORMAT
>     (relative to the toplevel of the work tree if not from a
>     `.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
> -   "Documentation/git.html" but not "Documentation/ppc/ppc.html"
> -   or "tools/perf/Documentation/perf.html".
> + - Otherwise, Git treats the pattern as a shell glob: '{asterisk}'
> +   matches anything except '/', '?' matches any one character except
> +   '/' and '[]' matches one character in a selected range. See
> +   fnmatch(3) and the FNM_PATHNAME flag for a more accurate
> +   description.
>
>   - A leading slash matches the beginning of the pathname.
>     For example, "/{asterisk}.c" matches "cat-file.c" but not

When reading the docs the other day I was thinking that we should
entirely git rid of these references to fnmatch(3) and write a
gitwildmatch man page.

One of the reasons for why fnmatch() was removed as a supported backend
was because it couldn't be relied on as a backend, so it doesn't make
sense to be referring to that OS-level documentation, wildmatch also has
other features.

Re: Missing ? wildcard character in gitignore documentation

[Duy Nguyen]

On Tue, Jan 30, 2018 at 6:07 PM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> On Tue, Jan 30 2018, Duy Nguyen jotted:
>
>> On Mon, Jan 29, 2018 at 10:47:10AM -0500, Randall S. Becker wrote:
>>> The implication of support for ? is there through the following paragraph from the gitignore documentation:
>>>
>>>     "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/*.html" matches "Documentation/git.html" but not
>>>     "Documentation/ppc/ppc.html" or
>>>     "tools/perf/Documentation/perf.html"."
>>>
>>> Of course you have to go read fnmatch(3), so it might be good for
>>> expand on this here :).
>>
>> I agree. How about something like this?
>>
>> -- 8< --
>> Subject: [PATCH] gitignore.txt: elaborate shell glob syntax
>>
>> `fnmatch(3)` is a great mention if the intended audience is
>> programmers. For normal users it's probably better to spell out what
>> a shell glob is.
>>
>> This paragraph is updated to roughly tell (or remind) what the main
>> wildcards are supposed to do. All the details are still hidden away
>> behind the `fnmatch(3)` wall because bringing the whole specification
>> here may be too much.
>>
>> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
>> ---
>>  Documentation/gitignore.txt | 11 +++++------
>>  1 file changed, 5 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
>> index 63260f0056..0f4b1360bd 100644
>> --- a/Documentation/gitignore.txt
>> +++ b/Documentation/gitignore.txt
>> @@ -102,12 +102,11 @@ PATTERN FORMAT
>>     (relative to the toplevel of the work tree if not from a
>>     `.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
>> -   "Documentation/git.html" but not "Documentation/ppc/ppc.html"
>> -   or "tools/perf/Documentation/perf.html".
>> + - Otherwise, Git treats the pattern as a shell glob: '{asterisk}'
>> +   matches anything except '/', '?' matches any one character except
>> +   '/' and '[]' matches one character in a selected range. See
>> +   fnmatch(3) and the FNM_PATHNAME flag for a more accurate
>> +   description.
>>
>>   - A leading slash matches the beginning of the pathname.
>>     For example, "/{asterisk}.c" matches "cat-file.c" but not
>
> When reading the docs the other day I was thinking that we should
> entirely git rid of these references to fnmatch(3) and write a
> gitwildmatch man page.

That's even better :) I forgot that we don't use fnmatch anymore.

> One of the reasons for why fnmatch() was removed as a supported backend
> was because it couldn't be relied on as a backend, so it doesn't make
> sense to be referring to that OS-level documentation, wildmatch also has
> other features.



-- 
Duy