Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

22.8 KB
Raw Blame
//! `wt step promote` — swap a branch into the main worktree.

use std::fs;
use std::io::ErrorKind;
use std::path::{Path, PathBuf};

use anyhow::{Context, bail};
use color_print::cformat;
use worktrunk::copy::{copy_dir_recursive, copy_leaf};
use worktrunk::git::{Repository, duplicated_branches};
use worktrunk::path::format_path_for_display;
use worktrunk::progress::Progress;
use worktrunk::styling::{eprintln, hint_message, info_message, success_message, warning_message};

use super::shared::list_and_filter_ignored_entries;

/// Move a file or directory, falling back to copy+delete on cross-device errors.
fn move_entry(src: &Path, dest: &Path, is_dir: bool) -> anyhow::Result<()> {
    // Ensure parent directory exists
    if let Some(parent) = dest.parent() {
        fs::create_dir_all(parent).with_context(|| {
            format!(
                "creating parent directory for {}",
                format_path_for_display(dest)
            )
        })?;
    }

    match fs::rename(src, dest) {
        Ok(()) => Ok(()),
        Err(e) if e.kind() == ErrorKind::CrossesDevices => copy_and_remove(src, dest, is_dir),
        Err(e) => Err(anyhow::Error::from(e).context(format!(
            "moving {} to {}",
            format_path_for_display(src),
            format_path_for_display(dest)
        ))),
    }
}

/// Copy then delete — fallback when `rename` fails with EXDEV (cross-device).
///
/// Refuses to delete when the copy reports a skip, since the source still holds
/// content the destination never received. A socket or FIFO is not a skip and
/// goes with the rest of the source: it carries no content to lose, and
/// refusing over one would abort a promote after the branch exchange.
fn copy_and_remove(src: &Path, dest: &Path, is_dir: bool) -> anyhow::Result<()> {
    let skipped = if is_dir {
        copy_dir_recursive(src, dest, None, true, &Progress::disabled())?
    } else {
        usize::from(copy_leaf(src, dest, None, true)?.is_none())
    };
    if skipped > 0 {
        bail!(
            "{} was not fully copied; refusing to remove the source; run with -vv to list what was skipped",
            format_path_for_display(src)
        );
    }

    if is_dir {
        fs::remove_dir_all(src).with_context(|| {
            format!("removing source directory {}", format_path_for_display(src))
        })?;
    } else {
        fs::remove_file(src)
            .with_context(|| format!("removing source file {}", format_path_for_display(src)))?;
    }
    Ok(())
}

const PROMOTE_STAGING_DIR: &str = "staging/promote";

/// Move gitignored files from both worktrees into a staging directory.
///
/// Called BEFORE the branch exchange because `git switch` silently overwrites
/// ignored files that collide with tracked files on the target branch.
///
/// Returns the staging directory path and the count of entries staged.
fn stage_ignored(
    repo: &Repository,
    path_a: &Path,
    entries_a: &[(PathBuf, bool)],
    path_b: &Path,
    entries_b: &[(PathBuf, bool)],
) -> anyhow::Result<(PathBuf, usize)> {
    let staging_dir = repo.wt_dir().join(PROMOTE_STAGING_DIR);
    fs::create_dir_all(&staging_dir).context("creating promote staging directory")?;

    let staging_a = staging_dir.join("a");
    let staging_b = staging_dir.join("b");
    let mut count = 0;

    // Move A's entries → staging/a
    for (src_entry, is_dir) in entries_a {
        let relative = src_entry
            .strip_prefix(path_a)
            .context("entry not under worktree A")?;
        let staging_entry = staging_a.join(relative);
        if fs::symlink_metadata(src_entry).is_ok() {
            move_entry(src_entry, &staging_entry, *is_dir)
                .with_context(|| format!("staging {}", format_path_for_display(relative)))?;
            count += 1;
        }
    }

    // Move B's entries → staging/b
    for (src_entry, is_dir) in entries_b {
        let relative = src_entry
            .strip_prefix(path_b)
            .context("entry not under worktree B")?;
        let staging_entry = staging_b.join(relative);
        if fs::symlink_metadata(src_entry).is_ok() {
            move_entry(src_entry, &staging_entry, *is_dir)
                .with_context(|| format!("staging {}", format_path_for_display(relative)))?;
            count += 1;
        }
    }

    // Clean up empty staging directory (can happen if all entries vanished
    // between listing and staging due to TOCTOU)
    if count == 0 && staging_dir.exists() {
        let _ = fs::remove_dir_all(&staging_dir);
    }

    Ok((staging_dir, count))
}

