commitizen-emoji

Getting started

commitizen-emoji allows you to easily use emojis in your commits with [commitizen].

Why?

According to the [Telegraph],
the average human attention span has recently dropped from 🙈 12 seconds to
8 seconds, docking us below that of a goldfish. Developers are much less likely
to read thoroughly the whole commit message of every file, when there are
📄 pages of a codebase itself. Reading even a single commit message requires
a maximum of a few seconds of focus per file. And we all know, that 🔥 wasting
an engineer's time is an unacceptable luxury.

Emojis satisfy this desire for fast and efficient scanning of the commit history
across files. There are several advantages that emojis bring:

##### 📌 they're small key text anchors

Emojis are a sequence of one or more code points that are displayed as a grapheme.

##### 🧐 they're eye-catching

Compare two pictures below.

![picture 1]
![picture 2]

A dull formal text looks pale next to a shiny emoji star ✨. Wait till you see a
git log or blame a file...

##### 📸 they're recognizable

Like really! You will definitely understand that this ⚡️ means performance
improvement, and this 🐛 means a bug fix. You can even choose one of supported
emoji packs to get around with a fixed and a relatively small amount of well
recognized emojis, like a [conventional] pack;

##### 📈 they're growing in numbers

You will always find a desired emoji for your needs.

##### they're fun 🎉 and fancy 💄!

Demo

sh
? Select the type of change you're committing:  (Use arrow keys or type to search)
❯ codestyle   🎨  Improve structure / format of the code.
  perf        ⚡️  Improve performance.
  prune       🔥  Remove code or files.
  bugfix      🐛  Fix a bug.
  hotfix      🚑️  Critical hotfix.
  feature     ✨  Introduce new features.
  docs        📝  Add or update documentation.
Other prompts and answers...

`sh

`Resulting commit title (with conventional set to false)`


✨ (nonconventional): no type specified only emoji and scope
Resulting commit title (with conventional set to true)

✨ feature(conventional): type comes with emoji and scope


Installation
> 🚩 Note
>
> Keep it local =)

`sh yarn add -D commitizen commitizen-emoji

`set as default adapter for your projects`


echo '{ "path": "./node_modules/commitizen-emoji" }' > ./.czrc


OR add this to your package.json

`json "config": { "commitizen": { "path": "./node_modules/commitizen-emoji" } },`

`Usage`

`sh yarn cz`

OR if [husky] hooks are set up

`sh

`if commit-msg hook contains commitlint scripts`


'a' will be neglected after commitlint checks commit

message prepared by commitizen

git commit -m 'a'
if commit-msg hook is not enabled

yarn cz


Customization
Configuring commitizen-emoji can be done in two equal ways:

I. package.json`json { "config": { "commitizenEmoji": {} } }`II../.czrc`sh { "config": { "commitizenEmoji": {} } }`

`Configuration Options`

#### types

By default commitizen-emoji comes preconfigured with the [Gitmoji] types and an author's version of type names.

But you always can declare your own set of types in the manner of gitmoji types.

> 🚩 Note > > Make sure your codes match with markdown emoji codes

`json { "config": { "commitizenEmoji": { "types": [ { "emoji": "😱", "code": ":scream:", "description": "I don't understand a bit in all this code.", "name": "wtf" } ] } } }`

#### replaceTypes

Should custom user types replace default gitmoji types.

Defaults tofalse - types will be merged.

User types will take precedence over default types, or renamed types.

> 🚩 Note > > This option will have no effect if types array is not defined or empty

`json "commitizenEmoji": { "types": [ { "emoji": "😱", "code": ":scream:", "description": "I don't understand a bit in all this code.", "name": "wtf" } ], "replaceTypes": true }`

#### scopes

List of custom user scopes.

Defaults to an empty array.

Affects the way the prompt behaves. If there are scopes, the prompt will suggest to select a scope instead of typing it.

`json { "config": { "commitizenEmoji": { "scopes": ["linters", "accounts", "tdd", "ci", "fixtures"] } } }`

#### symbol

Should emoji be depicted as a grapheme or as a code.

Defaults tofalse - code.

> 🚩 Note > > Some terminals (e.g., Windows terminal) cannot substitute a code > with a grapheme, so it helps to show an emoji correctly in your terminal.

`json { "config": { "commitizenEmoji": { "symbol": true } } }`

#### skipQuestions

List of question that must be skipped by the prompt.

Defaults to an empty array.

`json { "config": { "commitizenEmoji": { "skipQuestions": ["scope", "body", "breakingBody", "issues"] } } }`

#### questions

User defined question for each prompt.

Defaults to an object with original questions.

`json { "config": { "commitizenEmoji": { "questions": { "type": "This will be displayed instead of original type question", "scope": "This will be displayed instead of original scope question", "subject": "This will be displayed instead of original subject question", "body": "This will be displayed instead of original body question", "breakingBody": "This will be displayed instead of original breakingBody question", "issues": "This will be displayed instead of original issues question" } } } }`

#### subjectMaxLength

Maximum length of the subject.

Defaults to75.

> 🚩 Note > > Make sure [commitlint] (if enabled) is configured to accept this length > of a commit title

`json { "config": { "commitizenEmoji": { "subjectMaxLength": 200 } } }`

#### issuesPrefix

Inserts prefix to all listed issues, .e.g.`sh

