Gitmoji: The Emoji Guide for Commit Messages, and Where It Fits

What gitmoji actually is, and who the guide is written for

Gitmoji is described in its README as an initiative to standardize and explain the use of emojis on GitHub commit messages. That is the whole scope. The project publishes a list of emojis with assigned intentions, a recommended message format, and an npm package called gitmojis so other tools can consume the list as a dependency. The README frames the benefit narrowly: using an emoji on a commit message gives an easy way of identifying the purpose or intention of a commit from the emoji alone.

The audience is therefore people who scan history rather than read it. If you run git log --oneline and want to know which of forty commits touched documentation and which fixed a bug, an emoji prefix does that without opening a diff. The README also notes that because there are many different emojis, a guide is needed to keep the choices consistent. That is the real product: not the emoji, but the shared mapping from intention to symbol. Without an agreed list, every contributor invents their own, and the signal collapses.

It is not a commit convention with machine-readable semantics. Nothing in the repository parses the emoji back out. The value is entirely in human reading, which is also why it is cheap to adopt and cheap to abandon.

The message format and what each position means

The README gives one format string, presented as a practical way to integrate gitmoji into a project:

<intention> [scope?][:?] <message>

Three parts. The intention is an emoji from the list. The scope is optional and the README describes it as a string that adds contextual information for the scope of the change. The message is a brief explanation of the change. The colon after the scope is optional as well, which is worth noting because it means the format is looser than Conventional Commits, where the colon and the parenthesised scope are structural and a parser will reject a subject that omits them.

That looseness cuts both ways. A human reading the log does not care whether the colon is present. A tool does. If you later want to generate a changelog from commit subjects, the gitmoji format gives you an emoji and free text, not a typed field you can filter on without writing your own mapping from emoji to category. The repository does not ship that mapping as a parser, only as data in the gitmojis package.

One practical consequence: the intention sits first, at the very start of the subject line. Anything that truncates the subject from the left, or that sorts or groups commits by leading character, will see the emoji before it sees the words.

Installing gitmoji-cli and making a first emoji commit

The repository you are reading is the guide and the data package. The command line tool is a separate project, gitmoji-cli, and the README points there explicitly for terminal use, describing it as an interactive client for using emojis on commit messages. Install it globally with npm:

npm i -g gitmoji-cli

After that, the client is what you invoke when committing. The README does not document the client's own flags or subcommands, so check that project's documentation for the exact invocation; what the guide guarantees is the emoji list and the message format the client draws from.

If you want the emoji data inside your own tooling instead of using the client, the README says the gitmojis are published on the gitmojis package so they can be used as a dependency:

npm install gitmojis

The package name is gitmojis, plural. The repository is gitmoji, singular, and the CLI is gitmoji-cli. Mixing these up is the most common first mistake when wiring the data into a script.

For manual use, no install is required at all. Pick an emoji from the list, write the subject in the documented shape, and commit. The README's own example is the format line above; a concrete subject following it would put the intention emoji first, an optional scope in brackets, and the message last.

Contributing a new emoji, and why the list is deliberately slow to change

The README describes the contribution path in some detail. You discuss emojis in the issues section, and to add a new emoji to the list you create an issue and send a pull request, following the instructions in the contributing guidelines under a section titled how to send a pull request and add a gitmoji. So additions are reviewed, not merged automatically.

That is a design decision with a cost. A reviewed list stays coherent: two emojis do not end up meaning the same thing, and the guide does not drift into a personal collection. The cost is latency. If your team needs a symbol for something the list does not cover, you either wait for the review or you go off-list, and off-list emojis are exactly the inconsistency the guide exists to prevent.

The repository layout supports this reading. It is a pnpm workspace with a packages directory and a turbo.json at the root, so the emoji data and any site or tooling built on it live as workspace packages rather than one flat codebase. The root package.json is private and declares Node 22 and pnpm 8 or newer as the engine requirements, with husky and lint-staged configured for pre-commit checks. If you plan to contribute, matching those versions locally is the first thing to check, because the workspace manager and Node major version are pinned.

