eslint-plugin-dotignore

Lint, sort, group, and fix .gitignore files with ESLint.

Git never complains about a .gitignore — it silently ignores what it can't parse, silently skips negations that can never apply, and happily tolerates duplicates, dead patterns, and trailing whitespace that changes nothing. This plugin makes all of that visible, and fixes most of it automatically.

Highlights

• Real parsing, not regex guessing — a dedicated gitignore language for ESLint's language API, with a proper AST, exact ranges, and spec-faithful semantics.
• Finds dead lines — negations Git can never apply, patterns already covered by earlier ones, ** that silently degrades to *.
• Keeps files tidy — alphabetical sorting and folder/file grouping with configurable headings, done without ever changing what Git actually ignores.
• Safe autofixes — every fix is semantics-preserving; when a reorder could change behavior, the rule declines instead of guessing.
• A reusable parser — import eslint-plugin-dotignore/parser and get the AST with zero ESLint baggage.

Installation

# pnpm
pnpm add -D eslint eslint-plugin-dotignore

# npm
npm install --save-dev eslint eslint-plugin-dotignore

# yarn
yarn add --dev eslint eslint-plugin-dotignore

Requires ESLint ≥ 9.7.0 (flat config) and Node ≥ 22.18.

Usage

// eslint.config.js
import dotignore from "eslint-plugin-dotignore";

export default [dotignore.configs.recommended];

That's it — .gitignore files are now linted. Prefer full control? Wire it manually:

import dotignore from "eslint-plugin-dotignore";

export default [
  {
    files: ["**/.gitignore"],
    plugins: { dotignore },
    language: "dotignore/gitignore",
    rules: {
      "dotignore/sort-patterns": "warn",
      "dotignore/group-patterns": "warn",
    },
  },
];

Rules

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
✅ Set in the recommended configuration.
🔒 Set in the strict configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

| Name                        | Description | 💼 | ⚠️ | 🔧 | 💡 | | :----------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :---- | :-- | :-- | :-- | | comment-spacing | enforce consistent spacing after '#' in comments | 🔒 | ✅ | 🔧 | | | group-patterns | group directory-only patterns and file patterns under configurable headings | 🔒 | | 🔧 | | | leading-slash-style | enforce a consistent leading-slash style for anchored patterns | 🔒 | ✅ | 🔧 | | | max-consecutive-blank-lines | limit consecutive blank lines | 🔒 | ✅ | 🔧 | | | no-backslash-path | disallow backslash as a path separator | ✅ 🔒 | | | 💡 | | no-duplicate-pattern | disallow duplicate and equivalent patterns | ✅ 🔒 | | 🔧 | | | no-empty-group | disallow group headings with no patterns under it | 🔒 | ✅ | 🔧 | | | no-empty-path-segment | disallow empty path segments | ✅ 🔒 | | | 💡 | | no-invalid-syntax | disallow patterns that violate the gitignore specification | ✅ 🔒 | | | | | no-misplaced-globstar | disallow '**' in positions where it loses its special meaning | ✅ 🔒 | | 🔧 | | | no-redundant-pattern | disallow patterns already covered by another pattern | ✅ 🔒 | | 🔧 | | | no-trailing-whitespace | disallow unescaped trailing whitespace | 🔒 | ✅ | 🔧 | | | no-unreachable-negation | disallow negations that Git can never apply | ✅ 🔒 | | | 💡 | | require-dir-slash | require a trailing slash on patterns that match existing directories | 🔒 | | 🔧 | | | sort-patterns | enforce alphabetical ordering of patterns | 🔒 | | 🔧 | |

Presets

• configs.recommended — spec violations and dead patterns as errors, whitespace and style hygiene as warnings. Reordering rules (sort-patterns, group-patterns) and the filesystem-aware require-dir-slash stay off — enable them deliberately.
• configs.strict — every rule as an error.

Using alongside Prettier

Formatter rules like prettier/prettier (from eslint-plugin-prettier) apply to every file their config matches — including .gitignore, which Prettier cannot parse. If you use such a setup, scope it to the files it understands:

import prettierRecommended from "eslint-plugin-prettier/recommended";

export default [
  { ...prettierRecommended, files: ["**/*.{js,ts,jsx,tsx}"] },
  dotignore.configs.recommended,
];

This applies to any rule that assumes JavaScript syntax — the same scoping every non-JavaScript ESLint language (JSON, Markdown, CSS) calls for.

The parser, standalone

The gitignore parser is exported on its own, free of any ESLint dependency:

import { parse } from "eslint-plugin-dotignore/parser";

const ast = parse("node_modules/\n!keep.txt\n");

Text in, AST out — every line classified as Pattern, Comment, or BlankLine, with exact ranges and locations. Useful for codemods, editor tooling, or anything else that needs to understand a .gitignore without string surgery.

License

MIT © Erdem Bircan