cloudparts

Commitizen (cz-cli)

A Node.js command, git cz, that replaces git commit with a set of prompts and assembles your answers into a message in the project’s chosen format, usually Conventional Commits.

What it is
Commit conventions
Type
Open source
Made by
Commitizen (Jim Cummins and contributors)
License
MIT
Facts checked
13 October 2026
Website Source code

What it is

Instead of typing a free-form message, you run git cz (or npx cz) and answer questions: what type of change, which scope, a short subject, a longer body, which issues it closes. Commitizen itself only provides the command and the prompt plumbing. The questions and the format come from an adapter, an npm module that a repository names in package.json under config.commitizen.path or in a .czrc file. The adapter gets an Inquirer.js instance to ask its questions and hands back a string, which Commitizen passes to git commit together with any other git commit flags you gave.

The usual adapter is cz-conventional-changelog, which writes messages in the Angular convention that became Conventional Commits (feat(search): add filter by price range) and caps the header line at 100 characters by default. Others add Jira ticket ids, emoji or fully custom questions. commitizen init cz-conventional-changelog --save-dev --save-exact installs an adapter and writes the config in one step. In a repository with no config, git cz behaves like plain git commit.

Commitizen is meant to run beside commit hooks, not replace them: it helps a contributor write a valid message up front, while a hook or CI check such as commitlint rejects invalid ones afterward. It can also run from Git’s prepare-commit-msg hook (cz --hook), so a plain git commit opens the prompts. Not to be confused with the Python project of the same name (commitizen-tools/commitizen), a separate tool that also provides a cz command and adds version bumping and changelog generation.

Why teams pick it

  • Contributors don’t have to read CONTRIBUTING.md to learn the message format: the prompts ask for each required field
  • Adapters are plain npm packages, so many repositories can share one convention, and teams can write their own
  • Pairs with tools that read the same format, such as commitlint (which ships a Commitizen adapter) and conventional-changelog, because the messages come out in the expected shape
  • cz --retry replays the last attempted message after a failing pre-commit hook, so you don’t re-answer every prompt

Watch out for

  • It only shapes messages from people who use it; anyone running plain git commit bypasses it, so enforcement still needs a commit-msg hook or a CI check
  • Node.js only: the README still lists testing against Node.js 12, 14 and 16, and you need npm to install it and its adapter
  • Development has slowed: the last feature release was 4.3.0 (January 2023, adding pnpm to init); 4.3.1 (September 2024) and 4.3.2 (June 2026) fixed bugs and dependencies
  • Running it from a Git hook needs exec < /dev/tty because hooks aren’t interactive, and with husky an npm script named commit makes precommit scripts run twice

How it fits with other technologies

Make a repository “Commitizen friendly” and commit through the prompts · bash

npm install --save-dev commitizen
npx commitizen init cz-conventional-changelog --save-dev --save-exact
# adds to package.json:
#   "config": { "commitizen": { "path": "cz-conventional-changelog" } }

git add src/search.ts
npx cz            # prompts for type, scope, subject, body and issues
# -> feat(search): add filter by price range

npx cz --retry    # reuse the last answers after a failed pre-commit hook

See it in a real stack

No architecture uses Commitizen (cz-cli) yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2015–2026

Projects with a structured commit format, such as AngularJS, whose commit guidelines the conventional-changelog tool was built around, documented the rules in a CONTRIBUTING file and relied on Git hooks to reject messages that broke them. Contributors had to dig the format out of the docs, or found out about it when a hook rejected their commit.

Jim Cummins published Commitizen to npm in April 2015 with a one-line description: “Git commit, but play nice with conventions.” Its first README set out the idea that still defines it: prompt contributors for the required fields at commit time instead of rejecting their commits later, and let each project pick a convention through an adapter, starting with cz-conventional-changelog for the Angular format. It described itself as a project that helps contributors be good open-source citizens.

Its README now points to conventional-changelog and commitlint as related projects, and commitlint ships its own Commitizen adapter. The configuration moved from a .cz.json file to package.json and .czrc, version 4.0.0 (July 2019) dropped Node.js 6 and 8, and 4.2.0 (August 2020) added the short cz binary name. Since 4.3.0 in January 2023 the project has mostly received maintenance releases.

Why it’s built this way

Prompt at commit time instead of rejecting afterward
Waiting for a hook to reject a message, or digging through CONTRIBUTING.md to find the format, made contributing harder. Asking for each field up front gives instant feedback.
Put the convention in a pluggable adapter
Every project and build process has different requirements, so Commitizen keeps only the command and delegates the questions and format to npm modules that many projects can share.
Work beside commit hooks, not instead of them
The authors treat committing as a declaration of intent to contribute; the maintainer decides the rules, and hooks remain useful to enforce them for people who don’t use the prompts.

Timeline

  1. 2015

    Commitizen 1.0 published to npm by Jim Cummins (April 20); 2.0.0 in October

  2. 2018

    3.0.0 (October 1)

  3. 2019

    4.0.0 drops Node.js 6 and 8 (July 18)

  4. 2020

    4.2.0 adds the cz binary name (August 24)

  5. 2023

    4.3.0 adds pnpm support to commitizen init (January 19)

  6. 2026

    4.3.2, a dependency update for npm trusted publishing (June 12)

Sources5 · facts checked 13 October 2026

Improve this page on GitHub