{"id":13527029,"url":"https://github.com/leoforfree/cz-customizable","last_synced_at":"2025-04-01T09:30:59.893Z","repository":{"id":37399553,"uuid":"45214384","full_name":"leoforfree/cz-customizable","owner":"leoforfree","description":"A standalone commit message helper or customizable commitizen adapter for https://github.com/commitizen/cz-cli","archived":false,"fork":false,"pushed_at":"2024-12-23T07:34:58.000Z","size":800,"stargazers_count":623,"open_issues_count":63,"forks_count":202,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-23T22:44:01.292Z","etag":null,"topics":["commit-message","commitizen","conventionalcommits"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/leoforfree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2015-10-29T22:25:39.000Z","updated_at":"2025-03-20T04:24:25.000Z","dependencies_parsed_at":"2024-01-10T11:07:43.439Z","dependency_job_id":"5d0d1e19-501a-4b31-9a8c-a8e8a3018a54","html_url":"https://github.com/leoforfree/cz-customizable","commit_stats":{"total_commits":154,"total_committers":31,"mean_commits":4.967741935483871,"dds":0.4025974025974026,"last_synced_commit":"04426ba7e30d9d0a0d53e173a0c0bb22dab1a70e"},"previous_names":["leonardoanalista/cz-customizable"],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoforfree%2Fcz-customizable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoforfree%2Fcz-customizable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoforfree%2Fcz-customizable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoforfree%2Fcz-customizable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leoforfree","download_url":"https://codeload.github.com/leoforfree/cz-customizable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246615926,"owners_count":20806029,"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":["commit-message","commitizen","conventionalcommits"],"created_at":"2024-08-01T06:01:39.579Z","updated_at":"2025-04-01T09:30:59.884Z","avatar_url":"https://github.com/leoforfree.png","language":"JavaScript","funding_links":[],"categories":["Repository","JavaScript","others","🛠️ Developer Tools"],"sub_categories":["Linter \u0026 Formatter"],"readme":"# cz-customizable\n\nThe customizable Commitizen plugin (or standalone utility) to help achieve consistent commit messages such as [Conventional Commits](https://www.conventionalcommits.org/). Note that you can create any commit message pattern. You don't have to use the pattern from the Conventional Commits. For example, my team uses this pattern: `[minor] add new feature xyz`\n\n![screenshot](screenshot.png)\n\nSuitable for large teams working with multiple projects with their own commit scopes. It allows you to **select** the pre-defined scopes or commit types. It works perfectly with https://github.com/semantic-release/semantic-release.\n\n\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![npm monthly downloads](https://img.shields.io/npm/dm/cz-customizable.svg?style=flat-square)](https://www.npmjs.com/package/cz-customizable)\n[![bundlephobia](https://badgen.net/bundlephobia/minzip/cz-customizable)](https://bundlephobia.com/package/cz-customizable)\n\n\nYou have two ways to use `cz-customizable`. Originally, this project started as a commitizen plugin (Option 1). We introduced the second option to run this `cz-customizable` in standalone mode (Option 2), just like any NodeJS script. It's recommended to use `Option 2` for simplicity. The way you configure is shared between both options.\n\n# Quick start **(New, recommended)**\n## Configuration\n\n* Copy contents of [the example config file](./cz-config-EXAMPLE.js) and paste into a new file `.cz-config.js`\n* Option 1: Move file `cz-config.js` to your home directory.\n* Option 2: Put file `cz-config.js` at the root level of your project and commit it to your code repository (Assuming you have a team agreement to use this tool).\n\n## cz-customizable via global install\n\n`npm i cz-customizable -g`\n\nThen run `cz-customizable` from your root repo. You can also use the alias `cz-cust`.\n\nIf everything is correct, you should see commit questions like the image above.\n\n# Slow start\n\n## Option 1 - cz-customizable via npx\n\n`npx cz-customizable`\n\n\n## Option 2 - cz-customizable in standalone mode\n\nUse `cz-customizable` without `commitzen`.\n\n* npm install `npm install cz-customizable --save-dev`\n* add a new script to your `package.json`:\n\n```\n\"scripts\" : {\n  ...\n  \"commit\": \"./node_modules/cz-customizable/standalone.js\"\n}\n```\n\n* See options below how to create and where you could put your `.cz-config.js` file.\n* now run: `npm run commit`.\n\n\n## Option 3 - cz-customizable as commitizen plugin\n\nThis is how this project started.\n\n* install commitizen in case you don't have it: `npm install -g commitizen`. Make sure you have the latest version of commitizen installed globally.\n\n* configure `commitizen` to use `cz-customizable` as plugin. Add those lines to your `package.json`:\n\n```\n...\n\"config\": {\n  \"commitizen\": {\n    \"path\": \"node_modules/cz-customizable\"\n  }\n}\n```\n\n\n## Configuration (Shared between options 1,2 and 3)\n\n* Copy contents of [the example config file](./cz-config-EXAMPLE.js) and paste into a new file `.cz-config.js`\n\n\n### Option 1 - You can make changes to your git repository, file `package.json`.\n\n* `cz-customizable` will first look for a file called `.cz-config.js` or `.config/cz-config.js` in the project root, near your `package.json`\n* If no config found, it will look for `.cz-config.js` or or `.config/cz-config.js` in your home directory\n* alternatively add the config location in your `package.json`:\n```\n...\n\"config\": {\n  \"commitizen\": { // not needed for standlone usage\n    \"path\": \"node_modules/cz-customizable\"\n  },\n  \"cz-customizable\": {\n    \"config\": \"config/path/to/my/config.js\"\n  }\n}\n```\n\nNote: option one allows you to have your config away from root directory. It also gives you a change to define any name to your `.cz-config.js`.\n\n\n### No Changes to your git repository*.\n\nThis is suitable when your team is not ready to roll `cz-customizable` across all teams but you still would like to use it for your own commits, no matter the project.\n\nSteps:\n* create config file:\n  * create a file called `.cz-config.js` in your git repository root (*Assumptions: you git ignore global on `~/.gitignore_global` for `.cz-config.js`). Or;\n  * create a file called `.cz-config.js` your home directory.\n\n#### Additional steps when used as commitizen plugin\n\n* npm install -g commitizen\n* npm install -g cz-customizable. Make sure you have version `\u003ev5.6.x`\n* create global commitizen config file `.czrc`: `echo '{ \"path\": \"cz-customizable\" }' \u003e ~/.czrc`\n* now run: `npx git-cz` or `git cz`.\n\n\n**Notes:**\n* you should commit your `.cz-config.js` file to your git when applicable.\n\n\n\nHopefully this will help you to have consistent commit messages and have a fully automated deployment without any human intervention.\n\n\n\n---\n## Options\n\nHere are the options you can set in your `.cz-config.js`:\n\n* **subjectLimit**: {number, default 100}: This is the subject limit. Example: `this is a new feature` or `fix a bug`\n* **subjectSeparator**: {string, default ': '}: This is the subject separator. Example: `feat: this is a new feature`\n* **typePrefix**: {string, default ''}: This is the commit type prefix. Example: config: `{ typePrefix: '[' }`, result: `[feat: this is a new feature`\n* **typeSuffix**: {string, default ''}: This is the commit type suffix. Example: config: `{ typePrefix: '[', typeSuffix: ']', subjectSeparator: ' ' }`, result: `[feat] this is a new feature`\n\n* **scopes**: {Array of Strings}: Specify the scopes for your particular project. Eg.: for some banking system: [\"acccounts\", \"payments\"]. For another travelling application: [\"bookings\", \"search\", \"profile\"]\n* **scopeOverrides**: {Object where key contains a Array of String}: Use this when you want to override scopes for a specific commit type. Example below specify scopes when type is `fix`:\n  ```\n  scopeOverrides: {\n    fix: [\n      {name: 'merge'},\n      {name: 'style'},\n      {name: 'e2eTest'},\n      {name: 'unitTest'}\n    ]\n  }\n  ```\n* **additionalQuestions**:{Array of object} To ask additional question. Answers will be appended to body part. All keys of object are required.\n  ```\n   additionalQuestions: [\n    {\n      type: 'input',\n      name: 'time',\n      message: 'Time spent (i.e. 1h 15m) (optional):\\n',\n      mapping: \"#time\"\n    },\n    {\n      type: 'input',\n      name: 'comment',\n      message: 'Jira comment (optional):\\n',\n      mapping: \"#comment\"\n    }\n  ],\n  ```\n* **allowCustomScopes**: {boolean, default false}: adds the option `custom` to scope selection so you can still type a scope if you need.\n* **allowBreakingChanges**: {Array of Strings: default none}. List of commit types you would like to the question `breaking change` prompted. Eg.: ['feat', 'fix'].\n* **skipQuestions**: {Array of Strings: default none}. List of questions you want to skip. Eg.: ['body', 'footer'].\n* **skipEmptyScopes**: {boolean, default false}: If a chosen type has no scopes declared, skip the scope question\n* **appendBranchNameToCommitMessage**: If you use `cz-customizable` with `cz-customizable-ghooks`, you can get the branch name automatically appended to the commit message. This is done by a commit hook on `cz-customizable-ghooks`. This option has been added on `cz-customizable-ghooks`, v1.3.0. Default value is `true`.\n* **ticketNumberPrefix**: {string, default 'ISSUES CLOSED:'}: Set custom prefix for footer ticker number.\n* **ticketNumberSuffix**: {string, default ''}: Set custom suffix for footer ticker number.\n* **fallbackTicketNumber**: {string, default ''}: Set fallback ticket number which will be used if `ticketNumber` is not provided.\n* **breakingPrefix**: {string, default 'BREAKING CHANGE:'}: Set a custom prefix for the breaking change block in commit messages.\n* **footerPrefix**: {string, default 'ISSUES CLOSED:'}: Set a custom prefix for the footer block in commit messages. Set to empty string to remove prefix.\n* **breaklineChar**: {string, default '|'}: It gets replaced with \\n to create the breakline in your commit message. This is supported for fields `body` and `footer` at the moment.\n* **upperCaseSubject**: { boolean, default false }: Capitalizes first subject letter if set to `true`\n* **askForBreakingChangeFirst**: { boolean, default false }: It asks for breaking change as first question when set to `true`\n* **usePreparedCommit**: { boolean, default false }: It re-uses commit from ./.git/COMMIT_EDITMSG when set to `true`\n\n## Related tools\n- (https://github.com/commitizen/cz-cli)\n- (https://github.com/leonardoanalista/corp-semantic-release)\n- (https://github.com/semantic-release/semantic-release)\n- (https://github.com/uglow/cz-customizable-ghooks)\n\n\n\n## GOTCHAS\n\n* backticks\nIf you wish to have backticks in your content, for example \"feat: \\`string\\`\", the commit preview will be \"feat: \\\\\\`string\\\\\\`\".\nDon't worry because on your `git log` will be \"feat: \\`string\\`\" as desired.\n\n* multiline contents on the body of the message\nBody is the only place where you can use a `pipe` to break lines.\nE.g.: you type this: `my items are:| - item01| - item 02`, which will become:\n\n\n```\nmy items are:\n - item01\n - item 02\n```\n\n\n## CONTRIBUTING\n\n### Contributor Guidelines\n* if you add a new config property, please remember to update files `README.md` and `index.d.ts`.\n* add or update relevant tests\n* Favor non-breaking changes when possible\n* Send preliminary PR if you would like to start a discussion\n\n### Conduct of Code:\n* Be polite, respectful and understanding that we are all here after working hours spending time to build something useful to all.\n* We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience\n\n\n\nLeonardo Correa","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoforfree%2Fcz-customizable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleoforfree%2Fcz-customizable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoforfree%2Fcz-customizable/lists"}