gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/commit-split.md

description, allowed-tools

description	allowed-tools
Split large commits into atomic commits through interactive guidance	Bash(git:*)

Commit Split - Interactive Atomic Commit Creation

Overview

The /commit-split command provides an interactive workflow that orchestrates multiple skills to help you split large commits into focused, atomic commits. Each atomic commit represents one logical change that can be independently reviewed, tested, and reverted.

Skills Orchestrated

This command coordinates a complete execution workflow:

1. commit-error-handling - Pre-flight validation

   • Operation: /commit-error-handling diagnose-issues
   • Ensures: Repository ready for splitting

2. commit-analysis - Change understanding

   • Operation: /commit-analysis analyze
   • Provides: Type, scope, and file analysis for grouping

3. atomic-commit - Core splitting logic (PRIMARY)

   • Operation: /atomic-commit interactive
   • Provides: File grouping, suggestions, sequence generation
   • This skill contains the core splitting algorithms

4. message-generation - Message creation

   • Operation: /message-generation complete (per commit)
   • Generates: Conventional commit message for each group

5. commit-best-practices - Quality assurance

   • Operation: /commit-best-practices check-pre-commit (optional)
   • Operation: /commit-best-practices review-commit (after each)
   • Validates: Tests pass, quality maintained

6. history-analysis - Project awareness

   • Operation: /history-analysis analyze-style (cached)
   • Ensures: Messages match project conventions

Interactive Workflow

The /commit-split command provides a guided experience:

1. Analyze changes → Show plan
2. Group files → Present groups
3. For each group:
   - Show files and changes
   - Generate message
   - Get user approval
   - Create commit
   - Review quality
4. Final summary

Alternative Workflows

For more control:

• /atomic-commit interactive - Same workflow, skill-level access
• /atomic-commit sequence - Generate script to execute
• Manual: Use /commit for each group after reviewing

For just analysis:

• /commit-review - Analysis without execution
• /atomic-commit suggest - Get suggestions only

Usage

/commit-split               # Start interactive commit splitting

What This Does

This command helps you:

1. Validate repository state and analyze all changes
2. Group related files by change type and scope
3. Generate conventional commit messages for each group
4. Create multiple focused commits interactively
5. Ensure each commit is atomic and well-documented

Complete Interactive Workflow

User: /commit-split
         ↓
┌─────────────────────────────────┐
│ Pre-Flight & Analysis           │
│ /commit-error-handling          │
│ /commit-analysis                │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Generate Splitting Plan         │
│ /atomic-commit suggest          │
│   → groups files                │
│   → calls /message-generation   │
│       for each group            │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│ Present Plan & Confirm          │
│ User reviews:                   │
│ - N commits                     │
│ - Files in each                 │
│ - Suggested messages            │
└────────────┬────────────────────┘
             ↓
             ┌────────┐
             │ Ready? │
             └───┬────┘
                 │
          ┌──────┴──────┐
         NO            YES
          ↓              ↓
      [Abort]    ┌──────────────┐
                 │ For Each     │
                 │ Group (1-N)  │
                 └──────┬───────┘
                        ↓
          ┌─────────────────────────────┐
          │ Show Group Details          │
          │ - Files                     │
          │ - Message                   │
          │ - Changes                   │
          └──────────┬──────────────────┘
                     ↓
          ┌─────────────────────────────┐
          │ Get User Action             │
          │ 1. Create                   │
          │ 2. Edit                     │
          │ 3. Skip                     │
          │ 4. Abort                    │
          └──────────┬──────────────────┘
                     ↓
              ┌──────┴──────┐
         Create          Skip/Abort
              ↓              ↓
    ┌──────────────────┐    │
    │ Pre-Commit Check │    │
    │ (optional)       │    │
    │ /commit-best-    │    │
    │ practices        │    │
    └────────┬─────────┘    │
             ↓              │
    ┌──────────────────┐    │
    │ git add <files>  │    │
    │ git commit -m "" │    │
    └────────┬─────────┘    │
             ↓              │
    ┌──────────────────┐    │
    │ Post-Commit      │    │
    │ Review           │    │
    │ /commit-best-    │    │
    │ practices        │    │
    └────────┬─────────┘    │
             ↓              │
    ┌──────────────────┐    │
    │ Show Progress    │    │
    │ Continue?        │    │
    └────────┬─────────┘    │
             │              │
             └──────────────┘
                     ↓
          ┌─────────────────────────────┐
          │ Final Summary               │
          │ - List commits created      │
          │ - Quality scores            │
          │ - Remaining changes         │
          │ - Verification commands     │
          └─────────────────────────────┘

Process

Step 1: Validate Repository and Analyze Changes

Orchestrates:

