Git Commit

Write clear, atomic commits. Detect and match project conventions first; use Conventional Commits as fallback. Every commit = one complete, working change.

Feature Branch Workflow

Philosophy: Commit early, commit often.

Feature branch: Create → [Change → Test → COMMIT]* → PR → Merge

Why frequent commits matter:

Benefit	Description
Easy rollback	Revert to last working state in seconds
Safety checkpoints	Never lose more than one small step
Better debugging	`git bisect` works with granular history
Collaboration	Others see incremental progress
Automation	Enables auto-changelogs and semantic versioning

Anti-pattern: One giant commit at end of feature (47 files, 2800+ lines). Split into logical increments instead.

Quick Start

Pre-Commit Checklist:

Code builds and tests pass
ONE logical change (describable in one sentence)
Checked project conventions (Step 1)

Workflow

Step 1: Detect Conventions (REQUIRED)

ls .commitlintrc* commitlint.config.* .czrc .cz.json 2>/dev/null
git log --oneline -15

Finding	Action
Config file exists	Follow those rules exactly
`feat:`, `fix:` pattern	Use Conventional Commits
`[JIRA-123]` pattern	Match ticket prefix format
`Component: message` pattern	Match component prefix format
No clear pattern	Use Conventional Commits (Step 2)

Step 2: Format Message

<type>(<scope>)!: <subject>     ← 50 chars ideal, 72 max
                                ← blank line
<body>                          ← wrap at 72 chars, optional
                                ← blank line
<footer>                        ← optional (Closes #123, BREAKING CHANGE)

Subject rules: Imperative mood (add not added), lowercase after colon, no trailing period, no filler words.

Types:

Type	Purpose	SemVer	Example
`feat`	New feature	MINOR	`feat(auth): add OAuth`
`fix`	Bug fix	PATCH	`fix(cart): prevent neg qty`
`docs`	Documentation	-	`docs(api): add examples`
`style`	Formatting	-	`style: fix indentation`
`refactor`	Code restructure	-	`refactor: extract helper`
`perf`	Performance	-	`perf(db): add index`
`test`	Tests	-	`test(auth): add edge cases`
`build`	Build/deps	-	`build: update webpack`
`ci`	CI config	-	`ci: add deploy workflow`
`chore`	Maintenance	-	`chore: update gitignore`
`revert`	Revert previous commit	-	`revert: let us not...`

Breaking changes: Add ! after type/scope, explain in body/footer.

feat(api)!: require API key for all endpoints

BREAKING CHANGE: Anonymous access removed. All requests need X-API-Key header.

Step 3: Body (When Needed)

Required	Optional
Breaking change (impact/migrate)	Self-explanatory from diff
Non-obvious fix (root cause)	Simple docs/style/chore
Complex feature (design decision)	Tests with descriptive names

Body content: WHY (motivation), WHAT problem, HOW users affected. Not: Which files (diff shows), line-by-line explanation (code comments).

Step 4: Footer

Closes #123                              # Issue reference
Fixes #456                               # Also closes issue
Refs: #789                               # Reference without closing
BREAKING CHANGE: <description>           # If not in body
Co-authored-by: Name <email@example.com> # Co-authorship
Reviewed-by: Name                        # Use hyphens in tokens

Commit Granularity

Atomic Commit = Smallest Complete Change

ONE purpose - single feature/fix/refactor
Self-contained - doesn't depend on uncommitted work
Leaves code working - builds pass, tests pass
Revertable alone - without breaking other features

What Goes Together vs Separate

Together (same commit)	Separate (different commits)
Feature + its unit tests	Feature + unrelated formatting
Bug fix + regression test	Bug fix + dependency update
API change + docs update	Refactor + new feature
Refactor + affected tests	Multiple unrelated fixes

When to Commit (Triggers)

Trigger	Action
Function works and tested	COMMIT now
Test passes (red → green)	COMMIT now
Bug fixed and verified	COMMIT before next task
About to refactor	COMMIT working state first
Starting new sub-task	COMMIT current progress
End of session / before pull	COMMIT if working

Key: Before starting new task, commit all current task changes.

When NOT to Commit

Situation	Why
Code doesn't build	Breaks bisect, blocks others
Tests failing*	Not a valid checkpoint
"I think this works" (untested)	Verify first, commit second
Mid-debugging / mid-fix	Wait until fix is complete
Uncertain about approach	Prototype first, commit when solid
CI still running / red	Wait for green, then commit fix

*Exception: TDD RED commits (test-only commits that intentionally fail) are valid.

"Commit often" means verified working increments, not untested guesses.

❌ BAD: Commit-and-pray workflow
───────────────────────────────
1. Write fix
2. "Looks right to me" → commit
3. Push → CI fails
4. "Oops, forgot X" → commit again
5. Push → CI fails again
6. Repeat 3 more times...
Result: 5 broken commits in history

✓ GOOD: Verify-then-commit workflow
───────────────────────────────
1. Write fix
2. Run tests locally → fails
3. Fix the issue
4. Run tests locally → passes
5. Commit
6. Push → CI passes
Result: 1 clean commit

Rule: If CI or local tests are red, you're not done. Fix first, verify, then commit.

TDD Pattern

test(auth): add failing test for validation  # RED
feat(auth): implement validation             # GREEN
refactor(auth): extract to helper            # REFACTOR

Examples

See references/examples.md for comprehensive examples. Quick reference:

# Feature with context
feat(auth): add password strength indicator

Users lacked feedback on password quality during signup.
Add real-time strength meter, requirements checklist, submission block.

Closes #234

# Bug fix with root cause
fix(api): handle null response from payment gateway

Gateway returns null on timeout. Add null check with retry logic.

Fixes #567

# Simple changes (no body needed)
docs(readme): add Docker installation steps
test(utils): add edge case tests for date parser
chore(deps): update lodash to 4.17.21

Bad	Problem	Good
`fix bug`	No context	`fix(cart): prevent duplicate items`
`update code`	Meaningless	`refactor(api): simplify errors`
`WIP`	Incomplete	Finish work, then commit
`misc fixes`	Multiple changes	Split into separate commits

Integration

When	Skill	Why
Before committing	`code-quality`	Ensure checks pass
After committing	`docs-check`	Check if docs need update
After PR review	`pr-review` → `git-commit`	Resolve then commit

References

references/examples.md - Extended examples by scenario

Output

Git commits created via standard git commands. No files saved. Commit history visible via git log.

git-commit