/// Distribute staged files to their new worktrees after a branch exchange.
///
/// B's original files (in staging/b) go to worktree A (which now has B's branch).
/// A's original files (in staging/a) go to worktree B (which now has A's branch).
fn distribute_staged(
    staging_dir: &Path,
    path_a: &Path,
    entries_a: &[(PathBuf, bool)],
    path_b: &Path,
    entries_b: &[(PathBuf, bool)],
) -> anyhow::Result<usize> {
    let staging_a = staging_dir.join("a");
    let staging_b = staging_dir.join("b");
    let mut count = 0;

    // Move B's staged entries → A (A now has B's branch)
    for (src_entry, is_dir) in entries_b {
        let relative = src_entry
            .strip_prefix(path_b)
            .context("entry not under worktree B")?;
        let staging_entry = staging_b.join(relative);
        let dest_entry = path_a.join(relative);
        if fs::symlink_metadata(&staging_entry).is_ok() {
            move_entry(&staging_entry, &dest_entry, *is_dir)
                .with_context(|| format!("distributing {}", format_path_for_display(relative)))?;
            count += 1;
        }
    }

    // Move A's staged entries → B (B now has A's branch)
    for (src_entry, is_dir) in entries_a {
        let relative = src_entry
            .strip_prefix(path_a)
            .context("entry not under worktree A")?;
        let staging_entry = staging_a.join(relative);
        let dest_entry = path_b.join(relative);
        if fs::symlink_metadata(&staging_entry).is_ok() {
            move_entry(&staging_entry, &dest_entry, *is_dir)
                .with_context(|| format!("distributing {}", format_path_for_display(relative)))?;
            count += 1;
        }
    }

    // Clean up staging directory (best-effort — files are already distributed)
    let _ = fs::remove_dir_all(staging_dir);

    Ok(count)
}

/// Result of a promote operation
pub enum PromoteResult {
    /// Branch was promoted successfully.
    ///
    /// `mismatch` is `true` when the promote did not restore canonical state
    /// (i.e. the target branch is not the default branch). Consumers can use
    /// this to detect that the safety warning was printed.
    Promoted {
        target: String,
        main_branch: String,
        swapped: usize,
        mismatch: bool,
    },
    /// Already in canonical state (requested branch is already in main)
    AlreadyInMain(String),
}

/// Resolve the worktree to promote, and its branch.
///
/// An explicit argument goes through the worktree selector, so it can name the
/// branch or its worktree's path. With no argument: from the main worktree,
/// restore the default branch (`^`); from a linked worktree, promote the
/// current one (`@`).
fn resolve_target(branch: Option<&str>, repo: &Repository) -> anyhow::Result<(PathBuf, String)> {
    use worktrunk::git::GitError;

    let selector = match branch {
        Some(b) => b,
        None if repo.current_worktree().is_linked()? => "@",
        None => "^",
    };
    let (path, branch) = repo.require_worktree(selector)?;
    // Promoting swaps two branches between worktrees, so a detached worktree
    // has nothing to swap in.
    let branch = branch.ok_or_else(|| GitError::DetachedHead {
        action: Some("promote".into()),
        worktree: Some(path.clone()),
    })?;
    Ok((path, branch))
}

/// Bail if a leftover staging dir exists from a previous interrupted promote —
/// it may contain the user's only copy of files from the failed swap.
/// Checked BEFORE `ensure_clean` so users see the recovery path first.
fn check_leftover_staging(staging_path: &Path) -> anyhow::Result<()> {
    if !staging_path.exists() {
        return Ok(());
    }
    let display = format_path_for_display(staging_path);
    Err(anyhow::anyhow!(
        "Files may need manual recovery from: {display}\n\
         Remove it to retry: rm -rf {display}"
    )
    .context("Found leftover staging directory from an interrupted promote"))
}

