Writing Git Commits

Workflow

1. Inspect — diffs --staged (staged) and diffs (unstaged); fallback to git diff --stat when raw line stats required
2. Group — cluster related changes by intent
3. Order — commit foundational changes first (deps, config, types), then features, then tests
4. Write — use the message format below
5. Stage & commit — git hunks list, git hunks add <hunk-id> (or git add <paths> for whole files), then git commit -m "..."

Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types

Rules

• Subject: imperative mood, lowercase, no period, ≤72 chars
• Scope: optional, the module/area affected (e.g., auth, pi, nix)
• Body: wrap at 72 chars, explain what and why (not how)
• Footer: Closes #123, BREAKING CHANGE: ...
• Atomic: each commit compiles/passes independently
• No mixed concerns: don't combine a bugfix with a refactor

Examples

feat(pi): add diff-renderer extension

chore: update flake inputs

fix(auth): prevent token refresh race condition

Tokens were being refreshed concurrently, causing 401s for
in-flight requests. Added a mutex around the refresh call.

Closes #42

refactor(shell): extract zsh plugin config to module

Grouping Heuristics

• Same file touched for different reasons → separate commits
• Multiple files for one feature → single commit
• Formatting/whitespace mixed with logic → split them
• Dependency updates → own commit (chore(deps): ...)
• Generated files (lockfiles, schemas) → commit with the change that caused them