{"id":18547960,"url":"https://github.com/jvanbruegge/commithelper","last_synced_at":"2025-10-20T02:48:56.011Z","repository":{"id":57204201,"uuid":"347105745","full_name":"jvanbruegge/commithelper","owner":"jvanbruegge","description":"A tool to create and lint commit messages","archived":false,"fork":false,"pushed_at":"2021-10-15T13:57:51.000Z","size":300,"stargazers_count":35,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T08:33:50.630Z","etag":null,"topics":["commit-message","conventional-commits","git-hooks"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jvanbruegge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-12T15:08:28.000Z","updated_at":"2022-12-24T04:17:54.000Z","dependencies_parsed_at":"2022-09-18T00:21:32.134Z","dependency_job_id":null,"html_url":"https://github.com/jvanbruegge/commithelper","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvanbruegge%2Fcommithelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvanbruegge%2Fcommithelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvanbruegge%2Fcommithelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvanbruegge%2Fcommithelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jvanbruegge","download_url":"https://codeload.github.com/jvanbruegge/commithelper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247965559,"owners_count":21025398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commit-message","conventional-commits","git-hooks"],"created_at":"2024-11-06T20:32:32.440Z","updated_at":"2025-10-20T02:48:50.963Z","avatar_url":"https://github.com/jvanbruegge.png","language":"TypeScript","readme":"# Commithelper\n\n[![Build](https://github.com/jvanbruegge/commithelper/actions/workflows/ci.yml/badge.svg)](https://github.com/jvanbruegge/commithelper/actions/workflows/ci.yml)\n\nA tool to create and lint commit messages. It has two modes `prompt` and `check`. The former asks you questions to create a well-formed commit message, while the latter lints a given commit message.\n\n![A screenshot of a terminal showing the tool](./console.png)\n\n## Table of contents:\n\n-   [Usage](https://github.com/jvanbruegge/commithelper#usage)\n-   [Comparison with other tools](https://github.com/jvanbruegge/commithelper#comparison-with-other-tools)\n    -   [commitlint](https://github.com/jvanbruegge/commithelper#commitlint)\n    -   [commitizen](https://github.com/jvanbruegge/commithelper#commitizen)\n-   [Setup](https://github.com/jvanbruegge/commithelper#setup)\n    -   [Setup with ghooks](https://github.com/jvanbruegge/commithelper#setup-with-ghooks)\n    -   [Setup with husky](https://github.com/jvanbruegge/commithelper#setup-with-husky)\n-   [Config File](https://github.com/jvanbruegge/commithelper#config-file)\n\n## Usage\n\nFirst add `commithelper` as a dev dependency to your project with `npm install commithelper --save-dev`.\n\n```\ncommithelper prompt [--file \u003cpath\u003e] [--config \u003cpath\u003e]\n```\n\nInteractively asks the user questions to create a commit message. Use the `--file` option to specify a path to write the final message to. If omitted the message is printed to stdout. If the path already contains a file that only contains comments (lines starting with `#`) this file is overwritten, but all comment lines (starting with `#`) are kept. If the path contains a file with non-comment lines no questions are asked and program exits sucessful. This is useful when other tooling is creating the commit message or when using `git commit --amend`. Use the `--config` option to specify where to find the config file. If this is omitted, the config is read from the `commithelper` field in the `package.json`.\n\n```\ncommithelper check [--file \u003cpath\u003e] [--fix] [--config \u003cpath\u003e]\n```\n\nLints a commit message according to the configuration. Use `--file` to specify where to find the file containing the commit message. If omitted the message is read from stdin. Use `--fix` to try to automatically fix the commit message to pass linting. This means it will correct capitalization of the subject and correctly wrap the body of the message. Use `--config` to specify where to find the config file. If this is omitted, the config is read from the `commithelper` field in the `package.json`.\n\nIt is recommended to use [git hooks](https://git-scm.com/docs/githooks) with this tool. There are several npm packages that help you set up git hooks automatically, e.g. [husky](https://github.com/typicode/husky) or [ghooks](https://github.com/ghooks-org/ghooks).\n\nUse the `prepare-commit-msg` hook with the `prompt` mode to interactively create a commit message and use the `commit-msg` hook for the `check` mode.\n\n## Comparison with other tools\n\n### commitlint\n\nThe [commitlint](https://github.com/conventional-changelog/commitlint) package and its plugins are only suited to check an existing commit message against a set of rules. While there is `@commitlint/prompt-cli`, it just states that the commits have to have the form `\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e` without telling you what the valid options are, so it is pretty useless.\n\nAlso it is very complicated to configure as many rules available are barely documented at all.\n\n### commitizen\n\nThe quesions in the `prompt` mode of `commithelper` is heavily inspired by [commitizen](https://github.com/commitizen/cz-cli). But commitizen can't lint an existing commit message, so if the user is using the git client built into their editor or provides the message with `git commit -m` commitizen can't help.\n\nAlso, by default commitizen requires one of several adapters, each with their own configuration options which makes setting it up quite complicated.\n\n## Setup\n\n### Setup with ghooks\n\nInstall ghooks in your project with `npm install ghooks --save-dev`. Then add `config.ghooks` to `package.json` like this:\n\n```json\n{\n  …\n  \"config\": {\n    \"ghooks\": {\n      \"prepare-commit-msg\": \"exec \u003c /dev/tty \u0026\u0026 npm exec -- commithelper prompt --file $1\",\n      \"commit-msg\": \"commithelper check --file $1 --fix\",\n      …\n    }\n  }\n  …\n}\n```\n\n### Setup with husky\n\nInstall husky in your project with `npm install husky --save-dev`. Then add a `prepare` script to your `package.json` that installs the husky hooks.\n\n```json\n{\n  \"scripts\": {\n    …,\n    \"prepare\": \"husky install\"\n  }\n}\n```\n\nThen add a new executable file `.husky/prepare-commit-msg` with the content:\n\n```sh\n#!/bin/sh\n. \"$(dirname \"$0\")/_/husky.sh\"\n\nexec \u003c /dev/tty \u0026\u0026 npm exec commithelper -- prompt --file $1\n```\n\nand a new executable file `.husky/commit-msg` with the content:\n\n```sh\n#!/bin/sh\n. \"$(dirname \"$0\")/_/husky.sh\"\n\nnpm exec commithelper -- check --file $1 --fix\n```\n\nThen run `npm run prepare` to install the hooks in your project.\n\n## Config file\n\nYou can either have a seperate json file and use the `--config` option to point `commithelper` to it, or omit `--config` and add a `commithelper` field in your `package.json`. The config object has the following fields:\n\n| key                      | type                                                          | default                                   | description                                                                                                                                                                                             |\n| ------------------------ | ------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **subjectLimit**         | `number`                                                      | `100`                                     | The maximum number of characters that the git subject line (first line of the commit message) is allowed to have. This is including the `type` and the `scope`                                          |\n| **subjectSeperator**     | `string`                                                      | `':'`                                     | The character to seperate `type` and `scope` from the subject. E.g. with '/' the message would look like `\u003ctype\u003e(\u003cscope\u003e)/\u003csubject\u003e`. May not be the empty string                                       |\n| **typePrefix**           | `string`                                                      | `''`                                      | A string that is added before the `type`, e.g. with '[', the message would look like `[\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e`                                                                                      |\n| **typeSuffix**           | `string`                                                      | `''`                                      | A string that is added after the `type`, e.g. with ']', the message would look like `\u003ctype\u003e](\u003cscope\u003e): \u003csubject\u003e`                                                                                       |\n| **types**                | `(string \\| { name: string, message: string })[]`             | _default names_: ['feat', 'fix', 'chore'] | All the commit types that are allowed for this repo. `name` is what will be at the place of `\u003ctype\u003e` in the commit message, `message` is the explanation presented to the user during `prompt` mode     |\n| **scopes**               | `(string \\| { name: string, message: string })[]`             | `[]`                                      | All the scopes that are allowed for all of the commit types                                                                                                                                             |\n| **scopeOverrides**       | `{ [type]: (string \\| { name: string, message: string })[] }` | `{}`                                      | Override the allowed scopes for a particular commit `type`. If this is set for a particular `type` the array defined here is used as allowed scopes instead of the array defined in the `scopes` option |\n| **allowCustomScopes**    | `boolean`                                                     | `false`                                   | Set this to true if the user is allowed to write out a scope that is not on the list of allowed scopes                                                                                                  |\n| **bodyWrap**             | `number`                                                      | `72`                                      | The maximum line length that is allowed in the commit body, wraps the body accordingly with `--fix` or in `prompt` mode                                                                                 |\n| **ticketPrefix**         | `string`                                                      | `'ISSUES CLOSED:'`                        | The string that marks the list of tickets that this commit closes. May not be the empty string                                                                                                          |\n| **ticketNumberPrefix**   | `string`                                                      | `'#'`                                     | A string that is in front of the ticket number. The default is useful for GitHub issues which start with `#` (e.g. `#134`). Use e.g. 'JIRA-' for other numbering systems                                |\n| **ticketSeperator**      | `string`                                                      | `','`                                     | The string which is used to seperate multiple ticket numbers in the same line                                                                                                                           |\n| **breakingPrefix**       | `string`                                                      | `'BREAKING CHANGES:'`                     | The string that should start the description of a breaking change. May not be the empty string                                                                                                          |\n| **breakingRequiresBody** | `boolean`                                                     | `false`                                   | Set this to `true` to require a commit with a breaking change to also have a body in addition to the note describing the breaking change                                                                |\n| **allowBreakingChanges** | `string[]`                                                    | `['feat', 'fix']`                         | The commit `types` that are allowed to have breaking changes. Use the empty array to allow breaking changes for all types                                                                               |\n| **upperCase**            | `boolean`                                                     | `false`                                   | Set this to `true` to require the first letter of the `\u003csubject\u003e` to be upper case (requires lower case when set to `false`)                                                                            |\n| **skipQuestions**        | `('body' \\| 'breaking' \\| 'issuesClosed')[]`                  | `[]`                                      | Do not ask the user for a body, breaking changes or closed issues                                                                                                                                       |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvanbruegge%2Fcommithelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjvanbruegge%2Fcommithelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvanbruegge%2Fcommithelper/lists"}