gitzy 🪄

> Interactive [conventional commits][conventional-commits] CLI, inspired by [git-cz][git-cz], with support for commitlint configuration, validation, and flexible setup. See features.

Gitzy CLI screenshot

_{Recorded with termsvg (glyphs look better IRL)}

![actions][actions-badge]
[![version][version-badge]][package]
[![downloads][downloads-badge]][npmtrends]
[![Install Size][install-size-badge]][packagephobia]
[![License][license-badge]][license]
[![Code Coverage][coverage-badge]][coverage]

- Features
- Usage
- Configuration
- Flags

Features

- Partial commitlint configuration support
- Config validation
- Multiple breaking-change formats (!, footer, both)
- Flexible emoji control
- Customizable type descriptions and emojis
- Dynamic scopes and types
- Friendly multiple issues support
- Retry (--retry) and dry-run (--dry-run) modes
- Git passthrough and hook support
- Flexible config discovery (package.json, .gitzyrc.*, .config/)
- ⚡ [Lightweight (~300 kB install)][packagephobia]

Usage

``sh-session npx gitzy

`or`


npm install -g gitzy
gitzy
gitzy -p -a
gitzy -m "added cool new feature" -t "feat" -s "amazing"
gitzy -lD --no-emoji


Configuration

By default, gitzy works out of the box and supports multiple configuration methods.

You can use a gitzy object in your package.json, or one of the following files:.gitzyrc, .gitzyrc.json, .gitzyrc.yaml, .gitzyrc.yml, .gitzyrc.js, .gitzyrc.cjs, gitzy.config.js, gitzy.config.cjs, .gitzyrc.mjs, or gitzy.config.mjs.

> [!NOTE] > All of these files can also live under a.config/ directory.

`Options`

The following configuration options are supported:

- breakingChangeEmoji - breakingChangeFormat - closedIssueEmoji - issuesHint - issuesPrefix - disableEmoji - details - headerMaxLength - headerMinLength - questions - scopes - types - useCommitlintConfig

`$3`

`sh feat: ✨ dope new feature

BREAKING CHANGE: 💥 breaks stuff`

`yml breakingChangeEmoji: "💥"`

`$3`

Allows you to customize the format of the breaking change indicator and prompt behavior.

- ! - Append !to the type/scope in the header and simply ask whether the change is a breaking change -footer - Prompt for a description and add a BREAKING CHANGEfooter (default) -both - Prompt for a description and add both an indicator (!) and a footer

#### Examples

`sh

`"!" format - adds ! to header, prompts for yes/no`


feat!: send an email to the customer when a product is shipped
"footer" format - prompts for description, adds to footer

feat: allow provided config object to extend other configs

BREAKING CHANGE: extends key in config file is now used for extending other config files

`"both" format - adds ! to header AND prompts for footer description`


chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.`

`yml breakingChangeFormat: "footer"

`Options: "!", "footer", or "both"`

$3

`sh fix: 🐛 resolved nasty bug

🏁 Closes #123`

`yml closedIssueEmoji: "🏁"`

`$3`

Allows you to customize the issues prompt hint.

`yml issuesHint: "#123, #456, resolves #789, org/repo#100"`

`$3`

Allows you to choose the issuesPrefix based on GitHub supported keywords.

`yml issuesPrefix: closes # must be one of close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved`

> [!TIP] > Specify multiple issues separated by commas:#123, #456, or with keywords: resolves #123, fixes #456, or cross-repo: org/repo#123.

`$3`

Disables all emojis; overrides breakingChangeEmoji, closedIssueEmoji, and emoji options.

`yml disableEmoji: false`

`$3`

Allows you to configure CLI and git message output by type. _Default emojis follow standards set by [gitmoji][gitmoji], except for refactor due to its narrower rendering in most terminals._

> [!CAUTION] > Emoji rendering varies by terminal. Some emojis (like ♻️) may cause alignment issues. Test custom emojis in your terminal before committing to them.

`yml details: chore: description: Other changes that don't modify src or test files emoji: "🤖" ci: description: Changes to CI configuration files and scripts emoji: "👷" docs: description: Add or update documentation. emoji: "📝" feat: description: A new feature emoji: "✨" fix: description: Fix a bug. emoji: "🐛" perf: description: Improve performance. emoji: "⚡️" refactor: description: Refactor code. emoji: "🔄" release: description: Deploy stuff. emoji: "🚀" revert: description: Revert changes. emoji: "⏪" style: description: Improve structure/format of the code. emoji: "🎨" test: description: Add or update tests. emoji: "✅"`

