Commit Command Reference

Complete technical reference for the commit command.

For practical usage and workflows, see the How-to Guide.

Command Syntax

r2r eac create commit-message [options]

Options and Flags

Flag	Short	Description	Default
`--commit`	`-c`	Automatically create the commit without opening editor	`false`
`--debug`	`-d`	Save intermediate outputs to `out/` directory for inspection	`false`
`--prompt`		Custom prompt file path (overrides team and system defaults)	System/team default

Examples

# Generate message and open editor
r2r eac create commit-message

# Generate and commit automatically
r2r eac create commit-message --commit

# Debug AI generation process
r2r eac create commit-message --debug

# Use custom prompt
r2r eac create commit-message --prompt /path/to/custom-prompt.md

# Auto-commit with debug output
r2r eac create commit-message --commit --debug

Commit Types

The AI uses standard semantic commit types:

Type	Description	Use Case	Example
`feat`	New feature or capability	Adding new functionality	`feat(src-auth): implement JWT authentication`
`fix`	Bug fix	Fixing broken behavior	`fix(src-api): resolve rate limiting race condition`
`refactor`	Code restructuring (no behavior change)	Improving code structure	`refactor(eac-core): extract validation logic`
`docs`	Documentation only	Documentation changes	`docs(specs): add authentication examples`
`chore`	Maintenance tasks	Dependency updates, tooling	`chore(deps): update dependencies`
`test`	Test changes only	Adding or modifying tests	`test(src-auth): add integration tests`
`perf`	Performance improvements	Optimizing performance	`perf(src-cache): optimize lookup algorithm`
`style`	Code formatting (no logic change)	Formatting, whitespace	`style(eac-core): apply gofmt`

Multi-Module Commits

For changes affecting multiple modules, use multi-module as the scope:

refactor(multi-module): reorganize validation logic

Generated Format

Standard Commit Structure

<type>(<module>): <short description>

<detailed description of changes>

<bullet points for key changes>

Files modified:
- path/to/file1.go
- path/to/file2.go

Single Module Example

feat(src-auth): implement JWT authentication system

Add secure authentication using JWT tokens for API access. The system
includes token generation, validation, and refresh mechanisms with
configurable expiration times.

Key changes:
- Token generation with HS256 signing
- Middleware for request authentication
- Token refresh endpoint
- Comprehensive test coverage

Files modified:
- src/auth/jwt.go
- src/auth/jwt_test.go
- src/auth/middleware.go

Multi-Module Example

refactor(multi-module): reorganize validation logic

Extract validation logic from individual modules into a shared validation
package to reduce duplication and improve consistency across the codebase.

eac-core changes:
- Create new validation package with common validators
- Add field validation helpers
- Implement error aggregation

src-auth changes:
- Replace local validators with shared validators
- Update tests to use new validation package

src-api changes:
- Migrate request validation to shared validators
- Remove duplicate validation code

Files modified:
- go/eac/core/validation/validators.go (new)
- go/eac/core/validation/validators_test.go (new)
- src/auth/validators.go (removed)
- src/auth/login.go
- src/api/handlers.go

Debug Mode

Enable debug mode with the --debug flag to inspect the AI generation process:

r2r eac create commit-message --debug

Debug Output Structure

Debug files are saved to out/commit-message/:

out/
├── commit-message/
│   ├── 01-context.md              # Git status, diff, recent commits
│   ├── 02-summary-prompt.md       # AI prompt for summary generation
│   ├── 03-summary-response.md     # AI-generated summary
│   ├── 04-module-prompts/
│   │   ├── src-auth.md            # Prompt for src-auth module
│   │   └── eac-core.md            # Prompt for eac-core module
│   ├── 05-module-responses/
│   │   ├── src-auth.md            # AI response for src-auth
│   │   └── eac-core.md            # AI response for eac-core
│   ├── 06-assembly-prompt.md      # Prompt to combine sections
│   ├── 07-assembly-response.md    # Final assembled message
│   ├── 08-validation-result.json  # Validation details
│   └── 09-final-message.txt       # Cleaned commit message

Debug File Contents

01-context.md

Contains the raw git context:

git status output
git diff --cached output
Recent commit history
Module ownership information

02-summary-prompt.md

The prompt sent to the AI to generate the overall summary, including:

Context about the changes
Instructions for summary format
Examples of good summaries

03-summary-response.md

The AI's response containing:

Identified commit type
Primary affected module
Overall change description

04-module-prompts/

Individual prompts for each affected module, containing:

