How to fix commit-msg hook failure in Git

The commit-msg hook typically outputs exactly what's wrong with your message. Look for output like:

husky - commit-msg hook exited with code 1 (error)
subject may not be empty [subject-empty]
type must be one of [feat, fix, docs, style, refactor, test, chore] [type-enum]

This tells you exactly which rules your message violated.

If your project uses Conventional Commits, format your message as:

<type>(<optional scope>): <description>

[optional body]

[optional footer]

Valid types include:
- feat: - New feature
- fix: - Bug fix
- docs: - Documentation changes
- style: - Formatting, no code change
- refactor: - Code restructuring
- test: - Adding/updating tests
- chore: - Maintenance tasks

Examples of valid messages:

git commit -m "feat: add user authentication"
git commit -m "fix(api): resolve null pointer in login handler"
git commit -m "docs: update README with installation steps"

When a commit fails, your message is saved to .git/COMMIT_EDITMSG. You can recover and edit it:

# View your rejected message
cat .git/COMMIT_EDITMSG

# Create a new commit with the saved message, opened in editor
git commit -e -F .git/COMMIT_EDITMSG

Or create an alias for easy recovery:

git config alias.recommit '!git commit -F "$(git rev-parse --git-dir)/COMMIT_EDITMSG" --edit'

# Then use:
git recommit

If you suspect the hook itself is broken, inspect it:

# View the hook script
cat .git/hooks/commit-msg

# Or if using Husky
cat .husky/commit-msg

Common issues to look for:
- Wrong shebang line (should be #!/usr/bin/env sh or similar)
- Script not executable (chmod +x .git/hooks/commit-msg)
- Windows line endings causing "cannot execute binary file" error
- Missing dependencies (commitlint not installed)

Fix permissions:

chmod +x .git/hooks/commit-msg
# Or for Husky
chmod +x .husky/commit-msg

If you see "cannot execute binary file" or similar, the hook file likely has Windows (CRLF) line endings:

# Check for CRLF endings
file .husky/commit-msg

# Convert to Unix line endings
sed -i 's/\r$//' .husky/commit-msg

# Or using dos2unix
dos2unix .husky/commit-msg

Ensure your editor and Git are configured for LF:

git config --global core.autocrlf input

If you need to commit urgently and will fix the message later:

git commit --no-verify -m "WIP: temporary commit"

Warning: Use this sparingly. The hook exists for a reason, and bypassing it regularly defeats its purpose. Some CI/CD pipelines will still validate commit messages and reject non-compliant ones.

If using commitlint, ensure it's properly configured:

# Check if commitlint.config.js exists
cat commitlint.config.js

A basic configuration should look like:

module.exports = {
  extends: ['@commitlint/config-conventional'],
};

Test your message manually:

echo "feat: test message" | npx commitlint

If commitlint isn't installed:

npm install --save-dev @commitlint/cli @commitlint/config-conventional