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 –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.
MODEL SELECTION
–model
Run “gk ai provider show” to inspect the active provider and configured model. For GitKraken-hosted AI, “gk ai models” lists available ids and marks the backend default with *. With the GitKraken provider, –model “” bypasses a saved global override once and uses the backend default.
plan, apply, split plan and split accept –model because they call AI. apply-plan and undo make no AI request and do not accept it. A later split re-runs AI, so repeat the same –model used for split plan when consistency matters.
gk ai compose split [flags]
Examples
gk ai compose split --branch feature/auth --base-branch main
gk ai compose split --model <model-id> --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
--model string AI model id for this invocation (does not change saved settings)
Options inherited from parent commands
--json Emit machine-readable JSON on stdout (GK_OUTPUT=json sets it session-wide)
--no-telemetry Disable telemetry (OTel spans, Sentry) for this invocation
--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