Skip to content

Commit Artifact Generation

Generate commit artifacts from staged git changes. Artifacts follow the Conventional Commits specification.

Overview

The smooth commit generate command analyzes staged git changes and produces a structured commit message. The system examines file changes, code patterns, and context to generate a commit artifact with type, scope, subject, and body.

How It Works

  1. Stage changes with git add
  2. Run smooth commit generate
  3. The system analyzes the diff and generates a structured commit artifact
  4. Commit manually or use --commit flag for automatic commit

The system analyzes:

  • Files changed and file types
  • Code additions and deletions
  • Surrounding code context
  • Commit patterns in repository history
  • Issue numbers from branch names (when detectable)

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

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 artifact generation in 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 Configuration for additional options.

Security and Data Handling

Smoothdev encrypts customer data in transit and at rest using tenant-scoped encryption keys. Source data is processed only for the requested operation and is not retained long term. Generated artifacts are returned to the user. Operational metrics and validation logs are retained to improve system reliability and quality.

Limitations

  • Staged changes are required; unstaged changes are not analyzed
  • Maximum diff size: 100KB. Larger diffs are truncated.
  • Binary files are excluded from analysis
  • Commit type selection is based on heuristics and may require manual adjustment
  • Issue detection requires branch names following patterns: feature/123-description, fix-123, 123-feature
  • The --commit flag requires a clean working tree (no unstaged changes to staged files)

See Also