gitzy 🪄

Conventional commits CLI with branch name generation and commitlint integration.

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

Features

Interactive conventional commit flow (type, scope, subject, body, breaking, issues)
Branch name generation from conventional commit prompts
Partial commitlint configuration support
Config validation via schema
Multiple breaking-change formats (!, footer, both)
Flexible emoji control (emoji.enabled config or GITZY_NO_EMOJI env var)
Customizable type descriptions and emojis
Dynamic scopes and types (string shorthand or full { name, description } objects)
Jira and GitHub issue reference patterns
Co-author support via --co-author
Sign-off (DCO) support via --signoff / -s (derives your git identity, or pass an override)
Retry (--retry), dry-run (--dry-run), amend (--amend), and hook (--hook) modes
JSON output (--json) for scripting and CI
--no-emoji flag (precedence: --no-emoji > GITZY_NO_EMOJI env > emoji.enabled config)
--stdin for piping answers as JSON (both commit and branch)
⚡ Lightweight (~170 kB install)

Usage

npx gitzy
# or
npm install -g gitzy
gitzy
gitzy commit --type feat -m "add dark mode"
gitzy branch --type feat -m "add dark mode" --scope ui

Subcommands

gitzy is the same as gitzy commit. Explicit subcommands:

Subcommand	Description
`gitzy`	Alias for `gitzy commit`
`gitzy commit`	Interactive conventional commit flow (default)
`gitzy branch`	Generate a branch name from a conventional commit prompt
`gitzy init`	Generate a starter `.gitzyrc.json` in the current dir (`--force` to overwrite)
`gitzy config`	Display the resolved config as JSON

`gitzy commit` flags

Flag	Alias	Description
`--type <type>`		set type inline (with `--subject`, skips all prompts)
`--scope <scope>`		set scope inline
`--subject <subject>`	`-m`	set subject inline (with `--type`, skips all prompts)
`--body <body>`		set body inline
`--breaking [breaking]`		mark as breaking; add message for `footer`/`both` formats
`--issue <issue...>`		set issues inline (repeatable: `--issue '#123' --issue '#456'`)
`--dry-run`	`-D`	show commit message without committing
`--retry`		retry last commit and skip prompts
`--amend`	`-a`	amend the previous commit (pre-fills prompts from HEAD)
`--no-verify`	`-n`	skip git hooks
`--json`		output structured JSON (see shape below)
`--no-emoji`		disable emoji in commit message
`--co-author <coAuthor...>`		add co-authors (repeatable: `--co-author "Name <email>"`)
`--signoff [signoff]`	`-s`	add a Signed-off-by trailer (derives your git identity; pass `"Name <email>"` to override)
`--hook`		enable running inside a git hook (e.g. `pre-commit`)
`--stdin`		read answers from stdin as JSON (CLI flags take priority)
`--version`	`-v`	display version number
`--help`	`-h`	display help for command

`commit --json` output shape

{
  "header": "feat: ✨ add dark mode",
  "body": "",
  "footer": "",
  "message": "feat: ✨ add dark mode",
  "parts": {
    "type": "feat",
    "scope": "",
    "subject": "add dark mode",
    "body": "",
    "breaking": "",
    "issues": [],
    "coAuthors": [],
    "signoff": false
  }
}

`gitzy branch` flags

Flag	Alias	Description
`--type <type>`		set type inline (with `--subject`, skips all prompts)
`--scope <scope>`		set scope inline
`--subject <subject>`	`-m`	set subject inline (with `--type`, skips all prompts)
`--issue <issue>`		set issue reference inline (e.g. `#42` or `PROJ-123`)
`--from <branch>`		create the branch from a base branch
`--amend`	`-a`	rename the current branch instead of creating a new one
`--no-checkout`		do not checkout the new branch after creating it
`--dry-run`	`-D`	show branch name without creating it
`--json`		output result as JSON (see shape below)
`--stdin`		read answers from stdin as JSON (CLI flags take priority)
`--help`	`-h`	display help for command

`branch --json` output shape

{ "branchName": "feat/add-dark-mode", "dryRun": false }

When used with --amend, also includes the previous branch name:

{
  "branchName": "feat/add-dark-mode",
  "dryRun": false,
  "oldName": "feat/dark-mode"
}

Configuration

By default, gitzy works out of the box. You can configure it via a gitzy key in package.json, or one of the following files:

.gitzyrc, .gitzyrc.json, .gitzyrc.js, .gitzyrc.cjs, .gitzyrc.mjs, gitzy.config.js, gitzy.config.cjs, gitzy.config.mjs, gitzy.config.ts, gitzy.config.mts

Note

All of these files can also live under a .config/ directory. TypeScript config files (.ts/.mts) require Node >=22.12.0 (built-in TypeScript stripping, no flag needed). Use a .js, .cjs, or .mjs config file if you are on an older Node version.

Use defineConfig for editor autocomplete:

// gitzy.config.js
import { defineConfig } from "gitzy";

export default defineConfig({
  // see options below
});

Use gitzy config to see all available config file locations and the resolved config.

Config Options

`types`

List of commit types. Accepts strings (looked up from builtins) or full objects.

