Emoji-Log: A new way to write Git commit messages

Add context to your commits with Emoji-Log.
171 readers like this.

I'm a full-time open source developer—or, as I like to call it, an ? open sourcerer. I've been working with open source software for over a decade and built hundreds of open source software applications.

I also am a big fan of the Don't Repeat Yourself (DRY) philosophy and believe writing better Git commit messages—ones that are contextual enough to serve as a changelog for your open source software—is an important component of DRY. One of the many workflows I've written is Emoji-Log, a straightforward, open source Git commit log standard. It improves the developer experience (DX) by using emoji to create better Git commit messages.

I've used Emoji-Log while building the VSCode Tips & Tricks repo, my ? Shades of Purple VSCode theme repo, and even an automatic changelog that looks beautiful.

Emoji-Log's philosophy

I like emoji (which is, in fact, the plural of emoji). I like 'em a lot. Programming, code, geeks/nerds, open source… all of that is inherently dull and sometimes boring. Emoji help me add colors and emotions to the mix. There's nothing wrong with wanting to attach feelings to the 2D, flat, text-based world of code.

Instead of memorizing hundreds of emoji, I've learned it's better to keep the categories small and general. Here's the philosophy that guides writing commit messages with Emoji-Log:

  1. Imperative
    • Make your Git commit messages imperative.
    • Write commit message like you're giving an order.
      • e.g., Use ✅ Add instead of ❌ Added
      • e.g., Use ✅ Create instead of ❌ Creating
  2. Rules
    • A small number of categories are easy to memorize.
    • Nothing more, nothing less
      • e.g. ? NEW, ? IMPROVE, ? FIX, ? DOC, ? RELEASE, and ✅ TEST
  3. Actions
    • Make Git commits based on actions you take.
    • Use a good editor like VSCode to commit the right files with commit messages.

Writing commit messages

Use only the following Git commit messages. The simple and small footprint is the key to Emoji-Logo.

    • Use when you add something entirely new.
      • e.g., ? NEW: Add Git ignore file
    • Use when you improve/enhance piece of code like refactoring etc.
      • e.g., ? IMPROVE: Remote IP API Function
    • Use when you fix a bug. Need I say more?
      • e.g., ? FIX: Case converter
    • Use when you add documentation, like README.md or even inline docs.
      • e.g., ? DOC: API Interface Tutorial
    • Use when you release a new version. e.g., ? RELEASE: Version 2.0.0
    • Use when you release a new version.
      • e.g., ✅ TEST: Mock User Login/Logout

That's it for now. Nothing more, nothing less.

Emoji-Log functions

For quick prototyping, I have made the following functions that you can add to your .bashrc/.zshrc files to use Emoji-Log quickly.

#.# Better Git Logs.
### Using EMOJI-LOG (https://github.com/ahmadawais/Emoji-Log).

