cz-git and czg: a Commitizen adapter that reads your commitlint config

The problem cz-git solves: a prompt that already knows your commitlint rules

Commitizen prompts you for a commit message. The default experience is a fixed set of questions with no awareness of the rules your repository enforces. You pick a type, you type a scope, and then commitlint rejects the result because the scope is not in your allowed list or the subject is too long. The prompt and the linter disagree, and the developer pays for it in a second attempt.

cz-git is a Commitizen adapter, which in Commitizen terms means it replaces the interactive plugin behind the commitizen command. The README describes the project as "DX first and more engineered, lightweight, customizable, standard output format" and states that the output follows the Conventional Commits specification. The engineering part is the interesting claim: the adapter is built to work with commitlint projects and, per the README, to "give relevant verification information to the command line." In other words, the prompt is meant to reflect the rules you already wrote down.

The audience is narrow and specific. This is for teams that have already decided on Conventional Commits and commitlint, use Node, and want the interactive path to be consistent with the CI check. If you have no commitlint config, you lose most of the reason to pick this adapter over a simpler one.

Two entry points: the adapter and the czg CLI

The repository ships two things that are easy to confuse. The first is cz-git, the Commitizen adapter, installed as a development dependency. The second is czg, a standalone CLI, installed globally. The README shows both installs with their reported package sizes:

$ npm i -D cz-git
+ cz-git          (1.76 MB)
added 1 package in 0.552s

$ npm i -g czg
+ czg             (1.32 MB)
added 1 package in 0.531s

The adapter route means you keep running the commitizen command and cz-git answers from behind it. The CLI route means you run czg directly and skip the commitizen layer. The README links separate "Why cz-git" and "Why czg" pages, which suggests the maintainers treat the choice as a real decision rather than a packaging detail. The practical difference is the size of your dependency tree and whether your team already has commitizen in its workflow. There is also a Homebrew formula for czg, referenced from the README badges, so macOS users have a path that does not involve a global npm install.

The monorepo layout supports this split. The top level holds a pnpm workspace with packages/ and scripts/ directories, a tsup.config.ts for bundling, and a vitest.config.ts for tests. The root package.json is marked private and lists scripts such as gen:schema, which generates the czrc schema, and docs:update. That schema generation matters more than it looks: it means the configuration surface is machine-described, which is how editors can offer completion inside your config file.

Installing cz-git and making a first commit with czg

The README points to https://cz-git.qbb.sh/guide/ for installation and https://cz-git.qbb.sh/cli/ for the CLI. The commands below are the ones quoted in the README itself.

For the CLI path, install czg globally and then run it inside a repository. The README's own package.json uses czg for its release commits under the script name "x", which is a fair signal that the CLI is the maintainers' own daily path:

npm i -g czg
czg

Running czg opens the interactive prompt. You should see a list of commit types to search and select, then a scope question, then a subject line. The README states that the tool supports search and selection on the command line, which is the feature aimed at reducing spelling errors.

For the adapter path, install cz-git as a development dependency and point Commitizen at it. The adapter is what Commitizen loads when you run the commitizen command:

npm i -D cz-git

Configuration lives in a czrc file, and the repository generates a schema for it via the gen:schema script. The README does not spell out the full config key list in the section available here; the schema file is the authoritative source, and the docs site is where the key reference lives. If you already have a commitlint.config.mjs, the adapter is designed to read the rules from it, so the first thing to verify after install is that the scopes and types shown in the prompt match the ones your linter enforces.

Monorepo scopes, emoji, and issue prefixes

Three features in the README deserve separate attention because they are the ones that change day to day behaviour.

The first is monorepo scope handling. The README says the adapter is "better for monorepo engineering" and links a recipes page for scopes. In a workspace with many packages, the scope list is the part of the prompt that goes stale fastest. An adapter that derives scopes from the repository rather than from a hand-maintained array is a genuine improvement, though the README does not state the derivation mechanism in the text available here, so treat the recipes page as required reading before you rely on it.

The second is emoji support. The README lists "Support commit with emoji" as a feature, and the repository topics include both emoji and emojis. Emoji in commit messages is a team preference, not a correctness issue, but it interacts with tooling: some changelog generators and terminal renderers handle it differently from plain text. Decide once and put it in the config rather than letting it drift per commit.

