stacksjs
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
0oroff: Disable the rule1orwarning: Warning (doesn't cause exit code to be non-zero)2orerror: 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 lengthbody-max-line-length: Enforces a maximum body line lengthbody-leading-blank: Enforces a blank line between header and bodyno-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:
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.
License
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