Skip to content

Should PathSpec snapshot its constructor's pattern list or reflect later changes? #185

Open

Description

@manav4u

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"))  # True

The 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:

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

  1. cpburnz commented on Nov 14, 2026

    @cpburnz
    Owner

    The contract for patterns passed into PathSpec/GitIgnoreSpec is:

    • For a sequence: it will be stored as is, but will not be modified. It is assumed it will not be modified externally and there's no guarantee if it is modified that its new state will be reflected by the spec.
    • For an iterable (not sequence): its values will be copied into a new list (i.e., 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions