This is a tiny CLI tool that automatically adds emojis to your commit messages based on conventional commit types.
- 📦 Easy Install: just install it once and forget about it
- 🛠️ Customizable: you can add your own emojis and trigger words, and change the format of the commit message as per your needs.
- 🫧 Seamless: operates with the
prepare-commit-msg
git hook, modifying your commit messages every time you make a commit.
Warning
There is a known issue with GitHub Desktop on Windows.
Hi, read the README.md
first (starting with Install). This emoji table is for quick reference. Btw it's generated from the default.jsonc file.
Close/open gigantic table
Type | Subtype | Emoji | Description |
---|---|---|---|
fix |
. |
🔧 | general fix |
fix |
typo |
✏️ | fixed typo in code, docs, ui, etc. |
fix |
bug |
🐛 | fixed a bug |
fix |
security |
🔒 | fixed security issues |
chore |
. |
🗑️ | did some chores |
chore |
release |
🔖 | new release commit (pairs well with bumpp) |
chore |
cleanup |
🧹 | cleaned up code, removed logs and debug stuff, made everyting ready for production |
chore |
license |
📜 | changed the license |
chore |
lint |
🧼 | fixed linting errors |
chore |
deps |
📦 | changed dependencies |
chore |
readme |
📕,📗,📘,📙 | update the README |
release |
🔖 | ||
cleanup |
🧹 | ||
lint |
🧼 | ||
deps |
. |
📦 | added/removed/changed dependencies |
deps |
up |
⬆️ | updated dependencies |
deps |
down |
⬇️ | downgraded dependencies |
up |
⬆️ | ||
down |
⬇️ | ||
build |
. |
🦺 | work regarding build processes |
build |
deps |
📦 | dependabot PRs (see the prefix in the dependabot.yml file on how to add an emoji to our friend's PRs) |
docs |
. |
📝 | documented something |
docs |
readme |
📕,📗,📘,📙 | |
feat |
. |
✨ | introduced a new feature |
feat |
enhance |
💎 | made something a little better (but still include in release notes) |
enhance |
💎 | made something a little better (omit from release notes) | |
test |
🧪 | worked on tests | |
refactor |
♻️ | refactored code, achieved the same with less | |
init |
🎉 | started a new project! | |
perf |
⚡ | improved performance, achieved the same faster | |
breaking |
💥 | special type: will be used if the commit contains an exclamation mark (! ), indicates breaking changes |
|
ci |
🦾 | changed workflow files, CI stuff | |
config |
⚙️ | changed configuration files | |
style |
🎨 | design changes, style changes | |
ui |
🪟 | worked on UI, UX or layout | |
text |
💬 | changed string literals, text content | |
revert |
⏪ | revert a commit | |
i18n |
🌐 | translated something | |
security |
🔒 | ||
wip |
🚧 | wildcard type, works for anything | |
add |
➕ | ||
remove |
➖ |
There are two different ways to install eemoji
:
- Locally: add it to a node project as a dev dependency. This way you can share it with other contributors.
- Globally: install it globally to use it everywhere, not just in node projects. Note that you will need to initialize it in other repository for it to work there.
Thanks to the postinstall
script, after installing eemoji
locally/globally, it will automatically create the git hook for the current repo. This means it will just work, but it's especially useful when other users are going to contribute to your repository.
Tip
If you use yarn
or pnpm
, which do not run postinstall
scripts by default, you need to run eemoji init
manually.
Besides that, you can create a prepare
script in your package.json
, so that it will be run automatically for others who contribute to your repository:
{
"scripts": {
"prepare": "eemoji init -c none"
}
}
npm i -D eemoji
npm i -g eemoji
Note
For eemoji
to work in a repository you still need to run the init command once, so that it can install the git hook there as well.
After installing it, just create a commit and see an emoji appended to it.
Go to the Config section for examples and to see how to customize it.
The cli tool also has some commands for removing eemoji
from a repository, running it manually, etc. But they are not that important. 👇
Use eemoji <command>
if you installed it globally, or npx eemoji <command>
if you installed it locally.
-h, --help
: show help for a command-v, --version
: show version
Installs the git hook in the current repository.
It will also ask you what type of config file you want to use, see Config.
The postinstall
script will run this command with the -c none
flag, so no config is assumed.
eemoji init
Flags:
Specify flags to skip the questions.
-c, --config <config>
: specify the config type,json
,ts
ornone
Removes eemoji
from the current repository, including the git hook, config file and its vscode settings if present.
eemoji cleanup
Runs the eemoji
on the current commit message manually.
This is used by the git hook, but also allows you to test eemoji
manually (specify a test file or it will use the current commit message in .git/COMMIT_EDITMSG
).
eemoji run
Arguments:
commit_file
: the file to run emoji on, defaults to.git/COMMIT_EDITMSG
Flags:
-d, --debug
: the debug level,0
for none,1
for some,2
for all-t, --test
: test mode, input a commit message instead of a file
The default configuration is here: default.jsonc and the Emojis section.
This is used if no config file is found in the project.
Apart from emojis, the config also specifies other things, like:
format
: the format of the commit message, see Format.strict
: enforce formatting, and only allow commits with emojis (default:true
)
eemoji
can be configured two different ways: json and typescript config files.
This way your emojis will be merged with the default ones.
Use the init
command and select the ts
config type.
defineDefaultConfig
: use this to append your emojis to the default onesdefineConfig
: use this to define your own config, without the default emojis
eemoji
will look for these config files:
eemoji.config.ts
See all ...
.eemojirc.{js,ts,cjs,mjs}
eemoji.config.{js,ts,cjs,mjs}
.config/eemoji.config.{js,ts,cjs}
The format specifies how the commit message will be formatted ({emoji} {type}: {subject}
is the default format btw, this property is optional here).
{type}
: this determines the emoji{subject}
: rest of the commit message{emoji}
: the place of the emoji to be inserted
Some other formats I could think of:
{emoji} {type} - {subject}
{emoji} {type} {subject}
{type}: {emoji} {subject}
import { defineConfig } from 'eemoji'
export default defineConfig({
format: '{emoji} {type}: {subject}',
emojis: {
fix: '🔧',
chore: '🗑️',
feat: '✨',
docs: '📝',
test: '🧪'
}
})
Example:
Commit message:
- before:
fix: navbar issue
- after:
🔧 fix: navbar issue
You can also nest emojis to create subtypes.
After finding the type, eemoji
will look for subtypes in the commit message.
This is useful for conventional commit scopes, but you can include the subtype anywhere in the commit message.
Notes:
- the
'.'
is the fallback subtype - specify multiple emojis by separating them with commas and a random one will be chosen:
💎,💲,💸,💰
import { defineConfig } from 'eemoji'
export default defineConfig({
emojis: {
fix: {
'.': '🔧',
'typo': '✏️',
'bug': '🐛'
},
chore: {
'.': '🗑️',
'release': '🔖',
'cleanup': '🧹',
'license': '📜',
'deps': '📦'
},
feat: '✨',
bounty: '💎,💲,💸,💰'
}
})
Examples:
Commit message:
- before:
fix: navbar issue
- after:
🔧 fix: navbar issue
- before:
fix: typo in README
- after:
✏️ fix: typo in README
- before:
chore: release v1.0.0
- after:
🔖 chore: release v1.0.0
- before:
chore(deps): update eslint
- after:
📦 chore(deps): update eslint
You can use presets, which are just functions with emoji objects that are included in the package.
Note
The emojis
property can be an array of presets and objects
import { defineConfig, presetDefault } from 'eemoji'
export default defineConfig({
emojis: [
presetDefault(),
{
feat: '✨',
fix: '🔧'
}
]
})
Same deal, but you overwrite the whole config.
Use the init
command and select the json
config type to generate a config file.
Important
You must specify the format
property
You also get types thanks to the JSON schema.
eemoji
will look for these config files:
.eemojirc.json
See all ...
.eemojirc
.eemojirc.{json,yaml,yml}
.config/eemojirc
.config/eemojirc.{json,yaml,yml}
eemoji
WILL NOT work with GitHub Desktop on Windows unless you do this.
This sucks, but this is an open issue with GitHub Desktop.
Follow these steps:
- Move
C:\Program Files\Git\cmd
to the top of your systemPATH
- Add
C:\Program Files\Git\bin
just below that - Restart GitHub Desktop
If it continues to fail to work, try this as well and restart everything:
- Run this command once:
git config stash.usebuiltin false
To add a new emoji to a preset (even the default config) or modify it, open an issue first.
Then, if it's okay:
- modify the default.jsonc file, add the emoji and a description
- The Action will take care of the rest (copying it to the json, updating the readme emoji table and the json schema)
- open a PR
Add a new jsonc
(note the c
at the end) file to the presets folder and name it as you wish.
Describe the emoji using comments.
Example:
{
"fix": "🔧", // general fix
"feat": "✨" // introduced a new feature
}
Locate the presets.ts file and add your preset like this:
export const [
presetDefault,
presetMinimal,
/* ... */
// add your presetSomething here
] = createPresets([
'default',
'minimal',
/* ... */
// add your file name here (without the .jsonc extension)
]) as [
Preset,
Preset,
/* ... */
// and make TypeScript happy
]
Then open a PR, the Action will take care of the rest.
ni
Use the stub
script to run have the latest changes build:
nr stub
Run commands with the dev
script:
nr dev <command>
Also check the TODO file and open an issue first if you want to work on something.
[![eemoji](https://img.shields.io/badge/😎%20eemoji-fccf1d?style=for-the-badge)](
https://github.com/Rettend/eemoji)