doc: document backslash in gitignore patterns

Because gitignore patterns are passed to fnmatch, the handling of backslashes is the same as it is there: it can be used to escape metacharacters. We do reference fnmatch(3) for more details, but it may be friendlier to point out this implication explicitly (especially for people who want to know about backslash handling and search the documentation for that word). There are also two cases that I've seen some other backslash-escaping systems handle differently, so let's describe those: 1. A backslash before any character treats that character literally, even if it's not otherwise a meta-character. As opposed to including the backslash itself (like "foo\bar" in shell expands to "foo\bar") or forbidding it ("foo\zar" is required to produce a diagnostic in C). 2. A backslash at the end of the string is an invalid pattern (and not a literal backslash). This second one in particular was a point of confusion between our implementation and the one in JGit. Our wildmatch behavior matches what POSIX specifies for fnmatch, so the code and documentation are in line. But let's add a test to cover this case. Note that the behavior here differs between wildmatch itself (which is what gitignore will use) and pathspec matching (which will only turn to wildmatch if a literal match fails). So we match "foo\" to "foo\" in pathspecs, but not via gitignore. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jeff King committed Oct 29, 2025 at 11:32 UTC 8a6d158a1d69996542ec0d28b63e83eaf46c5945
2 files changed +7
Documentation/gitignore.adoc
+5
@@ -111,6 +111,11 @@ PATTERN FORMAT
111 one of the characters in a range. See fnmatch(3) and the
112 FNM_PATHNAME flag for a more detailed description.
113
114 + - A backslash ("`\`") can be used to escape any character. E.g., "`\*`"
115 + matches a literal asterisk (and "`\a`" matches "`a`", even though
116 + there is no need for escaping there). As with fnmatch(3), a backslash
117 + at the end of a pattern is an invalid pattern that never matches.
118 +
119 Two consecutive asterisks ("`**`") in patterns matched against
120 full pathname may have special meaning:
121
t/t3070-wildmatch.sh
+2
@@ -235,6 +235,8 @@ match 1 1 1 1 aaaaaaabababab '*ab'
235 match 1 1 1 1 'foo*' 'foo\*'
236 match 0 0 0 0 foobar 'foo\*bar'
237 match 1 1 1 1 'f\oo' 'f\\oo'
238 +match 0 0 0 0 \
239 + 1 1 1 1 'foo\' 'foo\'
240 match 1 1 1 1 ball '*[al]?'
241 match 0 0 0 0 ten '[ten]'
242 match 1 1 1 1 ten '**[!te]'