1. /commit-error-handling diagnose-issues - Validate state
2. /commit-analysis analyze - Understand changes

Pre-Flight Checks:

# Verify git repository
git rev-parse --git-dir 2>/dev/null

If not a git repo, show error and exit.

Change Analysis:

# Get all changes
git status --short

# Get detailed diff
git diff HEAD

# Count changes
git status --short | wc -l

Analysis Output:

• Total files and line changes
• Type detection for each file
• Scope identification
• Initial grouping strategy

This provides the data for intelligent splitting.

Direct access:

• /commit-error-handling diagnose-issues - Just validation
• /commit-analysis analyze - Just analysis

If no changes, show message and exit.

Step 2: Generate Splitting Plan

Orchestrates: /atomic-commit suggest

This operation:

1. Groups related files:

   • Strategy: Type-based (feat, fix, docs, test)
   • Alternative strategies: scope-based, feature-based

2. Generates commit messages for each group:

   • Uses: /message-generation complete
   • Format: Conventional commits
   • Style: Matches project conventions (from /history-analysis)

3. Creates execution plan:

   • Commit order (dependencies respected)
   • File → commit mapping
   • Estimated changes per commit

Plan Structure:

Group 1: feat(auth) - 5 files, +386 lines
  feat(auth): implement OAuth authentication system

Group 2: test(auth) - 2 files, +240 lines
  test(auth): add comprehensive OAuth tests

Group 3: docs - 1 file, +128 lines
  docs: add OAuth authentication guide

Direct access:

• /atomic-commit group - Just grouping
• /atomic-commit suggest - Suggestions only
• /atomic-commit sequence - Executable script

Step 3: Present Splitting Plan

Shows the complete plan generated by skill orchestration:

INTERACTIVE COMMIT SPLITTING
═════════════════════════════════════════════

I've analyzed your changes and identified 4 logical
commits to create. I'll guide you through each one.

SPLITTING PLAN:
────────────────────────────────────────────

📦 Commit 1: Authentication Feature
   Type: feat(auth)
   Files: 5 files
   Lines: +386 -0

📦 Commit 2: Authentication Tests
   Type: test(auth)
   Files: 2 files
   Lines: +240 -0

📦 Commit 3: Utility Refactoring
   Type: refactor
   Files: 2 files
   Lines: +79 -119

📦 Commit 4: Documentation Updates
   Type: docs
   Files: 2 files
   Lines: +230 -42

════════════════════════════════════════════

Let's create these commits one by one.
You'll review each before it's created.

Ready to start? (y/n)

User reviews and confirms before any commits are created.

This transparency allows users to understand the splitting strategy before execution.

Step 4: Create Commits Iteratively

For each commit group, orchestrates:

Per-Commit Workflow:

For each group (1 to N):
  ↓
  1. Show group details
  2. Present generated message
     (from /message-generation complete)
  ↓
  3. Get user action:
     - Create with message
     - Edit message
     - Skip group
     - Abort
  ↓
  4. If creating:
     a. Stage files: git add <files>
     b. Validate (optional):
        /commit-best-practices check-pre-commit
     c. Create commit: git commit -m "message"
     d. Review quality:
        /commit-best-practices review-commit
  ↓
  5. Show progress
  6. Continue to next group

User Control Points:

• Review each commit before creation
• Edit any generated message
• Skip groups to commit separately
• Abort if plan needs adjustment

Quality Assurance (optional, configurable):

• Pre-commit checks before each commit
• Post-commit review after each commit
• Rollback guidance if issues found

Detailed Commit Creation Loop

For each group:

1. Show Group Details

═══════════════════════════════════════════
COMMIT 1 of 4: Authentication Feature
═══════════════════════════════════════════

FILES TO COMMIT (5 files):
────────────────────────────────────────────
 M src/auth/oauth.js                  +156
 M src/auth/providers.js              +89
 M src/auth/middleware.js             +73
 M src/auth/config.js                 +45
 M src/auth/index.js                  +23

CHANGES SUMMARY:
────────────────────────────────────────────
- Implements OAuth2 authentication flow
- Adds provider support (Google, GitHub)
- Includes authentication middleware
- Adds configuration management
- Exports unified auth interface

PROPOSED COMMIT MESSAGE:
────────────────────────────────────────────
feat(auth): implement OAuth authentication system

- Add OAuth2 authentication flow
- Implement provider support for Google and GitHub
- Add authentication middleware
- Include configuration management

════════════════════════════════════════════

What would you like to do?

1. Create commit with this message (recommended)
2. Edit the message
3. Skip this group
4. Abort splitting

Enter choice (1/2/3/4):

2. Handle User Choice

Choice 1: Create commit

