Semantic Commit

Commit Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Guidelines

• Start with a short prefix followed by colon and space (feat:, fix:, docs:, refactor:, test:, chore:, etc.)
• Isolate your changes and commit only what you did (no unrelated files)
• feat: for user-visible features, fix: for bug fixes
• A scope MAY be added in parentheses, e.g.

  fix(parser):

  - only when it meaningfully improves clarity
• Short description in imperative mood explaining what changed, not how
• Body MAY be included after one blank line for context, rationale, or non-obvious behavior
• Footers MAY be included (Token: value format, use

  -

  instead of spaces in tokens)
• Breaking changes should be explained clearly in description or body, no special marking required
• Clarity and usefulness matter more than strict conformance

Commit Types

feat

fix

docs

style

refactor

perf

test

build

ci

chore

revert

Workflow

digraph commit_workflow {
    rankdir=TB;
    node [shape=box];
    
    check [label="Check git status"];
    stage [label="Stage changes\n(if needed)"];
    review [label="Review staged diff"];
    analyze [label="Analyze changes\nDetermine type & scope"];
    write [label="Write commit message"];
    commit [label="Execute git commit"];
    
    check -> stage;
    stage -> review;
    review -> analyze;
    analyze -> write;
    write -> commit;
}

1. Check Repository State

git status --short
git diff --cached --stat   # staged changes
git diff --stat            # unstaged changes

2. Stage Changes

• Ask which files to stage
• Stage only files you changed for this task (avoid unrelated changes)

3. Review Staged Changes

git diff --cached

4. Determine Type and Scope

• Type: What category of change? (feat, fix, refactor, etc.)
• Scope: What area of the codebase? Only add when it meaningfully improves clarity
• Breaking: Does this break backward compatibility? Explain clearly in description or body

Writing Good Commit Messages

Subject Line

• Use imperative mood: "add feature" not "added feature"
• Keep under 50 characters when possible
• Don't end with a period
• Explain what changed, not how

Body (Optional)

• Explain motivation for the change
• Contrast with previous behavior
• Note any side effects

fix(parser): handle unicode characters in filenames

Previously, filenames with non-ASCII characters would cause
a decode error. Now using UTF-8 decoding with fallback to
latin-1 for legacy files.

Closes #123

Footer (Optional)

-

• Closes #123

  or

  Fixes #456

  for issue references

• Co-authored-by: Name <email>

  for pair programming

• Reviewed-by: Name <email>

  for review attribution

Examples

feat(api): add user profile endpoint

fix: prevent null pointer on empty config

docs: add installation instructions

style: apply prettier formatting

refactor: rename processData to parseInput

perf(db): add index for user lookups

test: add coverage for auth module

build: upgrade react to v18

ci: add node 20 to test matrix

chore: remove unused imports

feat(api): change response format to JSON arrays

Common Mistakes

fix

feat

refactor

Quick Reference

feat:     New feature for users
fix:      Bug fix for users  
docs:     Documentation only
style:    Formatting, no logic change
refactor: Code change, no behavior change
perf:     Performance improvement
test:     Adding/fixing tests
build:    Build system, dependencies
ci:       CI configuration
chore:    Maintenance, tooling
revert:   Reverting commits