API

Functions

gitmatch.compile(patterns: Iterable, ignorecase: bool = False) → Gitignore

Compile a collection of gitignore patterns into a Gitignore instance. Any invalid or empty patterns are discarded.

Trailing newlines are stripped from the patterns before compiling, so you can compile a pre-existing .gitignore file by simply doing:

with open("path/to/.gitignore") as fp:
    gi = gitmatch.compile(fp)

Parameters

• patterns – an iterable of gitignore patterns

• ignorecase (bool) – Whether the patterns should match case-insensitively

gitmatch.pattern2regex(pattern: AnyStr, ignorecase: bool = False) → Optional[Regex]

Convert a gitignore pattern to a regular expression and return a Regex object. If the pattern is empty or a comment, returns None.

Parameters

• pattern – a gitignore pattern

• ignorecase (bool) – Whether the pattern should match case-insensitively

Raises

InvalidPatternError – If the given pattern is invalid

Classes

Note

Although the Sphinx docs don’t show it, all of the gitmatch classes are generic in typing.AnyStr; i.e., they should be written in type annotations as Gitignore[AnyStr], Gitignore[str], or Gitignore[bytes], as appropriate.

class gitmatch.Gitignore

A collection of compiled gitignore patterns

match(path: Union[AnyStr, PathLike], is_dir: bool = False) → Optional[Match]

Test whether the given relative path matches the collection of patterns. If is_dir is true or if path ends in a slash, path is treated as a path to a directory; otherwise, it treated as a path to a file.

If on Windows and path is not an instance of pathlib.PurePosixPath, or if on any OS and path is an instance of pathlib.PureWindowsPath, any backslashes in path will be converted to forward slashes before matching.

If a match is found, a Match object is returned containing information about the matching pattern and the path or portion thereof that matched. The Match object may be either “truthy” or “falsy” depending on whether the matching pattern is negative or not. If none of the patterns match the path, match() returns None. Hence, if you’re just interested in whether the patterns say the path should be gitignored, call bool() on the result or use it in a boolean context like an if ... : line.

Raises

InvalidPathError – If path is empty, is absolute, is not normalized (aside from an optional trailing slash), contains a NUL character, or starts with ...

class gitmatch.Pattern

A compiled gitignore pattern

dir_only: bool

Whether the pattern only matches directories

ignorecase: bool

Whether the pattern is case-insensitive

match(path: AnyStr, is_dir: bool = False) → bool

Test whether the pattern matches the given path. path is assumed to be a relative, normalized, /-separated path. If is_dir is true, the path is assumed to refer to a directory; otherwise, it is assumed to refer to a file.

Unlike Gitignore.match(), this method only tests path itself, not any of its parent paths.

negative: bool

Whether the pattern is negative or not

pattern: AnyStr

The original gitignore pattern provided to compile(), with trailing spaces stripped

regex: Pattern

A compiled regular expression pattern

class gitmatch.Regex

A gitignore pattern that has been converted to a regular expression

compile() → Pattern

Compile the regular expression

dir_only: bool

Whether the pattern only matches directories

ignorecase: bool

Whether the pattern is case-insensitive

negative: bool

Whether the pattern is negative or not

pattern: AnyStr

The original gitignore pattern provided to compile(), with trailing spaces stripped

regex: AnyStr

The regular expression equivalent of the pattern

class gitmatch.Match

Information about a successful match of a path against a pattern. A Match is truthy if the pattern was not negative and falsy otherwise.

path: AnyStr

The path that matched. This may be a parent path of the value passed to match().

property pattern: AnyStr

The original gitignore pattern provided to compile(), with trailing spaces stripped

pattern_obj: Pattern

The compiled Pattern object that matched the path

Exceptions

exception gitmatch.InvalidPathError

Bases: ValueError

Raised by Gitignore.match() when given an invalid path

msg

A description of the problem with the path

path

The invalid path

exception gitmatch.InvalidPatternError

Bases: ValueError

Raised by pattern2regex() when given an invalid pattern

pattern

The invalid pattern