# Stage only the files in this group
git add src/auth/oauth.js src/auth/providers.js src/auth/middleware.js src/auth/config.js src/auth/index.js

# Create the commit
git commit -m "feat(auth): implement OAuth authentication system

- Add OAuth2 authentication flow
- Implement provider support for Google and GitHub
- Add authentication middleware
- Include configuration management"

# Show success
echo "✅ Commit 1 created successfully"
git log -1 --oneline

Choice 2: Edit message Prompt user for new message:

Enter your commit message:
(Use conventional commits format: <type>(<scope>): <subject>)

> _

Then create commit with user's message.

Choice 3: Skip Skip this group, move to next.

Choice 4: Abort Exit without creating any more commits. Already created commits remain.

3. Show Progress

After each commit:

PROGRESS: 1 of 4 commits created

✅ Commit 1: feat(auth) - abc1234

Remaining commits:
 📦 Commit 2: test(auth) - 2 files
 📦 Commit 3: refactor - 2 files
 📦 Commit 4: docs - 2 files

Continue to next commit? (y/n)

Step 5: Complete and Verify

After all commits created:

Final Validation:

• List all created commits
• Show remaining uncommitted changes (if any)
• Provide git commands to verify:
  • git log --oneline -N
  • git log -p -N

Quality Report: For each commit created:

• Commit hash
• Message
• Quality score (from /commit-best-practices review-commit)

Next Steps Guidance:

• Run full test suite
• Push commits
• Create pull request
• Use /commit-best-practices revert-guidance if needed

Final Summary Display:

═══════════════════════════════════════════
COMMIT SPLITTING COMPLETE
═══════════════════════════════════════════

CREATED COMMITS:
────────────────────────────────────────────
✅ abc1234 - feat(auth): implement OAuth authentication system
✅ def5678 - test(auth): add comprehensive OAuth tests
✅ ghi9012 - refactor: simplify utility functions
✅ jkl3456 - docs: add OAuth authentication guide

SUMMARY:
────────────────────────────────────────────
Total commits created: 4
Files committed: 12
Remaining changes: 0

═══════════════════════════════════════════

VERIFY YOUR COMMITS:
────────────────────────────────────────────
git log --oneline -4
git log -p -4

NEXT STEPS:
────────────────────────────────────────────
✓ Run tests to verify everything works
✓ Push commits: git push
✓ Create pull request if needed

═══════════════════════════════════════════

Great job creating atomic commits!
Your git history is now clean and logical.

Alternative: If Skipped Groups

If user skipped some groups, show remaining files:

REMAINING UNCOMMITTED CHANGES:
────────────────────────────────────────────
 M src/utils.js
 M README.md

These files were skipped during splitting.
Run /commit to commit them, or /commit-split to try again.

Smart Grouping Strategies

The /atomic-commit skill implements multiple grouping strategies:

Strategy 1: Type-Based Grouping

Group by change type first:

• All feat changes together (if same scope)
• All fix changes together
• All refactor changes together
• All docs changes together
• All test changes together

Strategy 2: Scope-Based Grouping

Group by module/component:

• All auth changes together
• All api changes together
• All ui changes together

Strategy 3: Feature-Based Grouping

Group by feature completion:

• Implementation + Tests together
• Feature code + Documentation together

Recommendation: Use Type-Based for most cases, Scope-Based for large features.

Direct access: /atomic-commit group strategy:<type|scope|feature>

Commit Message Generation

For each group, the /message-generation skill generates a message:

Template:

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

<body>

Subject Generation:

• Analyze primary change in the files
• Use active voice, imperative mood
• Keep under 50 characters
• Example: "implement OAuth authentication system"

Body Generation (bullet points):

• List major changes in the group
• Keep bullets concise (under 72 chars)
• Focus on what and why, not how
• Example:

  - Add OAuth2 authentication flow
  - Implement provider support for Google and GitHub
  - Include authentication middleware
  

Direct access: /message-generation complete files:"<files>" type:<type> scope:<scope>

Edge Cases

Case 1: Single File, Multiple Concerns

If one file has multiple unrelated changes:

WARNING: Complex Changes Detected
────────────────────────────────────────────
File: src/app.js

This file contains multiple types of changes:
- New feature: OAuth integration
- Bug fix: Memory leak fix
- Refactor: Code cleanup

RECOMMENDATION:
Use git add -p to stage changes interactively,
or manually split the file changes.

Cannot automatically split this file.

Case 2: Interdependent Changes

If changes must stay together:

NOTE: Interdependent Changes
────────────────────────────────────────────
These files must be committed together:
- src/auth/oauth.js (defines function)
- src/auth/index.js (exports function)

Keeping them in the same commit: Commit 1

Case 3: Very Large Number of Files

If 20+ files:

