Committing Code

Create well-structured, atomic commits that follow Conventional Commits specification.

Use this skill when making commits, writing commit messages, splitting changes into logical units, or following project commit conventions.

Supporting files: CONVENTIONAL-COMMITS.md for commit message format, ATOMIC-COMMITS.md for splitting changes.

Quick Start

# Stage specific changes (not all at once)
git add -p

# Commit with conventional format
git commit -m "feat(parser): add support for array parsing"

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common types:

Workflow Checklist

When committing, follow these steps:

Commit Workflow:
- [ ] Step 1: Review all changes (git diff)
- [ ] Step 2: Identify logical units of work
- [ ] Step 3: Stage changes for first unit (git add -p)
- [ ] Step 4: Write commit message (conventional format)
- [ ] Step 5: Verify commit is atomic (single purpose)
- [ ] Step 6: Repeat for remaining units

Step 1: Review Changes

git status
git diff

Look for mixed concerns:

• Whitespace changes mixed with logic changes
• Multiple unrelated features
• Bug fixes mixed with refactoring

Step 2: Identify Logical Units

Each commit should be:

• Single-purpose: One logical change
• Complete: Codebase works after commit
• Reversible: Can be reverted independently

Bad (mixed concerns):

Add user authentication and fix typo in README and update deps

Good (separate commits):

feat(auth): add user authentication
docs: fix typo in README
deps: update lodash to 4.17.21

Step 3: Stage Selectively

Use interactive staging to pick specific changes:

# Stage by hunks
git add -p

# Commands in interactive mode:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks
# e - manually edit hunk
# q - quit

Step 4: Write Commit Message

Format:

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

<body explaining why, not what>

<footer with references/breaking changes>

Examples:

Simple fix:

fix(api): handle null response from payment gateway

Feature with body:

feat(search): add fuzzy matching for product names

Users frequently misspell product names. Fuzzy matching
improves search success rate by ~40% based on analytics.

Closes #234

Breaking change:

feat(api)!: change authentication to OAuth2

BREAKING CHANGE: API now requires OAuth2 tokens instead of
API keys. See migration guide in docs/auth-migration.md.

Step 5: Verify Atomicity

Before finalizing, check:

• Does this commit do ONE thing?
• Can it be described in one short sentence?
• Would reverting it break unrelated features?
• Are tests passing after this commit?

Step 6: Repeat

Continue staging and committing remaining logical units.

Common Patterns

After Large Refactoring Session

# You've made many changes. Split them:
git stash                    # Save current state
git stash show -p | head     # Review what you have
git checkout -p stash        # Selectively apply changes
git add -p                   # Stage first logical unit
git commit -m "refactor: ..."
# Repeat until stash is empty

Fix-up Previous Commit

# Made a mistake in last commit (not yet pushed)
git add <files>
git commit --amend --no-edit

# Or with new message
git commit --amend -m "fix: corrected message"

Interactive Rebase (cleanup before PR)

# Squash/reorder last N commits
git rebase -i HEAD~N

# In editor:
# pick   abc1234 feat: add feature
# fixup  def5678 fix typo
# squash ghi9012 more changes

Tips

• Write commit messages in imperative mood ("add feature" not "added feature")
• Keep subject line under 50 characters
• Wrap body at 72 characters
• Reference issues in footer: Closes #123, Fixes #456
• Breaking changes require exclamation mark (!) or BREAKING CHANGE: footer
• When unsure about scope, omit it: feat: add new feature

Resources

• Conventional Commits Spec
• Atomic Commits Guide
• Commit Message Format