fix(extensions): use pathspec for gitignore-compatible .extensionignore matching

Rubiss · Rubiss · commit 13c25bc01e90 · 2026-03-09T22:02:27.000-04:00
Replace fnmatch with pathspec.GitIgnoreSpec to get proper .gitignore semantics where * does not cross directory boundaries. This addresses review feedback on #1781. Changes: - Switch from fnmatch to pathspec>=0.12.0 (GitIgnoreSpec.from_lines) - Normalize backslashes in patterns for cross-platform compatibility - Distinguish directories from files for trailing-slash patterns - Update docs to accurately describe supported pattern semantics - Add edge-case tests: .., absolute paths, empty file, backslashes, * vs ** boundary behavior, and ! negation - Move changelog entry to [Unreleased] section
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,12 @@ Recent changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
+
 ## [0.2.0] - 2026-03-09
 
 ### Changed
@@ -62,7 +68,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Higher-priority catalogs win on merge conflicts (same extension id in multiple catalogs)
   - 13 new tests covering catalog stack resolution, merge conflicts, URL validation, and `install_allowed` enforcement
   - Updated RFC, Extension User Guide, and Extension API Reference documentation
-- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
 
 ## [0.1.13] - 2026-03-03
 
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
@@ -338,11 +338,18 @@ Extension authors can create a `.extensionignore` file in the extension root to
 
 ### Format
 
-The file uses glob-style patterns, one per line:
+The file uses `.gitignore`-compatible patterns (one per line), powered by the [`pathspec`](https://pypi.org/project/pathspec/) library:
 
 - Blank lines are ignored
 - Lines starting with `#` are comments
-- Patterns are matched against both the file/folder name and its path relative to the extension root
+- `*` matches anything **except** `/` (does not cross directory boundaries)
+- `**` matches zero or more directories (e.g., `docs/**/*.draft.md`)
+- `?` matches any single character except `/`
+- A trailing `/` restricts a pattern to directories only
+- Patterns containing `/` (other than a trailing slash) are anchored to the extension root
+- Patterns without `/` match at any depth in the tree
+- `!` negates a previously excluded pattern (re-includes a file)
+- Backslashes in patterns are normalised to forward slashes for cross-platform compatibility
 - The `.extensionignore` file itself is always excluded automatically
 
 ### Example
@@ -367,12 +374,21 @@ CONTRIBUTING.md
 
 ### Pattern Matching
 
-| Pattern | Matches |
-|---------|---------|
-| `*.pyc` | Any `.pyc` file in any directory |
-| `tests/` | The `tests` directory (and all its contents) |
-| `docs/*.draft.md` | Draft markdown files inside `docs/` |
-| `.github` | The `.github` directory at any level |
+| Pattern | Matches | Does NOT match |
+|---------|---------|----------------|
+| `*.pyc` | Any `.pyc` file in any directory | — |
+| `tests/` | The `tests` directory (and all its contents) | A file named `tests` |
+| `docs/*.draft.md` | `docs/api.draft.md` (directly inside `docs/`) | `docs/sub/api.draft.md` (nested) |
+| `.env` | The `.env` file at any level | — |
+| `!README.md` | Re-includes `README.md` even if matched by an earlier pattern | — |
+| `docs/**/*.draft.md` | `docs/api.draft.md`, `docs/sub/api.draft.md` | — |
+
+### Unsupported Features
+
+The following `.gitignore` features are **not applicable** in this context:
+
+- **Multiple `.extensionignore` files**: Only a single file at the extension root is supported (`.gitignore` supports files in subdirectories)
+- **`$GIT_DIR/info/exclude` and `core.excludesFile`**: These are Git-specific and have no equivalent here
 
 ---
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -13,6 +13,7 @@ dependencies = [
     "truststore>=0.10.4",
     "pyyaml>=6.0",
     "packaging>=23.0",
+    "pathspec>=0.12.0",
 ]
 
 [project.scripts]
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
@@ -6,7 +6,6 @@
 without bloating the core framework.
 """
 
-import fnmatch
 import json
 import hashlib
 import os
@@ -19,6 +18,8 @@
 from datetime import datetime, timezone
 import re
 
+import pathspec
+
 import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
@@ -285,10 +286,18 @@ def __init__(self, project_root: Path):
     def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]], Set[str]]]:
         """Load .extensionignore and return an ignore function for shutil.copytree.
 
-        The .extensionignore file uses glob-style patterns (one per line).
+        The .extensionignore file uses .gitignore-compatible patterns (one per line).
         Lines starting with '#' are comments. Blank lines are ignored.
         The .extensionignore file itself is always excluded.
 
+        Pattern semantics mirror .gitignore:
+        - '*' matches anything except '/'
+        - '**' matches zero or more directories
+        - '?' matches any single character except '/'
+        - Trailing '/' restricts a pattern to directories only
+        - Patterns with '/' (other than trailing) are anchored to the root
+        - '!' negates a previously excluded pattern
+
         Args:
             source_dir: Path to the extension source directory
 
@@ -300,14 +309,22 @@ def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]
         if not ignore_file.exists():
             return None
 
-        patterns: List[str] = []
-        for line in ignore_file.read_text().splitlines():
+        lines: List[str] = ignore_file.read_text().splitlines()
+
+        # Normalise backslashes in patterns so Windows-authored files work
+        normalised: List[str] = []
+        for line in lines:
             stripped = line.strip()
             if stripped and not stripped.startswith("#"):
-                patterns.append(stripped)
+                normalised.append(stripped.replace("\\", "/"))
+            else:
+                # Preserve blanks/comments so pathspec line numbers stay stable
+                normalised.append(line)
 
         # Always ignore the .extensionignore file itself
