Guide · Open source
How to use gitmoji: emoji commit messages, step by step
Updated · written with AI from the project's own documentation and checked against our catalogue data
Gitmoji is a shared guide that pairs emojis with the purpose of a Git commit, so you can see what a change does by scanning the start of its message. This tutorial explains what the project provides, how to install the gitmoji-cli client with npm, and the message format to follow. By the end you will be able to write emoji-prefixed commits and decide whether the convention suits your team.
gitmojicarloscuesta/gitmoji · ★ 16.8k · MIT Install options & downloads Quick start
- 1Check prerequisites. Make sure Node.js and npm are installed, since the gitmoji-cli install command needs them.
- 2Install gitmoji-cli. Run npm i -g gitmoji-cli to install the interactive client globally.
- 3Browse the emoji guide. Open gitmoji.dev and find the emoji that matches the purpose of your change.
- 4Write the message. Follow the pattern intention, optional scope, then a brief message.
- 5Agree on conventions as a team. Decide which emojis your team will use so commit history stays consistent.
- 6Optionally use the npm package. Add the gitmojis npm package if you want the emoji list inside your own tooling.
What gitmoji is and what it provides
Gitmoji is an initiative to standardize and explain the use of emojis in GitHub commit messages. Each emoji in the list is meant to signal the purpose or intention of a change, such as a bug fix or a new feature, when it is written at the start of a commit message.
The project publishes the guide on its website at gitmoji.dev and also as an npm package, so tools can use the emoji list as a dependency.
Install the gitmoji-cli client
Gitmoji's README links to gitmoji-cli, an interactive command-line client for picking emojis while you commit. Node.js and npm are required for the install command shown in the README.
Install it globally with the command below.
npm i -g gitmoji-cliUse the commit message format
The README suggests a practical pattern for commit messages. It has three parts: an intention, an optional scope, and a message. The intention is an emoji from the list, the scope is an optional string giving context for the change, and the message is a brief explanation of the change.
- intention: an emoji from the list
- scope: an optional string that adds contextual information for the scope of the change
- message: a brief explanation of the change
<intention> [scope?][:?] <message>Choose the right emoji for each change
The guide on gitmoji.dev lists the emojis and what each one signals. Pick the one that best matches the purpose of the commit. Because the README calls gitmoji a convention rather than a formal spec, the team should agree on which emojis to use and how to apply them.
If you want an emoji added to the list, the README says to create an issue and send a pull request. Discussion of emojis happens in the issues section.
Use the npm package in your own tooling
The gitmojis are published as an npm package so you can use the emoji list as a dependency in your own project. Check the package listing linked from the README for its contents.
Add the gitmoji badge to your README
If your project uses gitmoji, the README shows an HTML snippet for a badge that links back to gitmoji.dev. Paste it near the top of your own README.
<a href="https://gitmoji.dev">
<img
src="https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square"
alt="Gitmoji"
/>
</a>What people use it for
- Scanning a long commit history and spotting bug fixes or new features by their leading emoji
- Keeping commit messages consistent across a team with a shared emoji list
- Pulling the emoji list into your own tooling through the gitmojis npm package
- Showing the gitmoji badge in a project README to signal that the project uses the convention
Frequently asked questions
How do I install gitmoji?
Gitmoji's README gives one install command for the client: npm i -g gitmoji-cli. This installs the interactive command-line client globally, and you need Node.js and npm first.
What are the requirements for gitmoji?
The README names Node.js and npm as the prerequisites, needed for the gitmoji-cli install command. The emoji guide itself is available on the website at gitmoji.dev.
Is gitmoji free to use?
Gitmoji is released under the MIT license, as stated in the README. The README does not describe any paid tier.
Is gitmoji a formal commit standard?
No. The README describes emojis as a convention rather than a formal spec, so it is not meant to be parsed strictly by machines. Teams that need a strict machine-parsed format should look elsewhere.
How does gitmoji compare to Conventional Commits?
Conventional Commits is a structured message format, while gitmoji adds a visual emoji cue to the start of a message. The two can be combined, since gitmoji suits developers who already use conventional commit-style messages.
What are the alternatives to gitmoji?
Comparable projects include Conventional Commits, Commitizen and Commitlint. Choose based on whether you want a visual cue, a structured format or commit linting.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Gitmoji suits teams that want a scannable commit history and developers who already use conventional-style messages and like a visual cue. Skip it if you need a strict machine-parsed commit format or prefer plain-text messages without symbols.
Install options & downloads