git-commit（Git 提交）

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:

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

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:

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)

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 protected] > # Co-authorship
Reviewed-by: Name                        # Use hyphens in tokens

Commit Granularity

Atomic Commit = Smallest Complete Change

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

What Goes Together vs Separate

When to Commit (Triggers)

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

When NOT to Commit

*_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

Integration

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.