Metadata-Version: 2.4
Name: git-check-ignore
Version: 1.0.1
Summary: A Python wrapper around `git` to check filenames against `.gitignore` files
Project-URL: Documentation, https://dd-dockyard.github.io/git-check-ignore/
Project-URL: Repository, https://github.com/dd-dockyard/git-check-ignore
Project-URL: Issues, https://github.com/dd-dockyard/git-check-ignore/issues
Author-email: Jordan Webb <jordan@dangerdevices.com>
License-Expression: AGPL-3.0-only
License-File: COPYING
Keywords: git,gitignore
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# git-check-ignore

This is a wrapper around git's [`check-ignore`](https://git-scm.com/docs/git-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.

[![Test, build, and publish](https://github.com/dd-dockyard/git-check-ignore/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/dd-dockyard/git-check-ignore/actions/workflows/publish.yml)

## Installation

`git-check-ignore` can be [installed from PyPI](https://pypi.org/project/git-check-ignore/):

```sh
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`:

```python
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`](https://docs.python.org/3/library/pathlib.html) objects:

```python
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:

```python
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](https://www.gnu.org/licenses/agpl-3.0.txt) license.
