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 –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.
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 plan [flags]
Examples
gk ai compose split plan --branch feature/auth --base-branch main
gk ai compose split plan --model <model-id> --branch feature/auth --base-branch main
gk ai compose split plan --direction area --instructions "keep migrations with models"
gk ai compose split plan --json
Options
-h, --help help for plan
--model string AI model id for this invocation (does not change saved settings)
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
--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 split - Split a multi-commit branch into stacked branches