gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/atomic-commit/group-files.md

Operation: Group Files

Group related files together for atomic commits.

Parameters from $ARGUMENTS

• strategy:type|scope|feature - Grouping strategy (default: type)
• show:all|summary - Output detail level (default: summary)

Workflow

Step 1: Get Changed Files

Invoke Bash to get file list:

git status --porcelain
git diff --cached --name-only
git diff --name-only

Capture complete list of changed files.

Step 2: Execute File Grouper

Run the file grouper script with selected strategy:

.claude/plugins/git-commit-assistant/commands/atomic-commit/.scripts/file-grouper.sh <strategy>

Step 3: Parse Grouping Results

Process grouper output based on strategy:

Strategy: type Groups files by commit type:

• feat: New features or enhancements
• fix: Bug fixes
• docs: Documentation changes
• style: Formatting, whitespace
• refactor: Code restructuring
• test: Test additions or changes
• chore: Build, dependencies, tooling

Strategy: scope Groups files by module/component:

• Extract scope from file path
• Group by common directory structure
• Identify module boundaries
• Example: auth/, api/, ui/, utils/

Strategy: feature Groups files by related functionality:

• Analyze dependencies between files
• Group interdependent changes
• Identify feature boundaries
• Requires dependency analysis

Step 4: Validate Groups

Check each group for atomicity:

• Single logical purpose
• Reasonable size (≤10 files per group)
• Clear scope boundary
• Independent from other groups

Step 5: Generate Output

Create structured grouping report:

Summary format:

📦 FILE GROUPS (strategy: type)

Group 1: feat (8 files)
  src/auth/oauth.ts
  src/auth/tokens.ts
  src/config/oauth.config.ts
  ...

Group 2: fix (3 files)
  src/api/endpoints.ts
  src/api/validation.ts
  tests/api.test.ts

Group 3: docs (2 files)
  README.md
  docs/authentication.md

Total: 3 groups, 13 files

Detailed format (show:all):

📦 GROUP 1: feat (8 files)

Files:
  ✓ src/auth/oauth.ts (+145, -0)
  ✓ src/auth/tokens.ts (+78, -0)
  ✓ src/auth/providers/github.ts (+95, -0)
  ✓ src/auth/providers/google.ts (+92, -0)
  ✓ src/config/oauth.config.ts (+34, -0)
  ✓ src/types/auth.types.ts (+56, -0)
  ✓ tests/auth/oauth.test.ts (+123, -0)
  ✓ tests/auth/tokens.test.ts (+67, -0)

Scope: auth
Purpose: OAuth 2.0 implementation
Dependencies: None
Atomic: ✅ Yes

Suggested commit:
  feat(auth): implement OAuth 2.0 authentication

Output Format

Return structured groupings:

strategy: type|scope|feature
groups:
  - id: 1
    type: feat|fix|docs|etc
    scope: module_name
    files: [list]
    stats:
      file_count: number
      additions: number
      deletions: number
    atomic: true|false
    suggested_message: "commit message"
summary:
  total_groups: number
  total_files: number
  ready_for_commit: true|false

Error Handling

• No changes: "No files to group. Make changes first."
• Invalid strategy: "Invalid strategy. Use: type, scope, or feature"
• Grouping failed: "Could not group files. Check git status."
• Too many groups: "Warning: 10+ groups detected. Consider broader grouping."

Grouping Strategies Explained

Type-based Grouping

Groups files by conventional commit type. Best for:

• Mixed-type changes
• Clear type boundaries
• Standard workflow

Algorithm:

1. Analyze diff content for each file
2. Detect commit type from changes
3. Group files of same type
4. Validate each group

Scope-based Grouping

Groups files by module/component. Best for:

• Changes across multiple modules
• Modular codebase structure
• Component isolation

Algorithm:

1. Extract directory structure
2. Identify module boundaries
3. Group files by module
4. Validate scope coherence

Feature-based Grouping

Groups files by related functionality. Best for:

• Complex feature implementation
• Interdependent changes
• Logical feature units

Algorithm:

1. Analyze file dependencies
2. Build dependency graph
3. Group connected components
4. Validate feature boundaries

Examples

Example 1: Type grouping

/atomic-commit group strategy:type
→ Groups: feat (5), fix (2), docs (1)

Example 2: Scope grouping

/atomic-commit group strategy:scope show:all
→ Detailed groups by module

Example 3: Feature grouping

/atomic-commit group strategy:feature
→ Groups by related functionality

Integration Notes

This operation is typically called:

1. After analyze-splitting recommends splitting
2. Before suggest-commits generates messages
3. As part of interactive-split workflow

Results feed into commit suggestion and sequence planning.