git-check-ignore

This is a wrapper around git's check-ignore command.

It can be used to determine if a particular pathname would be ignored by a repository's .gitignore files. It shells out to git to accomplish this. This has the disadvantage that you must have git installed and available on your PATH, but has the advantage that this module's results will always agree with git's.

Installation

git-check-ignore can be installed from PyPI:

pip install git-check-ignore

Documentation

Documentation can be found at https://dd-dockyard.github.io/git-check-ignore/

The source code can be found at https://github.com/dd-dockyard/git-check-ignore

Example Usage

The ignored_pathnames and not_ignored_pathnames functions are the simplest way to use this module. Given a list of names, they iterate through the names that would or would not be ignored by git:

from git_check_ignore import ignored_pathnames, not_ignored_pathnames

for ignored in ignored_pathnames("README.md", "foo.py", "bar.py"):
    print(f"{ignored} is ignored")

for not_ignored in not_ignored_pathnames("README.md", "foo.py", "bar.py"):
    print(f"{not_ignored} is not ignored")

The ignored_paths and not_ignored_paths functions are the same, but return pathlib.Path objects:

from git_check_ignore import ignored_pathnames, not_ignored_pathnames

for ignored in ignored_paths("README.md", "foo.py", "bar.py"):
    if ignored.exists():
        print(f"{ignored} is ignored and exists")

for not_ignored in not_ignored_paths("README.md", "foo.py", "bar.py"):
    if not_ignored.exists():
        print(f"{not_ignored} is not ignored and exists")

The git_check_ignore function provides the most information, and allows you to determine which .gitignore pattern matched a particular pathname:

from git_check_ignore import git_check_ignore

for r in git_check_ignore("README.md", "foo.py", "bar.py"):
    if r.ignored:
        print(f"{r.pathname} is ignored")
    if r.match:
        print(f"matched {r.match.pattern} at line {r.match.linenum} of {r.match.source}")

License

This software is provided under the terms of the AGPL 3.0 license.