-        patterns.append(".extensionignore")
+        normalised.append(".extensionignore")
+
+        spec = pathspec.GitIgnoreSpec.from_lines(normalised)
 
         def _ignore(directory: str, entries: List[str]) -> Set[str]:
             ignored: Set[str] = set()
@@ -316,17 +333,15 @@ def _ignore(directory: str, entries: List[str]) -> Set[str]:
                 rel_path = str(rel_dir / entry) if str(rel_dir) != "." else entry
                 # Normalise to forward slashes for consistent matching
                 rel_path_fwd = rel_path.replace("\\", "/")
-                for pattern in patterns:
-                    # Strip trailing slash so "tests/" matches directory name "tests"
-                    pat = pattern.rstrip("/")
-                    # Match against the entry name itself
-                    if fnmatch.fnmatch(entry, pat):
+
+                entry_full = Path(directory) / entry
+                if entry_full.is_dir():
+                    # Append '/' so directory-only patterns (e.g. tests/) match
+                    if spec.match_file(rel_path_fwd + "/"):
                         ignored.add(entry)
-                        break
-                    # Match against the relative path from the source root
-                    if fnmatch.fnmatch(rel_path_fwd, pat):
+                else:
+                    if spec.match_file(rel_path_fwd):
                         ignored.add(entry)
-                        break
             return ignored
 
         return _ignore
diff --git a/tests/test_extensions.py b/tests/test_extensions.py
@@ -1774,3 +1774,167 @@ def test_extensionignore_relative_path_match(self, temp_dir, valid_manifest_data
         dest = proj_dir / ".specify" / "extensions" / "test-ext"
         assert (dest / "docs" / "guide.md").exists()
         assert not (dest / "docs" / "internal" / "draft.md").exists()
+
+    def test_extensionignore_dotdot_pattern_is_noop(self, temp_dir, valid_manifest_data):
+        """Patterns with '..' should not escape the extension root."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={"README.md": "# Hello"},
+            ignore_content="../sibling/\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # Everything should still be copied — the '..' pattern matches nothing inside
+        assert (dest / "README.md").exists()
+        assert (dest / "extension.yml").exists()
+        assert (dest / "commands" / "hello.md").exists()
+
+    def test_extensionignore_absolute_path_pattern_is_noop(self, temp_dir, valid_manifest_data):
+        """Absolute path patterns should not match anything."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={"README.md": "# Hello", "passwd": "sensitive"},
+            ignore_content="/etc/passwd\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # Nothing matches — /etc/passwd is anchored to root and there's no 'etc' dir
+        assert (dest / "README.md").exists()
+        assert (dest / "passwd").exists()
+
+    def test_extensionignore_empty_file(self, temp_dir, valid_manifest_data):
+        """An empty .extensionignore should exclude only itself."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={"README.md": "# Hello", "notes.txt": "notes"},
+            ignore_content="",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "README.md").exists()
+        assert (dest / "notes.txt").exists()
+        assert (dest / "extension.yml").exists()
+        # .extensionignore itself is still excluded
+        assert not (dest / ".extensionignore").exists()
+
+    def test_extensionignore_windows_backslash_patterns(self, temp_dir, valid_manifest_data):
+        """Backslash patterns (Windows-style) are normalised to forward slashes."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "docs/internal/draft.md": "draft",
+                "docs/guide.md": "# Guide",
+            },
+            ignore_content="docs\\internal\\draft.md\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "docs" / "guide.md").exists()
+        assert not (dest / "docs" / "internal" / "draft.md").exists()
+
+    def test_extensionignore_star_does_not_cross_directories(self, temp_dir, valid_manifest_data):
+        """'*' should NOT match across directory boundaries (gitignore semantics)."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "docs/api.draft.md": "draft",
+                "docs/sub/api.draft.md": "nested draft",
+            },
+            ignore_content="docs/*.draft.md\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # docs/*.draft.md should only match directly inside docs/, NOT subdirs
+        assert not (dest / "docs" / "api.draft.md").exists()
+        assert (dest / "docs" / "sub" / "api.draft.md").exists()
+
+    def test_extensionignore_doublestar_crosses_directories(self, temp_dir, valid_manifest_data):
+        """'**' should match across directory boundaries."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "docs/api.draft.md": "draft",
+                "docs/sub/api.draft.md": "nested draft",
+                "docs/guide.md": "guide",
+            },
+            ignore_content="docs/**/*.draft.md\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert not (dest / "docs" / "api.draft.md").exists()
+        assert not (dest / "docs" / "sub" / "api.draft.md").exists()
+        assert (dest / "docs" / "guide.md").exists()
+
+    def test_extensionignore_negation_pattern(self, temp_dir, valid_manifest_data):
+        """'!' negation re-includes a previously excluded file."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "docs/guide.md": "# Guide",
+                "docs/internal.md": "internal",
+                "docs/api.md": "api",
+            },
+            ignore_content="docs/*.md\n!docs/api.md\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # docs/*.md excludes all .md in docs, but !docs/api.md re-includes it
+        assert not (dest / "docs" / "guide.md").exists()
+        assert not (dest / "docs" / "internal.md").exists()
+        assert (dest / "docs" / "api.md").exists()

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ dependencies = [`
`13`	`13`	`"truststore>=0.10.4",`
`14`	`14`	`"pyyaml>=6.0",`
`15`	`15`	`"packaging>=23.0",`
	`16`	`+ "pathspec>=0.12.0",`
`16`	`17`	`]`
`17`	`18`
`18`	`19`	`[project.scripts]`