Conventional Commit

Create git commits that follow the Conventional Commits v1.0.0 specification.

Workflow

1. Gather context

Run these in parallel:

git status
git diff --cached
git diff
git log --oneline -10

2. Analyze changes

• Identify what changed (files, functions, features, fixes)
• Identify why it changed (bug fix, new feature, refactor, etc.)
• Group related changes — if changes are unrelated, suggest splitting into multiple commits
• Check for sensitive files (.env, credentials, secrets) and warn before staging

3. Stage changes

• Stage only related changes with git add <specific-files>
• Never use git add -A or git add . without confirming with the user
• If unstaged changes exist that belong to a different logical change, leave them unstaged

4. Write the commit message

Format per Conventional Commits v1.0.0:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type (required)

Pick the most specific type:

Scope (optional)

A noun in parentheses describing the section of the codebase:

feat(auth): add OAuth2 login flow
fix(parser): handle empty input gracefully
docs(readme): update installation steps

Derive scope from: package name, module, directory, or feature area.

Description (required)

• Imperative mood: "add" not "added" or "adds"
• Lowercase first letter
• No period at end
• Max ~50 characters for the entire first line (type + scope + description)

Body (optional)

• Separate from description with a blank line
• Explain what and why, not how
• Wrap at 72 characters
• Use when the description alone is insufficient

Footer (optional)

• Separate from body with a blank line
• Format: token: value or token #value
• Use - instead of spaces in tokens (except BREAKING CHANGE)

Common footers:

• BREAKING CHANGE: <description> — breaking API change (SemVer MAJOR)
• Refs: #123 — reference issues
• Reviewed-by: Name <email>
• Co-authored-by: Name <email>

Breaking changes

Indicate with either:

1. An exclamation mark after type/scope, e.g. feat(api)!: change response format
2. A BREAKING CHANGE: footer with explanation
3. Both for maximum clarity

5. Create the commit

Use a HEREDOC for multi-line messages:

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 login flow

Implement OAuth2 authorization code flow with PKCE for
secure browser-based authentication. Replaces the legacy
session-based auth which had CSRF vulnerabilities.

BREAKING CHANGE: /api/login now returns a JWT instead of
setting a session cookie
Refs: #342
EOF
)"

For single-line commits:

git commit -m "fix(parser): handle empty input without panic"

6. Do NOT push

Never push to remote unless the user explicitly asks.

Examples

Simple fix:

fix: resolve null pointer in user lookup

Scoped feature:

feat(api): add pagination to list endpoints

Multi-line with breaking change:

feat(config)!: switch to YAML configuration format

Migrate from JSON to YAML for all configuration files.
Existing JSON configs are no longer supported.

BREAKING CHANGE: configuration files must be in YAML format
Refs: #891

Documentation:

docs: correct typos in contributing guide

Multiple footers:

fix(db): prevent connection pool exhaustion

Add connection timeout and max idle settings to prevent
pool exhaustion under high load.

Refs: #456
Reviewed-by: Alice <alice@example.com>