{"id":16392847,"url":"https://github.com/jimmy-guzman/gitzy","last_synced_at":"2026-05-11T01:27:49.595Z","repository":{"id":37283047,"uuid":"330223776","full_name":"jimmy-guzman/gitzy","owner":"jimmy-guzman","description":"🪄 An interactive conventional commits cli","archived":false,"fork":false,"pushed_at":"2025-06-15T11:59:03.000Z","size":2144,"stargazers_count":5,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T12:31:33.613Z","etag":null,"topics":["cli","conventional-commits"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimmy-guzman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-16T17:59:56.000Z","updated_at":"2025-06-02T22:10:31.000Z","dependencies_parsed_at":"2024-02-15T13:49:50.607Z","dependency_job_id":"52e13891-821f-458a-a1d1-897397e23378","html_url":"https://github.com/jimmy-guzman/gitzy","commit_stats":{"total_commits":354,"total_committers":6,"mean_commits":59.0,"dds":0.5451977401129944,"last_synced_commit":"583433662ad96d425b809c0221187201249fe9e3"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/jimmy-guzman/gitzy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmy-guzman%2Fgitzy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmy-guzman%2Fgitzy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmy-guzman%2Fgitzy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmy-guzman%2Fgitzy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimmy-guzman","download_url":"https://codeload.github.com/jimmy-guzman/gitzy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmy-guzman%2Fgitzy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259978297,"owners_count":22941123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","conventional-commits"],"created_at":"2024-10-11T04:51:35.826Z","updated_at":"2026-05-11T01:27:49.589Z","avatar_url":"https://github.com/jimmy-guzman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitzy 🪄\n\n\u003e Interactive [conventional commits][conventional-commits] CLI with branch name generation and commitlint integration.\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"750\" src=\"./assets/demo.cast.svg\" alt=\"Gitzy CLI screenshot\"\u003e\u003cbr\u003e\n  \u003csub\u003eRecorded with \u003ca href=\"https://github.com/MrMarble/termsvg\"\u003etermsvg\u003c/a\u003e (glyphs look better IRL)\u003c/sub\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\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- 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` \u003e `GITZY_NO_EMOJI` env \u003e `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 \u003ctype\u003e`             |       | set type inline (with `--subject`, skips all prompts)           |\n| `--scope \u003cscope\u003e`           |       | set scope inline                                                |\n| `--subject \u003csubject\u003e`       | `-m`  | set subject inline (with `--type`, skips all prompts)           |\n| `--body \u003cbody\u003e`             |       | set body inline                                                 |\n| `--breaking [breaking]`     |       | mark as breaking; add message for `footer`/`both` formats       |\n| `--issue \u003cissue...\u003e`        |       | 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 \u003ccoAuthor...\u003e` |       | add co-authors (repeatable: `--co-author \"Name \u003cemail\u003e\"`)       |\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  }\n}\n```\n\n### `gitzy branch` flags\n\n| Flag                  | Alias | Description                                               |\n| --------------------- | ----- | --------------------------------------------------------- |\n| `--type \u003ctype\u003e`       |       | set type inline (with `--subject`, skips all prompts)     |\n| `--scope \u003cscope\u003e`     |       | set scope inline                                          |\n| `--subject \u003csubject\u003e` | `-m`  | set subject inline (with `--type`, skips all prompts)     |\n| `--issue \u003cissue\u003e`     |       | set issue reference inline (e.g. `#42` or `PROJ-123`)     |\n| `--from \u003cbranch\u003e`     |       | 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\u003e [!NOTE]\n\u003e All of these files can also live under a `.config/` directory. TypeScript config files (`.ts`/`.mts`) require Node \u003e=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\" to enable co-author prompt):\nprompts: [\n  \"type\",\n  \"scope\",\n  \"subject\",\n  \"body\",\n  \"breaking\",\n  \"issues\",\n  \"coAuthors\",\n];\n```\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\u003e [!NOTE]\n\u003e Set the `GITZY_NO_EMOJI` environment variable or pass `--no-emoji` to disable all emojis. Precedence: `--no-emoji` flag \u003e `GITZY_NO_EMOJI` env \u003e `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\u003e [!TIP]\n\u003e 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\u0026style=flat-square\u0026logo=github\n[version-badge]: https://img.shields.io/npm/v/gitzy?style=flat-square\u0026logo=npm\n[package]: https://npmx.dev/package/gitzy\n[downloads-badge]: https://img.shields.io/npm/dm/gitzy?style=flat-square\u0026logo=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\u0026logo=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\u0026logo=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\u0026query=$.install.pretty\u0026label=install%20size\u0026style=flat-square\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDggMTA4Ij48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzAwNjgzOCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzMyZGU4NSIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjxwYXRoIGZpbGw9InVybCgjYSkiIGQ9Ik0yMS42NjcgNzMuODA5VjMzLjg2N2wyOC4zMy0xNi4xODggMjguMzM3IDE2LjE4OFY2Ni4xM0w0OS45OTcgODIuMzIxIDM1IDczLjc1VjQxLjYwNGwxNC45OTctOC41N0w2NSA0MS42MDR2MTYuNzg4bC0xNS4wMDMgOC41NzEtMS42NjMtLjk1di0xNi42NzJsOC4zODItNC43OTItNi43MTktMy44MzgtOC4zMyA0Ljc2M1Y2OS44OGw4LjMzIDQuNzYyIDIxLjY3LTEyLjM4M1YzNy43MzdsLTIxLjY3LTEyLjM3OS0yMS42NjMgMTIuMzc5djM5Ljg4TDQ5Ljk5NyA5MCA4NSA3MFYzMEw0OS45OTcgMTAgMTUgMzB2NDB6Ii8+PC9zdmc+\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmy-guzman%2Fgitzy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimmy-guzman%2Fgitzy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmy-guzman%2Fgitzy/lists"}