Module-specific changes
Module context
Instructions for detailed analysis

05-module-responses/

AI-generated detailed analysis for each module

06-assembly-prompt.md

Prompt to combine all sections into final commit message

07-assembly-response.md

The assembled commit message before validation

08-validation-result.json

Validation results including:

Pass/fail status
Validation errors
Retry attempts
Contract checks

09-final-message.txt

The final commit message after all cleanup and validation

When to Use Debug Mode

Use --debug when:

AI generates unexpected messages
Validation fails repeatedly
Understanding module analysis
Troubleshooting formatting issues
Customizing AI prompts
Investigating performance issues
Learning how the AI works

Validation and Retry Logic

Automatic Retry

The command automatically retries up to 5 times if validation fails:

Attempt 1: ✗ Invalid format - missing module in parentheses
Attempt 2: ✗ Invalid format - incorrect bullet structure
Attempt 3: ✓ Validation passed

Common Auto-fixes

The retry logic automatically corrects:

Missing module identifier in header
Incorrect bullet formatting (uses - instead of * or •)
Extra whitespace in headers or body
Invalid commit type (suggests closest valid type)
Missing or malformed file list

Validation Rules

Commit messages are validated against:

Format: Must follow <type>(<module>): <description> pattern
Commit type: Must be one of: feat, fix, refactor, docs, chore, test, perf, style
Module: Must exist in project contracts or be "multi-module"
Structure: Must have description, details, and file list
File list: Must start with "Files modified:" and use bullet points

Manual Intervention

If all 5 retry attempts fail:

Error: Failed to generate valid commit message after 5 attempts.

Please check:
1. Staged changes are valid
2. Module contracts are up to date
3. Debug output in out/commit-message/

Try running with --debug for detailed diagnostics.

Solutions:

Check out/commit-message/08-validation-result.json for specific errors
Review module contracts: r2r eac show modules
Verify staged changes: git diff --cached
Check if changes match a clear pattern (feat, fix, etc.)

Integration with Work Command

Command Comparison

Command	Use Case	Working Directory	Auto-staging
`r2r eac create commit-message`	Direct commit message generation	Any git repo	No (manual `git add`)
`r2r eac work commit`	Workspace-aware commits	Inside work workspace	Yes (with `--all`)

Work Command Example

# Create workspace
r2r eac work create feature/authentication

# Develop feature
vim src/auth/jwt.go

# Use commit command directly (manual staging)
git add src/auth/
r2r eac create commit-message --commit

# Or use work commit (auto-staging)
r2r eac work commit --all

Both commands use the same AI engine and validation logic.

Advanced Usage

Custom Editor

Configure your preferred editor for commit message editing:

# Vim
export GIT_EDITOR="vim"
r2r eac create commit-message

# VS Code (wait for window to close)
export GIT_EDITOR="code --wait"
r2r eac create commit-message

# Nano
export GIT_EDITOR="nano"
r2r eac create commit-message

Pre-commit Hook Integration

Automatically generate commit messages when committing:

# .git/hooks/prepare-commit-msg
#!/bin/bash

# Only generate message if commit message is empty
if [ -z "$2" ]; then
  r2r eac create commit-message --commit
fi

Make the hook executable:

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

CI/CD Validation

Validate commit message format in continuous integration:

# Validate commit message format in CI
git log -1 --pretty=%B > last-commit.txt

# Parse and validate (implement custom validator)
if ! validate-commit-format last-commit.txt; then
  echo "Invalid commit message format"
  exit 1
fi

Batch Commits

Commit multiple logical changes separately:

# Commit multiple logical changes separately
for dir in go/eac/auth go/eac/api go/eac/core; do
  if git diff --cached --name-only | grep -q "^$dir/"; then
    git reset  # Unstage all
    git add $dir/
    r2r eac create commit-message --commit
  fi
done

Soft Reset

To undo the last commit while preserving changes:

git reset --soft HEAD~1

# What happens:
# 1. Undoes the last commit
# 2. Preserves all changes in staging area
# 3. Allows you to recommit with a new message

Use when:

You want to improve the commit message
You need to add more changes to the last commit
You committed too early and want to stage additional files

Configuration

AI Provider Setup

Configure your AI provider on first use:

# Configure AI provider (first time)
r2r eac init

# Select provider: openai, anthropic, azure, etc.
# Enter API key when prompted

Custom Prompts

Customize AI behavior using the three-tier prompt system. Prompts are loaded with the following priority:

Priority Order

Command Flag (highest priority)

r2r eac create commit-message --prompt /path/to/custom.md

