Advanced usage of conventional commits with breaking changes, issue references, and multi-file commits.
Create conventional commits directly for advanced scenarios.
Check the repository state:
git status
git diff --staged
git log --oneline -5
Stop if repository is in conflict state or no changes are staged.
Look at what's staged and determine:
Type - What kind of change is this?
feat - new featurefix - bug fixdocs - documentation onlystyle - formatting onlyrefactor - code restructure (no behavior change)perf - performance improvementtest - test changesbuild - build/dependency changesci - CI/CD changeschore - maintenance/toolingScope - What part of the project is affected?
auth, api, ui, db)user not users)Breaking changes? - Does this break existing functionality?
If yes: Use ! marker and include BREAKING CHANGE: footer
Issue references? - Is this linked to any issues?
Fixes #123 - for bug fixesCloses #456 - for any issue typeRelates to #789 - for references without closingtype(scope): short description
Examples:
feat(auth): add two-factor authenticationfix(payment): prevent duplicate chargesdocs(readme): add installation guideRules for header:
Add a body when:
Format:
Example:
feat(auth): add JWT token support
Implement JWT tokens for stateless authentication across the API.
- Add JWT generation and validation service
- Update authentication middleware
- Add refresh token endpoint
- Add token expiration handling
Add footer for breaking changes or issue references.
Breaking change example:
feat(api)!: restructure response format
BREAKING CHANGE: User endpoints now return nested structure
Before:
{ "id": 1, "name": "John" }
After:
{ "user": { "id": 1, "name": "John" } }
Migration: Update clients to access response.user
Closes #567
Issue reference example:
fix(payment): prevent duplicate charges
Users could be charged twice when clicking submit multiple times.
- Add idempotency keys to payment requests
- Disable button during processing
- Add concurrency tests
Fixes #834
Build the complete message and use heredoc format:
git commit -m "$(cat <<'EOF'
type(scope): description
Body explaining the change if needed.
BREAKING CHANGE: or issue references if needed
Fixes #123
EOF
)"
Important: Use single quotes in <<'EOF' to prevent shell expansion.
After committing, verify:
git log -1 --format=fuller
Check that:
Always do:
Never do:
If changes contain multiple unrelated things:
Example:
# Commit 1
feat(api): add user endpoint
# Commit 2
chore(deps): upgrade TypeScript
# Commit 3
docs: update API documentation
Detailed examples and patterns: EXAMPLE.md