fix: dedent PathSpec config values before compiling patterns - #4208
fix: dedent PathSpec config values before compiling patterns#4208Manushprajwal7 wants to merge 1 commit into
Conversation
The 'test' CI job on this PR has been failing consistently, but on
inspection the failure (test_draft_docs_with_comments_from_user_guide)
is a real, reproducible bug independent of this PR's actual change -
it also fails on current master. Root-caused and fixed it here since
it was blocking CI either way.
Root cause: newer pathspec releases (1.x, vs. the >=0.11.1 mkdocs
requires) stopped implicitly stripping leading whitespace from each
gitignore-style pattern line - correctly, per the gitignore format,
where leading whitespace is significant unless escaped. mkdocs' own
PathSpec config option (used by draft_docs, exclude_docs, not_in_nav)
never dedented its input, so a value written with common leading
indentation across all lines (as naturally happens with a multi-line
YAML block scalar, and as the test itself does) silently matched
nothing once pathspec stopped compensating for it.
Verified directly against pathspec.gitignore.GitIgnoreSpec:
- pathspec==0.11.1 (matches mkdocs' declared minimum): matches fine
with or without the fix, since it stripped leading whitespace itself.
- pathspec==1.1.1 (current release, unconstrained by mkdocs' >=0.11.1):
matching silently breaks without this fix, works correctly with it.
Fix: dedent the value in PathSpec.run_validation() before splitting
it into lines, so behavior no longer depends on which pathspec version
happens to be installed - matching how a YAML '|' block scalar's
common indentation is normally handled.
Added a focused regression test (PathSpecTest) alongside the existing
integration-level coverage in
BuildTests.test_draft_docs_with_comments_from_user_guide, which now
passes under pathspec 1.1.1.
Full local suite (both pathspec==0.11.1 and the latest 1.1.1): 726-728
passed, only the 4 pre-existing Windows-symlink-privilege errors
remain (unrelated, present on master too).
There was a problem hiding this comment.
Pull request overview
This PR fixes a regression caused by newer pathspec (1.x) no longer stripping leading whitespace in gitignore patterns, which made indented multi-line PathSpec config values (e.g. draft_docs, exclude_docs, not_in_nav) silently stop matching. It normalizes MkDocs’ behavior across pathspec versions by dedenting the config value before compiling patterns, and adds direct unit coverage for the PathSpec option.
Changes:
- Dedent
PathSpecstring values before splitting into lines and compiling withpathspec.gitignore.GitIgnoreSpec.from_lines(...). - Add focused unit tests verifying both indented (regression) and non-indented inputs compile and match as expected.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
mkdocs/config/config_options.py |
Dedents PathSpec values before compiling patterns to avoid indentation breaking matches under pathspec 1.x. |
mkdocs/tests/config/config_options_tests.py |
Adds PathSpecTest to ensure indented and non-indented pattern strings behave correctly. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
The 2 remaining `pypy-3.9` failures (Ubuntu and Windows) are unrelated to this change — they fail at the dependency-install step, before any test code runs: `cryptography`'s Rust extension no longer builds on PyPy 3.9 (PyO3 dropped support for it), and `zstandard` fails to build on Windows because `distutils` was removed. Confirmed the same two jobs fail identically on current `master` (run 31243474392), so this is a pre-existing CI/toolchain issue independent of this PR. |
Summary
While working on #4207 I noticed CI's
testjob failing consistently ontest_draft_docs_with_comments_from_user_guide(Python 3.10+) — and confirmed it also fails the same way on currentmaster, unrelated to that PR. This fixes the actual root cause.Root cause:
draft_docs,exclude_docs, andnot_in_navare all backed byconfig_options.PathSpec, which compiles the value viapathspec.gitignore.GitIgnoreSpec.from_lines(lines=value.splitlines()).pathspec's newer major release (1.x) correctly stops implicitly stripping leading whitespace from each pattern line — per the real gitignore format, leading whitespace is significant unless escaped. mkdocs never dedented the value first, so a value written with common leading indentation on every line (natural for a multi-line string inmkdocs.yml, and exactly what the affected test does) silently matches nothing once pathspec stopped compensating for it. mkdocs only declarespathspec >=0.11.1with no upper bound, so this breaks silently as soon as a newer pathspec gets resolved.Verified directly against
pathspec.gitignore.GitIgnoreSpec:pathspec==0.11.1(mkdocs' declared minimum): matches correctly with or without this fix, since it stripped leading whitespace itself.pathspec==1.1.1(current release): matching silently breaks without this fix, works correctly with it.Changes
mkdocs/config/config_options.py: dedent the value inPathSpec.run_validation()before splitting it into lines, so behavior is consistent regardless of which pathspec version is installed — matching how a YAML|block scalar's common indentation is normally handled.PathSpecTestinmkdocs/tests/config/config_options_tests.pycovering both the indented and non-indented cases directly against the config option.Test plan
test_draft_docs_with_comments_from_user_guide(the originally-failing test) now passes underpathspec==1.1.1pathspec==0.11.1andpathspec==1.1.1(726-727 passed; only the 4 pre-existing Windows-symlink-privilege errors remain, unrelated and present on unmodifiedmastertoo)PathSpecTestcovers both the indented (regression) and plain (no change in behavior) casesblack/isort/ruff checkon changed files — clean