Handling Hook Failures
You'll learn what happens when your pre-commit hooks fail and how to handle those situations gracefully.
When lint-staged runs during a Git commit and discovers linting errors or formatting issues, it fails the entire commit — nothing gets staged, and your commit is blocked. This is intentional: it prevents broken or poorly formatted code from entering your repository's history.
What Happens on Failure
When ESLint or Prettier detects unfixable issues, lint-staged exits with a non-zero status code. Git sees this failure and aborts the commit. You'll see error messages in your terminal explaining what went wrong — usually specific rule violations or files that couldn't be auto-formatted.
How to Fix It Properly
The correct approach is to address the issues:
- Read the error messages to identify which rules failed
- Fix the code manually if
--fixcouldn't handle it - Re-stage your changes with
git add - Attempt the commit again
Think of it like airport security: if your bag triggers an alarm, you can't just skip the check — you need to resolve the issue before proceeding.
Emergency Bypass
In rare emergencies (production hotfixes, urgent reverts), you can bypass hooks:
git commit --no-verify -m "Emergency fix"
The --no-verify flag skips all pre-commit hooks. Use this sparingly — it defeats the purpose of having quality gates and should be documented in your commit message.
Best Practices
- Fix issues properly rather than bypassing
- If bypassing, document why in your commit message
- Review bypassed commits immediately after the emergency
- Configure your hooks to be fast enough that developers won't be tempted to skip them
Key Takeaway: Hook failures are protective guardrails — fix the underlying issues rather than routinely bypassing them, reserving --no-verify only for genuine emergencies.