Gitmoji Template
Gitmoji uses an emoji at the start of a commit message to communicate the kind of change. Choose the emoji by its meaning in the Gitmoji guide, then write a clear description. Tower supports Gitmoji on both Mac and Windows: type :: in the commit subject to open its emoji picker.
- Your team uses emoji prefixes to make commit history easier to scan.
- You want a visual indication of the change alongside a descriptive subject.
- You use Tower's Gitmoji picker and want a reusable message structure.
Template
Replace each <placeholder> by hand when you write a commit.
Lines starting with # are guidance that Git removes in its default cleanup mode.
Completed example
A bug fix preventing repeated submissions in a web app.
🐛 Prevent duplicate form submissions Disable the submit button while the request is pending so repeated clicks cannot create duplicate entries. Re-enable it after a failed request so the user can retry.
Guidance
Rules
Based on Gitmoji. Refer to the original guide for the full convention.
- Begin the subject with a Gitmoji emoji or shortcode, followed by a space and a meaningful description.
- Use the official emoji meanings; choose by the intent of the change rather than decoration.
- Common mappings: ✨
:sparkles:for features, 🐛:bug:for fixes, 📝:memo:for documentation, ♻️:recycle:for refactoring, and ⚡️:zap:for performance. - Keep Unicode emoji and shortcode usage consistent with the repository's existing convention.
- Use 💥
:boom:for breaking changes and explain the compatibility impact and migration in the body. - An emoji does not replace the description; a reader should understand the change from the words too.
- The optional body structure and concise subject are recommendations for this template, not additional requirements imposed by Gitmoji.
Optional fields
- Scope
- If your team uses scopes, include the affected area after the emoji, for example
🐛 (forms): prevent duplicate submissions. - Body
- Add context after a blank line when the subject alone is insufficient.
- Issue references
- Include a real issue reference when the change is linked to one; do not invent an identifier.
Common mistakes
- Picking an emoji for its appearance rather than its documented meaning.
- Using only an emoji or a vague subject such as "Updates".
- Switching between Unicode and shortcodes without following the team's convention.
- Assuming an emoji prefix alone makes the message a Conventional Commit.
How it relates to other templates
Gitmoji adds a visual indicator to the Simple Commit structure. You can use the Bug Fix or Detailed Change body sections when more context helps. Gitmoji and Conventional Commits are separate conventions: an emoji before the type does not follow the standard Conventional Commits prefix and may fail its validators. Follow your team's tooling if you combine them.
Use this template
Use in Tower
Tower supports Gitmoji on both Mac and Windows. Type :: in the commit subject to open the emoji picker, then replace the template's <gitmoji> placeholder with the emoji that matches your change. See Gitmoji in Tower.
Tower for Mac
- Open Tower's Settings and select the Templates tab.
- Create a new template and enter the subject and body below. You can also download the template file and import it from the same tab. After importing, remove the lines that start with
#. They're guidance for Git's editor. - To use it by default, set it as the global Git value in the Templates tab, or pick it as the default commit template in a repository's settings.
- When you write a commit, click the Commit template button below the description field, or type t: or / in the subject field to choose a template.
More details: Commit Templates in the Tower for Mac documentation.
Tower for Windows
- Open Tower's Preferences and select the Templates tab.
- Click + to create a new template and enter the subject and body below.
- To use it by default, set it as the global default template, or pick it as the default in a repository's settings.
- When you write a commit, click the Commit template button in the commit composer, or type t: or / in the subject field to choose a template.
More details: Commit Templates in Tower for Windows.
Template fields for Tower
The library version with Git's # comment lines removed. If you edited the template above, copy your version from the editor instead.
Subject
<gitmoji> <Summarize the change>Body
<Optional body: explain what changed and why.>Use with the Git command line
Download gitmessage-gitmoji.txt
The commands below assume the file is in your Downloads folder.
macOS and Linux (Terminal)
Try it once
Run this in a repository with staged changes. Git opens your editor with the template filled in:
git commit --template ~/Downloads/gitmessage-gitmoji.txtMake it the default for one repository
From the repository's root folder, save the file as .gitmessage and point Git to it:
mv ~/Downloads/gitmessage-gitmoji.txt .gitmessage
git config commit.template .gitmessageMake it your global default
Save the file in your home folder and use it for every repository without its own setting:
mv ~/Downloads/gitmessage-gitmoji.txt ~/.gitmessage
git config --global commit.template "~/.gitmessage"Windows (PowerShell)
Try it once
Run this in a repository with staged changes. Git opens your editor with the template filled in:
git commit --template "$HOME\Downloads\gitmessage-gitmoji.txt"Make it the default for one repository
From the repository's root folder, save the file as .gitmessage and point Git to it:
Move-Item "$HOME\Downloads\gitmessage-gitmoji.txt" .gitmessage
git config commit.template .gitmessageMake it your global default
Save the file in your home folder and use it for every repository without its own setting:
Move-Item "$HOME\Downloads\gitmessage-gitmoji.txt" "$HOME\.gitmessage"
git config --global commit.template "~/.gitmessage"Share it with your team
Commit .gitmessage to the repository so everyone has the same file. Sharing the file does not configure anyone's Git: Git never applies settings from a repository automatically, so each teammate runs this once in their clone:
git config commit.template .gitmessageInspect, change, or remove the default
# Show the configured template and where it's set
git config --show-origin --get commit.template
# Point to a different file
git config commit.template path/to/other-template.txt
# Remove the repository or global setting
git config --unset commit.template
git config --global --unset commit.template- Templates guide, hooks enforce. A template only pre-fills the editor. To reject messages that don't follow a convention, add a commit-msg hook.
- Only the editor uses templates.
git commit -mandgit commit -Fbypass the template. - Unchanged templates abort the commit. If you save without editing the template, Git stops with "you did not edit the message".
- Comment removal depends on cleanup. Git strips
#lines under its defaultstripcleanup mode. With--cleanup=verbatim,--cleanup=whitespace, or a matchingcommit.cleanupsetting, they stay in the message. If you changedcore.commentChar,#lines aren't treated as comments. - Other commands write their own messages.
git revertandgit mergedon't loadcommit.template.
Setting up Git from scratch? The Git Config Generator builds a complete .gitconfig for you. See the git commit documentation for all options.
Use with coding agents
This skill teaches your coding agent to draft commit messages in the Gitmoji format, following the published Gitmoji convention. It uses the library version of the template. Edits you make in the editor above aren't included.
- Follows your repository's instructions and your explicit requests first.
- Reads the staged changes and keeps unstaged work out of the message.
- Never invents motivation, issue numbers, benchmarks, or test results. It leaves placeholders and asks instead.
- Flags breaking changes and unrelated changes that should be split.
- Drafts only. It won't stage, commit, or push unless you ask it to.
Download skill commit-message-gitmoji-v1.0.0.zip · Agent Skills format · MIT-0 license
Contains commit-message-gitmoji/SKILL.md with the instructions, references/REFERENCE.md with the rules and a completed example, and assets/template.txt.
Install in Claude Code
- Unzip the download. It contains a single folder named after the skill.
- Move that folder to
.claude/skills/in your repository to share it with your team, or to~/.claude/skills/to use it in all your projects. - Start a new Claude Code session and ask it to draft a commit message. You can also invoke the skill directly with
/commit-message-gitmoji.
See the Claude Code skills documentation for details.
Other agents
The package uses the open Agent Skills format, but we've only tested the agents listed above. For any other agent, check its documentation for skill support, or add the instructions below to its configuration file, such as AGENTS.md.
Copy the instructions
Add these instructions to your agent's configuration or your repository's AGENTS.md:
## Commit messages
Follow the Gitmoji convention (https://gitmoji.dev/).
```text
<gitmoji> <Summarize the change>
<Optional body: explain what changed and why.>
```
Rules:
- Begin the subject with a Gitmoji emoji or shortcode, followed by a space and a meaningful description.
- Use the official emoji meanings; choose by the intent of the change rather than decoration.
- Common mappings: ✨ `:sparkles:` for features, 🐛 `:bug:` for fixes, 📝 `:memo:` for documentation, ♻️ `:recycle:` for refactoring, and ⚡️ `:zap:` for performance.
- Keep Unicode emoji and shortcode usage consistent with the repository's existing convention.
- Use 💥 `:boom:` for breaking changes and explain the compatibility impact and migration in the body.
- An emoji does not replace the description; a reader should understand the change from the words too.
- The optional body structure and concise subject are recommendations for this template, not additional requirements imposed by Gitmoji.
- Check recent messages for the repository's choice of Unicode emoji or shortcodes and any scope format before drafting.
- Select the emoji from the official Gitmoji meanings based on the staged change; do not invent emoji meanings.
- Prefer one emoji that represents the main intent. If there are unrelated changes, suggest splitting them instead of adding a string of emoji.
- Keep the written subject descriptive without relying on the emoji to convey the whole change.
- For a breaking change, use the breaking-change emoji and explain the impact and supported migration steps; do not assume it triggers semantic-version tooling.
When writing a commit message:
- Base it on the staged changes (`git diff --staged`). Don't describe unstaged work as part of the commit.
- If the staged changes are unrelated to each other, suggest splitting the commit.
- Never invent motivation, issue identifiers, benchmark numbers, or test results. Keep a `<placeholder>` and ask instead.
- Call out breaking changes and include migration information supported by the changes.
- Draft the message for review. Don't stage, commit, or push unless explicitly asked.