Git Commits

Expert guidance for creating well-formatted, meaningful commits that tell a clear story.

Current Git Context

• Current git status: !git status
• Staged changes: !git diff --staged
• Unstaged changes: !git diff
• Recent commits: !git log --oneline -10
• Current branch: !git branch --show-current

Quick Start

Create a Well-Formatted Commit

# Stage specific files
git add src/auth.ts src/types.ts

# Commit with clear message
git commit -m "Add JWT authentication

Implements token-based authentication with refresh tokens.
Includes middleware for protected routes and token validation."

Key Rules:

• First line: Imperative mood, capitalized, < 50 chars, no period
• Blank line after summary
• Body: Wrap at 72 chars, explain what and why (not how)
• Test before committing

Conventional Commits Format

type(scope): Summary in imperative mood

More detailed explanatory text if needed, wrapped at 72 characters.
Explain the "what" and "why" of the change, not the "how".

Closes #issue-number

Types: feat, fix, docs, style, refactor, perf, test, chore

Examples:

feat(auth): Add user authentication endpoint
fix(cache): Resolve race condition in invalidation
refactor(api): Extract validation into middleware
perf(db): Add indexes for user dashboard queries

Core Principles

1. Commit Related Changes

One logical change per commit. Fixing two bugs? Two separate commits.

# Good: Separate commits
git add auth.py
git commit -m "Fix authentication token validation"

git add database.py
git commit -m "Add index to users table for performance"

# Bad: Unrelated changes
git add auth.py database.py
git commit -m "Fix various issues"

2. Commit Often

Small, frequent commits are easier to understand and revert if needed.

Benefits:

• Easier to understand each change
• Simpler to revert if needed
• Better collaboration
• Clearer project history

3. Test Before Committing

Pre-commit checklist:

# Run tests
pytest                     # Python
npm test                   # JavaScript

# Run linters
pylint src/               # Python
eslint src/               # JavaScript

# Check formatting
black --check src/        # Python
prettier --check src/     # JavaScript

# Review changes
git status                 # What will be committed
git diff --staged          # Actual changes

MAKE SURE NEW CHANGES ARE COVERED BY AUTOMATED TESTS AND ALL TESTS PASS.

4. Don't Commit Half-Done Work

Only commit when a logical component is complete. Use git stash for incomplete work:

# Need to switch branches but work isn't complete
git stash save "WIP: User authentication form validation"
git checkout other-branch

# Come back later
git checkout feature/auth
git stash pop

Good vs Bad Examples

Feature Implementation

Good:

Add user profile page

Implements the user profile page with the following:
- Display user information (name, email, avatar)
- Edit profile form with validation
- Upload avatar with image preview
- Update API endpoint integration

Tests included for form validation and API calls.

Bad:

Add stuff

Bug Fix

Good:

Fix race condition in cache invalidation

The cache was not being properly invalidated when multiple
requests updated the same resource simultaneously, causing
stale data to be served to users.

Changed the invalidation logic to use atomic operations with
a distributed lock to ensure cache consistency.

Fixes #1234

Bad:

Fix bug

Refactoring

Good:

Extract authentication logic into middleware

Moved authentication checks from individual route handlers
into reusable middleware. This reduces code duplication and
makes authentication logic easier to maintain and test.

No functional changes - all existing tests pass.

Bad:

Update code

Anti-Patterns to Avoid

❌ Vague messages: "Fix bug", "Update code", "Changes", "WIP", "asdf"

❌ Too much in one commit: "Fix login, add dashboard, update deps, refactor tests"

❌ Misleading messages: Commit message says "Fix typo" but actually rewrites authentication system

❌ No context: Summary line only, no body when body is needed

❌ Half-done work: Committing code that doesn't compile or fails tests

Testing Requirements

Every commit should include tests and pass all existing tests.

Test Coverage Expectations

New features:

• Unit tests for core logic
• Integration tests for API endpoints
• E2E tests for critical user flows

Bug fixes:

• Regression test that fails before the fix
• Test passes after the fix

Refactoring:

• All existing tests pass
• No change in functionality

Templates and References

• Detailed guidelines - Comprehensive commit best practices
• Commit template - Reusable message template

Related Skills

• For stacked PR workflows, see @git-stacked-prs
• For advanced operations like amend/rebase, see @git-advanced

Philosophy

Git is not a backup system. Each commit should tell a story:

• What changed?
• Why did it change?
• How does it improve the codebase?

Good commit history enables:

• Easy code review
• Clear understanding of evolution
• Simple debugging with git bisect
• Confident refactoring
• Team collaboration