Git Conventional Commits Guide

Basic Commands

Each commit type has a dedicated shortcut command. Here are the basic patterns:

git feat "your message"    # New features
git fix "your message"     # Bug fixes
git docs "your message"    # Documentation changes
git style "your message"   # Code style changes (formatting, semicolons, etc)
git refactor "your message"    # Code refactoring
git perf "your message"    # Performance improvements
git test "your message"    # Adding or updating tests
git build "your message"   # Build system or external dependency changes
git ci "your message"      # CI configuration changes
git chore "your message"   # Other changes that don't modify src or test files
git revert "your message"  # Reverting previous changes

Advanced Usage

Adding a Scope

Scope indicates which part of the codebase is affected. Use the -s or --scope flag:

git feat -s backend "add user authentication"
# Result: feat(backend): add user authentication

git fix -s ui "fix button alignment"
# Result: fix(ui): fix button alignment

Breaking Changes

Mark breaking changes using the -b or --breaking flag:

git feat -b -s api "change authentication flow"
# Result: feat(api)!: change authentication flow

git refactor -b "complete overhaul of user system"
# Result: refactor!: complete overhaul of user system

Adding Body and Footer

Use --body and --footer for additional information:

git fix -s auth -m "fix login timeout" \
    --body "The timeout was not properly handling token expiration" \
    --footer "Fixes #123"

# Result:
# fix(auth): fix login timeout
#
# The timeout was not properly handling token expiration
#
# Fixes #123

Using the Full Conventional Commit Helper

For maximum control, use the commit-conventional command:

git commit-conventional \
    -t feat \
    -s api \
    -b \
    -m "new authentication system" \
    --body "- Adds OAuth2 support\n- Improves security" \
    --footer "BREAKING CHANGE: New authentication flow required"

# Result:
# feat(api)!: new authentication system
#
# - Adds OAuth2 support
# - Improves security
#
# BREAKING CHANGE: New authentication flow required

Command Options Reference

Each command accepts these flags:

-t, --type: Commit type (required for commit-conventional)
-s, --scope: Component scope (optional)
-b, --breaking: Mark as breaking change (optional)
-m, --message: Commit message (required)
--body: Detailed description (optional)
--footer: Footer notes, breaking change descriptions, or issue references (optional)

Examples for Common Scenarios

Feature Development

# New feature
git feat "add user registration"

# New feature with scope
git feat -s auth "add OAuth support"

# Breaking feature change
git feat -b -s api "redesign user endpoints"

Bug Fixes

# Simple fix
git fix "correct email validation"

# Fix with scope
git fix -s validation "fix email regex"

# Fix with issue reference
git fix -s auth -m "fix login timeout" --footer "Fixes #123"

Documentation

# Update docs
git docs "update README installation steps"

# Update API docs
git docs -s api "update endpoint documentation"

Code Improvements

# Style changes
git style "format according to new style guide"

# Performance improvement
git perf -s database "optimize query performance"

# Refactoring
git refactor -s core "simplify error handling"

Testing

# Add tests
git test "add unit tests for user service"

# Update tests
git test -s api "update integration tests"

Maintenance

# Build changes
git build "update webpack configuration"

# CI changes
git ci "add new deploy workflow"

# Chores
git chore "update dependencies"

byaruhaf/Git Conventional Commits Guide.md