From ff2995645c6483c8745de7de16fbe2f862a04091 Mon Sep 17 00:00:00 2001
From: Rupayon Haldar <80724680+rupayon123@users.noreply.github.com>
Date: Tue, 22 Sep 2026 08:30:47 -0400
Subject: [PATCH] Document gitignore patterns that raise despite Git accepting
 them

---
 pathspec/patterns/gitignore/basic.py | 8 ++++++++
 pathspec/patterns/gitignore/spec.py  | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/pathspec/patterns/gitignore/basic.py b/pathspec/patterns/gitignore/basic.py
index e93169c..93539a8 100644
--- a/pathspec/patterns/gitignore/basic.py
+++ b/pathspec/patterns/gitignore/basic.py
@@ -133,6 +133,14 @@ def pattern_to_regex(
 		"""
 		Convert the pattern into a regular expression.
 
+		Raises :class:`~pathspec.patterns.gitignore.base.GitIgnorePatternError`
+		for invalid patterns, including a bare ``!`` (also when followed by
+		unescaped trailing spaces) or an unmatched trailing backslash. Unlike
+		blank lines and comments, these inputs do not return ``(None, None)``.
+		Git accepts these lines without a diagnostic, so callers reading ignore
+		files must be prepared to handle this exception even when Git accepts
+		the file.
+
 		*pattern* (:class:`str` or :class:`bytes`) is the pattern to convert into a
 		regular expression.
 
diff --git a/pathspec/patterns/gitignore/spec.py b/pathspec/patterns/gitignore/spec.py
index 28b299f..3da9f31 100644
--- a/pathspec/patterns/gitignore/spec.py
+++ b/pathspec/patterns/gitignore/spec.py
@@ -167,6 +167,14 @@ def pattern_to_regex(
 		"""
 		Convert the pattern into a regular expression.
 
+		Raises :class:`~pathspec.patterns.gitignore.base.GitIgnorePatternError`
+		for invalid patterns, including a bare ``!`` (also when followed by
+		unescaped trailing spaces) or an unmatched trailing backslash. Unlike
+		blank lines and comments, these inputs do not return ``(None, None)``.
+		Git accepts these lines without a diagnostic, so callers reading ignore
+		files must be prepared to handle this exception even when Git accepts
+		the file.
+
 		*pattern* (:class:`str` or :class:`bytes`) is the pattern to convert into a
 		regular expression.