gitzy 🪄

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

Table of Contents

• 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)

Usage

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

breakingChangeEmoji

feat: ✨ dope new feature

BREAKING CHANGE: 💥 breaks stuff

breakingChangeEmoji: "💥"

breakingChangeFormat

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 CHANGE footer (default)
• both - Prompt for a description and add both an indicator (!) and a footer

Examples

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

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

closedIssueEmoji

fix: 🐛 resolved nasty bug

🏁 Closes #123

closedIssueEmoji: "🏁"

issuesHint

Allows you to customize the issues prompt hint.

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

issuesPrefix

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

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.

disableEmoji

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

disableEmoji: false

details

Allows you to configure CLI and git message output by type. Default emojis follow standards set by 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.

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: "✅"

headerMaxLength

headerMaxLength: 64

headerMinLength

headerMinLength: 3

questions

Allows you to toggle questions.

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.

scopes

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

scopes: []

Will enable the scope question if scopes are provided.

types

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

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

useCommitlintConfig

If enabled, uses Commitlint configuration for:

• types → rules[type-enum][2]
• scopes → rules[scope-enum][2]
• headerMaxLength → rules[header-max-length][2]
• headerMinLength → rules[header-min-length][2]

useCommitlintConfig: false

Flags

| Flag | Alias | Description | | -------------------------- | ----- | ------------------------------------------------------------------------------------- | | --version | -v | output the version number | | --body <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 <body> | -i | set issues inline | | --passthrough <flags...> | -p | pass remaining arguments to git (e.g. after --) | | --scope <scope> | -s | set scope inline | | --subject <message> | -m | set subject inline | | --type <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 <questions...> | -S | skip prompts (choices: "type", "scope", "subject", "body", "breaking", "issues") | | --help | -h | display help for command |

Credits

• git-cz by streamich