# Git Commit, Add all and Push — in one step.
function gcap() {
    git add . && git commit -m "$*" && git push

# NEW.
function gnew() {
    gcap "? NEW: $@"

function gimp() {
    gcap "? IMPROVE: $@"

# FIX.
function gfix() {
    gcap "? FIX: $@"

function grlz() {
    gcap "? RELEASE: $@"

# DOC.
function gdoc() {
    gcap "? DOC: $@"

function gtst() {
    gcap "✅ TEST: $@"

To install these functions for the fish shell, run the following commands:

function gcap; git add .; and git commit -m "$argv"; and git push; end;
function gnew; gcap "? NEW: $argv"; end
function gimp; gcap "? IMPROVE: $argv"; end;
function gfix; gcap "? FIX: $argv"; end;
function grlz; gcap "? RELEASE: $argv"; end;
function gdoc; gcap "? DOC: $argv"; end;
function gtst; gcap "✅ TEST: $argv"; end;
funcsave gcap
funcsave gnew
funcsave gimp
funcsave gfix
funcsave grlz
funcsave gdoc
funcsave gtst

If you prefer, you can paste these aliases directly in your ~/.gitconfig file:

# Git Commit, Add all and Push — in one step.
cap = "!f() { git add .; git commit -m \"$@\"; git push; }; f"

# NEW.
new = "!f() { git cap \"? NEW: $@\"; }; f"
imp = "!f() { git cap \"? IMPROVE: $@\"; }; f"
# FIX.
fix = "!f() { git cap \"? FIX: $@\"; }; f"
rlz = "!f() { git cap \"? RELEASE: $@\"; }; f"
# DOC.
doc = "!f() { git cap \"? DOC: $@\"; }; f"
tst = "!f() { git cap \"✅ TEST: $@\"; }; f"

Emoji-Log examples

Here's a list of repos that use Emoji-Log.

Ahmad Awais
Founder & CEO at Langbase.com — Ship composable hyper-personalized Al apps in seconds · Ex VP DevRel Eng. Rapid · Google Developers Advisory Board (gDAB) founding member. 🧑‍💻 AI/ML/DevTools Angel Investor ❯ AI/ML Advisory Board member San Francisco, DevNetwork


So sad that simple and concise messages are not enough for people these days, they feel the need to dress everything up with inane little images.

Emoji log is simple and concise. It's actually what we call #M11Y Media based accessibility. E.g. just like if there's a ✅mark behind a notification you instantly know it's an "OK NOTICE" and something good happened. And when there's ❌behind it. That's a "SOMETHING WENT WRONG" notification — even before you read what happened.

In reply to by fredd (not verified)

To me it is unneeded fluff. A simple 'OK' or 'NOT OK' would suffice as far as I am concerned.

I think that peoples reliance on visual cues, and the ridiculous overuse of gifs, memes, etc, to convey ones message helps to contribute to deterioration of the written word that pollutes the internet.

I also think that such things aid in making it easier for people to skip the details. They see the tick or the cross and then just skim the specifics.

Maybe it is just me being the old fart that I am but I enjoy reading words.

In reply to by mrahmadawais

Thanks for your honesty. I also prefer less UI. But Emoji makes this 2D world a bit more fun.

In reply to by fredd (not verified)

I wrote about it under the heading of Philosophy! Kindly read that. "Instead of memorizing hundreds of emoji, I've learned it's better to keep the categories small and general." Can you and your team seriously remember hundreds of emoji messages from GitMoji?

In reply to by eyarz (not verified)

I like the idea of enriching commit messages with symbols - but emojis seem to overdo it.

One problem is that they will rarely match their intended meaning well. The 'fix' emoji that you use primarily means an animal and associates with wildlife. So what does that have to do with fixing things?

Another problem is that emojis do not have a universal meaning. Take the thumbs up for example - in the US it's a sign of approval, in Greece it is an insult.

Some visual clues in commit messages are a nice idea, but you're better off using simpler, more abstract symbols. Look at JIRA for a good example.

You're right I should do a better job at explaining the emoji as well. Thank you.

? Emoji meaning: A "package emoji" — which can contain new stuff.
? Emoji meaning: An "OK Hand emoji" — which is meant to appreciate an improvement.
? Emoji meaning: A "bug emoji" — which means there was a bug that got fixed.
? Emoji meaning: A "book emoji" — which means documentation or notes just like in a book.
? Emoji meaning: A "rocket emoji" — which is meant to show a new release/launch.
✅ Emoji meaning: A "check emoji" — which says some test were run successfully.

In reply to by Zort (not verified)

Thanks for the ideas.
In your .gitconfig/aliases example, I did run into an issue. I had to change:
cap = "!f() { git add .; git commit -m \"$@\"; git push; }; f"
cap = "!f() { git add .; git commit -m \"$*\"; git push; }; f"

This made it match up with your bash/zsh functions.

Viewing this article, I cannot see any of your example emoji in Chrome. Switching to Mozilla I can see them. That's one of the risks of using images instead of text, emoji aren't universally supported on all platforms.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.