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 Commit Format
<type>[optional scope]: <description>
[optional 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 |
Common Scopes
Example scopes for a repository:
| Scope | Usage |
|---|---|
core |
Core library changes |
cli |
CLI application changes |
api |
API/interface changes |
auth |
Authentication/authorization changes |
db |
Database schema or query changes |
copilot |
GitHub Copilot instructions/skills |
config |
Configuration file changes |
deps |
Dependency updates |
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
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, <72 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>
<optional body>
<optional footer>
EOF
)"
Best Practices
- One logical change per commit
- Present tense: "add" not "added"
- Imperative mood: "fix bug" not "fixes bug"
- Reference issues:
Closes #123,Refs #456 - Keep description under 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)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.