Gitmoji — An Emoji Guide for Commit Messages

Introduction

Gitmoji is a standardized emoji guide for git commit messages. Each emoji maps to a specific type of change, making commit history scannable at a glance. The project includes a searchable web reference and a CLI tool that walks you through composing well-structured commits.

What Gitmoji Does

• Defines a curated set of emoji-to-intent mappings for commit messages
• Provides an interactive CLI that prompts for the right emoji, scope, and description
• Offers a searchable web reference at gitmoji.dev for quick lookup
• Integrates with git hooks to enforce emoji-prefixed commits across teams
• Supports custom emoji mappings via a local configuration file

Architecture Overview

The project is split into two parts: the gitmoji specification (a JSON list of emoji-intent pairs) and gitmoji-cli (a Node.js CLI tool). The CLI hooks into git commit via an interactive wizard or can be set up as a prepare-commit-msg hook. The web reference is a static site generated from the same JSON source of truth.

Self-Hosting & Configuration

• Install the CLI globally: npm install -g gitmoji-cli
• Initialize in a repo: gitmoji -i to set up a git hook
• Configure with gitmoji -g to set emoji format (emoji character vs :code:)
• Add custom mappings in .gitmoji config file at the project root
• Works alongside Commitlint and Husky for enforced commit conventions

Key Features

• Over 70 curated emoji mappings covering features, fixes, docs, CI, deps, and more
• Interactive commit wizard with fuzzy search for finding the right emoji
• Git hook integration for team-wide commit message consistency
• Configurable emoji output format: Unicode emoji or GitHub :shortcode: syntax
• Active community maintaining the specification with regular additions

Comparison with Similar Tools

• Conventional Commits — uses text prefixes like feat:/fix: instead of emoji; Gitmoji adds visual scanning speed
• Commitizen — similar interactive commit flow; Gitmoji focuses on emoji semantics rather than changelog generation
• Commitlint — validates commit format but does not suggest content; pairs well with Gitmoji for enforcement
• Semantic Release — automates versioning from commits; can consume Gitmoji-prefixed messages with a parser plugin

FAQ

Q: Can I use Gitmoji with Conventional Commits? A: Yes. Many teams combine both, using an emoji prefix followed by a conventional type like feat: or fix:.

Q: Does the emoji format affect git tooling? A: No. Git treats emoji as regular UTF-8 characters. GitHub, GitLab, and Bitbucket all render them in commit logs.

Q: How do I enforce Gitmoji across a team? A: Run gitmoji -i in the repo to install a prepare-commit-msg hook, or pair it with Husky and Commitlint.

Q: Can I customize the emoji list? A: Yes. Create a .gitmoji configuration file to add, remove, or remap emoji to match your team's conventions.

Sources

• https://github.com/carloscuesta/gitmoji
• https://gitmoji.dev/