Repository navigation
Description
What is the intended ownership contract for a mutable list passed to PathSpec or GitIgnoreSpec? Should later changes to that list affect matching, or should the spec represent a snapshot?
On current master, changing the original list changes spec.patterns, len(spec) and equality, but matching still uses the old patterns. The API docs describe matching against self.patterns, but do not explicitly promise support for changing the list after construction. I'm asking about the contract before proposing a repair.
Reproduction on current master
Tested against commit 3dfbd9192ae36b0058b0e306ea44da132a5a025c (reports version 1.1.1), using the simple backend on Linux with CPython 3.10.12 and 3.14.9:
from pathspec import PathSpec
patterns = list(PathSpec.from_lines("gitignore", ["*.py"]).patterns)
spec = PathSpec(patterns, backend="simple")
patterns.extend(PathSpec.from_lines("gitignore", ["*.txt"]).patterns)
fresh = PathSpec(patterns, backend="simple")
print(len(spec)) # 2
print(spec == fresh) # True
print(spec.match_file("a.txt")) # False
print(fresh.match_file("a.txt")) # True
print((spec + PathSpec([], backend="simple")).match_file("a.txt")) # TrueThe equivalent case with GitIgnoreSpec has the same result. Native backends were not tested.
The constructor retains the supplied sequence as self.patterns, while the simple backend builds its own indexed pattern list during construction. This seems to explain why the public pattern list and matching can disagree after the append. Adding an empty spec reconstructs the backend and changes the result.
Historical comparison, not a guarantee
A separate control using the v0.12.1 source on CPython 3.10.12 accepts a.txt from both the existing spec and a fresh spec after the same list change. That control uses "gitwildmatch" rather than "gitignore" and omits the backend argument, since 0.12.1 predates backends. This shows earlier behavior, not that mutation was intentionally part of the supported API. The exact change that introduced the difference has not been bisected.
If snapshot semantics are intended, should spec.patterns also remain a snapshot so it describes the patterns actually used? If live-list semantics are intended, should matching reflect the changed list? I don't want to assume either answer or propose a change that conflicts with the backend design.
No patch or assignment request is included.
References:
- API documentation
- Current PathSpec source
- Prior state-consistency fix for failed
+=, which concerns a different update path.
AI assistance was used for the investigation and this report. The runtime results above come from the focused reproduction and historical control, not a full test-suite run.
Activity
cpburnz commentedon Nov 14, 2026
The contract for patterns passed into PathSpec/GitIgnoreSpec is:
list(patterns).At least since the introduction of backends (and possibly before) the sequence is implicitly copied anyway when it's filtered (see internal usage of
enumerate_patterns()). The purpose of patterns is to preserve the patterns the spec was created with.