types: ["feat", "fix", "chore", "docs", "refactor", "test", "style", "ci"];
// or with custom descriptions/emojis:
types: [
  { name: "feat", description: "A new feature", emoji: "✨" },
  { name: "fix", description: "Fix a bug", emoji: "🐛" },
];

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

`scopes`

List of scopes to choose from. Enables the scope prompt when non-empty.

scopes: ["api", "ui", "cli"];
// or with descriptions:
scopes: [{ name: "api", description: "Public API surface" }, { name: "ui" }];

`prompts`

Controls which prompts are shown and in what order.

// Default:
prompts: ["type", "scope", "subject", "body", "breaking", "issues"];

// All available prompts (add "coAuthors"/"signoff" to enable those prompts):
prompts: [
  "type",
  "scope",
  "subject",
  "body",
  "breaking",
  "issues",
  "coAuthors",
  "signoff",
];

Note

The signoff prompt is a text input prefilled with your git identity (edit to customize, clear to skip) that adds a Signed-off-by trailer. It is opt-in (not in the default prompts). The --signoff / -s flag works regardless of this config, and accepts an optional "Name <email>" to override the derived identity.

`header`

Controls the commit header length validation.

header: {
  max: 50, // default
  min: 5,  // default
}

`body`

Controls the commit body length validation. The body prompt is optional — press Enter twice (submit an empty line) to skip it.

body: {
  max: 70, // default
  min: 5,  // default
}

`breaking`

Controls the breaking change prompt behavior.

"!" — append ! to the type/scope, ask yes/no
"footer" — prompt for a description, add a BREAKING CHANGE footer (default)
"both" — add both ! and a footer

breaking: {
  format: "footer", // "!", "footer", or "both"
}

Examples

# "!" format
feat!: send an email to the customer when a product is shipped

# "footer" format
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
chore!: drop support for Node 6

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

`emoji`

Controls emoji rendering.

emoji: {
  enabled: true,    // default; set to false or use GITZY_NO_EMOJI env var to disable
  breaking: "💥",  // emoji prepended to breaking change footer
  issues: "🏁",    // emoji prepended to issue references
}

Note

Set the GITZY_NO_EMOJI environment variable or pass --no-emoji to disable all emojis. Precedence: --no-emoji flag > GITZY_NO_EMOJI env > emoji.enabled config.

`issues`

Controls the issues prompt behavior.

issues: {
  pattern: "github",  // "github" (default) or "jira"
  prefix: "closes",   // "close" | "closes" | "closed" | "fix" | "fixes" | "fixed" | "resolve" | "resolves" | "resolved"
  hint: "#123, #456, resolves #789, org/repo#100",
}

Tip

Specify multiple issues separated by commas: #123, #456, or with keywords: resolves #123, fixes #456, or cross-repo: org/repo#123. Use pattern: "jira" for Jira-style keys like PROJ-123.

`branch`

Controls branch name generation.

branch: {
  pattern: "{type}/{scope}/{issue}-{subject}", // default
  separator: "/",    // separator used within each slugified segment (type, scope, subject)
  max: 72,           // max branch name length
  checkout: true,    // auto-checkout after creation
}

Pattern tokens: {type}, {scope}, {issue}, {subject} — any token that has no value is omitted along with its surrounding separators.

Branch name examples

type	scope	issue	subject	output
`feat`	`ui`		`add dark mode`	`feat/ui/add/dark/mode`
`fix`		`#42`	`login crash`	`fix/#42-login/crash`
`chore`	`deps`		`bump typescript`	`chore/deps/bump/typescript`
`feat`		`PROJ-1`	`new dashboard`	`feat/PROJ-1-new/dashboard`

commitlint integration

gitzy always auto-detects a local commitlint config file and merges its rules as a base. Any values set in your gitzy config take priority. Use gitzy config to inspect the resolved configuration.

Credits

git-cz by streamich

Name		Name	Last commit message	Last commit date
Latest commit History 643 Commits
.github		.github
.husky		.husky
.vscode		.vscode
assets		assets
docs		docs
e2e		e2e
src		src
.commitlintrc.json		.commitlintrc.json
.editorconfig		.editorconfig
.gitignore		.gitignore
.nvmrc		.nvmrc
.releaserc.yml		.releaserc.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
cspell.json		cspell.json
eslint.config.ts		eslint.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

gitzy 🪄

Table of Contents

Features

Usage

Subcommands

`gitzy commit` flags

`commit --json` output shape

`gitzy branch` flags

`branch --json` output shape

Configuration

Config Options

`types`

`scopes`

`prompts`

`header`

`body`

`breaking`

Examples

`emoji`

`issues`

`branch`

Branch name examples

commitlint integration

Credits

About

Uh oh!

Releases 65

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

gitzy 🪄

Table of Contents

Features

Usage

Subcommands

gitzy commit flags

commit --json output shape

gitzy branch flags

branch --json output shape

Configuration

Config Options

types

scopes

prompts

header

body

breaking

Examples

emoji

issues

branch

Branch name examples

commitlint integration

Credits

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 65

Uh oh!

Contributors

Uh oh!

Languages

`gitzy commit` flags

`commit --json` output shape

`gitzy branch` flags

`branch --json` output shape

`types`

`scopes`

`prompts`

`header`

`body`

`breaking`

`emoji`

`issues`

`branch`