---
# System prepended metadata

title: Commit Management
tags: [commitizen, git, commit, husky, commitlint, github, conventional commits]

---

# Commit Management

<img src="https://hackmd.io/_uploads/HyIDqtWjT.jpg" alt="The image is designed for an article cover about Commit Management and Conventional Commits" style="float: left; width: 50%; margin: 0 2rem 1rem 0; border-radius: 6px"/>

This document outlines the setup of three key tools designed to automate and standardize the commit process in your project. [`Commitizen`](https://www.npmjs.com/package/commitizen#making-your-repo-commitizen-friendly) is utilized for crafting commit messages that adhere to a predefined format, making the change log more readable and the versioning process smoother. [`CommitLint`](https://commitlint.js.org/#/) then checks these commit messages for compliance with the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format, ensuring consistency across the project's history. [Husky](https://typicode.github.io/husky/) intervenes at the pre-commit stage, running checks to verify that the commit messages meet the required standards before allowing a commit to proceed. Together, these tools streamline your workflow, enforcing a disciplined approach to commit messaging that enhances project maintainability and collaboration.

## Installation

- Create a new repository [^1]

Start by initializing your project and creating a new git repository. This sets the foundation for your project's version control.

`yarn`: 
```bash
yarn init -y
git init
```
`npm`: 
```bash
npm init -y
git init
```

- Set up `.gitignore` [^1]

Remember to add a `.gitignore` file to keep unnecessary files out of your repository. You can find templates for `.gitignore` files tailored to various development environments [here](https://github.com/github/gitignore).

[^1]: Skip this item if you are adding commit instruments to an existing repo

- Install `Commitizen` in your new repo

Incorporate `Commitizen` into your project to streamline the creation of commit messages according to the `conventional commit` format.

`yarn`: 
```shell
yarn add -D commitizen
```
`npm`:
```shell
npm i -D commitizen
```

- Initialize the conventional changelog adapter

This step integrates the conventional changelog adapter with `Commitizen`, ensuring your commit messages adhere to standard conventions.

`yarn`: 
```shell
npx commitizen init cz-conventional-changelog --yarn --dev --exact
```
`npm`:
```shell
npx commitizen init cz-conventional-changelog --save-dev --save-exact
```

- Create a `Commitizen` script in `package.json`

Add a script to your `package.json` to facilitate easy commit message creation through `Commitizen`.

```json
"scripts": {
  "commit": "git add . & cz"
},
```

- Install `commitlint`

`commitlint` checks if your commit messages meet the conventional commit format. This step is crucial for maintaining a clean commit history.

`yarn`:
```shell
yarn add -D @commitlint/{cli,config-conventional}
```
`npm`:
```shell
npm i -D @commitlint/{cli,config-conventional}
```

- Configure `commitlint` to use the `conventional commits` config

By configuring `commitlint` with the `conventional commits` standard, you ensure your project's commits are consistently formatted and meaningful.

```shell
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.cjs
```

- Install and initialize `Husky`

`Husky` makes git hooks easy, allowing you to enforce commit message standards before commits are finalized.
`yarn`:
```shell
yarn add -D husky
yarn husky init
```
`npm`:
```shell
npm i -D husky
npx husky init
```

- Consider removing the unused `husky` pre-commit file

After initializing `Husky`, you might find a `pre-commit` hook that's not needed. Feel free to delete this if it doesn't serve your project.

- Ensure every commit message is checked for conformity by adding a linting command to the `commit-msg` hook.

`yarn`:
```shell
echo "yarn commitlint --edit \$1" > .husky/commit-msg
```
`npm`:
```shell
echo "npx commitlint --edit \$1" > .husky/commit-msg
```

- Make the created file executable

```shell
chmod +x .husky/commit-msg
```

## Making Commits

- Test a failing commit

Try making a commit with a message that doesn't follow the conventional format to see how `commitlint` catches errors.

```shell
git add .
git commit -m "foo: this will fail"
```

You should see an error message like this:

```text
input: foo: this will fail
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
```

- Run the script and complete the commit details

Use the `yarn commit` script to invoke `Commitizen`, which guides you through creating a properly formatted commit message.

`yarn`:
```shell
yarn commit
```
`npm`:
```shell
npm run commit
```

```
? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests
```

- Enjoy making conventional commits

With these tools in place, you're all set to create clear, consistent, and conventional commits that enhance project maintainability and collaboration.