Where gitmoji is the wrong tool

The clearest failure mode is a project that generates release notes from commit history with a Conventional Commits parser. Those parsers expect a type token such as a word followed by a colon, and they use it to decide whether a commit is a feature, a fix or a chore. An emoji at the front of the subject is not that token. You can put both in one subject, but then you are maintaining two conventions and the emoji is decorative, which defeats the stated purpose of identifying intention from the emoji alone.

The second case is any environment where emoji input is unreliable. The README does not discuss terminals, fonts or editors, and it does not claim the tooling handles rendering. If a contributor's editor mangles multi-byte characters, or their terminal shows a placeholder box, the signal is gone for whoever reads that log. Gitmoji assumes the whole chain from keyboard to log viewer preserves the character, and the repository does not verify that assumption for you.

Third, gitmoji is a convention, not an enforcement mechanism. There is no hook in this repository that rejects a commit without an emoji. If your team's problem is that people write bad commit messages, adding a list of emojis does not fix it, because a vague message with an emoji in front is still vague. The guide improves the first character of the subject and nothing else.

Conventional Commits, and the real difference in approach

Conventional Commits is the alternative most often weighed against gitmoji, and the difference is not cosmetic. Conventional Commits defines a structured type prefix that tooling parses: the type is a controlled vocabulary of words, and the structure is strict enough that a release automation script can group commits by type without human judgement. Its output is machine-readable by design.

Gitmoji's prefix is an emoji, and its stated purpose in the README is human identification of intent at a glance. The repository publishes the mapping as data in the gitmojis package, so a determined team could build a parser on top, but the project does not ship one, and the format string in the README marks the scope and the colon as optional, which is the opposite of what a parser wants.

So the trade is legibility against parseability. Gitmoji wins when the primary consumer is a person scrolling a log or a pull request list, because an emoji is faster to recognise than a word. Conventional Commits wins when the primary consumer is a script that must not guess. Choosing both means accepting the redundancy, and the honest position is that most teams should pick the one their downstream tooling actually reads.

Licence, maintenance and what an upgrade costs you

The code is available under the MIT licence, per the README, and the LICENSE file sits at the repository root. MIT is permissive: you can use the emoji data in a commercial product, modify it, and redistribute it, provided the copyright notice and permission notice are preserved. That is the general shape of the licence, not legal advice for your situation; if you are embedding the data in a distributed product, have someone check the notice requirements.

The maintenance picture is concrete. The repository is not archived, and the last push was on 2026-09-18. The most recent release in the list is v3.15.0 from 2025-03-12, preceded by v3.14.0 in October 2023 and v3.13.5 in May 2023. So releases are infrequent and unevenly spaced, which is consistent with a project whose main artefact is a curated list rather than a fast-moving runtime. A stalled release cadence matters little here: the emoji mapping does not rot, and the gitmojis package is data.

Upgrade cost is correspondingly low for consumers. If you depend on gitmojis, a new version adds or adjusts entries in a list, and your code that reads it does not change shape. The larger cost is social, not technical: every new emoji is a new symbol your contributors have to learn, and the guide's usefulness depends on people actually using the same one for the same thing.

Editorial conclusion

Adopt gitmoji if your team already reads commit subjects in a terminal and wants a one-glance signal for intent; the format is small enough to learn in an afternoon. Do not adopt it if your release notes are generated by a Conventional Commits parser or if your contributors cannot reliably type emoji. Before rolling it out, verify two things: that gitmoji-cli is the tool you want (it is a separate repository from the one that holds the emoji list), and that your CI or changelog tooling does not key off the first character of the subject line. The repository itself is a specification and a package, not a commit hook; nothing enforces the format unless you add something that does.

Frequently asked questions

Official sources

1. carloscuesta/gitmoji on GitHub
2. License: MIT
3. Project website
4. README
5. Releases