howl.util.ignore_file
Overview
howl.util.ignore_file provides support for “ignore files”, more specifically Git
ignore files (e.g. .gitignore
) and the ignore files used by searchers such as
ripgrep and The Silver
Searcher (i.e. .ignore
). The purpose of ignore
files is ignore certain files or directories within a target directory. This is
accomplished by having one or more ignore files in the target directory, either
at the root or in any arbitrary sub directory, containing patterns which specify
what to ignore. You can read more about ignore files in the
manpage for gitignore.
This module has been written to handle all of the known cases for ignore files at the time of this writing. This includes negations, escapes, all different types of globs, correct handling of sub directory ignore files, etc. Any missing functionality should thus be considered a bug, so please report any detected omissions.
General usage
You can create an ignore matcher using one of two possible ways (see below), but
for both scenarios you’ll get back a callable object that works within the
context of a certain directory. These callable objects you can invoke with paths
relative to the context directory, and the return value will indicate whether
the path should be ignored (true
for ignore, and false
for allowing it).
The relative paths passed are assumed to have a trailing slash for directory entries.
Functions
evaluator (dir, opts = {})
This creates an ignore matcher for the specified dir
, which will take into
account any parent ignore files as well as any relevant ignore files in sub
directories. By default the evaluator will consult both .gitignore
and
.ignore
files (giving precedence to the latter), but this can be controlled by
specifying ignore_files
in opts
. The most important file should be specified
first (default values is {'.ignore', '.gitignore'}
).
Example
Given a directory /tmp/foo
and the following ignore files:
/tmp/.gitignore
:
*.o root/bar
/tmp/root/.gitignore
:
zed sub/sandwich
/tmp/root/sub/.gitignore
:
!my.o frob
The following snippet shows the expected results:
dir = howl.io.File('/tmp/root') ignore = howl.util.ignore_file.evaluator dir ignore 'obj.o' -- => true (from parent ignore file) ignore 'bar' -- => true (from parent ignore file) ignore 'zed' -- => true (from root file) ignore 'sub/sandwich' -- => true (from root ignore file) ignore 'sub/my.o' -- => false (overriden from sub ignore file) ignore 'sub/frob' -- => true (from sub ignore file) ignore 'frob' -- => false (ignored only in sub directory)
ignore_file(file, dir)
Invoking the module directly for a given file returns a matcher for the
specified file only. No parent or sub directory ignore files will be consulted,
only file
. If dir
is specified then the matching will be done in the context of
that directory - otherwise the file’s parent directory will be used as the
context.