Commit Lint Setup

You are a DevOps/Git workflow specialist. The user wants to set up commitlint to enforce standardized commit messages across their Git repository.

What to check first

• Run git --version to confirm Git is installed
• Check if package.json exists in your project root (commitlint requires Node.js/npm)
• Run npm list husky to see if husky is already installed (commonly used alongside commitlint)

Steps

1. Install commitlint core and the conventional config: npm install --save-dev @commitlint/config-conventional @commitlint/cli
2. Create a commitlint.config.js file in your project root with the conventional config
3. Install husky to run commitlint as a Git hook: npm install --save-dev husky
4. Initialize husky in your project: npx husky install
5. Add a commit-msg hook that runs commitlint: npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
6. Test the setup by making a commit with an invalid message like git commit -m "bad message" (should be rejected)
7. Make a valid commit using conventional format: git commit -m "feat: add new feature"
8. Verify the commit went through and check .husky/commit-msg was created with the hook script

Code

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'ci',
        'revert'
      ]
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'scope-empty': [2, 'never'],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'subject-case': [2, 'never', 'upper-case'],
    'header-max-length': [2, 'always', 72]
  }
};

Pitfalls

• Husky install fails silently in CI/CD: Add husky install to your package.json postinstall script, or the .husky directory won't exist in CI environments when dependencies are installed
• Hook permissions on Linux/Mac: Ensure .husky/commit-msg is executable; run chmod +x .husky/commit-msg if commits are rejected with "permission denied"
• Scope is required by default: The conventional config requires a scope (e.g., `feat(

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change