@wider/utils_regexp-gitignore - Convert gitIgnore declarations into a regular expression

You provide the list of gitIgnore formatted definition files or JSON objects that define the files of interest

You get back a regular expression that can be used to test a well formed file path string. Returns true if the given string matches the file specification. true means that the file is to be ignored.

Alternatively, instead of a path string, you can test same functionality on a nodeJS.fs.dirent

Documentation

Full Documentation

Install

npm install "@wider/utils_regexp-gitignore"

Use within your project

The following illustrates the use of pattern .gitignore definitions that are in the run time current working directory. Here we are looking for a package.json that is not in the gitignore folders (such as node_modules) and not in your own .jsdoc folder or a files whose names start .myOwn

import path from "path";
import gitIgnore from "@wider/utils_regexp-gitignore";

const source_git = path.join(process.cwd(), "./.gitignore"); //find the standard gitignore file in the directory of the applications  or wherever you may have placed it 
const source_myOwn = [".jsdoc/", ".myOwn*"]; // add in your own extras - which eg you might pick up from your own `settings.json`
const directions = {exclude : source_git, include : source_myOwn};

const myRegularExpression = gitIgnore(directions);

// 	you can then use this regular expression repeatedly as required
if (myRegularExpression.test(path.resolve("./whatEverYouWant")))
	yourCodeForAFileToBeIgnored;
else
	yourCodeForAFileToBeAccepted

About the directions

The directions as to which files should be accepted or rejected are given as an object with typeDef of directionsToCreateAFilter as seen in the utils_regexp-gitignore API.

You can provide Array objects for both include and exclude directions - if you include both then the exclude are applied first.

If you provide real gitignore files please remember that .gitignore system itself operates with a collection of ignore specifications in different locations within nodeJS and the system as indicated by the gitignore documentation. You need to provide all the file components of relevance to you in the order they are to apply so as to get an identical impact to what git tools would do. In many cases just your main ./.gitignore file alone may suffice.

The files selected by include are not equivalent of the ! operator in .gitignore exclude file. In gitignore the ! operator can override the other directives. Placing the entry instead in the include section will only find files in locations that have not been excluded. You can still use the ! operator in both include and exclude but it may make your brain work overtime working out what you are achieving - it is more efficient to use a positive exclude than a negative include and easier for the next developer to read.

About the conversion

The conversion can give rise to seriously large regular expressions, but they will invariably perform faster than the equivalent code in javascript.

The characters and diphthongs such as * . / ! ** \! and newline are recognised for their gitignore use and newlines and comments # are stripped out.

The tutorial in the jsDoc documentation in this package includes examples.

Limitation

This is a regular expression parsing of the file's full path. Paths provided via nodeJS path.resolve() have trailing directory delimiter stripped off and so it is not possible for this tool to detect if a path you provide is intended to be a directory. If you need to detect if the reference is a directory, please use instead

import {GipDirent} from "@wider/utils_regexp-gitignore";

const myGip = new GipDirent(sameObjectAsutils_regexp-gitignore);

if (myGip.test(dirEntOrFullFilePath))
	yourCodeForAFileToBeIgnored;