gitmoji-commit

Gitmoji Commit

Help the user turn a pile of working changes into a clean sequence of commits, each in the Gitmoji + Conventional Commits style: a leading emoji that signals the kind of change, then a conventional type and an imperative subject.

✨ feat: add avatar upload to the profile page

The user runs git themselves. Your job is to plan the commits and produce the messages + commands they can copy — not to run git add or git commit.

The workflow

1. Survey everything that changed. Don't assume the right things are staged. Inspect the whole working tree (all read-only and safe):

   • git status — staged, unstaged, and untracked files at a glance
   • git diff --staged and git diff — the actual content of staged and unstaged edits
   • For untracked files, look at the new files themselves Read the substance, not just filenames: a change under tests/ that backs a new feature is part of that feature's story; a .md file might be user docs or just a code comment.

2. Group changes into reviewable commits. This is the heart of it. Aim for atomic commits — each commit is one coherent concern that a reviewer can understand on its own. The point is reviewability: someone reading the history should be able to follow your reasoning commit by commit.

   • Keep related edits together (a feature + its tests + its doc note can be one commit if they tell one story).
   • Split unrelated edits apart (a bug fix and an unrelated config tweak are two commits, even if both are staged right now).
   • Separate mechanical noise from logic: pure formatting, renames, or generated files shouldn't be buried in a substantive diff — give them their own commit so reviewers can skim past them.
   • Default to file-level grouping so the staging recipe is clean copy-paste (git add path/a path/b). Only when a single file genuinely mixes two concerns, suggest interactive git add -p — and tell the user it's interactive (they pick hunks).
   • Dependencies: use judgment. When a feature directly uses a dependency it adds (the manifest edit and the code tell one story and build together), bundle the manifest — e.g. package.json, pyproject.toml, Cargo.toml — with the feature commit. When the dependency change is independent (a routine upgrade, an unrelated bump), give it its own commit. Either way, the generated lockfile is always separate and last (next section).

3. Order the sequence sensibly. Order so each commit stands on its own and, ideally, the tree builds at every step. A light heuristic: foundational/prep changes first, the feature or fix that uses them next, and mechanical/generated changes (formatting, lockfiles) last so they don't bury the real diff. Lockfiles are always the final, separate commit — see below.

4. For each commit, produce three things: the gitmoji message (subject, plus a why-focused body when non-trivial), the git add command(s) that stage exactly that group, and a signed git commit command.

5. Hand over the recipe. Present the commits as an ordered, runnable sequence. Don't run any of it — staging and committing are the user's calls.

Lockfiles go last, in their own commit

In JavaScript/TypeScript/bun projects, dependency lockfiles get their own commit, ordered last, never mixed with source changes:

• package-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml, bun.lock, bun.lockb

Why: lockfiles are large, generated, and conflict constantly on merge. When they conflict, the clean resolution is usually to regenerate (npm install, pnpm install, bun install) rather than hand-merge. Keeping them isolated in the last commit means that regeneration touches exactly one commit and never entangles your actual source changes. The same principle applies to other ecosystems' lockfiles (Cargo.lock, poetry.lock, composer.lock) — isolate them too if they show up.

