ESLint Auto-Fix: Preview Changes Before You Commit

The problem: 400 lint errors and a tempting shortcut

You open a pull request and the CI lint check fails with hundreds of errors. A teammate suggests running eslint --fix to clean everything up in one command. It sounds efficient, but if you run it across the whole repository without looking, you may commit changes you did not intend.

The useful takeaway: ESLint's --fix flag is safe for mechanical style corrections when you preview it first, limit the files it touches, and review the result. It is not a substitute for human judgment on complex code.

What --fix actually changes

ESLint categorizes rules as fixable or non-fixable. A fixable rule includes an automatic correction function that ESLint can apply to your source code. Common examples include missing semicolons, inconsistent quotes, and unnecessary whitespace. Non-fixable rules—such as many logic or complexity rules—require manual editing.

This behavior applies to ESLint 8.x and 9.x. Configuration format differs between those versions, but the --fix behavior is consistent.

Worked example: preview before you apply

Run these commands from your project root. You need read and write access to the target files, and ideally a clean Git working tree so you can inspect and undo changes.

1. Confirm ESLint is installed

npx eslint --version

Expected check: a version number prints. If the command fails, install ESLint locally first.

2. Preview changes without modifying files

npx eslint --fix-dry-run 'src/**/*.js'

--fix-dry-run reports what would change but writes nothing to disk. Review the output for each file. If you see changes to logic or unexpected rewrites, stop and inspect those rules.

3. Apply fixes to a scoped set of files

npx eslint --fix 'src/components/Button.js' 'src/utils/format.js'

Replace the file paths with your own. Scoping to specific files or directories reduces the chance of surprise changes in unrelated code.

4. Review what changed

git diff --stat

Open the full diff and review every hunk. If something looks wrong, roll back.

5. Roll back if needed

Because --fix modifies files on disk, this is a state-changing operation. With Git, you can undo uncommitted changes:

git checkout -- .

or, on newer Git versions:

git restore .

Only run this after you have confirmed the changes are unwanted; it discards all uncommitted modifications.

Limitations and trade-offs

• Not every rule is fixable. Run --fix-dry-run first to see which issues remain after automatic correction.
• Complex patterns can produce unintended edits. Auto-fix may reformat code in ways that are syntactically correct but harder to read or inconsistent with team conventions.
• Large fixes create large commits. Fixing hundreds of files at once makes the diff hard to review and can obscure real changes in the same pull request.

Practical check: after running --fix, run your test suite and compare git diff against your expectations. If tests fail or the diff includes files you did not mean to touch, revert and fix those files manually.

Recommended workflow

1. Run npx eslint --version to confirm the tool is available.
2. Run --fix-dry-run on a small directory or file set.
3. Review the preview output.
4. Run --fix only on the files you intend to change.
5. Inspect git diff and run tests.
6. Commit only the intended lint fixes, ideally in a separate commit from feature work.

--fix is a helpful assistant, not an autopilot. Use it for style and formatting, keep humans in the loop for logic, and always review the diff before committing.