GitLint

Efficient Git Commit Message Linting and Formatting

GitLint is a tool for enforcing consistent Git commit message conventions. It analyzes commit messages to ensure they follow the Conventional Commits specification and other configurable rules.

Installation

# Install globally
npm install -g @stacksjs/gitlint

# Or using bun
bun install -g @stacksjs/gitlint

We are looking to get it published as gitlint on npm, but it's not allowing us to do so due to git-lint. Please npm 🙏🏽

Usage

CLI

# Check a commit message from a file
gitlint path/to/commit-message.txt

# Use with git commit message hook (common use case)
gitlint --edit $1

# Show help
gitlint --help

Git Hooks Integration

GitLint can automatically install Git hooks for your repository:

# Install the commit-msg hook
gitlint hooks --install

# Force overwrite if a hook already exists
gitlint hooks --install --force

# Uninstall the hooks
gitlint hooks --uninstall

Or manually add to your .git/hooks/commit-msg file:

#!/bin/sh
gitlint --edit "$1"

Or use with husky:

// package.json
{
  "husky": {
    "hooks": {
      "commit-msg": "gitlint --edit $HUSKY_GIT_PARAMS"
    }
  }
}

Configuration

Create a gitlint.config.js file in your project root:

// gitlint.config.js
module.exports = {
  verbose: true,
  rules: {
    'conventional-commits': 2,
    'header-max-length': [2, { maxLength: 72 }],
    'body-max-line-length': [2, { maxLength: 100 }],
    'body-leading-blank': 2,
    'no-trailing-whitespace': 1
  },
  ignores: [
    '^Merge branch',
    '^Merge pull request'
  ]
}

Rule Levels

• 0 or off: Disable the rule
• 1 or warning: Warning (doesn't cause exit code to be non-zero)
• 2 or error: Error (causes exit code to be non-zero)

Built-in Rules

• conventional-commits: Enforces conventional commit format (<type>(scope): description)
• header-max-length: Enforces a maximum header length
• body-max-line-length: Enforces a maximum body line length
• body-leading-blank: Enforces a blank line between header and body
• no-trailing-whitespace: Checks for trailing whitespace

Programmatic Usage

import { lintCommitMessage, parseCommitMessage } from '@stacksjs/gitlint'

// Lint a commit message
const result = lintCommitMessage('feat: add new feature')
console.log(result.valid) // true or false
console.log(result.errors) // array of error messages
console.log(result.warnings) // array of warning messages

// Parse a commit message
const parsed = parseCommitMessage('feat(scope): description\n\nBody text\n\nCloses #123')
console.log(parsed.type) // 'feat'
console.log(parsed.scope) // 'scope'
console.log(parsed.references) // [{issue: '123', ...}]

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