Git commit-msg hook to automatically bring some emojion to commit messages.
Assumes Conventional Commits with commit types roughly based on (a subset of) the Angular commit message format.
- Rewrites (some) commit type prefixes to emoji:
fix: broken thing now works
->🪲 broken thing now works
- Inserts emoji to to illustrate type of (some) commits, even when not using conventional-commit
type:
prefix:
fix broken thing
->🪲 fix broken thing
- Rewrites
:emoji_shortcodes:
to unicode emoji characters (for nicer display in terminals too, e.g.git log
)
initial commit :tada:
->initial commit 🎉
npm install emojional-commitment --save-dev
# configure git commit-msg hook to call `npx emojional-commitment`
# ..here we use husky to manage git hooks:
npm install husky --save-dev
npm set-script prepare "husky install"
npm run prepare
# add the hook: (slightly complex to work around npx bug - see below)
npx --package=husky -c "husky add .husky/commit-msg 'npx emojional-commitment \"\$1\"'"
# commit updated dev dependencies and the .husky/commit-msg git hook to your repo
git add .husky/commit-msg package*.json
git commit -m "build: process commit messages with emojional-commitment"
# `emojional-commitment` will run every time you commit
At the time of writing, npx has a bug not passing through escaped command arguments - so we can't simply run npx husky add commit-msg 'npx emojional-commitment $1'
. See https://github.com/typicode/husky/issues/1019, https://github.com/npm/cli/issues/3067.
<type>: commit message
-><emoji> commit message
Roughly based on (a subset of) the Angular commit message format - although not every commit needs a <type>:
prefix, and not every type prefix needs an emoji..see philosophy, below
Emoji | Type prefix(es) | Description |
---|---|---|
✨ |
feat feature
|
New feature |
🪲 | fix |
Bug fix |
🏎 | perf |
A code change that improves performance |
♻️ | refactor |
A code change that neither fixes a bug nor adds a feature |
🚥 |
test tests
|
Add or fix tests |
💅 |
tidy polish style
|
Tidy/prettify code |
Emoji | Type prefix(es) | Description |
---|---|---|
📚 |
docs doc
|
Documentation-only changes |
🛠️ | build |
Changes that affect the build system or external dependencies |
🤖 | ci |
Changes to our CI configuration files and scripts |
We intentionally avoid doing anything for other commit types - see below. Not every commit needs an emoji..
-
Commit history that's fun/pleasing to inspect, and benefits from enhanced ease/speed of interpretation/skimming.
- We're primarily concerned with the apearance of a list of commits - inspecting single commit typically comes with a bunch more context that we're aware of/paying attention to beyond just the commit message
-
Use emoji to add some fun / colour - but also add meaning. Avoid additional cruft in commit messages that serves no purpose or causes confusion. In particular we keep the number of emoji/commit types low - and don't feel the need to annotate every single commit.
- Opinion: the Angular convention of type prefixes for every commit introduces too much cruft that often doesn’t enhance the meaning of the commit message, while breaking the left-alignment of the actual message content - inhibiting easy scanning of a commit history.
- Emoji replacing type prefixes solves the left-alignment problem, while significantly reducing the total character count for much improved scanning.
-
Emoji add emphasis - not every commit needs to be highlighted with one. (In fact we try to use as few as possible so the ones we do use stand out better.)
- We intentionally avoid doing anything for:
-
chore:
- should be of little significance, not something to draw attention to while reviewing historic commits. Encourage the use of more descriptive types - or simply no type prefix for small things. (Just describe the change, don’t need make a big deal of it - it’s an advantage to make it appear of secondary importance in the commit history). -
Releases - just commit with version label, including “v” prefix:
vX.X.X
. Self-explanatory, no additional annotation required. -
Merge commits - generally aim to squash-and-merge, picking a descriptive type (
feat|fix|refactor..
). If doing a merge commit (--no-ff
), stick with standard GitHub conventionMerge pull request #xx from <repo/branch>
. (The story will be told by the individual commits and their commit messages, which is where we wish to draw attention.) -
Reverts - generally stick with standard git convention
Revert ‘<original commit id>’
- a revert typically represents a small step backwards. If we're reverting a significant feature/behaviour, we'd expect to see an appropriately descriptive commit message - the revert itself is likely a (temporary)🪲 fix:
..
-
- The presence of some emoji draw quick attention to more significant commits - features, fixes, tests, docs, refactoring1, meta-changes not regarding app itself (build/ci).
- We intentionally avoid doing anything for:
Finally - to be used by people with a healthy disregard for rules(!) If you wish to sprinkle your commits with emoji on occasion, this package isn't here to police that.. (that's why we also rewrite :shortcodes:
and provide flexibility when no <type>:
prefix is given). But do try to use sparingly, appreciating the intent of Conventional Commits and the philosophy above.. 😉
- We pad emoji with
en-space
characters to provide pleasing visual spacing when displayed on GitHub etc
-
Of note, “refactoring” describes more than just cutting/pasting code around - it also encompasses many implementation changes (that don’t affect external behaviour) - e.g. underlying algorithm changes or rewrites. “Refactoring is intended to improve the design, structure, and/or implementation” - https://en.wikipedia.org/wiki/Code_refactoring ↩