7.3 KiB
7.3 KiB
description
| description |
|---|
| Compose commit message body with bullet points and proper formatting |
Operation: Write Commit Body
Compose a well-formatted commit message body with bullet points, proper wrapping, and clear explanation of changes.
Parameters from $ARGUMENTS
Required:
changes:- Comma-separated list of changes or file paths
Optional:
wrap:- Line wrap length (default: 72)format:- Output format (bullets|paragraphs, default: bullets)why:- Additional context about why changes were made
Format: body changes:"Change 1,Change 2,Change 3" [why:"explanation"]
Workflow
Step 1: Parse Parameters
Extract parameters from $ARGUMENTS:
# Parse changes (supports both quoted and comma-separated)
changes=$(echo "$ARGUMENTS" | grep -oP 'changes:"\K[^"]+' || echo "$ARGUMENTS" | grep -oP 'changes:\K[^,]+')
wrap=$(echo "$ARGUMENTS" | grep -oP 'wrap:\K[0-9]+' || echo "72")
format=$(echo "$ARGUMENTS" | grep -oP 'format:\K[^ ]+' || echo "bullets")
why=$(echo "$ARGUMENTS" | grep -oP 'why:"\K[^"]+')
Step 2: Validate Parameters
Check required parameters:
if [ -z "$changes" ]; then
echo "ERROR: changes parameter is required"
echo "Usage: body changes:\"<change1>,<change2>\" [why:\"<explanation>\"]"
exit 1
fi
Validate format:
if [ "$format" != "bullets" ] && [ "$format" != "paragraphs" ]; then
echo "ERROR: Invalid format '$format'"
echo "Valid formats: bullets, paragraphs"
exit 1
fi
Step 3: Invoke Body Composer Script
Pass parameters to the utility script for intelligent formatting:
# Export variables for script
export CHANGES="$changes"
export WRAP_LENGTH="$wrap"
export FORMAT="$format"
export WHY_CONTEXT="$why"
# Run composer
/home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation/.scripts/body-composer.sh
The script will:
- Split changes into individual items
- Format as bullet points or paragraphs
- Wrap lines at specified length
- Add context if provided
- Ensure imperative mood
Step 4: Format Output
Present the generated body:
COMMIT BODY GENERATED
═══════════════════════════════════════════════
BODY:
───────────────────────────────────────────────
<blank line>
<formatted body content with bullet points>
<wrapped at 72 characters>
VALIDATION:
───────────────────────────────────────────────
✓ Blank line before body
✓ Lines wrapped at 72 characters
✓ Bullet points used
✓ Imperative mood
✓ Proper formatting
STATISTICS:
───────────────────────────────────────────────
Lines: X
Longest line: XX chars
Bullet points: X
═══════════════════════════════════════════════
Output Format
Return structured output:
- Formatted body text
- Validation results
- Statistics (line count, wrapping)
- Suggestions for improvement (if any)
Error Handling
Missing required parameters:
ERROR: Missing required parameter 'changes'
Usage: body changes:"<change1>,<change2>" [why:"<explanation>"]
Example: body changes:"Implement OAuth2 flow,Add provider support"
Line too long:
WARNING: Line exceeds 72 characters (XX chars)
Line: "- Very long description that goes on and on..."
Suggestion: Split into multiple bullet points or wrap text
Non-imperative mood:
WARNING: Use imperative mood in body
Current: "- Added authentication"
Correct: "- Add authentication"
Body Formatting Rules
Structure:
<blank line required between subject and body>
<body content>
- Bullet point 1
- Bullet point 2
- Bullet point 3
Line Wrapping:
- Target: 72 characters per line
- Hard limit: No line should exceed 80 characters
- Use hard wraps, not soft wraps
Bullet Points:
- Use
-for bullet points - Consistent indentation
- One thought per bullet
- Imperative mood
Content Focus:
- Explain WHAT and WHY, not HOW
- Focus on user-facing changes
- Provide context when needed
- Avoid implementation details
Integration with Agent
The commit-assistant agent uses this operation to:
- Generate body content from analyzed changes
- Format file lists into readable bullet points
- Add context about why changes were made
- Ensure proper formatting and wrapping
Usage Examples
Example 1: Basic Body with Changes
# Input
/message-generation body changes:"Implement OAuth2 flow,Add Google provider,Add GitHub provider,Include middleware"
# Output
BODY:
- Implement OAuth2 flow
- Add Google provider
- Add GitHub provider
- Include middleware
Example 2: Body with Context
# Input
/message-generation body changes:"Refactor database queries,Add connection pooling" why:"Improve performance under load"
# Output
BODY:
- Refactor database queries
- Add connection pooling
Improve performance under high load conditions.
Example 3: Body from File List
# Input
/message-generation body changes:"src/auth/oauth.js,src/auth/providers/google.js,src/auth/providers/github.js"
# Output
BODY:
- Add OAuth authentication module
- Implement Google provider
- Implement GitHub provider
- Add provider configuration
Example 4: Paragraph Format
# Input
/message-generation body changes:"Update authentication flow" why:"Previous implementation had security vulnerabilities" format:paragraphs
# Output
BODY:
Update authentication flow to address security vulnerabilities
discovered in the previous implementation. The new approach uses
industry-standard OAuth2 protocol with secure token handling.
Best Practices
Be Clear:
- ✅ "Add user authentication with OAuth2"
- ❌ "Add stuff"
Use Bullet Points:
- ✅ Multiple related changes as bullets
- ❌ Long paragraphs of text
Focus on What/Why:
- ✅ "Add caching to improve performance"
- ❌ "Add Redis instance with 5-minute TTL"
Keep It Concise:
- ✅ Brief, clear explanations
- ❌ Essay-length descriptions
Wrap Properly:
- ✅ "This is a properly wrapped line that doesn't exceed\nthe 72 character limit"
- ❌ "This is a very long line that goes on and on and on and exceeds the character limit"
When to Include a Body
Include body when:
- Multiple files changed
- Changes need explanation
- Context is important
- Implications not obvious
Omit body when:
- Change is self-explanatory
- Subject line is sufficient
- Trivial change
- Documentation only
Body Templates
Feature Addition:
- Add <feature name>
- Implement <capability 1>
- Implement <capability 2>
- Include <supporting feature>
Bug Fix:
- Resolve <issue>
- Add validation for <edge case>
- Update error handling
Fixes issue where <description of bug>
Refactoring:
- Extract <component>
- Simplify <logic>
- Improve <aspect>
No functional changes, improves code maintainability.
Performance:
- Optimize <operation>
- Add caching for <data>
- Reduce <metric>
Improves performance by <measurement>.