\n \n Recorded with termsvg (glyphs look better IRL)\n
\n\n\n![actions][actions-badge]\n[![version][version-badge]][package]\n[![downloads][downloads-badge]][npmtrends]\n[![Install Size][install-size-badge]][packagephobia]\n[![License][license-badge]][license]\n[![Code Coverage][coverage-badge]][coverage]\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n- [Subcommands](#subcommands)\n- [Configuration](#configuration)\n- [Config Options](#config-options)\n\n## Features\n\n- Interactive conventional commit flow (`type`, `scope`, `subject`, `body`, `breaking`, `issues`)\n- Branch name generation from conventional commit prompts\n- Partial commitlint configuration support\n- Config validation via schema\n- Multiple breaking-change formats (`!`, `footer`, `both`)\n- Flexible emoji control (`emoji.enabled` config or `GITZY_NO_EMOJI` env var)\n- Customizable type descriptions and emojis\n- Dynamic scopes and types (string shorthand or full `{ name, description }` objects)\n- Jira and GitHub issue reference patterns\n- Co-author support via `--co-author`\n- Sign-off (DCO) support via `--signoff` / `-s` (derives your git identity, or pass an override)\n- Retry (`--retry`), dry-run (`--dry-run`), amend (`--amend`), and hook (`--hook`) modes\n- JSON output (`--json`) for scripting and CI\n- `--no-emoji` flag (precedence: `--no-emoji` > `GITZY_NO_EMOJI` env > `emoji.enabled` config)\n- `--stdin` for piping answers as JSON (both `commit` and `branch`)\n- ⚡ [Lightweight (~170 kB install)][packagephobia]\n\n## Usage\n\n```sh-session\nnpx gitzy\n# or\nnpm install -g gitzy\ngitzy\ngitzy commit --type feat -m \"add dark mode\"\ngitzy branch --type feat -m \"add dark mode\" --scope ui\n```\n\n## Subcommands\n\n`gitzy` is the same as `gitzy commit`. Explicit subcommands:\n\n| Subcommand | Description |\n| -------------- | ------------------------------------------------------------------------------ |\n| `gitzy` | Alias for `gitzy commit` |\n| `gitzy commit` | Interactive conventional commit flow (default) |\n| `gitzy branch` | Generate a branch name from a conventional commit prompt |\n| `gitzy init` | Generate a starter `.gitzyrc.json` in the current dir (`--force` to overwrite) |\n| `gitzy config` | Display the resolved config as JSON |\n\n### `gitzy commit` flags\n\n| Flag | Alias | Description |\n| --------------------------- | ----- | ------------------------------------------------------------------------------------------ |\n| `--type ` | | set type inline (with `--subject`, skips all prompts) |\n| `--scope ` | | set scope inline |\n| `--subject ` | `-m` | set subject inline (with `--type`, skips all prompts) |\n| `--body ` | | set body inline |\n| `--breaking [breaking]` | | mark as breaking; add message for `footer`/`both` formats |\n| `--issue ` | | set issues inline (repeatable: `--issue '#123' --issue '#456'`) |\n| `--dry-run` | `-D` | show commit message without committing |\n| `--retry` | | retry last commit and skip prompts |\n| `--amend` | `-a` | amend the previous commit (pre-fills prompts from HEAD) |\n| `--no-verify` | `-n` | skip git hooks |\n| `--json` | | output structured JSON (see shape below) |\n| `--no-emoji` | | disable emoji in commit message |\n| `--co-author ` | | add co-authors (repeatable: `--co-author \"Name \"`) |\n| `--signoff [signoff]` | `-s` | add a Signed-off-by trailer (derives your git identity; pass `\"Name \"` to override) |\n| `--hook` | | enable running inside a git hook (e.g. `pre-commit`) |\n| `--stdin` | | read answers from stdin as JSON (CLI flags take priority) |\n| `--version` | `-v` | display version number |\n| `--help` | `-h` | display help for command |\n\n#### `commit --json` output shape\n\n```json\n{\n \"header\": \"feat: ✨ add dark mode\",\n \"body\": \"\",\n \"footer\": \"\",\n \"message\": \"feat: ✨ add dark mode\",\n \"parts\": {\n \"type\": \"feat\",\n \"scope\": \"\",\n \"subject\": \"add dark mode\",\n \"body\": \"\",\n \"breaking\": \"\",\n \"issues\": [],\n \"coAuthors\": [],\n \"signoff\": false\n }\n}\n```\n\n### `gitzy branch` flags\n\n| Flag | Alias | Description |\n| --------------------- | ----- | --------------------------------------------------------- |\n| `--type ` | | set type inline (with `--subject`, skips all prompts) |\n| `--scope ` | | set scope inline |\n| `--subject ` | `-m` | set subject inline (with `--type`, skips all prompts) |\n| `--issue ` | | set issue reference inline (e.g. `#42` or `PROJ-123`) |\n| `--from ` | | create the branch from a base branch |\n| `--amend` | `-a` | rename the current branch instead of creating a new one |\n| `--no-checkout` | | do not checkout the new branch after creating it |\n| `--dry-run` | `-D` | show branch name without creating it |\n| `--json` | | output result as JSON (see shape below) |\n| `--stdin` | | read answers from stdin as JSON (CLI flags take priority) |\n| `--help` | `-h` | display help for command |\n\n#### `branch --json` output shape\n\n```json\n{ \"branchName\": \"feat/add-dark-mode\", \"dryRun\": false }\n```\n\nWhen used with `--amend`, also includes the previous branch name:\n\n```json\n{\n \"branchName\": \"feat/add-dark-mode\",\n \"dryRun\": false,\n \"oldName\": \"feat/dark-mode\"\n}\n```\n\n## Configuration\n\nBy default, `gitzy` works out of the box. You can configure it via a `gitzy` key in `package.json`, or one of the following files:\n\n`.gitzyrc`, `.gitzyrc.json`, `.gitzyrc.js`, `.gitzyrc.cjs`, `.gitzyrc.mjs`,\n`gitzy.config.js`, `gitzy.config.cjs`, `gitzy.config.mjs`, `gitzy.config.ts`, `gitzy.config.mts`\n\n> [!NOTE]\n> 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.\n\nUse `defineConfig` for editor autocomplete:\n\n```js\n// gitzy.config.js\nimport { defineConfig } from \"gitzy\";\n\nexport default defineConfig({\n // see options below\n});\n```\n\nUse `gitzy config` to see all available config file locations and the resolved config.\n\n## Config Options\n\n### `types`\n\nList of commit types. Accepts strings (looked up from builtins) or full objects.\n\n```js\ntypes: [\"feat\", \"fix\", \"chore\", \"docs\", \"refactor\", \"test\", \"style\", \"ci\"];\n// or with custom descriptions/emojis:\ntypes: [\n { name: \"feat\", description: \"A new feature\", emoji: \"✨\" },\n { name: \"fix\", description: \"Fix a bug\", emoji: \"🐛\" },\n];\n```\n\n**Built-in types:** `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `release`, `revert`, `style`, `test`\n\n### `scopes`\n\nList of scopes to choose from. Enables the `scope` prompt when non-empty.\n\n```js\nscopes: [\"api\", \"ui\", \"cli\"];\n// or with descriptions:\nscopes: [{ name: \"api\", description: \"Public API surface\" }, { name: \"ui\" }];\n```\n\n### `prompts`\n\nControls which prompts are shown and in what order.\n\n```js\n// Default:\nprompts: [\"type\", \"scope\", \"subject\", \"body\", \"breaking\", \"issues\"];\n\n// All available prompts (add \"coAuthors\"/\"signoff\" to enable those prompts):\nprompts: [\n \"type\",\n \"scope\",\n \"subject\",\n \"body\",\n \"breaking\",\n \"issues\",\n \"coAuthors\",\n \"signoff\",\n];\n```\n\n> [!NOTE]\n> The `signoff` prompt is a text input prefilled with your git identity (edit to\n> customize, clear to skip) that adds a `Signed-off-by` trailer. It is opt-in\n> (not in the default `prompts`). The `--signoff` / `-s` flag works regardless\n> of this config, and accepts an optional `\"Name \"` to override the\n> derived identity.\n\n### `header`\n\nControls the commit header length validation.\n\n```js\nheader: {\n max: 50, // default\n min: 5, // default\n}\n```\n\n### `body`\n\nControls the commit body length validation. The body prompt is optional — press **Enter** twice (submit an empty line) to skip it.\n\n```js\nbody: {\n max: 70, // default\n min: 5, // default\n}\n```\n\n### `breaking`\n\nControls the breaking change prompt behavior.\n\n- `\"!\"` — append `!` to the type/scope, ask yes/no\n- `\"footer\"` — prompt for a description, add a `BREAKING CHANGE` footer (default)\n- `\"both\"` — add both `!` and a footer\n\n```js\nbreaking: {\n format: \"footer\", // \"!\", \"footer\", or \"both\"\n}\n```\n\n#### Examples\n\n```sh\n# \"!\" format\nfeat!: send an email to the customer when a product is shipped\n\n# \"footer\" format\nfeat: allow provided config object to extend other configs\n\nBREAKING CHANGE: `extends` key in config file is now used for extending other config files\n\n# \"both\" format\nchore!: drop support for Node 6\n\nBREAKING CHANGE: use JavaScript features not available in Node 6.\n```\n\n### `emoji`\n\nControls emoji rendering.\n\n```js\nemoji: {\n enabled: true, // default; set to false or use GITZY_NO_EMOJI env var to disable\n breaking: \"💥\", // emoji prepended to breaking change footer\n issues: \"🏁\", // emoji prepended to issue references\n}\n```\n\n> [!NOTE]\n> 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.\n\n### `issues`\n\nControls the issues prompt behavior.\n\n```js\nissues: {\n pattern: \"github\", // \"github\" (default) or \"jira\"\n prefix: \"closes\", // \"close\" | \"closes\" | \"closed\" | \"fix\" | \"fixes\" | \"fixed\" | \"resolve\" | \"resolves\" | \"resolved\"\n hint: \"#123, #456, resolves #789, org/repo#100\",\n}\n```\n\n> [!TIP]\n> 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`.\n\n### `branch`\n\nControls branch name generation.\n\n```js\nbranch: {\n pattern: \"{type}/{scope}/{issue}-{subject}\", // default\n separator: \"/\", // separator used within each slugified segment (type, scope, subject)\n max: 72, // max branch name length\n checkout: true, // auto-checkout after creation\n}\n```\n\n**Pattern tokens:** `{type}`, `{scope}`, `{issue}`, `{subject}` — any token that has no value is omitted along with its surrounding separators.\n\n#### Branch name examples\n\n| type | scope | issue | subject | output |\n| ------- | ------ | -------- | ----------------- | ---------------------------- |\n| `feat` | `ui` | | `add dark mode` | `feat/ui/add/dark/mode` |\n| `fix` | | `#42` | `login crash` | `fix/#42-login/crash` |\n| `chore` | `deps` | | `bump typescript` | `chore/deps/bump/typescript` |\n| `feat` | | `PROJ-1` | `new dashboard` | `feat/PROJ-1-new/dashboard` |\n\n### commitlint integration\n\ngitzy 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.\n\n## Credits\n\n- [git-cz](https://github.com/streamich/git-cz) by [streamich](https://github.com/streamich)\n\n[actions-badge]: https://img.shields.io/github/actions/workflow/status/jimmy-guzman/gitzy/release.yml?branch=main&style=flat-square&logo=github\n[version-badge]: https://img.shields.io/npm/v/gitzy?style=flat-square&logo=npm\n[package]: https://npmx.dev/package/gitzy\n[downloads-badge]: https://img.shields.io/npm/dm/gitzy?style=flat-square&logo=npm\n[npmtrends]: https://www.npmtrends.com/gitzy\n[license]: https://github.com/jimmy-guzman/gitzy/blob/master/LICENSE\n[license-badge]: https://img.shields.io/github/license/jimmy-guzman/gitzy?style=flat-square&logo=open-source-initiative\n[conventional-commits]: https://www.conventionalcommits.org/\n[coverage-badge]: https://img.shields.io/codecov/c/github/jimmy-guzman/gitzy?style=flat-square&logo=codecov\n[coverage]: https://codecov.io/github/jimmy-guzman/gitzy\n[packagephobia]: https://packagephobia.com/result?p=gitzy\n[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+\n","readmeFilename":"README.md"}
![\"Gitzy](\"./assets/demo.cast.svg\")