Semantic Commit

Create git commits following the Conventional Commits specification.

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

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

If no changes are staged:

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

3. Review Staged Changes

git diff --cached

Understand what was modified to write an accurate message.

4. Determine Type and Scope

Based on the changes:

• 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)

Include after one blank line when context, rationale, or non-obvious behavior needs explanation:

• 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)

Use Token: value format (use - instead of spaces in token names):

• Closes #123 or Fixes #456 for issue references
• Co-authored-by: Name <email> for pair programming
• Reviewed-by: Name <email> for review attribution

Examples

Common Mistakes

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