[BUG] gitignore documentation inconsistent with actual behaviour
To
git@vger.kernel.org
From
dana
Date
2018-10-11 10:19:06 UTC
Hello,

I'm a contributor to ripgrep, which is a grep-like tool that supports using
gitignore files to control which files are searched in a repo (or any other
directory tree). ripgrep's support for the patterns in these files is based on
git's official documentation, as seen here:

  https://git-scm.com/docs/gitignore

One of the most common reports on the ripgrep bug tracker is that it does not
allow patterns like the following real-world examples, where a ** is used along
with other text within the same path component:

  **/**$$*.java
  **.orig
  **local.properties
  !**.sha1

The reason it doesn't allow them is that the gitignore documentation explicitly
states that they're invalid:

  A leading "**" followed by a slash means match in all directories...

  A trailing "/**" matches everything inside...

  A slash followed by two consecutive asterisks then a slash matches zero or
  more directories...

  Other consecutive asterisks are considered invalid.

git itself happily accepts these patterns, however, apparently treating the **
like a single * without fnmatch(3)'s FNM_PATHNAME flag set (in other words, it
matches / as a regular character, thus crossing directory boundaries).

ripgrep's developer is loathe to reverse-engineer this undocumented behaviour,
and so the reports keep coming, both for ripgrep itself and for down-stream
consumers of it and its ignore crate (including most notably Microsoft's VS Code
editor).

My request: Assuming that git's actual handling of these patterns is intended,
would it be possible to make it 'official' and explicitly add it to the
documentation?

References (the first one is the main bug):

https://github.com/BurntSushi/ripgrep/issues/373
https://github.com/BurntSushi/ripgrep/issues/507
https://github.com/BurntSushi/ripgrep/issues/859
https://github.com/BurntSushi/ripgrep/issues/945
https://github.com/BurntSushi/ripgrep/issues/1080
https://github.com/BurntSushi/ripgrep/issues/1082
https://github.com/Microsoft/vscode/issues/24050

dana