Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! `wt step squash` — squash commits into one (also used by `wt merge --squash`).
use anyhow::Context;
use color_print::cformat;
use worktrunk::HookType;
use worktrunk::config::UserConfig;
use worktrunk::git::WorkingTree;
use worktrunk::styling::{
eprintln, format_with_gutter, info_message, println, progress_message, success_message,
};
use super::super::command_approval::{
approve_commit_template_append, approve_or_skip, resolve_template_for_preview,
};
use super::super::command_executor::FailureStrategy;
use super::super::commit::{CommitGenerator, CommitOutcome, HookGate, StageMode};
use super::super::context::CommandEnv;
use super::super::hooks::{HookAnnouncer, execute_hook};
use super::super::repository_ext::auto_stage;
use super::super::template_vars::TemplateVars;
use super::shared::print_dry_run;
/// Caller's stance on project commit-message guidance approval.
///
/// `wt step squash` runs its own gate (the user invokes squash directly, so
/// there's no upstream decision to attach to). `wt merge` resolves the append
/// through its own `approve_commit_template_append` gate up front and passes
/// the result here so `handle_squash` doesn't gate it a second time.
#[derive(Debug, Clone)]
pub enum PreApprovedGuidance {
/// No pre-approval — `handle_squash` runs its own gate via
/// `approve_commit_template_append` (only if the LLM is configured).
RunOwnGate,
/// Caller already resolved the guidance through an upstream batch.
/// `None` means "guidance not configured or user declined".
Resolved(Option<String>),
}
/// Result of a squash operation
#[derive(Debug, Clone, serde::Serialize)]
#[serde(tag = "outcome", rename_all = "snake_case")]
pub enum SquashResult {
/// Squash or commit occurred. Carries the resulting commit's SHA, message,
/// and resolved stage mode so callers can render structured output.
Squashed {
#[serde(rename = "commit")]
sha: String,
message: String,
stage_mode: StageMode,
},
/// Nothing to squash: no commits ahead of target branch
NoCommitsAhead { target: String },
/// Nothing to squash: already a single commit
AlreadySingleCommit,
/// Squash attempted but resulted in no net changes (commits canceled out)
NoNetChanges,
}
/// Handle shared squash workflow (used by `wt step squash` and `wt merge`)
///
/// # Arguments
/// * `hooks` - Whether to run pre-commit hooks. `Run` triggers an internal approval
/// prompt; `NoHooksFlag` skips with a "(--no-hooks)" message; `Silent` skips silently
/// (used when the caller already declined approval upstream and announced it).
/// * `stage` - CLI-provided stage mode. If None, uses the effective config default.
/// * `announcer` - Post-commit hooks register on the caller's announcer; the
/// caller decides when to flush. Multi-phase callers (`wt merge --squash`
/// combining post-commit + post-remove + post-switch + post-merge) share
/// one announce line; standalone callers (`wt step squash`) construct an
/// announcer of their own and flush right after.
pub fn handle_squash(
target: Option<&str>,
yes: bool,
hooks: HookGate,
stage: Option<StageMode>,
announcer: &mut HookAnnouncer<'_>,
pre_approved_guidance: PreApprovedGuidance,
) -> crate::output::CommandResult<SquashResult> {
// Load config once, run LLM setup prompt, then reuse config
let mut config = UserConfig::load().context("Failed to load config")?;
// One-time LLM setup prompt (errors logged internally; don't block commit)
let _ = crate::output::prompt_commit_generation(&mut config);
let env = CommandEnv::for_selector(config, "@")?;
handle_squash_in(
&env,
target,
yes,
hooks,
stage,
announcer,
pre_approved_guidance,
)
}
/// Run the squash in the caller's already-selected environment. Reusing it
/// keeps the source worktree and the approved project-config cache consistent.
pub fn handle_squash_in(
env: &CommandEnv,
target: Option<&str>,
yes: bool,
hooks: HookGate,
stage: Option<StageMode>,
announcer: &mut HookAnnouncer<'_>,
pre_approved_guidance: PreApprovedGuidance,
) -> crate::output::CommandResult<SquashResult> {
let repo = &env.repo;
// Rewriting history under a half-finished operation is never what the user
// meant, and mid-rebase HEAD is detached — so this runs ahead of the branch
// check, which would otherwise blame the detached HEAD and point at
// `git switch`, the one command that throws the operation away.
repo.ensure_no_operation_in_progress("squash")?;
// Squash auto-stages, and `git add -A` would resolve an unmerged path to
// whatever is on disk — conflict markers included. `wt.stage` gates that
// directly; refusing here too keeps the approval prompt below from asking
// about hooks for a squash that cannot happen.
let wt = repo.worktree_at(&env.worktree_path);
wt.ensure_no_unmerged_paths("squash")?;
// Squash requires being on a branch (can't squash in detached HEAD)
let current_branch = env.require_branch("squash")?.to_string();
let ctx = env.context(yes);
let resolved = env.resolved();
// Defer project-guidance approval until we know an LLM call will happen
// (after the NoCommitsAhead / AlreadySingleCommit early-exits). When the
// caller pre-approved via an upstream batch (e.g. `wt merge`), use that
// value directly to avoid a second prompt mid-flow.
let llm_configured = resolved.commit_generation.is_configured();
let approve_guidance = || -> anyhow::Result<Option<String>> {
match &pre_approved_guidance {
PreApprovedGuidance::Resolved(value) => Ok(value.clone()),
PreApprovedGuidance::RunOwnGate if llm_configured => {
approve_commit_template_append(&ctx)
}
PreApprovedGuidance::RunOwnGate => Ok(None),
}
};
// CLI flag overrides config value
let stage_mode = stage.unwrap_or(resolved.commit.stage());
// Check if any pre-commit hooks exist (needed for skip message and approval)
let project_config = repo.load_project_config()?;
let user_hooks = ctx.config.hooks(ctx.project_id().as_ref());
let any_hooks_exist = user_hooks.get(HookType::PreCommit).is_some()
|| project_config
.as_ref()
.is_some_and(|c| c.hooks.get(HookType::PreCommit).is_some());
// Resolve the hook gate: Run triggers an approval prompt and downgrades to Silent
// on decline (approve_or_skip prints its own message). NoHooksFlag prints the skip
// message itself; Silent stays quiet so the upstream caller's decline message isn't
// followed by a spurious "(--no-hooks)" line.
let hooks = match hooks {
HookGate::Run => {
if approve_or_skip(
&ctx,
&[HookType::PreCommit, HookType::PostCommit],
"Commands declined, squashing without hooks",
)? {
HookGate::Run
} else {
HookGate::Silent
}
}
HookGate::NoHooksFlag => {
if any_hooks_exist {
eprintln!("{}", info_message("Skipping pre-commit hooks (--no-hooks)"));
}
HookGate::NoHooksFlag
}
HookGate::Silent => HookGate::Silent,
};
// Get and validate target ref (any commit-ish for merge-base calculation)
let integration_target = repo.require_target_ref(target)?;
// #3519: when the branch's history extends past the local target into the
// target's upstream, measure the squash against the upstream — so commits
// already published there are never folded into the squash commit.
let span_target = repo
.span_upstream(&integration_target)?
.unwrap_or_else(|| integration_target.clone());
let template_vars = TemplateVars::new().with_target(&integration_target);
// Stage on both sides of the pre-commit hooks (user first, then project);
// `auto_stage` says why.
auto_stage(&wt, stage_mode)?;
if hooks.run()
&& execute_hook(
&ctx,
HookType::PreCommit,
&template_vars.as_extra_vars(),
FailureStrategy::FailFast,
)?
{
auto_stage(&wt, stage_mode)?;
}
// Resolve HEAD once, so the span, the message's commit list, and the
// compare-and-swap that finally moves the branch all describe one tip.
let head_sha = wt.run_command(&["rev-parse", "HEAD"])?.trim().to_string();
// Get merge base with target branch (required for squash)
let merge_base = repo
.merge_base(&head_sha, &span_target)?
.context("Cannot squash: no common ancestor with target branch")?;
// Count commits since merge base
let commit_count = repo.count_commits(&merge_base, &head_sha)?;
// Check if there are staged changes in addition to commits
let has_staged = wt.has_staged_changes()?;
// Handle different scenarios
if commit_count == 0 && !has_staged {
// No commits and no staged changes - nothing to squash
return Ok(SquashResult::NoCommitsAhead {
target: span_target,
});
}
if commit_count == 1 && !has_staged {
// Single commit, no staged changes - already squashed
return Ok(SquashResult::AlreadySingleCommit);
}
// From here on, an LLM call may happen — gate the project append.
let project_append = approve_guidance()?;
let generator = CommitGenerator::new(&resolved.commit_generation, project_append.as_deref());
if commit_count == 0 && has_staged {
// Just staged changes, no commits - commit them directly (no squashing needed)
let CommitOutcome {
sha,
message,
stage_mode,
} = generator
.commit_staged_changes(&wt, true, true, stage_mode)
.map_err(|failure| {
failure.map_result(|outcome| SquashResult::Squashed {
sha: outcome.sha,
message: outcome.message,
stage_mode: outcome.stage_mode,
})
})?;
return Ok(SquashResult::Squashed {
sha,
message,
stage_mode,
});
}
// Either multiple commits OR single commit with staged changes - squash them
// Get diff stats early for display in progress message
let range = format!("{merge_base}..{head_sha}");
let commit_text = if commit_count == 1 {
"commit"
} else {
"commits"
};
// Get total stats (commits + any working tree changes)
let total_stats = if has_staged {
wt.prepare_staged_diff(&merge_base).stats_summary()
} else {
wt.prepare_commit_diff(&merge_base, &head_sha)
.stats_summary()
};
let with_changes = if has_staged {
match stage_mode {
StageMode::Tracked => " & tracked changes",
_ => " & working tree changes",
}
} else {
""
};
// Build parenthesized content: stats only (stage mode is in message text)
let parts = total_stats;
let squash_progress = if parts.is_empty() {
format!("Squashing {commit_count} {commit_text}{with_changes} into a single commit...")
} else {
// Gray parenthetical with separate cformat for closing paren (avoids optimizer)
let parts_str = parts.join(", ");
let paren_close = cformat!("<bright-black>)</>");
cformat!(
"Squashing {commit_count} {commit_text}{with_changes} into a single commit <bright-black>({parts_str}</>{paren_close}..."
)
};
eprintln!("{}", progress_message(squash_progress));
// Back up working-tree changes before the squash commit absorbs them
if has_staged {
let backup_message = format!("{} → {} (squash)", current_branch, span_target);
let backup = wt.create_safety_backup(&backup_message)?;
backup.print_recovery_hints(repo)?;
}
// Get commit subjects and bodies for the squash message
let commit_details = repo.commit_message_details(&range)?;
// Generate squash commit message
eprintln!(
"{}",
progress_message("Generating squash commit message...")
);
generator.emit_hint_if_needed();
// Get current branch and repo name for template variables
let repo_root = wt.root()?;
let repo_name = repo_root
.file_name()
.and_then(|n| n.to_str())
.unwrap_or("repo");
let commit_message = crate::llm::SquashInputs {
worktree: &wt,
target_branch: &span_target,
merge_base: &merge_base,
commit_details: &commit_details,
current_branch: ¤t_branch,
repo_name,
config: &resolved.commit_generation,
project_append: project_append.as_deref(),
// `wt.stage` above already put everything in the real index.
staging_index: None,
}
.generate_message()?;
// Display the generated commit message
let formatted_message = generator.format_message_for_display(&commit_message);
eprintln!("{}", format_with_gutter(&formatted_message, None));
// Squash the way `git rebase` rewrites history: detach HEAD onto the merge
// base, commit there, and move the branch to the result. The branch keeps
// its commits until the commit exists, so a commit that fails — a
// `pre-commit` hook rejecting it, a broken signing setup — leaves the
// branch and its history where they were. Committing through `git commit`
// rather than plumbing is what keeps git's own hooks, `commit.cleanup`,
// signing, and identity resolution behaving as they do for any other
// commit; those hooks see a detached HEAD, as they do under `git rebase`.
let tree = wt.run_command(&["write-tree"])?.trim().to_string();
let base_tree = repo
.run_command(&["rev-parse", &format!("{merge_base}^{{tree}}")])?
.trim()
.to_string();
// One compare-and-swap moves the branch, refusing if it moved since
// `head_sha` was read; ORIG_HEAD then keeps the pre-squash tip, as `git
// reset` and `git rebase` leave it. That write is best-effort, exactly as
// `git reset` makes it: the branch has already moved by then, so failing
// over ORIG_HEAD would report a squash that landed as an error.
let branch_ref = format!("refs/heads/{current_branch}");
let move_branch = |new_sha: &str, reflog_message: &str| -> anyhow::Result<()> {
wt.run_command(&[
"update-ref",
"-m",
reflog_message,
&branch_ref,
new_sha,
&head_sha,
])
.with_context(|| cformat!("Failed to update <bold>{current_branch}</>"))?;
let _ = wt.run_command(&["update-ref", "ORIG_HEAD", &head_sha]);
Ok(())
};
if tree == base_tree {
// The commits cancel out, so the squash produces no commit and the
// branch moves to the merge base, where `wt merge` finds nothing left
// to integrate.
move_branch(&merge_base, "wt squash: no net changes")?;
eprintln!(
"{}",
info_message(format!(
"No changes after squashing {commit_count} {commit_text}"
))
);
return Ok(SquashResult::NoNetChanges);
}
// `--no-deref` moves HEAD itself, leaving the branch, the index and the
// working tree untouched; the compare-and-swap refuses if the branch moved
// while the message was being generated.
//
// TOCTOU note: `write-tree` above snapshots the index, and the commit below
// re-reads it, so an external process staging into this worktree in between
// lands in the squash commit. Precise timing, and the consequence is minor
// — unexpected content in a commit whose diff the user is about to see, and
// whose message still describes the commits being folded in.
wt.run_command(&[
"update-ref",
"--no-deref",
"-m",
"wt squash: detach to build the squash commit",
"HEAD",
&merge_base,
&head_sha,
])
.context("Failed to detach HEAD onto the merge base")?;
let commit_sha = match wt
.run_command(&["commit", "-m", &commit_message])
.context("Failed to create squash commit")
.and_then(|_| wt.run_command(&["rev-parse", "HEAD"]))
{
Ok(sha) => sha.trim().to_string(),
Err(err) => return Err(reattach_after_failure(&wt, &branch_ref, err).into()),
};
let subject = commit_message.lines().next().unwrap_or_default();
if let Err(err) = move_branch(&commit_sha, &format!("wt squash: {subject}")) {
return Err(reattach_after_failure(&wt, &branch_ref, err).into());
}
let result = SquashResult::Squashed {
sha: commit_sha.clone(),
message: commit_message,
stage_mode,
};
let completion = (|| -> anyhow::Result<()> {
reattach_head(&wt, &branch_ref)?;
let commit_hash = repo.short_sha(&commit_sha)?;
eprintln!(
"{}",
success_message(cformat!("Squashed @ <dim>{commit_hash}</>"))
);
if hooks.run() {
let extra_vars = template_vars.as_extra_vars();
announcer.register(&ctx, HookType::PostCommit, &extra_vars, None)?;
}
Ok(())
})();
match completion {
Ok(()) => Ok(result),
Err(error) => Err(crate::output::CommandFailure::with_result(error, result)),
}
}
/// Put HEAD back on the branch it was detached from for the squash commit.
fn reattach_head(wt: &WorkingTree<'_>, branch_ref: &str) -> anyhow::Result<()> {
wt.run_command(&["symbolic-ref", "HEAD", branch_ref])
.with_context(|| {
cformat!(
"HEAD is left detached; to put it back, run <bold>git symbolic-ref HEAD {branch_ref}</>"
)
})?;
Ok(())
}
/// Reattach HEAD after a failure that struck while it was detached, and return
/// the failure that got us here.
///
/// The branch never moved, so a successful reattach restores the worktree
/// exactly as it was and leaves nothing to report beyond `err`.
fn reattach_after_failure(
wt: &WorkingTree<'_>,
branch_ref: &str,
err: anyhow::Error,
) -> anyhow::Error {
match reattach_head(wt, branch_ref) {
Ok(()) => err,
Err(reattach_err) => err.context(format!("{reattach_err:#}")),
}
}
/// Handle `wt step squash --show-prompt`
///
/// Builds and outputs the squash prompt without running the LLM or squashing.
pub fn step_show_squash_prompt(
target: Option<&str>,
stage: Option<StageMode>,
) -> anyhow::Result<()> {
// `--show-prompt` never invokes the LLM, so the `yes` flag is irrelevant
// — pass false; the guidance gate inside `preview_squash` is dry-run only.
preview_squash(target, stage, false, false)
}
/// Handle `wt step squash --dry-run`
///
/// Renders the squash prompt, prints the LLM command, generates the message, and prints
/// it without staging, running hooks, or squashing.
pub fn step_dry_run_squash(
target: Option<&str>,
stage: Option<StageMode>,
yes: bool,
) -> anyhow::Result<()> {
preview_squash(target, stage, true, yes)
}
/// Shared implementation for `--show-prompt` and `--dry-run` on squash. `--show-prompt`
/// (`dry_run = false`) outputs only the rendered prompt; `--dry-run` additionally calls
/// the LLM and prints the command and the generated message.
fn preview_squash(
target: Option<&str>,
stage: Option<StageMode>,
dry_run: bool,
yes: bool,
) -> anyhow::Result<()> {
let env = CommandEnv::for_selector(UserConfig::load().context("Failed to load config")?, "@")?;
let repo = &env.repo;
let commit_config = env.config.commit_generation(env.project_id().as_ref());
let integration_target = repo.require_target_ref(target)?;
// #3519: preview against the same upstream-aware span the real squash uses.
// TODO(#3519 follow-up): unlike `handle_squash`, this path (--dry-run /
// --show-prompt) has no test asserting it measures against the stale
// target's upstream — a snapshot test pinning the preview output in that
// topology would close the one unasserted consumer of `span_upstream`.
let span_target = repo
.span_upstream(&integration_target)?
.unwrap_or(integration_target);
let wt = repo.current_worktree();
let current_branch = wt.branch()?.unwrap_or_else(|| "HEAD".to_string());
let merge_base = repo
.merge_base("HEAD", &span_target)?
.context("Cannot generate squash message: no common ancestor with target branch")?;
let range = format!("{}..HEAD", merge_base);
let commit_details = repo.commit_message_details(&range)?;
let repo_root = wt.root()?;
let repo_name = repo_root
.file_name()
.and_then(|n| n.to_str())
.unwrap_or("repo");
let ctx = env.context(yes);
let project_append = resolve_template_for_preview(&ctx, &commit_config, dry_run)?;
// `--dry-run` stages into a copy of the index so the previewed prompt spans
// what a real squash would commit: `handle_squash` stages before generating
// the message, and the prompt's diff is read from the index. `--show-prompt`
// skips it, the cheap "what's already staged" path — the same split
// `preview_commit` makes for `wt step commit`.
let stage_mode = stage.unwrap_or(env.resolved().commit.stage());
let temp_index = if dry_run && stage_mode != StageMode::None {
let temp = wt.temp_index()?;
temp.stage(stage_mode)?;
Some(temp)
} else {
None
};
let staging_index = temp_index.as_ref();
let inputs = crate::llm::SquashInputs {
worktree: &wt,
target_branch: &span_target,
merge_base: &merge_base,
commit_details: &commit_details,
current_branch: ¤t_branch,
repo_name,
config: &commit_config,
project_append: project_append.as_deref(),
staging_index,
};
let prompt = inputs.prompt()?;
if !dry_run {
println!("{}", prompt);
return Ok(());
}
let message = inputs.generate_message()?;
print_dry_run(&prompt, &commit_config, &message)
}