---
title: "Gitmoji Commit"
type: concept
tags: ["git", "gitmoji", "code-quality"]
last_updated: 2026-04-25
---

## Definition

Gitmoji Commit 是一种提交规范，使用标准化 Emoji（Gitmoji）作为提交类型的视觉前缀，使开发者能在 git log 中通过 Emoji 快速识别变更意图。

## Format

```
<Gitmoji> JIRA-ID: short description
```

示例：
- `✨ JIRA-214: add SSO login flow`
- `🐛 JIRA-315: fix token refresh race`
- `♻️ JIRA-522: refactor audit service boundaries`
- `📚 JIRA-623: document API error catalog`
- `🧪 JIRA-724: add session timeout regression tests`
- `🔧 JIRA-811: add branch policy validation`
- `📦 JIRA-902: upgrade GitHub Actions versions`

## Official Gitmoji Catalog

| Emoji | 含义 | 使用场景 |
|-------|------|----------|
| ✨ | 新功能 | 新增 agent、catalog 功能 |
| 🐛 | 缺陷修复 | bug fix |
| ♻️ | 重构 | 代码结构优化 |
| 📚 | 文档 | 仅限现有功能/贡献指南的文档更新 |
| 🧪 | 测试 | 测试编写或更新 |
| 💄 | 样式 | UI/样式调整（不改变行为） |
| 🔧 | 配置 | 工作流、CI/CD、配置变更 |
| 📦 | 依赖 | 依赖或平台升级 |
| 🚀 | 部署 | 部署相关变更 |

## Gitmoji Selection Principle

> 优先选择反映**实际变更类型**的 Gitmoji，而非个人偏好。

特殊情况：
- 为新 agent（全新 catalog 功能）→ 优先使用 `✨` 而非 `📚`（因为 Gitmoji 将 `✨` 定义为新功能）
- 仅更新现有 agent 文档或贡献指南 → 使用 `📚`

## Automated Validation

通过 commit-msg hook 自动验证格式：

```bash
commit_regex='^(🚀|✨|🐛|♻️|📚|🧪|💄|🔧|📦) [A-Z]+-[0-9]+: .+$'
```

不符合格式的提交将被拒绝。

## Official References

- Primary: [gitmoji.dev](https://gitmoji.dev/)
- Source of truth: [github.com/carloscuesta/gitmoji](https://github.com/carloscuesta/gitmoji)

## Sources
- [[project-management-jira-workflow-steward]]