# gitignore-fs

> determine if any file is gitignored (complete implementation of gitignore rules)

Latest version **2.2.3** (published 2025-11-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install gitignore-fs
pnpm add gitignore-fs
yarn add gitignore-fs
bun add gitignore-fs
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.3 |
| Published | 2025-11-12 |
| First published | 2021-06-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 4 |
| Unpacked size | 87 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Andy Edwards |
| Maintainers | jedwards1211 |
| Keywords | gitignore, git |

## Links

- npm: https://www.npmjs.com/package/gitignore-fs
- Repository: https://github.com/jedwards1211/gitignore-fs
- Homepage: https://github.com/jedwards1211/gitignore-fs#readme
- Issues: https://github.com/jedwards1211/gitignore-fs/issues
- npm.io page: https://npm.io/package/gitignore-fs

## Dependencies (4)

- [ignore](https://npm.io/package/ignore.md) ^5.1.8
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.26.0
- [promisify-child-process](https://npm.io/package/promisify-child-process.md) ^4.1.1
- [babel-plugin-add-module-exports](https://npm.io/package/babel-plugin-add-module-exports.md) ^1.0.4

## Recent versions

- 2.2.3 (latest) — 2025-11-12
- 2.2.2 — 2022-11-18
- 2.2.1 — 2022-11-18
- 2.2.0 — 2022-11-17
- 2.1.0 — 2021-06-10
- 2.0.0 — 2021-06-10
- 1.0.0 — 2021-06-04

## README

# gitignore-fs

[![CircleCI](https://circleci.com/gh/jedwards1211/gitignore-fs.svg?style=svg)](https://circleci.com/gh/jedwards1211/gitignore-fs)
[![Coverage Status](https://codecov.io/gh/jedwards1211/gitignore-fs/branch/master/graph/badge.svg)](https://codecov.io/gh/jedwards1211/gitignore-fs)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![npm version](https://badge.fury.io/js/gitignore-fs.svg)](https://badge.fury.io/js/gitignore-fs)

If you're using a library to ignore gitignored files, it probably doesn't do it right! Use this library to be match git behavior 100%.

Determine if any file is gitignored. This is intended to be a complete implementation of the gitignore spec, including `$GIT_DIR`, `$GIT_DIR/info/excludes`, and the `core.excludesFile` configuration variable.

**Requires Node >= 8.**

# Getting started

```
npm install --save gitignore-fs
```

```js
const Gitignore = require('gitignore-fs')

const gitignore = new Gitignore()

console.log(gitignore.ignoresSync('node_modules')) // true or false depending on your config
```

# API

## `class Gitignore`

Each instance of this class keeps a separate cache of gitignore rules.

### `new Gitignore([options])`

Creates a new Gitignore instance.

#### `options.initialRules` (`string[]`, _optional_)

These rules will be applied at lowest precedence (lower than rules from `core.excludesFile`).
Paths with a slash in the beginning or middle are relative to the closest enclosing git directory.

#### `options.finalRules` (`string[]`, _optional_)

These rules will be applied at highest precedence (higher than `.gitignore` files).
Paths with a slash in the beginning or middle are relative to the closest enclosing git directory.

### `.ignores(path)`

Determines if the given `path` is gitignored asynchronously.

#### `path` (`string`, **required**)

The path to test. **Must end with / if it is a directory!**

#### Returns (`Promise<boolean>`)

A promise that will resolve to `true` if `path` is gitignored, `false` otherwise

### `.ignoresSync(path)`

Determines if the given `path` is gitignored synchronously.

#### `path` (`string`, **required**)

The path to test. **Must end with / if it is a directory!**

#### Returns (`boolean`)

`true` if `path` is gitignored, `false` otherwise

### `.clearCache()`

Clears the entire gitignore rule cache.

---
_Source: https://npm.io/package/gitignore-fs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._