npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

gitzy

v7.0.10

Published

interactive conventional commits cli

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

epic_tachoepic_tacho

Keywords

conventional commitscligit

Readme

gitzy 🪄

Interactive conventional commits CLI with branch name generation and commitlint integration.

actions version downloads Install Size License Code Coverage

Table of Contents

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
  • 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>") | | --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": []
  }
}

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" to enable co-author prompt):
prompts: [
  "type",
  "scope",
  "subject",
  "body",
  "breaking",
  "issues",
  "coAuthors",
];

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