`Issues: 2, 3 becomes`


Issues: https://harbarfor.atlassian.net/browse/2, https://harbarfor.atlassian.net/browse/3.


Defaults to an empty string.
> 🚩 Note
>
> URL validation is done by [URL node module], so make sure your prefix conform 
> to validation rules of this module.
>
>
> Any string can be used as a prefix

`json { "config": { "commitizenEmoji": { "issuesPrefix": "https://harbarfor.atlassian.net/browse/" } } }`

#### conventionalFormat

Should the title contain an emoji with its name, in order to pass commit linters (e.g., commitlint), or to please your preferences.

Defaults tofalse - name is not added.

`json { "config": { "commitizenEmoji": { "conventionalFormat": true } } }`

#### selectedTypesByCode

List of gitmoji types that user wants to work with. Types are picked by emoji codes.

Defaults to an empty array - all gitmoji types are used.

> 🚩 Note > > If replaceTypes option is set to true, this list is neglected. > > If usePack option is provided and types option is not, this list is neglected. > > All nonexistant code name will be ignored

`json { "config": { "commitizenEmoji": { "selectedTypesByCode": [":art:", ":memo:", ":sparkles:", ":bug:"] } } }`

#### typeNamesByCode

Map of code-name pairs.

Allows to redefine emoji names by selecting them by a gitmoji code and giving them new names.

You can examine [default code-name pairs].

> 🚩 Note > > If types are provided and replaceTypes is set to true, this map is neglected.

`json { "config": { "commitizenEmoji": { "typeNamesByCode": { ":fire:": "cowabunga", ":poop:": "it-is-treason-then" } } } }`

#### usePack

Allows to use one of the most popular sets of types.

Defaults to an empty string - standard gitmoji types are used.

Each set comes with appropriate names and emojis, that are opinionated.

> 🚩 Note > > If types are provided, this option is neglected.

`json { "config": { "commitizenEmoji": { "usePack": "conventional" } } }``

Examples

.czrc

Cudos

Check out the origins of emoji commits - gitmoji fancy website.

[gitmoji]: https://raw.githubusercontent.com/carloscuesta/gitmoji/master/src/data/gitmojis.json
[commitizen]: https://github.com/commitizen/cz-cli
[picture 1]: https://github.com/zorgick/commitizen-emoji/blob/master/assets/without_emoji.jpg?raw=true
[picture 2]: https://github.com/zorgick/commitizen-emoji/blob/master/assets/with_emoji.jpg?raw=true
[husky]: https://github.com/typicode/husky
[commitlint-config-gitmoji]: https://github.com/arvinxx/gitmoji-commit-workflow
[commitlint]: https://commitlint.js.org/#/reference-rules
[conventional]: https://www.conventionalcommits.org/en/v1.0.0/
[Telegraph]: https://www.telegraph.co.uk/science/2016/03/12/humans-have-shorter-attention-span-than-goldfish-thanks-to-smart/
[URL node module]: https://nodejs.org/api/url.html
[default code-name pairs]: https://github.com/zorgick/commitizen-emoji/blob/master/src/constants/types.ts

commitizen-emoji

Getting started

commitizen-emoji allows you to easily use emojis in your commits with [commitizen].

Why?

Emojis satisfy this desire for fast and efficient scanning of the commit history
across files. There are several advantages that emojis bring:

##### 📌 they're small key text anchors

Emojis are a sequence of one or more code points that are displayed as a grapheme.

##### 🧐 they're eye-catching

Compare two pictures below.

![picture 1]
![picture 2]

A dull formal text looks pale next to a shiny emoji star ✨. Wait till you see a
git log or blame a file...

##### 📸 they're recognizable

##### 📈 they're growing in numbers

You will always find a desired emoji for your needs.

##### they're fun 🎉 and fancy 💄!

Demo

sh
? Select the type of change you're committing:  (Use arrow keys or type to search)
❯ codestyle   🎨  Improve structure / format of the code.
  perf        ⚡️  Improve performance.
  prune       🔥  Remove code or files.
  bugfix      🐛  Fix a bug.
  hotfix      🚑️  Critical hotfix.
  feature     ✨  Introduce new features.
  docs        📝  Add or update documentation.
Other prompts and answers...

`sh

`Resulting commit title (with conventional set to false)`


✨ (nonconventional): no type specified only emoji and scope
Resulting commit title (with conventional set to true)

✨ feature(conventional): type comes with emoji and scope