LARGE CHANGE SET DETECTED
────────────────────────────────────────────
You have 47 files changed.

This is a lot! Consider:

1. Splitting by module/feature first
2. Creating multiple PRs
3. Committing incrementally as you work

Would you like me to try splitting anyway? (y/n)

Error Handling

Not a git repository:

ERROR: Not a git repository
Run: git init

(Detected by /commit-error-handling diagnose-issues)

No changes to split:

NO CHANGES TO SPLIT

Your working tree is clean.
Make some changes first, then run /commit-split.

Commit creation failed:

ERROR: Failed to create commit

<git error message>

This may happen if:
- Git user.name or user.email not configured
- Repository is in conflicted state
- Pre-commit hooks failed

Fix the issue and try again.

Use /commit-error-handling diagnose-issues for detailed diagnostics.

Granular Control Options

Option 1: Use atomic-commit Skill Directly

The /commit-split command is a wrapper around /atomic-commit interactive.

For equivalent functionality with more control:

/atomic-commit interactive

Additional atomic-commit operations:

• /atomic-commit analyze - Just check if should split
• /atomic-commit group strategy:type - Just group files
• /atomic-commit suggest - Just get suggestions
• /atomic-commit sequence output:script - Generate bash script

Option 2: Generate Script and Execute

Generate an executable script:

/atomic-commit sequence output:script > split-commits.sh
chmod +x split-commits.sh
./split-commits.sh

This gives you a script you can review and modify before execution.

Option 3: Manual with Guidance

Get the plan without execution:

/commit-review  # Get analysis and recommendations
/atomic-commit suggest  # Get specific suggestions

Then manually:

git add file1 file2 file3
/commit "feat(auth): add OAuth"

git add file4 file5
/commit "test(auth): add tests"

Option 4: Analysis Only

Just understand your changes without committing:

/commit-review  # Full analysis
/commit-analysis analyze  # Just change analysis
/atomic-commit analyze  # Just atomicity check

Tips

Before Splitting:

• Run /commit-review first to see the splitting plan
• Ensure all changes are related to work you want to commit
• Consider using git stash for truly unrelated changes

During Splitting:

• Review each proposed message carefully
• Edit messages if the generated ones aren't perfect
• Skip groups if you want to commit them separately
• Don't worry about making mistakes - commits can be amended

After Splitting:

• Run tests to verify everything still works
• Review commits with git log -p
• Use git commit --amend if you need to fix the last commit
• Push all commits together or create a PR

Examples

Example 1: Feature Development

Files changed: 8
Groups: 3
- feat(payment): 5 files
- test(payment): 2 files
- docs: 1 file

Result: 3 clean atomic commits

Example 2: Bug Fix with Refactoring

Files changed: 4
Groups: 2
- fix(api): 2 files (the actual fix)
- refactor: 2 files (cleanup done while fixing)

Result: 2 separate commits (fix can be cherry-picked)

Example 3: Mixed Changes

Files changed: 15
Groups: 5
- feat(auth): 6 files
- feat(profile): 4 files
- fix(api): 2 files
- test: 2 files
- docs: 1 file

Result: 5 focused commits

Best Practices

1. Keep It Simple: Don't overthink grouping
2. Test Between Commits: Each commit should work
3. Review Messages: Generated messages are suggestions
4. Be Consistent: Follow your team's commit conventions
5. Document Why: Use commit body for complex changes
6. One Story Per Commit: Each commit tells one story

Related Skills and Commands

Core Skill: atomic-commit

The /commit-split command is powered by the atomic-commit skill:

Full Skill Access: /atomic-commit

• analyze - Determine if should split
• group - Group related files
• suggest - Generate commit breakdown
• sequence - Create execution plan
• interactive - Full guided workflow (what /commit-split uses)

Supporting Skills

Analysis:

• /commit-analysis - Change type/scope detection
• /commit-error-handling - Repository validation

Message Generation:

• /message-generation - Conventional commit messages
• /history-analysis - Project convention learning

Quality Assurance:

• /commit-best-practices - Validation and review

Related Commands

Analysis Phase:

• /commit-review - Analyze and get recommendations (no execution)

Execution Phase:

• /commit-split - Interactive splitting (this command)
• /commit - Single atomic commit

Complete Workflow

1. Analysis: /commit-review
   ↓ If split needed
2. Execution: /commit-split
   ↓ Creates N atomic commits
3. Verify: /commit-best-practices review-commit

Documentation

• Atomic Commits Guide: .claude/commands/commit-best-practices/workflow-tips.md
• Splitting Strategies: .claude/commands/atomic-commit/ skill documentation
• Skill Architecture: .claude/docs/SKILL_ARCHITECTURE.md
• Agent Reference: .claude/agents/commit-assistant.md