Overview

Commit Sentinel is a configurable git commit-msg hook that validates commit messages, branch names, and file scopes before allowing commits to proceed. When validation fails, it provides clear feedback and intelligent suggestions for fixes. The tool helps teams maintain consistent git conventions and catch common mistakes early — from verb tense and casing to conventional commit types and branch naming patterns.

Key Features

Technologies

Installation

npm install --save-dev commit-sentinel
npx commit-sentinel install

The install command adds a commit-msg hook to .git/hooks. If a hook already exists, commit-sentinel is chained to preserve existing functionality.

Configuration Example

Create .commit-sentinel.json in your project root or run npx commit-sentinel init:

{
  "commits": {
    "enabled": true,
    "enforce": true,
    "tense": "imperative",
    "case": "sentence",
    "minLength": 10,
    "maxLength": 72,
    "noTrailingPeriod": true,
    "noGenericMessages": true,
    "requireType": false,
    "allowedTypes": ["feat", "fix", "docs", "chore", "refactor"],
    "forbiddenWords": ["WIP", "wip", "fixup"]
  },
  "branches": {
    "enabled": true,
    "enforce": true,
    "allowedPrefixes": ["feature", "bugfix", "hotfix"],
    "requireTicketNumber": true,
    "ticketPattern": "[0-9]{4,}",
    "namingPattern": "kebab-case",
    "exempt": ["main", "develop", "release-*"]
  },
  "scope": {
    "enabled": false,
    "rules": []
  }
}

Usage Example

When a commit fails validation, Commit Sentinel provides clear error messages and suggestions:

❌  Commit blocked by commit-sentinel

Commit: "added login screen"

- Verb tense is wrong. Required: imperative mood (e.g. "Add feature")
- Subject case is wrong. Required: Sentence case (first letter capitalised)

💡 Suggestions:
   Try: "Add login screen"

Technical Highlights

• Composable Hooks: Intelligently chains with existing git hooks instead of overwriting them, preserving your workflow
• Flexible Enforcement: Every check supports warn-only mode (enforce: false) for gradual adoption in existing projects
• CLI Commands: Includes validate, validate-branch, install, uninstall, and init commands for manual testing and CI integration
• Programmatic API: Export CommitSentinel class for custom integrations and automated workflows
• Smart Suggestions: Context-aware auto-corrections for common mistakes (case conversion, verb conjugation, trailing periods)

CLI Commands

# Install the git hook
npx commit-sentinel install

# Remove the hook
npx commit-sentinel uninstall

# Manually validate a commit message (useful in CI)
npx commit-sentinel validate "feat: add login screen"

# Manually validate a branch name
npx commit-sentinel validate-branch "feature/1234-add-login"

# Generate a default config file
npx commit-sentinel init

Preset Examples

{
  "commits": {
    "requireType": true,
    "allowedTypes": ["feat", "fix", "docs", "chore", "refactor", "test"],
    "tense": "imperative",
    "case": "lower",
    "maxLength": 72
  }
}

{
  "scope": {
    "enabled": true,
    "enforce": true,
    "rules": [
      { "path": "src/shared/**", "name": "shared code" },
      { 
        "path": "db/migrations/**", 
        "message": "Database migrations should be committed separately" 
      }
    ]
  }
}

{
  "commits": {
    "tense": null,
    "case": null,
    "minLength": 8,
    "maxLength": 100,
    "forbiddenWords": ["WIP", "wip", "TODO", "FIXME"]
  },
  "branches": {
    "enabled": false
  }
}

← Back to ProjectsView on GitHub →