Use for one-off experiments or testing new prompts

Team Override (version controlled)
Location: .r2r/eac/templates/ai/commit/
For team-wide customizations
Committed to git, affects entire team
System Default (fallback)
Location: templates/ai/commit/
Shipped with r2r
View to understand baseline behavior

Available Prompts

Prompt File	Purpose	Override Location
`module.md`	Multi-module commit sections	`.r2r/eac/templates/ai/commit/module.md`
`top-level.md`	Top-level commit header	`.r2r/eac/templates/ai/commit/top-level.md`

Creating Team Overrides

Step 1: Copy system default

cp templates/ai/commit/module.md .r2r/eac/templates/ai/commit/module.md

Step 2: Edit for your team's style

# Edit to match team conventions
nano .r2r/eac/templates/ai/commit/module.md

Step 3: Commit to git

git add .r2r/eac/templates/ai/commit/module.md
git commit -m "chore(eac): customize commit message prompt for team"

Step 4: Test

git add some-file.go
r2r eac create commit-message --debug
# Output shows: "Using team override prompt"

Testing Prompts

Use --debug to see which prompt is being used:

r2r eac create commit-message --debug
# Shows: "ℹ️  Using team override prompt"
# or:    "ℹ️  Using system default prompt"
# or:    "ℹ️  Using command flag prompt"

Example Customization

Edit .r2r/eac/templates/ai/commit/module.md to customize commit generation:

# Team Commit Message Prompt

Generate commit messages focusing on:
- Business value and user impact
- Technical implementation approach
- Testing strategy

Use our team conventions:
- Keep descriptions under 50 characters
- Use present tense ("add" not "added")
- Reference JIRA tickets when applicable

Format: <type>(<module>): <description> [JIRA-123]

Detailed Guide

For comprehensive customization guide including examples, troubleshooting, and best practices, see:

cat .r2r/eac/templates/ai/README.md

Performance

Parallel Processing

Multi-module commits process modules in parallel for speed:

Processing 3 modules...
[src-auth] Started
[src-api]  Started
[eac-core] Started
[src-auth] Complete (2.3s)
[eac-core] Complete (2.5s)
[src-api]  Complete (2.8s)
Total: 2.8s (vs 7.6s sequential)

Performance factors:

Number of modules: More modules = more parallel processing benefit
AI provider latency: Varies by provider and region
Change complexity: Larger diffs take longer to analyze
Retry attempts: Validation failures add overhead

Caching

Context analysis results are cached during retry attempts to avoid re-processing:

Git status (cached between retries)
Git diff (cached between retries)
Recent commits (cached between retries)
Module ownership (cached between retries)

Cache is cleared after successful commit or command termination.

Example Outputs

Documentation Update

docs(specs): add authentication specification examples

Add comprehensive examples for authentication specifications including
JWT, OAuth2, and session-based authentication patterns.

Changes:
- Add JWT authentication example spec
- Add OAuth2 flow specification
- Add session management examples
- Update specification guidelines

Files modified:
- specs/src-auth/jwt-authentication.feature (new)
- specs/src-auth/oauth2-flow.feature (new)
- docs/specifications.md

Performance Optimization

perf(src-cache): optimize cache lookup with bloom filter

Reduce cache miss overhead by adding bloom filter for quick existence
checks before expensive cache operations. Improves performance by 40%
for cache-miss scenarios.

Implementation:
- Add bloom filter with configurable false positive rate
- Check bloom filter before cache lookup
- Benchmark shows 40% improvement for misses
- No impact on cache-hit performance

Files modified:
- src/cache/cache.go
- src/cache/bloom.go (new)
- src/cache/cache_test.go
- src/cache/benchmark_test.go

Breaking Change

refactor(src-api): change response format to JSON:API spec

BREAKING CHANGE: Update all API responses to follow JSON:API specification.
Clients must update to handle new response structure.

Changes:
- Implement JSON:API response formatter
- Update all handlers to use new format
- Add migration guide for clients
- Update API documentation

Files modified:
- src/api/response.go
- src/api/handlers.go
- src/api/handlers_test.go
- docs/api-migration.md (new)

Bug Fix

fix(src-cache): resolve race condition in cache invalidation

Fix concurrent map access race condition that occurred during cache
invalidation under high load. Add proper mutex locking to protect
shared state.

Changes:
- Add sync.RWMutex to cache struct
- Lock during invalidation operations
- Add race detector tests

Files modified:
- src/cache/cache.go
- src/cache/cache_test.go