Commit Split

Commit Split

Commit split helps turn a broad staged change set into smaller, related commits.

Quick Start

# Stage your changes
git add .

# Generate a split plan (non-mutating)
coco commit split --plan -i

# Or use the shorthand
coco commit --split -i

# Review the plan, then apply it
coco commit split --apply -i

The -i flag (or "mode": "interactive" in your config) is required so the plan can be displayed for review. Without it, the plan is written to stdout which works for scripting but not for the typical interactive workflow.

Commands

coco commit split --plan
coco commit split --apply
coco commit --split          # shorthand for --plan

--plan is non-mutating. It reads staged changes, condenses the diffs using the existing diff parser, builds a staged hunk inventory for modified files, and asks the configured model to group files or hunks into proposed commits.

--apply starts from a generated plan and creates one commit per group. Whole-file groups stage the listed files. Hunk groups apply selected staged hunks directly to the index with git apply --cached, which allows separate commits from different parts of the same file.

Whole-file groups intentionally abort if a planned file also has unstaged or untracked changes, because staging the whole file would otherwise mix unrelated work into a generated commit. Hunk groups do not stage the whole file.

Requirements

Commit split requires a configured AI provider since it uses the model to analyze your staged changes and propose groupings. Make sure your .coco.config.json has a working service block:

{
  "mode": "interactive",
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "sk-..."
      }
    }
  }
}

Any provider works (OpenAI, Anthropic, Ollama). If you are using dynamic model routing, the split plan uses the commit task model.

Safety Rules

• Every staged file must appear exactly once in the plan.
• A file can be assigned either as a whole file or by all of its hunk IDs, but not both.
• If a file is split by hunks, every generated hunk for that file must be assigned exactly once.
• Plan files must match real staged files.
• Plan hunks must match real staged hunk IDs.
• Apply mode unstages the current index, stages one group at a time, applies selected hunks with git apply --cached, and uses the existing createCommit utility.
• Unstaged overlap blocks whole-file apply mode.

Hunk-Level Limits

Hunk-level apply is intentionally fail-closed. If a generated hunk patch cannot be applied cleanly after earlier split commits have changed the file, the command stops and leaves the remaining working tree changes available for manual review.

Troubleshooting

"No result handler provided for interactive mode"

This was a bug in versions before 0.35 where the split path did not properly wire up interactive output. Update to the latest version. If you still see it, make sure you are passing -i or have "mode": "interactive" in your config.

"No staged changes found"

Run git add . (or stage specific files) before running the split command.

Plan quality is poor

Try adding context with --additional:

coco commit split --plan -i --additional "This branch adds auth and updates tests"

Or use a stronger model for the commit task via dynamic model routing.