Installation
> 🚩 Note
>
> Keep it local =)

`sh yarn add -D commitizen commitizen-emoji

`set as default adapter for your projects`


echo '{ "path": "./node_modules/commitizen-emoji" }' > ./.czrc


OR add this to your package.json

`json "config": { "commitizen": { "path": "./node_modules/commitizen-emoji" } },`

`Usage`

`sh yarn cz`

OR if [husky] hooks are set up

`sh

`if commit-msg hook contains commitlint scripts`


'a' will be neglected after commitlint checks commit

message prepared by commitizen

git commit -m 'a'
if commit-msg hook is not enabled

yarn cz


Customization
Configuring commitizen-emoji can be done in two equal ways:

I. package.json`json { "config": { "commitizenEmoji": {} } }`II../.czrc`sh { "config": { "commitizenEmoji": {} } }`

`Configuration Options`

#### types

By default commitizen-emoji comes preconfigured with the [Gitmoji] types and an author's version of type names.

But you always can declare your own set of types in the manner of gitmoji types.

> 🚩 Note > > Make sure your codes match with markdown emoji codes

`json { "config": { "commitizenEmoji": { "types": [ { "emoji": "😱", "code": ":scream:", "description": "I don't understand a bit in all this code.", "name": "wtf" } ] } } }`

#### replaceTypes

Should custom user types replace default gitmoji types.

Defaults tofalse - types will be merged.

User types will take precedence over default types, or renamed types.

> 🚩 Note > > This option will have no effect if types array is not defined or empty

`json "commitizenEmoji": { "types": [ { "emoji": "😱", "code": ":scream:", "description": "I don't understand a bit in all this code.", "name": "wtf" } ], "replaceTypes": true }`

#### scopes

List of custom user scopes.

Defaults to an empty array.

Affects the way the prompt behaves. If there are scopes, the prompt will suggest to select a scope instead of typing it.

`json { "config": { "commitizenEmoji": { "scopes": ["linters", "accounts", "tdd", "ci", "fixtures"] } } }`

#### symbol

Should emoji be depicted as a grapheme or as a code.

Defaults tofalse - code.

> 🚩 Note > > Some terminals (e.g., Windows terminal) cannot substitute a code > with a grapheme, so it helps to show an emoji correctly in your terminal.

`json { "config": { "commitizenEmoji": { "symbol": true } } }`

#### skipQuestions

List of question that must be skipped by the prompt.

Defaults to an empty array.

`json { "config": { "commitizenEmoji": { "skipQuestions": ["scope", "body", "breakingBody", "issues"] } } }`

#### questions

User defined question for each prompt.

Defaults to an object with original questions.

#### subjectMaxLength

Maximum length of the subject.

Defaults to75.

> 🚩 Note > > Make sure [commitlint] (if enabled) is configured to accept this length > of a commit title

`json { "config": { "commitizenEmoji": { "subjectMaxLength": 200 } } }`

#### issuesPrefix

Inserts prefix to all listed issues, .e.g.`sh

`Issues: 2, 3 becomes`


Issues: https://harbarfor.atlassian.net/browse/2, https://harbarfor.atlassian.net/browse/3.


Defaults to an empty string.
> 🚩 Note
>
> URL validation is done by [URL node module], so make sure your prefix conform 
> to validation rules of this module.
>
>
> Any string can be used as a prefix

`json { "config": { "commitizenEmoji": { "issuesPrefix": "https://harbarfor.atlassian.net/browse/" } } }`

#### conventionalFormat

Should the title contain an emoji with its name, in order to pass commit linters (e.g., commitlint), or to please your preferences.

Defaults tofalse - name is not added.

`json { "config": { "commitizenEmoji": { "conventionalFormat": true } } }`

#### selectedTypesByCode

List of gitmoji types that user wants to work with. Types are picked by emoji codes.

Defaults to an empty array - all gitmoji types are used.

`json { "config": { "commitizenEmoji": { "selectedTypesByCode": [":art:", ":memo:", ":sparkles:", ":bug:"] } } }`

#### typeNamesByCode

Map of code-name pairs.

Allows to redefine emoji names by selecting them by a gitmoji code and giving them new names.

You can examine [default code-name pairs].

> 🚩 Note > > If types are provided and replaceTypes is set to true, this map is neglected.

`json { "config": { "commitizenEmoji": { "typeNamesByCode": { ":fire:": "cowabunga", ":poop:": "it-is-treason-then" } } } }`

#### usePack

Allows to use one of the most popular sets of types.

Defaults to an empty string - standard gitmoji types are used.

Each set comes with appropriate names and emojis, that are opinionated.

> 🚩 Note > > If types are provided, this option is neglected.

`json { "config": { "commitizenEmoji": { "usePack": "conventional" } } }``

Examples

.czrc

Cudos

Check out the origins of emoji commits - gitmoji fancy website.