How to Use Emojis in Git Commit Messages

Why Use Emojis in Git Commits?

A well-structured commit history is a form of documentation. Emojis add visual scannability — a quick glance at 🐛 tells you it's a bug fix; ✨ signals a new feature; 📝 means documentation. When browsing hundreds of commits in git log or a GitHub repository, emojiEmoji
A Japanese word (絵文字) meaning 'picture character' — small graphical symbols used in digital communication to express ideas, emotions, and objects. prefixes let you parse the nature of each change at a glance.

The most widely adopted convention is Gitmoji (gitmoji.dev), a specification that assigns specific emojis to specific types of code changes. Many teams also use emojis alongside or instead of Conventional Commits (feat, fix, docs, etc.).

The Gitmoji Convention

Gitmoji defines a standardized vocabulary. Here are the most commonly used entries:

How to Write an Emoji Commit

Using the Literal Emoji Character

The simplest approach is to paste the emoji character directly into your commit message:

git commit -m "✨ Add user avatar upload feature"
git commit -m "🐛 Fix null pointer in payment processor"
git commit -m "📝 Update API authentication docs"

This works on any modern terminal, GitHub, GitLab, Bitbucket, and most CI/CD dashboards. The emoji is stored as a literal UTF-8UTF-8
A variable-width Unicode encoding that uses 1 to 4 bytes per character, dominant on the web (used by 98%+ of websites). character in the commit message.

Using Shortcode Notation

Some teams prefer to write shortcodes instead of literal emojis, then render them in their tooling:

git commit -m ":sparkles: Add user avatar upload feature"
git commit -m ":bug: Fix null pointer in payment processor"
git commit -m ":memo: Update API authentication docs"

GitHub renders shortcodes in commit messages automatically — :sparkles: becomes ✨ in the GitHub web UI. However, in the terminal git log, you'll see the raw text instead of the emoji. Most teams prefer literal emojis for this reason.

Installing the Gitmoji CLI

The official Gitmoji CLI tool provides an interactive prompt for choosing emojis when you commit:

# Install with npm
npm install -g gitmoji-cli

# Use instead of git commit
gitmoji -c

Running gitmoji -c opens an interactive list. Type to search, use arrow keys to select, press Enter, then fill in the commit title and body. The CLI inserts the emoji and formats the commit for you.

Integrating with Git Hooks

You can enforce Gitmoji in a project using a commit-msg hook. Create .git/hooks/commit-msg:

#!/bin/bash
commit_msg=$(cat "$1")
if ! echo "$commit_msg" | grep -qP "^(:\w+:|[\x{1F300}-\x{1F9FF}])"; then
  echo "Error: Commit message must start with a Gitmoji emoji or shortcode."
  exit 1
fi

This rejects any commit that doesn't begin with an emoji or Gitmoji shortcode.

Combining Emojis with Conventional Commits

Some teams blend Conventional Commits format with Gitmoji:

✨ feat(auth): add OAuth2 login support
🐛 fix(payments): handle expired card gracefully
📝 docs(api): add rate limiting documentation
♻️ refactor(db): extract query builder to separate module

This hybrid format gives you the machine-parseable type(scope): structure that tools like semantic-release use, plus the visual emoji prefix for human readers.

Viewing Emoji Commits in the Terminal

Standard git log renders emoji characters correctly in most modern terminals (iTerm2, macOS Terminal, Windows Terminal, GNOME Terminal). If your terminal shows question marks or boxes instead of emojis, the issue is usually the terminal's font or locale settings.

Fix font issues by using a Nerd Font or enabling emoji rendering in your terminal settings. Fix locale issues by ensuring LANG is set to a UTF-8 locale:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

For a prettier log, use this alias:

git config --global alias.elog "log --oneline --graph --pretty=format:'%Cred%h%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'"
git elog

Emoji Commits on Platforms

GitHub: Displays literal emoji characters natively in commit messages, PR titles, issue titles, and release notes. Shortcodes are also rendered.

GitLab: Same as GitHub — emoji characters and shortcodes both render.

Bitbucket: Renders literal emoji characters. Shortcode support is more limited.

Terminal git log: Shows raw UnicodeUnicode
Universal character encoding standard that assigns a unique number to every character across all writing systems and symbol sets, including emoji. characters. Modern terminals render these correctly.

CI/CD pipelines: Most modern CI systems (GitHub Actions, GitLab CI, CircleCI) handle emoji in commit messages without issues. They're just text.

A Simple Team Emoji Policy

If Gitmoji feels like too much to memorize, start with a small set of 5–6 emojis that cover 90% of commits:

Document your team's chosen emoji set in the project README and stick to it. Consistency matters more than completeness.

Converting Text Descriptions to Emojis

Not sure which emoji fits your commit? EmojiFYI's text-to-emoji tool can help. Describe what your commit does in plain English and it suggests matching emojis. It's a quick way to find the right emoji without memorizing the full Gitmoji spec.