Fancier commits with emojis.
npm install commitizen-emojicommitizen-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 š!
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 scopeResulting 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-emojiset 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 to
false - 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 to
false - 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 to
75.> š© 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 to
false - 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"
}
}
}
``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