Use 📦️ build (or ➕/➖/⬆️ when it's specifically adding/removing/upgrading a dep) for the lockfile commit, e.g. 📦️ build: update package-lock.json.

Sign each commit

Add -S to every suggested git commit command so commits are cryptographically signed:

git commit -S -m "✨ feat: ..."

Before presenting the recipe, check whether signing is already configured:

• git config --get commit.gpgsign (if true, signing happens automatically — -S is harmless and explicit, keep it)
• git config --get user.signingkey

If neither is set, still include -S, but add a one-line note that it will fail until the user configures a signing key (GPG or SSH), pointing them to git config user.signingkey and gpg.format. If signing is already on, no note is needed.

Message format rules

• Subject: <emoji> <type>: <description> — e.g. 🐛 fix: handle null user in payment processor.
  • Imperative mood ("add", "fix", "remove" — not "added"/"fixes").
  • Lowercase the first word of the description; no trailing period.
  • Aim for ~50 characters; hard-stop around 72.
  • One space after the emoji. Some emoji (🚑️ 🔒️ 📦️) carry a variation selector — copy them as-is from the list.
• Scope (optional): add a parenthesized scope when it clarifies where the change lives: ✨ feat(auth): add SSO login. Use it when the repo has clear modules; skip it when it'd be noise.
• Body (optional, encouraged for non-trivial changes): blank line after the subject, then explain the why and context a reviewer needs — not a restatement of the diff. Wrap at ~72 characters.
• Breaking changes: 💥 with a ! after the type and a BREAKING CHANGE: footer, e.g. 💥 feat!: drop support for Node 16.
• Issue references: add a footer like Refs: #123 or Closes: #123 when the user mentions a ticket.

Emoji → type mapping (common cases)

Pick by intent — the single emoji that fits the dominant change; the type follows from it. The full official list of all 73 gitmojis is in references/gitmojis.md; consult it for cases not below (accessibility, i18n, feature flags, database, secrets, healthchecks, etc.).

Intent	Emoji	Type
Introduce a new feature	✨	feat
Fix a bug	🐛	fix
Critical hotfix	🚑️	fix
Simple fix for a non-critical issue	🩹	fix
Fix a security/privacy issue	🔒️	fix
Add or update documentation	📝	docs
Add or update comments in source	💡	docs
Refactor code (no behavior change)	♻️	refactor
Improve code structure / format	🎨	refactor
Remove code or files	🔥	refactor
Remove dead code	⚰️	refactor
Move or rename resources	🚚	refactor
Improve performance	⚡️	perf
Add, update, or pass tests	✅	test
Add a failing test (TDD)	🧪	test
Add or update UI / style files	💄	style
Fix compiler / linter warnings	🚨	style
Add or update config files	🔧	chore
Work in progress	🚧	chore
Add or update dev scripts	🔨	chore
Add or update logs	🔊	chore
Add a dependency	➕	build
Remove a dependency	➖	build
Upgrade dependencies	⬆️	build
Downgrade dependencies	⬇️	build
Pin dependencies	📌	build
Add or update compiled files / packages / lockfiles	📦️	build
Add or update CI build system	👷	ci
Fix CI build	💚	ci
Deploy stuff	🚀	chore
Release / version tag	🔖	chore
Revert changes	⏪️	revert
Merge branches	🔀	— (merge)
Begin a project	🎉	chore
Fix typos	✏️	fix
Introduce breaking changes	💥	feat!/fix!
Add or update types	🏷️	feat

When more than one row fits, prefer the more specific one (🚑️ over 🐛 for a true hotfix; ⚰️ over 🔥 when the point is removing dead code).

Worked example

Suppose git status shows: a new debounce on a search input (search.js) plus its test (search.test.js), the lodash.debounce dependency it uses added to package.json, an unrelated typo fix in README.md, and a regenerated package-lock.json.

The feature directly uses the new dependency, so the manifest rides with it. That's two concerns + a lockfile → three commits, lockfile last:

# 1 — the feature, its test, and the dependency it needs (one buildable story)
git add src/search.js src/search.test.js package.json
git commit -S -m "✨ feat(search): debounce query input" -m "Searching fired a request on every keystroke, hammering the API on fast typers. Debounce by 300ms so we only query once typing settles. Adds lodash.debounce and a test covering the timing."

# 2 — unrelated docs typo, on its own
git add README.md
git commit -S -m "✏️ fix: correct typo in README setup steps"

# 3 — lockfile last, isolated so a merge conflict can just be regenerated
git add package-lock.json
git commit -S -m "📦️ build: update package-lock.json"

For a single-commit change with no body, one -m is enough:

git add report.py
git commit -S -m "♻️ refactor(report): simplify build with a line-total helper"

If the user prefers to commit everything as one (declining the split), pick the emoji for the most significant change and say what you set aside.