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

Type	Description
feat	A new feature (user-visible)
fix	A bug fix (user-visible)
docs	Documentation only changes
style	Changes that do not affect the meaning of the code (formatting, semicolons, etc.)
refactor	A code change that neither fixes a bug nor adds a feature
perf	A code change that improves performance
test	Adding missing tests or correcting existing tests
build	Changes that affect the build system or external dependencies
ci	Changes to CI configuration files and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

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

Changes	Commit
New endpoint added	feat(api): add user profile endpoint
Bug causing crash	fix: prevent null pointer on empty config
Updated README	docs: add installation instructions
Reformatted code	style: apply prettier formatting
Renamed internal function	refactor: rename processData to parseInput
Optimized query	perf(db): add index for user lookups
Added unit tests	test: add coverage for auth module
Updated dependencies	build: upgrade react to v18
Changed CI config	ci: add node 20 to test matrix
Cleaned up files	chore: remove unused imports
Breaking API change	feat(api): change response format to JSON arrays

Common Mistakes

Mistake	Fix
Past tense ("added")	Use imperative ("add")
Too vague ("fix bug")	Be specific ("fix null check in parser")
Too long subject	Keep concise, move details to body
Wrong type	fix = bug, feat = new capability, refactor = no behavior change
Combining unrelated changes	Split into multiple commits
Overusing scope	Only add scope when it meaningfully improves clarity

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