Skip to content

AI-Powered Commit Messages

Generate conventional commit messages automatically from your staged changes using AI.

Overview

The SmoothDev CLI analyzes your git diff and generates structured, meaningful commit messages that follow the Conventional Commits specification. This eliminates the cognitive overhead of writing commit messages and ensures consistency across your team.

How It Works

  1. Stage your changes with git add
  2. Run the generator with smooth commit generate
  3. Review the message - the AI analyzes your diff and creates a structured message
  4. Commit - either manually with git commit -m "..." or automatically with --commit

The AI examines:

  • Files changed and their types
  • Code additions and deletions
  • Context from surrounding code
  • Common patterns and conventions
  • Issue numbers from branch names

Basic Usage

Generate a Commit Message

# Stage your changes
git add .

# Generate commit message
smooth commit generate

Example Output:

feat: add user authentication with Auth0

- Implement Auth0 device flow authentication
- Add token storage and refresh logic
- Create auth command group with login/logout
- Add secure token file permissions (0600)

Generate and Commit Immediately

# Stage and commit in one step
git add .
smooth commit generate --commit

This automatically commits with the generated message, saving you from copy-pasting.

Commit Message Format

Generated messages follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

Types

The AI automatically selects the appropriate type based on your changes:

Type Description Example
feat New feature feat: add user authentication
fix Bug fix fix: resolve memory leak in cache
docs Documentation only docs: update API reference
style Code style changes style: format code with prettier
refactor Code refactoring refactor: extract validation logic
perf Performance improvement perf: optimize database queries
test Adding/updating tests test: add unit tests for auth
build Build system changes build: update webpack config
ci CI/CD changes ci: add GitHub Actions workflow
chore Maintenance tasks chore: update dependencies

Subject Line

  • Concise - Typically 50-72 characters
  • Imperative mood - "add feature" not "added feature"
  • No period - Ends without punctuation
  • Lowercase - Starts with lowercase (except proper nouns)

Body

  • Bullet points - Clear, structured list of changes
  • What and why - Explains what changed and why
  • Breaking changes - Noted with BREAKING CHANGE: prefix

Advanced Usage

Associate with an Issue

Link commits to issues automatically:

# Specify issue number
smooth commit generate --issue 123

# Or use branch name (auto-detected)
git checkout feature/123-add-auth
smooth commit generate  # Automatically includes issue #123

Output:

feat: add user authentication (#123)

- Implement Auth0 device flow authentication
- Add token storage and refresh logic

Latency Profiles

Choose between speed and quality:

# Fast generation (lower quality, faster)
smooth commit generate --latency-profile fast

# Balanced (default)
smooth commit generate --latency-profile balanced

# High quality (slower, more detailed)
smooth commit generate --latency-profile quality
Profile Speed Quality Use Case
fast ~2s Good Quick commits, small changes
balanced ~5s Better Most commits (default)
quality ~10s Best Important commits, complex changes

Custom Templates

Use a custom commit message template:

smooth commit generate --template .commit-template.txt

Template Format (.commit-template.txt):

{{type}}({{scope}}): {{subject}}

{{body}}

Refs: #{{issue}}

Examples

Feature Addition

Changes: - Added new API endpoint - Created tests - Updated documentation

Generated Message:

feat: add user profile API endpoint

- Create GET /api/users/:id endpoint
- Add authentication middleware
- Implement user profile serialization
- Add integration tests for profile endpoint
- Update API documentation with new endpoint

Bug Fix

Changes: - Fixed null pointer exception - Added defensive checks

Generated Message:

fix: prevent null pointer exception in user lookup

- Add null check before accessing user properties
- Return 404 when user not found
- Add test case for missing user scenario

Documentation Update

Changes: - Updated README - Added examples

Generated Message:

docs: improve installation instructions

- Add prerequisites section
- Include troubleshooting steps
- Add examples for common use cases
- Fix broken links to API reference

Breaking Change

Changes: - Changed API response format - Updated client code

Generated Message:

feat!: change API response format to include metadata

BREAKING CHANGE: API responses now include metadata wrapper

- Wrap all responses in { data, metadata } structure
- Add pagination metadata to list endpoints
- Update client to handle new response format
- Migrate existing API consumers

Best Practices

Before Generating

  1. Stage related changes - Only stage files for a single logical change
  2. Review your diff - Run git diff --staged to verify changes
  3. Split large changes - Break big changes into multiple commits

After Generating

  1. Review the message - Ensure it accurately describes your changes
  2. Edit if needed - The AI is good but not perfect; adjust as needed
  3. Maintain consistency - Use similar patterns across your commits

Tips for Better Messages

  • Atomic commits - One logical change per commit
  • Stage selectively - Use git add -p for partial staging
  • Clear intent - Make sure changes have a clear purpose
  • Test first - Ensure tests pass before committing

Troubleshooting

"No staged changes detected"

Problem: No files are staged for commit.

Solution:

# Stage specific files
git add file1.py file2.py

# Or stage all changes
git add .

# Then generate
smooth commit generate

Generated message is too generic

Problem: Message doesn't capture the nuance of your changes.

Solution:

  • Use --latency-profile quality for more detailed analysis
  • Stage fewer files at once for more focused messages
  • Edit the generated message to add context

Wrong commit type selected

Problem: AI chose chore when it should be feat.

Solution:

  • Review your changes - ensure they clearly represent a feature
  • Edit the message manually before committing
  • Consider splitting the commit if it mixes types

Large diffs timeout

Problem: Very large diffs take too long or fail.

Solution:

  • Split changes into smaller commits
  • Use --latency-profile fast for large changes
  • Stage files incrementally

Integration with Git Hooks

Prepare Commit Message Hook

Automatically generate commit messages when you run git commit:

.git/hooks/prepare-commit-msg:

#!/bin/bash

# Only generate for new commits (not amend, merge, etc.)
if [ "$2" = "" ]; then
    # Generate message and write to commit message file
    smooth commit generate > "$1"
fi

Make it executable:

chmod +x .git/hooks/prepare-commit-msg

Now git commit will automatically generate a message!

Commit Message Validation Hook

Validate that commits follow conventions:

.git/hooks/commit-msg:

#!/bin/bash

# Check if message follows conventional commits format
if ! grep -qE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?: .+" "$1"; then
    echo "Error: Commit message must follow Conventional Commits format"
    echo "Example: feat: add new feature"
    exit 1
fi

Configuration

Configure commit generation behavior in your user or repository config:

# Set default latency profile
smooth config set defaults.latency_profile balanced

# Set default issue detection
smooth config set defaults.detect_issue true

See the Configuration Guide for more options.

See Also