Commit Workflow

When to Use

• Before every commit — to enforce conventional commit format consistently
• When a diff mixes multiple logical concerns (feat + refactor + docs)
• When you want emoji-annotated commits for visual git history
• In teams that enforce Conventional Commits via CI

Prerequisites

• Changes staged or present as unstaged modifications
• Optional: pre-commit hooks configured (husky, pre-commit, or similar)

Workflow

1. Stage and Inspect

If nothing is staged, stage everything and inspect what changed:

# Check current state
git --no-pager status --short

# Stage all if nothing is staged
$staged = git --no-pager diff --cached --name-only
if (-not $staged) { git add -A }

# Review the diff
git --no-pager diff --cached --stat

2. Run Pre-Commit Checks (Optional)

# Node.js projects
npm run lint; if ($LASTEXITCODE -eq 0) { npm run build }

# Python projects
ruff check .; if ($LASTEXITCODE -eq 0) { pytest --tb=short -q }

# Generic pre-commit hooks
pre-commit run --all-files

Skip with --no-verify flag on the final commit if checks are handled externally.

3. Analyze the Diff for Atomic Splits

git --no-pager diff --cached

Ask: Do these changes serve more than one logical purpose?

Split when changes involve:

• Different concerns (e.g., new feature and bug fix)
• Different file types (e.g., source code and documentation)
• Different modules with no dependency between them

If splitting, use git add -p to stage partial hunks:

git add -p   # interactive hunk selection

4. Write the Commit Message

Format: <emoji> <type>(<scope>): <imperative description>

Type → Emoji mapping (most common):

Rules:

• First line ≤ 72 characters
• Imperative mood: "add feature" not "added feature"
• Scope is optional: feat(auth): add JWT refresh

git commit -m "✨ feat(api): add pagination to /users endpoint"

5. Multi-Commit Flow (Split Changes)

# First logical unit
git add src/api/users.ts
git commit -m "✨ feat(api): add cursor-based pagination to users endpoint"

# Second logical unit
git add docs/api.md
git commit -m "📝 docs(api): document pagination parameters for users endpoint"

# Third logical unit (cleanup found along the way)
git add src/utils/query.ts
git commit -m "♻️ refactor(utils): extract page-size validation into shared helper"

Examples

Feature with Docs

git add -A
git commit -m "✨ feat(notifications): add real-time push alerts via WebSocket

- Implement WebSocket connection pool
- Add client-side reconnect logic with exponential backoff
- Write integration tests for disconnect/reconnect scenarios"

Hotfix

git add src/auth/token.ts
git commit -m "🚑️ fix(auth): prevent JWT secret from leaking into error logs"

Breaking Change

git commit -m "💥 feat(config)!: rename API_KEY to COPILOT_API_KEY

BREAKING CHANGE: rename environment variable API_KEY → COPILOT_API_KEY.
Update .env files and CI secrets before deploying."

Common Rationalizations

Red Flags

• Meaningless commit messages like fix, update, changes, stuff
• Multiple unrelated changes bundled in one commit
• No issue or PR reference in the commit message
• Hundreds of lines of changes committed as "minor fix"
• Tests and implementation in separate commits for the same feature

Verification

• Commit message follows the format above (<emoji> <type>(<scope>): description)
• Each commit contains exactly one logical change
• Breaking changes are marked with BREAKING CHANGE:
• git log --oneline tells a readable story of the changes

Tips

• Check git log --oneline after — if you can't parse the history at a glance, the messages need work
• One commit = one revert: if reverting a commit breaks something unrelated, it wasn't atomic
• Use git commit --amend to fix the last message before pushing
• git add -p is your friend for splitting mixed diffs without stashing
• CI commit lint: if you enforce the format with commitlint, configure it to accept the leading emoji

See Also

• add-to-changelog — keep CHANGELOG in sync after committing
• Conventional Commits spec
• gitmoji reference
• Inspired by: awesome-claude-code/resources/slash-commands/commit