Conventional commit

Git Commit with Conventional Commits

Overview

Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine appropriate type, scope, and message. Conventional commits specifications: https://www.conventionalcommits.org/en/v1.0.0/

Conventional Commit Format

<type>[optional scope]: <description>

<body>

[optional footer(s)]

Commit Types

Type	Purpose
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting/style (no logic)
refactor	Code refactor (no feature/fix)
perf	Performance improvement
test	Add/update tests
build	Build system/dependencies
ci	CI/config changes
chore	Maintenance/misc
revert	Revert commit

Breaking Changes

# Exclamation mark after type/scope
feat!: remove deprecated endpoint

# BREAKING CHANGE footer
feat: allow config to extend other configs

BREAKING CHANGE: `extends` key behavior changed

AI Agent Footers

AI agents MUST NOT add Signed-off-by tags. Only humans can legally be author of a commit.

When AI tools contribute to development, proper attribution helps track the evolving role of AI in the development process.

Contributions MUST include an Assisted-by trailer in the following format:

Assisted-by: AGENT_NAME:MODEL_VERSION

Where:

• AGENT_NAME is the name of the AI tool or framework
• MODEL_VERSION is the exact model label used for the session

Example:

Assisted-by: Codex:GPT-5.5

Do not omit the Assisted-by: key. Do not shorten a point release or user-visible model label, for example using GPT-5 when the active model is GPT-5.5. If the exact model label is unavailable or contradicts the user-visible selector, ask the user before committing.

Workflow

1. Analyze Diff

# If files are staged, use staged diff
git diff --staged

# If nothing staged, use working tree diff
git diff

# Also check status
git status --porcelain

2. Stage Files (if needed)

If nothing is staged or you want to group changes differently:

# Stage specific files
git add path/to/file1 path/to/file2

# Stage by pattern
git add *.test.*
git add src/components/*

# Interactive staging
git add -p

Never commit secrets (.env, credentials.json, private keys).

3. Generate Commit Message

Analyze the diff to determine:

• Type: What kind of change is this?
• Scope: What area/module is affected?
• Description: One-line summary of what changed (present tense, imperative mood, short enough that the full subject is <=50 chars)

4. Execute Commit

# Single line
git commit -m "<type>[scope]: <description>"

# Multi-line with body/footer
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>

<body wrapped at 72 chars>

<optional footer>
EOF
)"

Do not pass long body paragraphs as single -m values. Git stores each argument exactly as provided and does not wrap commit message text.

After committing, verify the message and amend immediately if it fails:

git show --format=%B --no-patch HEAD | awk '
NR == 1 && length($0) > 50 { print "subject >50: " length($0); bad=1 }
NR > 1 && length($0) > 72 { print "body >72: " length($0); bad=1 }
END { exit bad }
'

Commit rules

• One logical change per commit
• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Present tense: "add" not "added"
• Imperative mood: "fix bug" not "fixes bug"
• Reference issues: Closes #123, Refs #456
• Always include a description body
• Use the body to explain what and why, not how
• Wrap body and footer lines at 72 characters

Git Safety Protocol

• NEVER update git config
• NEVER run destructive commands (--force, hard reset) without explicit request
• NEVER skip hooks (--no-verify) unless user asks
• NEVER force push to main/master
• If commit fails due to hooks, fix and create NEW commit (don't amend)