gk ai compose split plan
Preview how a multi-commit branch would be split
Synopsis
Preview how a multi-commit branch would be split into a stack of smaller branches. It analyzes the existing commits in –base-branch..–branch; it does not include uncommitted working-tree changes. The range must contain at least two commits.
Read-only: this command does not create branches, move refs, change HEAD, or
modify the index or working tree. It costs AI tokens. To keep that true, it
refuses a –branch or –base-branch that exists only as origin/
This preview is advisory. There is no saved split-plan format and no command that applies this exact result. A later “gk ai compose split” re-runs the AI analysis, so its proposed partitions may differ from this preview.
–branch defaults to the current branch; pass it explicitly when HEAD is detached. –base-branch defaults to main.
–direction guides how existing commits are assigned to branches: auto lets the AI infer the grouping, area prefers subsystem boundaries, type prefers conventional commit types, and custom requires –instructions. With area or type, –instructions adds constraints after the preset. Direction does not change the commit range; –branch and –base-branch do that.
With –output json the result includes {plan, partitions, source}. Each partition has a .branchName and the .commitIds assigned to it. A preview has no undoId because there is nothing to undo. The same generated ref names live at plan.branches[].partitioning.partitions[].branchName; do not compare against the enclosing branchGroup.name, which is only the AI’s logical grouping label.
gk ai compose split plan [flags]
Examples
gk ai compose split plan --branch feature/auth --base-branch main
gk ai compose split plan --direction area --instructions "keep migrations with models"
gk ai compose split plan --output json
Options
-h, --help help for plan
Options inherited from parent commands
--base-branch string Base branch that starts the commit range to split (default: main)
--branch string Branch to split (default: current branch)
--direction string How AI groups work: auto (infer), area (subsystem), type (change type), custom (requires --instructions) (default "auto")
--instructions string Additional AI grouping guidance; appended to area/type, or used without a preset for auto/custom
--no-telemetry Disable telemetry (OTel spans, Sentry) for this invocation
--output string Output format: text or json (default "text")
--session string (Optional) Isolate auth and cache under a named session
--workdir string Path to the git repository to operate on (default: current directory)
SEE ALSO
- gk ai compose split - Split a multi-commit branch into stacked branches