mirror of
https://github.com/github/spec-kit.git
synced 2026-03-16 18:33:07 +00:00
feat(extensions): support .extensionignore to exclude files during install (#1781)
* feat(extensions): support .extensionignore to exclude files during install Add .extensionignore support so extension authors can exclude files and folders from being copied when users run 'specify extension add'. The file uses glob-style patterns (one per line), supports comments (#), blank lines, trailing-slash directory patterns, and relative path matching. The .extensionignore file itself is always excluded from the copy. - Add _load_extensionignore() to ExtensionManager - Integrate ignore function into shutil.copytree in install_from_directory - Document .extensionignore in EXTENSION-DEVELOPMENT-GUIDE.md - Add 6 tests covering all pattern matching scenarios - Bump version to 0.1.14 * fix(extensions): use pathspec for gitignore-compatible .extensionignore matching 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
This commit is contained in:
@@ -332,6 +332,67 @@ echo "$config"
|
||||
|
||||
---
|
||||
|
||||
## Excluding Files with `.extensionignore`
|
||||
|
||||
Extension authors can create a `.extensionignore` file in the extension root to exclude files and folders from being copied when a user installs the extension with `specify extension add`. This is useful for keeping development-only files (tests, CI configs, docs source, etc.) out of the installed copy.
|
||||
|
||||
### Format
|
||||
|
||||
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
|
||||
- `*` 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
|
||||
|
||||
```gitignore
|
||||
# .extensionignore
|
||||
|
||||
# Development files
|
||||
tests/
|
||||
.github/
|
||||
.gitignore
|
||||
|
||||
# Build artifacts
|
||||
__pycache__/
|
||||
*.pyc
|
||||
dist/
|
||||
|
||||
# Documentation source (keep only the built README)
|
||||
docs/
|
||||
CONTRIBUTING.md
|
||||
```
|
||||
|
||||
### Pattern Matching
|
||||
|
||||
| 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
|
||||
- **Negation inside excluded directories**: Because file copying uses `shutil.copytree`, excluding a directory prevents recursion into it entirely. A negation pattern cannot re-include a file inside a directory that was itself excluded. For example, the combination `tests/` followed by `!tests/important.py` will **not** preserve `tests/important.py` — the `tests/` directory is skipped at the root level and its contents are never evaluated. To work around this, exclude the directory's contents individually instead of the directory itself (e.g., `tests/*.pyc` and `tests/.cache/` rather than `tests/`).
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Extension ID
|
||||
|
||||
Reference in New Issue
Block a user