The third is issue linking. The README mentions better linking with issuePrefix "for issue", and the recipes link is named default-issues. This is the feature that turns a commit into a clickable reference in your tracker. It only pays off if your team actually uses the prefix convention consistently, which means it belongs in the shared config, not in individual habits.

OpenAI-generated commit messages and what that costs you

The README lists "OpenAI support" with the line "Let the AI generate your git commit message." This is the feature most likely to divide a team, and the documentation available here does not describe the request shape, the model used, or what gets sent. Before enabling it, you need answers the README does not provide: which endpoint receives the diff, whether the diff leaves your network, and what happens when the API call fails or returns something that does not parse as a Conventional Commit.

The failure mode is worth stating plainly. An AI-generated subject that passes commitlint is not the same as a subject that is accurate. Commitlint checks shape, not truth. If your team's review process depends on commit messages describing intent, a generated message that satisfies the regex is a weaker signal than a human one. The feature is opt-in and the README presents it as one capability among several, so the reasonable default is to leave it off until someone owns the review of what it produces.

Where cz-git is the wrong tool

The clearest limitation is the Node dependency in the commit path. Both cz-git and czg are distributed through npm, and the README's install instructions are npm commands. If your repository has contributors who work without Node installed, or if your CI environment is deliberately minimal, an interactive Node prompt is a poor fit. A commit-msg hook that validates with a shell script has no such dependency.

The second limitation is philosophical. cz-git improves the interactive prompt. It does not replace commitlint, and the README positions the two as complementary. If your actual problem is that commits reach main with bad messages, the interactive prompt is not the control that stops them; the hook and the CI check are. Teams sometimes adopt a nicer prompt and assume the enforcement problem is solved, which it is not.

The third is configuration surface. The repository generates a czrc schema, which implies a config file with many keys. A large config surface is a maintenance cost, and the docs site is where that cost is documented. If your team will not read the config reference, you will end up with defaults you did not choose.

Alternatives and the real difference in approach

Commitizen's own default adapter is the baseline comparison. It asks the same category of questions but does not read your commitlint configuration, so the prompt and the linter can disagree. cz-git's stated value is closing that gap. If you have no commitlint config, the default adapter is simpler and you give up little.

cz-customizable is the other reference point, and the root package.json keyword list includes it alongside cz-git, cz-adapter, and cz-cli. The difference is where the configuration lives. cz-customizable is configured through its own dedicated file that describes the questions and the message template. cz-git leans on commitlint as the source of truth and generates a schema for its own czrc keys. If your team already treats commitlint.config.mjs as the canonical statement of commit rules, cz-git's approach avoids describing the same rules twice. If you would rather have one self-contained file that defines the whole prompt with no dependency on a linter config, the customizable approach is more direct.

Neither tool removes the need for a commit-msg hook. That is a separate layer in every case.

Maintenance, licence, and what to check before adopting

The repository is MIT licensed, stated in both the README badge area and the root package.json. MIT is permissive: you can use it commercially, modify it, and redistribute it, provided the copyright notice and licence text are preserved. That is the licence text, not legal advice; if your organisation has a policy on dependency licences, route it through whoever owns that policy.

Maintenance looks current rather than dormant. The last push was on 2026-08-22, and the most recent release, v1.14.0, is dated the same day. Before that, v1.13.2 landed on 2026-08-11 and v1.13.1 on 2026-05-09. The pattern is a burst of releases in August after a quieter May, which is normal for a project of this size and tells you the maintainer is still shipping. The repository is not archived.

Upgrade cost is the part worth thinking about before you commit. The project is a pnpm workspace with a root package.json that is private and versioned at 1.14.0, and the release script runs lint, tests, a version bump via bumpp, and a publish step. That is a well-instrumented release process, which is good news for consumers. The risk sits in the configuration: because the adapter reads commitlint rules and the czrc schema is generated by a script, a commitlint major upgrade can change what the prompt accepts. Pin your commitlint version in the lockfile and read the changelog before bumping it.

Editorial conclusion

Adopt cz-git if your repository already has a commitlint config and you want the interactive prompt to enforce it rather than duplicate it, and if a Node dependency in the commit path is acceptable. Skip it if contributors cannot install Node, or if you want the commit message format enforced outside the interactive prompt rather than inside it. Before rolling it out, run czg in a scratch clone and confirm that the scopes and rules you expect are the ones the prompt shows, because the adapter derives them from commitlint rather than from a separate list you maintain.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Zhengqbbb/cz-git on GitHub