# ignorelib
## Use the syntax and semantics of gitignore with custom ignore file names and locations
git has a comprehensive mechanism for selecting files to ignore inside repositories.
`ignorelib` lets you use the same system, customized to your own needs.
You can read about the semantics of gitignore here: https://git-scm.com/docs/gitignore
This library is a lightly-modified version of the [gitignore implementation](https://github.com/dulwich/dulwich/blob/master/dulwich/ignore.py) in [dulwich](https://www.dulwich.io/), a pure Python implementation of git.
# Installation
```
python -m pip install ignorelib
```
# Usage
## Setup
The primary entrypoint is the class factory method `IgnoreFilterManager.build()`, with the following inputs:
* `path`: the root path (required). All path checks you make are relative to this path.
* `global_ignore_file_paths`: an optional list of file paths to attempt to load global ignore patterns from.
* Relative paths are relative to the root path (for git, this would be `.git/info/exclude`)
* User expansion is performed, so paths like (for git) `~/.config/git/ignore` work.
* Files that cannot be loaded are silently ignored, so you don't need to check if they exist or not.
* Files earlier in the list take precedence, and these files take precendence over the patterns in `global_patterns`.
* `global_patterns`: an optional list of global ignore patterns. These are the things that should always be ignored (for git, this would be `.git` to exclude the repo directory)
* `ignore_file_name`: an optional file name for the per-directory ignore file (for git, this would be `.gitignore`).
* `ignore_case`: an optional boolean for specifying whether to ignore case, defaulting to false.
## Use
You check if a given path is ignored with the `is_ignored()` method of an `IgnoreFilterManager` object, which takes a (relative) path and returns `True` if it matches an ignore pattern.
It returns `False` if it is explicitly not ignored (using a pattern starting with `!`), or `None` if the file does not match any patterns.
Note that this allows you to distinguish between the default state (not ignoring) and actually matching a pattern that prevents it from being ignored.
To iterate over not-ignored files, `IgnoreFilterManager.walk()` has the same interface as `os.walk()` but without taking a root path, as this comes from the the `IgnoreFilterManager`.
After using an `IgnoreFilterManager` instance to get a number of paths, you can extract the state (i.e., all loaded patterns with their sources) in a JSON-serializable format with the `IgnoreFilterManager.to_dict()` method.
### Example
To replicate the behavior of git, you would do something like:
```python
import os.path
import ignorelib
def get_filter_manager_for_path(path):
return ignorelib.IgnoreFilterManager(path,
global_ignore_file_paths=[
os.path.join('.git', 'info', 'exclude'), # relative to input path, so within the repo
os.path.expanduser(os.path.join('~', '.config', 'git', 'ignore')) # absolute
],
global_patterns=['.git'],
ignore_file_name='.gitignore')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/benkehoe/ignorelib",
"name": "ignorelib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5,<4.0",
"maintainer_email": "",
"keywords": "ignore,git,gitignore",
"author": "Ben Kehoe",
"author_email": "ben@kehoe.io",
"download_url": "https://files.pythonhosted.org/packages/d0/4a/4d76ff7d494ce1299e735e5d3a199d973e73c5bf5f39b927826063ed86cb/ignorelib-0.3.0.tar.gz",
"platform": "",
"description": "# ignorelib\n## Use the syntax and semantics of gitignore with custom ignore file names and locations\n\ngit has a comprehensive mechanism for selecting files to ignore inside repositories.\n`ignorelib` lets you use the same system, customized to your own needs.\n\nYou can read about the semantics of gitignore here: https://git-scm.com/docs/gitignore\n\nThis library is a lightly-modified version of the [gitignore implementation](https://github.com/dulwich/dulwich/blob/master/dulwich/ignore.py) in [dulwich](https://www.dulwich.io/), a pure Python implementation of git.\n\n# Installation\n```\npython -m pip install ignorelib\n```\n\n# Usage\n## Setup\nThe primary entrypoint is the class factory method `IgnoreFilterManager.build()`, with the following inputs:\n* `path`: the root path (required). All path checks you make are relative to this path.\n* `global_ignore_file_paths`: an optional list of file paths to attempt to load global ignore patterns from.\n * Relative paths are relative to the root path (for git, this would be `.git/info/exclude`)\n * User expansion is performed, so paths like (for git) `~/.config/git/ignore` work.\n * Files that cannot be loaded are silently ignored, so you don't need to check if they exist or not.\n * Files earlier in the list take precedence, and these files take precendence over the patterns in `global_patterns`.\n* `global_patterns`: an optional list of global ignore patterns. These are the things that should always be ignored (for git, this would be `.git` to exclude the repo directory)\n* `ignore_file_name`: an optional file name for the per-directory ignore file (for git, this would be `.gitignore`).\n* `ignore_case`: an optional boolean for specifying whether to ignore case, defaulting to false.\n\n## Use\nYou check if a given path is ignored with the `is_ignored()` method of an `IgnoreFilterManager` object, which takes a (relative) path and returns `True` if it matches an ignore pattern.\nIt returns `False` if it is explicitly not ignored (using a pattern starting with `!`), or `None` if the file does not match any patterns.\nNote that this allows you to distinguish between the default state (not ignoring) and actually matching a pattern that prevents it from being ignored.\n\nTo iterate over not-ignored files, `IgnoreFilterManager.walk()` has the same interface as `os.walk()` but without taking a root path, as this comes from the the `IgnoreFilterManager`.\n\nAfter using an `IgnoreFilterManager` instance to get a number of paths, you can extract the state (i.e., all loaded patterns with their sources) in a JSON-serializable format with the `IgnoreFilterManager.to_dict()` method.\n\n### Example\n\nTo replicate the behavior of git, you would do something like:\n```python\nimport os.path\n\nimport ignorelib\n\ndef get_filter_manager_for_path(path):\n return ignorelib.IgnoreFilterManager(path,\n global_ignore_file_paths=[\n os.path.join('.git', 'info', 'exclude'), # relative to input path, so within the repo\n os.path.expanduser(os.path.join('~', '.config', 'git', 'ignore')) # absolute\n ],\n global_patterns=['.git'],\n ignore_file_name='.gitignore')\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Use the syntax and semantics of gitignore with custom ignore file names and locations",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/benkehoe/ignorelib",
"Repository": "https://github.com/benkehoe/ignorelib"
},
"split_keywords": [
"ignore",
"git",
"gitignore"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fafb9dd9b4421238e979932f949192aa9dba3689eedbc8a76d95042150a4c28",
"md5": "4a0dacebb491fc5ab65fd3bc2b2220e9",
"sha256": "2575083ff18534a8a3925a2a531b0d2f9d326efe550dc54e726ab5d6a6598d0c"
},
"downloads": -1,
"filename": "ignorelib-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a0dacebb491fc5ab65fd3bc2b2220e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5,<4.0",
"size": 10737,
"upload_time": "2020-10-27T15:29:28",
"upload_time_iso_8601": "2020-10-27T15:29:28.658792Z",
"url": "https://files.pythonhosted.org/packages/0f/af/b9dd9b4421238e979932f949192aa9dba3689eedbc8a76d95042150a4c28/ignorelib-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d04a4d76ff7d494ce1299e735e5d3a199d973e73c5bf5f39b927826063ed86cb",
"md5": "049e5fc377474f4c2fcdda9ffc52891f",
"sha256": "712ae752cdf1717c53c5009169b167f4e23c963e5405f86af1078329923e08fd"
},
"downloads": -1,
"filename": "ignorelib-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "049e5fc377474f4c2fcdda9ffc52891f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5,<4.0",
"size": 10175,
"upload_time": "2020-10-27T15:29:30",
"upload_time_iso_8601": "2020-10-27T15:29:30.623807Z",
"url": "https://files.pythonhosted.org/packages/d0/4a/4d76ff7d494ce1299e735e5d3a199d973e73c5bf5f39b927826063ed86cb/ignorelib-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-10-27 15:29:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "benkehoe",
"github_project": "ignorelib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ignorelib"
}
JSON