/// Print the user-facing announcement for the promote operation: either a
/// "restoring main worktree" info line or a mismatch warning plus a hint
/// for restoring canonical locations.
fn print_promote_announcement(is_restoring: bool, default_branch: Option<&str>) {
    if is_restoring {
        // Restoring default branch to main worktree - no warning needed
        eprintln!("{}", info_message("Restoring main worktree"));
        return;
    }

    // Creating mismatch - show warning and how to restore
    eprintln!(
        "{}",
        warning_message("Promoting creates mismatched worktree state (shown as ⚐ in wt list)",)
    );
    // Only show restore hint if we know the default branch
    if let Some(default) = default_branch {
        eprintln!(
            "{}",
            hint_message(cformat!(
                "To restore canonical locations, run <underline>wt step promote {default}</>"
            ))
        );
    }
}

/// Exchange branches between two worktrees.
///
/// Steps: detach target → detach main → switch main → switch target.
/// Both worktrees must be clean (verified by caller). Failure here is
/// near-impossible given the preconditions (`ensure_clean` passed, branches
/// exist, detach released locks); if it does happen, the caller surfaces the
/// error and the worktrees may be left in a detached state for the user to
/// resolve manually.
fn exchange_branches(
    main_wt: &worktrunk::git::WorkingTree<'_>,
    main_branch: &str,
    target_wt: &worktrunk::git::WorkingTree<'_>,
    target_branch: &str,
) -> anyhow::Result<()> {
    let steps: &[(&worktrunk::git::WorkingTree<'_>, &[&str], &str)] = &[
        (target_wt, &["switch", "--detach"], "detach target"),
        (main_wt, &["switch", "--detach"], "detach main"),
        (
            main_wt,
            &["switch", "--end-of-options", target_branch],
            "switch main",
        ),
        (
            target_wt,
            &["switch", "--end-of-options", main_branch],
            "switch target",
        ),
    ];

    for (wt, args, label) in steps {
        wt.run_command(args)
            .with_context(|| format!("branch exchange failed at: {label}"))?;
    }

    Ok(())
}

/// Handle `wt step promote` command
///
/// Promotes a branch to the main worktree, exchanging it with whatever branch is currently there.
///
/// ## Interruption recovery
///
/// The swap uses a staging directory at `.git/wt/staging/promote/` and proceeds
/// in three phases:
///
/// 1. **Stage**: move ignored files from both worktrees into staging (`a/`, `b/`)
/// 2. **Exchange**: detach + `git switch` to swap branches
/// 3. **Distribute**: move staged files to their new worktrees, then delete staging
///
/// A hard kill at any phase leaves files in staging, never deleted. The next run
/// detects the leftover directory and bails with a recovery path. A kill during
/// `git switch` may leave a worktree detached (fix: `git switch <branch>`).
pub fn handle_promote(branch: Option<&str>) -> anyhow::Result<PromoteResult> {
    use worktrunk::git::GitError;

    let repo = Repository::current()?;
    let worktrees = repo.list_worktrees()?;

    if worktrees.is_empty() {
        anyhow::bail!("No worktrees found");
    }

    // For normal repos, worktrees[0] is the main worktree
    // For bare repos, there's no main worktree - we don't support promote there
    if repo.is_bare()? {
        anyhow::bail!("wt step promote is not supported in bare repositories");
    }

    let main_wt = &worktrees[0];
    let main_path = &main_wt.path;
    let main_branch = main_wt
        .branch
        .clone()
        .ok_or_else(|| GitError::DetachedHead {
            action: Some("promote".into()),
            worktree: Some(main_path.clone()),
        })?;

    let (target_path, target_branch) = resolve_target(branch, &repo)?;

    // Check if target is already in main worktree
    if target_branch == main_branch {
        return Ok(PromoteResult::AlreadyInMain(target_branch));
    }

    // The exchange checks each branch out in the other worktree, which git
    // refuses while a third worktree holds it — and by then both worktrees are
    // detached. Worktrunk never creates such a duplicate, but `git worktree
    // add --force` can.
    let duplicated = duplicated_branches(worktrees);
    for branch in [&main_branch, &target_branch] {
        if duplicated.contains(branch.as_str()) {
            let paths: Vec<_> = worktrees
                .iter()
                .filter(|wt| wt.branch.as_ref() == Some(branch))
                .map(|wt| format_path_for_display(&wt.path).to_string())
                .collect();
            return Err(anyhow::anyhow!(paths.join("\n")).context(cformat!(
                "Cannot promote: <bold>{branch}</> is checked out in {} worktrees",
                paths.len()
            )));
        }
    }

    // Bail early if a leftover staging dir exists from a previous interrupted promote —
    // checked before `ensure_clean` so users see the recovery path first.
    let staging_path = repo.wt_dir().join(PROMOTE_STAGING_DIR);
    check_leftover_staging(&staging_path)?;

    // Ensure both worktrees are clean
    let main_working_tree = repo.worktree_at(main_path);
    let target_working_tree = repo.worktree_at(&target_path);

    main_working_tree.ensure_clean("promote", Some(&main_branch), false)?;
    target_working_tree.ensure_clean("promote", Some(&target_branch), false)?;

    // Check if we're restoring canonical state (promoting default branch back to main worktree)
    // Only lookup default_branch if needed for messaging (already resolved if no-arg from main)
    let default_branch = repo.default_branch();
    let is_restoring = default_branch.as_ref() == Some(&target_branch);
    print_promote_announcement(is_restoring, default_branch.as_deref());

    // Discover gitignored entries BEFORE branch exchange — .gitignore rules belong
    // to the current branch and will change after `git switch`.
    let worktree_paths: Vec<PathBuf> = worktrees.iter().map(|wt| wt.path.clone()).collect();
    let no_excludes: &[String] = &[];
    let main_entries =
        list_and_filter_ignored_entries(main_path, &main_branch, &worktree_paths, no_excludes)?;
    let target_entries = list_and_filter_ignored_entries(
        &target_path,
        &target_branch,
        &worktree_paths,
        no_excludes,
    )?;

    // Move gitignored files to staging BEFORE branch exchange.
    // `git switch` silently overwrites ignored files that collide with tracked
    // files on the target branch — staging them first prevents data loss.
    let staged = if !main_entries.is_empty() || !target_entries.is_empty() {
        let (dir, count) = stage_ignored(
            &repo,
            main_path,
            &main_entries,
            &target_path,
            &target_entries,
        )
        .context(format!(
            "Failed to stage ignored files. Already-staged files may be recoverable from: {}",
            format_path_for_display(&staging_path)
        ))?;
        if count > 0 { Some((dir, count)) } else { None }
    } else {
        None
    };

    // Exchange branches (detach both, then switch to swapped branches).
    // Failure is near-impossible (both worktrees verified clean, branches exist).
    // If it somehow fails, stale staging detection recovers on next run.
    exchange_branches(
        &main_working_tree,
        &main_branch,
        &target_working_tree,
        &target_branch,
    )?;

    // Distribute staged files to their new worktrees (after branch exchange)
    let swapped = if let Some((ref staging_dir, _)) = staged {
        distribute_staged(
            staging_dir,
            main_path,
            &main_entries,
            &target_path,
            &target_entries,
        )
        .context(format!(
            "Failed to distribute staged files. Staged files may be recoverable from: {}",
            format_path_for_display(staging_dir)
        ))?
    } else {
        0
    };

    // Print success messages only after everything succeeded. These go to
    // stderr regardless of --format, matching `rebase`/`push`: the human
    // status line is stderr, the JSON envelope on stdout is unaffected.
    eprintln!(
        "{}",
        success_message(cformat!(
            "Promoted: main worktree now has <bold>{target_branch}</>; {} now has <bold>{main_branch}</>",
            worktrunk::path::format_path_for_display(&target_path)
        ))
    );
    if swapped > 0 {
        let path_word = if swapped == 1 { "path" } else { "paths" };
        eprintln!(
            "{}",
            success_message(format!("Swapped {swapped} gitignored {path_word}"))
        );
    }

    Ok(PromoteResult::Promoted {
        target: target_branch,
        main_branch,
        swapped,
        mismatch: !is_restoring,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_move_entry_file() {
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("source.txt");
        let dest = tmp.path().join("subdir/dest.txt");

        fs::write(&src, "content").unwrap();
        move_entry(&src, &dest, false).unwrap();

        assert!(!src.exists());
        assert_eq!(fs::read_to_string(&dest).unwrap(), "content");
    }

    #[test]
    fn test_move_entry_directory() {
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("srcdir");
        let dest = tmp.path().join("nested/destdir");

        fs::create_dir_all(src.join("inner")).unwrap();
        fs::write(src.join("inner/file.txt"), "nested").unwrap();
        fs::write(src.join("root.txt"), "root").unwrap();

        move_entry(&src, &dest, true).unwrap();

        assert!(!src.exists());
        assert_eq!(
            fs::read_to_string(dest.join("inner/file.txt")).unwrap(),
            "nested"
        );
        assert_eq!(fs::read_to_string(dest.join("root.txt")).unwrap(), "root");
    }

    #[test]
    fn test_move_entry_failure_keeps_source_and_destination() {
        use path_slash::PathExt;

        let tmp = worktrunk::testing::test_tempdir();
        let src = tmp.path().join("source file");
        let blocker = tmp.path().join("existing file");
        fs::write(&src, b"source data").unwrap();
        fs::write(&blocker, b"existing data").unwrap();
        let blocked_parent = blocker.join("destination");

        let error = move_entry(&src, &blocked_parent, false).unwrap_err();
        assert!(error.downcast_ref::<std::io::Error>().is_some());
        assert_eq!(
            error.to_string(),
            format!(
                "creating parent directory for '{}'",
                blocked_parent.to_slash_lossy()
            )
        );
        assert_eq!(fs::read(&src).unwrap(), b"source data");
        assert_eq!(fs::read(&blocker).unwrap(), b"existing data");

        let occupied = tmp.path().join("existing directory");
        fs::create_dir(&occupied).unwrap();
        fs::write(occupied.join("protected"), b"existing data").unwrap();
        let error = move_entry(&src, &occupied, false).unwrap_err();
        assert!(error.downcast_ref::<std::io::Error>().is_some());
        assert_eq!(
            error.to_string(),
            format!(
                "moving '{}' to '{}'",
                src.to_slash_lossy(),
                occupied.to_slash_lossy()
            )
        );
        assert_eq!(fs::read(&src).unwrap(), b"source data");
        assert_eq!(
            fs::read(occupied.join("protected")).unwrap(),
            b"existing data"
        );
    }

    #[test]
    fn test_copy_and_remove_file() {
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("source.txt");
        let dest = tmp.path().join("dest.txt");

        fs::write(&src, "content").unwrap();
        copy_and_remove(&src, &dest, false).unwrap();

        assert!(!src.exists());
        assert_eq!(fs::read_to_string(&dest).unwrap(), "content");
    }

    #[test]
    fn test_copy_and_remove_directory() {
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("srcdir");
        let dest = tmp.path().join("destdir");

        fs::create_dir_all(src.join("sub")).unwrap();
        fs::write(src.join("sub/file.txt"), "nested").unwrap();
        fs::write(src.join("root.txt"), "root").unwrap();

        copy_and_remove(&src, &dest, true).unwrap();

        assert!(!src.exists());
        assert_eq!(
            fs::read_to_string(dest.join("sub/file.txt")).unwrap(),
            "nested"
        );
        assert_eq!(fs::read_to_string(dest.join("root.txt")).unwrap(), "root");
    }

    #[test]
    fn test_copy_and_remove_keeps_a_source_that_was_not_fully_copied() {
        // The move copies then deletes, so an entry the copy skipped would be
        // destroyed rather than moved. A source that is already gone is the
        // deterministic case: `copy_leaf` reports the skip, and the delete —
        // which would take a file recreated since — must not be reached.
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("gone.txt");
        let dest = tmp.path().join("dest.txt");

        let err = copy_and_remove(&src, &dest, false).unwrap_err();

        assert!(
            err.to_string().contains("was not fully copied"),
            "unexpected error: {err}"
        );
        assert!(!dest.exists());
    }

    #[cfg(unix)]
    #[test]
    fn test_copy_and_remove_drops_a_non_regular_file() {
        // A socket has no content the destination can be short of, so it does
        // not hold up the move. Refusing over one would strand real content:
        // `distribute_staged` runs after the branch exchange, and a promote
        // that dies there leaves the staged files behind a `check_leftover_
        // staging` refusal whose remedy deletes them.
        let tmp = worktrunk::testing::tempdir().unwrap();
        let src = tmp.path().join("srcdir");
        let dest = tmp.path().join("destdir");
        fs::create_dir_all(&src).unwrap();
        fs::write(src.join("regular.txt"), "content").unwrap();
        let listener = std::os::unix::net::UnixListener::bind(src.join("sock")).unwrap();
        drop(listener);
        // Closing the fd doesn't unlink, so the socket is still there to
        // classify. Asserted, so the test can't pass on a fixture that made none.
        assert!(src.join("sock").exists());

        copy_and_remove(&src, &dest, true).unwrap();

        assert!(!src.exists());
        assert_eq!(
            fs::read_to_string(dest.join("regular.txt")).unwrap(),
            "content"
        );
        assert!(!dest.join("sock").exists());
    }
}