commit-workflow

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 && npm run build

# Python projects
ruff check . && 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):

Type	Emoji	Use for
feat	✨	New feature
fix	🐛	Bug fix
fix	🚑️	Critical hotfix
docs	📝	Documentation only
style	💄	Formatting, no logic change
refactor	♻️	Code change without feat/fix
perf	⚡️	Performance improvement
test	✅	Adding or fixing tests
chore	🔧	Build, tooling, config
ci	👷	CI/CD changes
revert	⏪️	Reverting a change
wip	🚧	Work in progress
security	🔒️	Security fix
breaking	💥	Breaking change
deps	➕	Add dependency
deps	➖	Remove dependency