gh-openshift-eng-ai-helpers-plugins-git/commands/commit-suggest.md

description, argument-hint

description	argument-hint
Generate Conventional Commits style commit messages or summarize existing commits	N

Name

git:commit-suggest

Synopsis

/git:commit-suggest       # Analyze staged changes
/git:commit-suggest [N]     # Analyze last N commits (1-100)

Description

AI-powered command that analyzes code changes and generates Conventional Commits–style messages.

Modes:

• Mode 1 (no argument) – Analyze staged changes (git add required)
• Mode 2 (with N) – Analyze last N commits to rewrite (N=1) or summarize for squash (N≥2)

Use cases:

• Create standardized commit messages
• Improve or rewrite existing commits
• Generate squash messages for PR merges

Difference from /git:summary – That command is read-only, while git:commit-suggest generates actionable commit message suggestions for user review and manual use.

Implementation

The command operates in two modes based on input:

Mode 1 (no argument):

1. Collect staged changes via git diff --cached
2. Analyze file paths and code content to identify type (feat/fix/etc.) and scope
3. Generate 3 commit message suggestions (Recommended, Standard, Minimal)
4. Display formatted suggestions and prompt user for selection
   • Ask: "Which suggestion would you like to use? (1/2/3 or skip)"
   • Support responses: 1, use option 2, commit with option 3, skip
   • Execute git commit with selected message if user requests

Mode 2 (with N):

1. Retrieve last N commits using git log
2. Parse commit messages to extract types, scopes, and descriptions
3. For N=1: Suggest improved rewrite For N≥2: Merge commits intelligently by type priority (fix > feat > perf > refactor > docs > test > chore)
4. Generate 3 commit message suggestions (Recommended, Standard, Minimal)
5. Display formatted suggestions and prompt user for selection
   • Ask: "Which suggestion would you like to use? (1/2/3 or skip)"
   • Support responses: 1, use option 2, amend with option 3, skip
   • Execute git commit --amend (N=1) or squash operation (N≥2) if user requests

Examples

# Generate message for staged files
git add src/auth.ts src/middleware.ts
/git:commit-suggest

# Rewrite last commit message
/git:commit-suggest 1

# Summarize last 5 commits for squash
/git:commit-suggest 5

Return Value

Generates 3 commit message suggestions:

• Suggestion #1 (Recommended) – Detailed with full body and metadata
• Suggestion #2 (Standard) – Concise with main points
• Suggestion #3 (Minimal) – Title and short summary

Each suggestion includes:

• Conventional Commits message (type(scope): description)
• Blank line between title and body
• Optional body text explaining the changes
• Optional footer (issue refs, co-authors, breaking changes, etc.)

Example:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Suggestion #1 (Recommended)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
feat(auth): add JWT authentication middleware

Implement token-based authentication for API endpoints.
The middleware verifies JWT tokens and extracts user information.

Fixes: #123

Which suggestion would you like to use? (1/2/3 or skip)

Mode 2 Specifics

• N=1 – Suggest improved rewrite for the last commit
• N≥2 – Generate unified squash message with footer: Squashed from N commits: + original commit list

Conventional Commits Reference

Format

type(scope): description

[optional body]

[optional footer]

Common Types

• feat – New feature
• fix – Bug fix
• docs – Documentation changes
• refactor – Code refactoring
• perf – Performance improvements
• test – Test additions or modifications
• build – Build system or dependency changes
• ci – CI configuration changes
• chore – Other changes that don't modify src or test files

Scope & Footer Examples

Scope: auth, api, ui, db, deps (indicates affected module)

Footer:

• Issue refs: Fixes: #123, Closes: #456, Related: #789
• Breaking changes: BREAKING CHANGE: description
• Co-authors: Co-authored-by: Name <email@example.com>

Arguments

• [N] (optional): Number of recent commits to analyze (1-100)
  • If omitted: Analyzes staged changes (Mode 1)
  • If N=1: Suggests improved rewrite for the last commit
  • If N≥2: Generates unified squash message for last N commits

See Also

• /git:summary – Display repository status and recent commits (read-only)
• Conventional Commits Specification