gk ai compose split
Split a multi-commit branch into stacked branches
Synopsis
Split a multi-commit branch 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.
Run “gk ai compose split plan” first when the user wants to review the proposed partitions. That preview is read-only, but it cannot be saved and replayed: the later split runs the AI analysis again, so its partitions may differ.
–branch defaults to the current branch; pass it explicitly when HEAD is detached. –base-branch defaults to main. The operation replaces the source branch with generated stack branches and may require a force-push afterwards. It costs AI tokens.
–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 is {partitions, undoId?}, where each partition
has a .branchName and the .commitIds assigned to it. Keep the undoId for
“gk ai compose undo
Use partitions[].branchName when checking the generated refs. A plan.branches[].branchGroup.name is the AI’s logical grouping label and may differ from the generated partition branch name.
When the analysis groups every commit into one partition there is nothing to split, so no branches are created and no undoId is returned. That is reported as “no branches created”, not as a failure; the branch is untouched.
gk ai compose split [flags]
Examples
gk ai compose split --branch feature/auth --base-branch main
gk ai compose split --direction area --instructions "keep migrations with models"
Options
--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")
-h, --help help for split
--instructions string Additional AI grouping guidance; appended to area/type, or used without a preset for auto/custom
Options inherited from parent commands
--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 - Plan and create clean, atomic commits from your working tree changes using AI
- gk ai compose split plan - Preview how a multi-commit branch would be split