eslint-plugin-diff

2.1.7 verified Sat Apr 25 auth: no javascript

ESLint plugin that filters lint output to only show errors on changed lines of code. Version 2.1.7 actively maintained, semver releases. Differentiators: works with both flat config (ESLint 9+) and legacy config, supports multiple modes (diff, ci, staged), includes CI autodetection with provider-based target branch detection. Ships TypeScript types. Requires eslint >=6.7.0 and node >=14.0.0. Does not provide custom rules, only processors and config presets.

Common errors

error Error: Cannot find module 'eslint-plugin-diff' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install --save-dev eslint-plugin-diff'.

error Configuration for rule 'diff/diff' is invalid ↓

cause Using the plugin name 'diff' in config but plugin not registered.

fix

Add 'plugins: [diff]' or use 'plugin:diff/diff' extends preset.

error fatal: not a git repository (or any of the parent directories): .git ↓

cause eslint-plugin-diff requires a git repository to compute diff.

fix

Initialize a git repository with 'git init' or run ESLint on a git repo.

Warnings

gotcha For staged mode, files with unstaged changes will emit a fatal error and block linting. ↓

fix Stage or revert unstaged changes before running ESLint in staged mode.

breaking v2.0.0 migrated from legacy config to flat config internally; old require() usage may break. ↓

fix Use ESM import instead of require; update config to use configs['flat/*'] if on ESLint 9.

gotcha In CI mode, if ESLINT_PLUGIN_DIFF_COMMIT is not set, the plugin fetches from origin, which may fail in shallow clone environments. ↓

fix Explicitly set ESLINT_PLUGIN_DIFF_COMMIT to a commit you have locally, or ensure full git history.

deprecated ESLint <6.7.0 is no longer supported as of v2.0.0. ↓

fix Upgrade eslint to >=6.7.0.

gotcha The plugin uses git diff internally; if git is not installed or the project is not a git repo, it throws an error. ↓

fix Run lint only in a git repository with git installed.

Install

npm install eslint-plugin-diff

yarn add eslint-plugin-diff

pnpm add eslint-plugin-diff

Imports

default export

wrong

const diff = require('eslint-plugin-diff')

correct

import diff from 'eslint-plugin-diff'

ESM default import; package ships TypeScript types.

flat config preset
wrong
```
diff.configs.diff
```
correct
```
diff.configs["flat/diff"]
```
Access via bracket notation with flat/ prefix; 'diff' key does not exist directly.
legacy config preset
wrong
```
"extends": ["diff/diff"]
```
correct
```
"extends": ["plugin:diff/diff"]
```
Must include 'plugin:' prefix for ESLint to resolve plugin scoped configs.

Quickstart

Flat config example with eslint-plugin-diff in diff mode, filtering lint output to changed lines.

import diff from 'eslint-plugin-diff';

export default [
  {
    files: ['**/*.js', '**/*.ts'],
    rules: { semi: 'error' }
  },
  ...diff.configs['flat/diff']
];