`$3`

`yml headerMaxLength: 64`

`$3`

`yml headerMinLength: 3`

`$3`

Allows you to toggle questions.

`yml questions: - type # Choose the type - scope # Choose the scope - subject # Add a short description - body # Add a longer description - breaking # Add a short description - issues # Add issues this commit closes, e.g. #123`

_scope question will not be shown if no scopes are provided._

`$3`

Allows you to provide a list of scopes to choose from.

`yml scopes: []`

_Will enable the scope question if scopes are provided._

`$3`

Allows you to provide a list of types to choose from. Further configurable via details.

`yml types: - chore - docs - feat - fix - refactor - test - style - ci - perf - revert - release`

`$3`

If enabled, uses Commitlint configuration for:

- types → [rules[type-enum][2]](https://commitlint.js.org/reference/rules#type-enum) -scopes → [rules[scope-enum][2]](https://commitlint.js.org/reference/rules#scope-enum) -headerMaxLength → [rules[header-max-length][2]](https://commitlint.js.org/reference/rules#header-max-length) -headerMinLength → [rules[header-min-length][2]](https://commitlint.js.org/reference/rules#header-min-length)

`yml useCommitlintConfig: false`

`Flags`

| Flag | Alias | Description | | -------------------------- | ----- | ------------------------------------------------------------------------------------- | |--version | -v| output the version number | |--body | -d| set body inline | |--breaking [breaking] | -b| mark as breaking; add message for "footer"/"both" formats, or the flag for "!" format | |--dry-run | -D| show commit message without committing | |--issues | -i| set issues inline | |--passthrough | -p | pass remaining arguments to git (e.g. after --) | |--scope | -s| set scope inline | |--subject | -m| set subject inline | |--type | -t| set type inline | |--commitlint | -l| leverage local commitlint config | |--retry | -r| retry last commit and skip prompts | |--no-emoji| | disable all emojis | |--hook | -H| enable running inside a git hook (e.g. pre-commit) | |--skip | -S| skip prompts (choices: "type", "scope", "subject", "body", "breaking", "issues") | |--help | -h` | display help for command |

Credits

- git-cz by streamich

[actions-badge]: https://img.shields.io/github/actions/workflow/status/jimmy-guzman/gitzy/release.yml?branch=main&style=flat-square&logo=github
[version-badge]: https://img.shields.io/npm/v/gitzy?style=flat-square&logo=npm
[package]: https://www.npmjs.com/package/gitzy
[downloads-badge]: https://img.shields.io/npm/dm/gitzy?style=flat-square&logo=npm
[npmtrends]: https://www.npmtrends.com/gitzy
[gitmoji]: https://gitmoji.carloscuesta.me/
[license]: https://github.com/jimmy-guzman/gitzy/blob/master/LICENSE
[license-badge]: https://img.shields.io/github/license/jimmy-guzman/gitzy?style=flat-square&logo=open-source-initiative
[conventional-commits]: https://www.conventionalcommits.org/
[git-cz]: https://github.com/streamich/git-cz
[coverage-badge]: https://img.shields.io/codecov/c/github/jimmy-guzman/gitzy?style=flat-square&logo=codecov
[coverage]: https://codecov.io/github/jimmy-guzman/gitzy
[packagephobia]: https://packagephobia.com/result?p=gitzy
[install-size-badge]: https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json%3Fp=gitzy&query=$.install.pretty&label=install%20size&style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDggMTA4Ij48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzAwNjgzOCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzMyZGU4NSIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjxwYXRoIGZpbGw9InVybCgjYSkiIGQ9Ik0yMS42NjcgNzMuODA5VjMzLjg2N2wyOC4zMy0xNi4xODggMjguMzM3IDE2LjE4OFY2Ni4xM0w0OS45OTcgODIuMzIxIDM1IDczLjc1VjQxLjYwNGwxNC45OTctOC41N0w2NSA0MS42MDR2MTYuNzg4bC0xNS4wMDMgOC41NzEtMS42NjMtLjk1di0xNi42NzJsOC4zODItNC43OTItNi43MTktMy44MzgtOC4zMyA0Ljc2M1Y2OS44OGw4LjMzIDQuNzYyIDIxLjY3LTEyLjM4M1YzNy43MzdsLTIxLjY3LTEyLjM3OS0yMS42NjMgMTIuMzc5djM5Ljg4TDQ5Ljk5NyA5MCA4NSA3MFYzMEw0OS45OTcgMTAgMTUgMzB2NDB6Ii8+PC9zdmc+

gitzy 🪄

> Interactive [conventional commits][conventional-commits] CLI, inspired by [git-cz][git-cz], with support for commitlint configuration, validation, and flexible setup. See features.

Gitzy CLI screenshot

_{Recorded with termsvg (glyphs look better IRL)}

- Features
- Usage
- Configuration
- Flags

Features

Usage

``sh-session npx gitzy

`or`


npm install -g gitzy
gitzy
gitzy -p -a
gitzy -m "added cool new feature" -t "feat" -s "amazing"
gitzy -lD --no-emoji


Configuration

By default, gitzy works out of the box and supports multiple configuration methods.

> [!NOTE] > All of these files can also live under a.config/ directory.

`Options`

The following configuration options are supported:

`$3`

`sh feat: ✨ dope new feature

BREAKING CHANGE: 💥 breaks stuff`

`yml breakingChangeEmoji: "💥"`

`$3`

Allows you to customize the format of the breaking change indicator and prompt behavior.

#### Examples

`sh

`"!" format - adds ! to header, prompts for yes/no`


feat!: send an email to the customer when a product is shipped
"footer" format - prompts for description, adds to footer

feat: allow provided config object to extend other configs

BREAKING CHANGE: extends key in config file is now used for extending other config files

`"both" format - adds ! to header AND prompts for footer description`


chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.`

`yml breakingChangeFormat: "footer"

`Options: "!", "footer", or "both"`

$3

`sh fix: 🐛 resolved nasty bug

🏁 Closes #123`

`yml closedIssueEmoji: "🏁"`

`$3`

Allows you to customize the issues prompt hint.

`yml issuesHint: "#123, #456, resolves #789, org/repo#100"`

`$3`

Allows you to choose the issuesPrefix based on GitHub supported keywords.

`yml issuesPrefix: closes # must be one of close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved`

> [!TIP] > Specify multiple issues separated by commas:#123, #456, or with keywords: resolves #123, fixes #456, or cross-repo: org/repo#123.

`$3`

Disables all emojis; overrides breakingChangeEmoji, closedIssueEmoji, and emoji options.

`yml disableEmoji: false`

`$3`

Allows you to configure CLI and git message output by type. _Default emojis follow standards set by [gitmoji][gitmoji], except for refactor due to its narrower rendering in most terminals._

> [!CAUTION] > Emoji rendering varies by terminal. Some emojis (like ♻️) may cause alignment issues. Test custom emojis in your terminal before committing to them.

`$3`

`yml headerMaxLength: 64`

`$3`

`yml headerMinLength: 3`

`$3`

Allows you to toggle questions.

_scope question will not be shown if no scopes are provided._

`$3`

Allows you to provide a list of scopes to choose from.

`yml scopes: []`

_Will enable the scope question if scopes are provided._

`$3`

Allows you to provide a list of types to choose from. Further configurable via details.

`yml types: - chore - docs - feat - fix - refactor - test - style - ci - perf - revert - release`

`$3`

If enabled, uses Commitlint configuration for:

`yml useCommitlintConfig: false`

`Flags`

Credits

- git-cz by streamich

gitzy

gitzy 🪄

Table of Contents

Features

Usage

or

Configuration

Options

$3

$3

"!" format - adds ! to header, prompts for yes/no

"footer" format - prompts for description, adds to footer

"both" format - adds ! to header AND prompts for footer description

Options: "!", "footer", or "both"

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Flags

Credits

gitzy

gitzy 🪄

Table of Contents

Features

Usage

or

Configuration

Options

$3

$3

"!" format - adds ! to header, prompts for yes/no

"footer" format - prompts for description, adds to footer

"both" format - adds ! to header AND prompts for footer description

Options: "!", "footer", or "both"

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Flags

Credits

`or`

`Options`

`$3`

`$3`

`"!" format - adds ! to header, prompts for yes/no`

`"both" format - adds ! to header AND prompts for footer description`

`Options: "!", "footer", or "both"`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Flags`

`or`

`Options`

`$3`

`$3`

`"!" format - adds ! to header, prompts for yes/no`

`"both" format - adds ! to header AND prompts for footer description`

`Options: "!", "footer", or "both"`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Flags`