Gitmoji Commits

Create meaningful commits with semantic gitmoji emojis that make commit history readable and visually organized.

Goal

Make commits that are easy to review, ship-safe, and visually clear:

• Only intended changes are included
• Commits are logically scoped (split when needed)
• Commit messages include semantic gitmojis describing the change type
• Messages follow Conventional Commits format with gitmoji prefix

When to Use This Skill

Use this skill when:

• User asks to commit changes with gitmoji support
• User wants emoji-enhanced commit messages
• Need to stage changes with gitmoji awareness
• Splitting work into multiple meaningful commits
• Creating Conventional Commits with visual distinction

Inputs to Ask For (if missing)

• Single commit or multiple commits? (Default: multiple small commits when unrelated changes exist)
• Any project-specific conventions? (scope requirements, commit message rules)
• Preference: auto-suggest gitmoji or let user choose?

Workflow (checklist)

1. Inspect the Working Tree

git status
git diff              # unstaged changes
git diff --stat       # summary if many changes

2. Decide Commit Boundaries

Split by:

• Feature vs refactor vs docs vs tests
• Backend vs frontend vs config
• Logic changes vs formatting/cleanup
• Dependency changes vs behavior changes

Tip: If mixed changes in one file, plan patch staging: git add -p

3. Determine Gitmoji for This Commit

Consult references/gitmoji-guide.md for complete mapping.

Quick reference:

• Feature: ✨ sparkles
• Bug fix: 🐛 bug
• Documentation: 📝 memo
• Test: 🧪 test_tube
• Refactor: ♻️ recycle
• Performance: ⚡ zap
• Style/UI: 💄 lipstick
• Dependencies: 📦 package
• Security: 🔐 lock
• Build/Config: ⚙️ gear
• Cleanup: 🗑️ wastebasket

Or use the selector script: scripts/gitmoji_selector.py "your commit description"

4. Stage the Right Changes

# Stage specific files
git add <file>

# Stage specific hunks from a file
git add -p

# Review what's staged
git diff --cached

# Unstage if needed
git restore --staged <file>

Sanity checks before committing:

• No secrets or tokens
• No debug logging
• No unrelated formatting churn
• All changes are intentional

5. Describe the Change Concisely

Before writing the message, describe what changed and why in 1-2 sentences.

If you can't describe it cleanly, the commit is too big or mixed—go back to step 2.

6. Write the Commit Message

Format: emoji type(scope): subject

Structure:

✨ feat(auth): Add two-factor authentication

- Implement TOTP support  
- Update user model with secret key
- Add verification endpoint

Closes #123

Rules:

• Subject line: max 50 characters
• Emoji at the start (from gitmoji selection)
• Type: feat, fix, refactor, docs, test, perf, style, chore, ci, build
• Scope (optional): Feature area (auth, api, ui, db, etc.)
• Subject: Imperative form ("Add" not "Added"), lowercase after scope
• Body: Explain what/why (not implementation details)
• Footer: Reference issues (Closes #123, Fixes #456)

Multi-line commits: Use git commit -v for an editor.

7. Run Verification

Run the repo's fastest meaningful check before moving on:

• Unit tests: npm test or bun test
• Linting: npm run lint
• Build: npm run build

8. Repeat for Next Commit

Until the working tree is clean, repeat steps 1-7.

Deliverable

Provide:

• Final commit message(s) with gitmojis
• Short summary per commit (what/why)
• Commands used to stage/review (at minimum: git diff --cached)
• Any test/build verification results

Gitmoji Reference

See references/gitmoji-guide.md for:

• Complete gitmoji catalog with descriptions
• Selection decision tree
• Conventional Commits examples
• Tips for consistent emoji usage

Helper Script

The scripts/gitmoji_selector.py script suggests gitmojis automatically:

# Analyze a message and suggest gitmoji
python3 scripts/gitmoji_selector.py "fix critical bug in authentication"

# Generate Conventional Commits format
python3 scripts/gitmoji_selector.py --conventional feat auth "Add two-factor authentication"

Best Practices

1. One emoji per commit: Each commit has exactly one primary gitmoji
2. Be specific: Choose the most appropriate emoji, not a generic one
3. Consistent scope: Use consistent scope names across commits
4. Clear messages: Subject line should be understandable without body
5. Atomic commits: Each commit should be independently buildable/testable