# 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.