[BUG] gitignore documentation inconsistent with actual behaviour

From: dana <dana@dana.is>
Date: Oct 11, 2018, 10:19 UTC
Message-ID: <C16A9F17-0375-42F9-90A9-A92C9F3D8BBA@dana.is>

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