gitzy 🪄

Conventional commits and branch CLI

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

Table of Contents

• Features
• Usage
• Subcommands
• Configuration
• Config Options

Features

• Interactive conventional commit flow (type, scope, subject, body, breaking, issues)
• Branch name generation from conventional commit prompts
• Squash the last N commits into a single conventional commit (gitzy squash)
• 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 (commit, branch, and squash)
• ⚡ 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
gitzy squash --count 3

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 squash	Squash the last N commits into a single conventional commit
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 without committing (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. prepare-commit-msg); inferred, with a warning, when omitted inside a hook
--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 without creating the branch (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"
}

gitzy squash flags

Prompts through the same flow as gitzy commit, pre-filled from the HEAD commit, then runs git reset --soft HEAD~N and commits the result. Refuses to run with changes already staged. Undo with git reset --soft ORIG_HEAD.

Flag	Alias	Description
--count <n>		number of commits to squash (default: commits ahead of origin/HEAD)
--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')
--co-author <coAuthor...>		add co-authors (repeatable: --co-author "Name <email>")
--dry-run	-D	show commit message without squashing
--no-verify	-n	skip git hooks
--no-emoji		disable emoji in commit message
--json		output result as JSON, without squashing (see shape below)
--stdin		read answers from stdin as JSON (CLI flags take priority)
--help	-h	display help for command

squash --json output shape

Same as commit --json, plus count:

{ "count": 3, "header": "feat: ✨ add 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) are loaded with Node's built-in type stripping, so they need no extra tooling.

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.

max caps the total body length and has no default; set it here or via commitlint's body-max-length rule.

body: {
  max: 500, // optional, no 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
  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