//! Worktree — a session's own checkout, on a branch of its own. //! //! A session that asks for one works in `/.luxe/worktrees//` instead of the //! checkout you are standing in, on a branch a person would have made, so its edits never land in //! your working tree and abandoning it is removing a directory. `.luxe/` ignores itself, so the //! worktree is invisible to your `git status`, your editor's search and your tests. //! //! The CLI calls [`prepare`] before the engine starts — once, so nothing moves under a running //! tool — and makes the result the process's working directory. Sessions, reviews and logs stay //! in the project's `.luxe/`: removing a worktree never takes any of them with it. mod push_route; pub(crate) use push_route::PUSH_ROUTE_MARK; use crate::program::{captured_command, resolve, run_bounded}; use std::path::{Path, PathBuf}; use std::time::Duration; /// How long a local git command may take. const GIT_DEADLINE: Duration = Duration::from_secs(30); /// How long fetching the base may take before the worktree is made from what is already here. const FETCH_DEADLINE: Duration = Duration::from_secs(30); /// How long fetching a pull request's head may take. Nothing can be made without it. const HEAD_FETCH_DEADLINE: Duration = Duration::from_secs(120); /// Where a project's session worktrees live, relative to it. pub const WORKTREES_DIR: &str = ".luxe/worktrees"; /// A session's worktree, made or found. #[derive(Debug, Clone, PartialEq, Eq)] pub struct SessionWorktree { /// The checkout pub path: PathBuf, /// Its branch pub branch: String, /// What a new branch was made from, like `origin/main`; `None` for a branch that existed pub base: Option, /// Whether it was made just now, rather than found from an earlier session pub created: bool, /// Whether the base could not be fetched, so a new branch starts from what was already here pub fetch_failed: bool, } /// Why a worktree could not be made. #[derive(Debug, thiserror::Error)] pub enum WorktreeError { /// The project is not a git repository, so there is nothing to branch. #[error("this project is not a git repository, so it cannot have a worktree")] NotARepository, /// The branch name is one git will not accept. #[error("`{0}` is not a branch name git accepts")] InvalidBranch(String), /// The branch is already checked out somewhere, which git allows only once. #[error("branch `{branch}` is already checked out at {path}")] CheckedOutElsewhere { /// The branch branch: String, /// Where path: String, }, /// Git refused, in its own words, bounded. #[error("git could not {operation}: {detail}")] Git { /// What was being done operation: &'static str, /// What git said detail: String, }, /// Git could not be run at all. #[error("could not run git: {0}")] Run(String), /// A local branch by the name a pull request needs holds other work. #[error( "a branch named `{0}` already exists here and is not this pull request's: rename it, and \ try again" )] BranchTaken(String), /// Nothing says how to reach the fork the pull request comes from. #[error("no remote here says how to reach the fork, and none could be made from `{0}`")] NoForkRemote(String), } /// A pull request to check out, and where its head lives. #[derive(Debug, Clone)] pub struct PullRequestCheckout<'a> { /// Where the head lives and the local branch it gets pub head: &'a crate::github::PullRequestHead, /// The host both repositories are on, which matches remotes to them pub host: &'a str, /// The remote this checkout reaches its own repository by, usually `origin` pub base_remote: &'a str, } /// A pull request's worktree, and how a push from it reaches the pull request. #[derive(Debug, Clone, PartialEq, Eq)] pub struct PullRequestWorktree { /// The worktree, on the pull request's local branch pub worktree: SessionWorktree, /// The remote its head is fetched from and pushed to pub remote: String, /// Whether that remote was added for it, rather than found pub remote_added: bool, } /// The directory a branch's worktree lives in: its name, with the slashes a branch may carry /// flattened so one branch is one directory. pub fn worktree_path(project: &Path, branch: &str) -> PathBuf { project.join(WORKTREES_DIR).join(branch.replace(['/', '\\'], "-")) } /// The project a luxe-made worktree belongs to, when `dir` is one or is inside one: what /// `/.luxe/worktrees/` leaves behind. `None` anywhere else. /// /// What a session in a worktree needs to reach what lives beside the project's `.luxe/` and never /// in a checkout, since `.luxe/` ignores itself: the project's own skills, for one. pub fn project_of(dir: &Path) -> Option { let parts: Vec<&std::ffi::OsStr> = dir.iter().collect(); let at = parts.windows(2).rposition(|pair| pair[0] == ".luxe" && pair[1] == "worktrees")?; // A worktree's name follows, and the project is everything before `.luxe` (at + 2 < parts.len() && at > 0).then(|| parts[..at].iter().collect()) } /// Makes the session's worktree for `branch`, or finds the one an earlier session made. /// /// A branch that exists is checked out as it is. A new one starts from `base` when given, else /// from the remote's default branch after a bounded fetch — so work starts from what is current — /// and failing that from `HEAD`. Offline, the fetch fails and the worktree is still made, from what /// is already here, and says so. pub async fn prepare( project: &Path, branch: &str, base: Option<&str>, ) -> Result { if git(project, &["rev-parse", "--git-dir"]).await.is_err() { return Err(WorktreeError::NotARepository); } if git(project, &["check-ref-format", "--branch", branch]).await.is_err() { return Err(WorktreeError::InvalidBranch(branch.to_string())); } let path = worktree_path(project, branch); // A worktree directory deleted by hand leaves git thinking it still exists let _ = git(project, &["worktree", "prune"]).await; let listed = git(project, &["worktree", "list", "--porcelain"]).await.unwrap_or_default(); match checked_out_at(&listed, branch) { Some(at) if same_path(&at, &path) => { return Ok(SessionWorktree { path, branch: branch.to_string(), base: None, created: false, fetch_failed: false, }); } Some(at) => { return Err(WorktreeError::CheckedOutElsewhere { branch: branch.to_string(), path: crate::paths::display(&at), }) } None => {} } let path_arg = crate::paths::display(&path); let exists = git(project, &["rev-parse", "--verify", "--quiet", &format!("refs/heads/{branch}")]) .await .is_ok(); if exists { git(project, &["worktree", "add", &path_arg, branch]) .await .map_err(|detail| WorktreeError::Git { operation: "add the worktree", detail })?; return Ok(SessionWorktree { path, branch: branch.to_string(), base: None, created: true, fetch_failed: false, }); } let (base, fetch_failed) = match base { Some(base) => (base.to_string(), false), None => default_base(project).await, }; git(project, &["worktree", "add", "--no-track", "-b", branch, &path_arg, &base]) .await .map_err(|detail| WorktreeError::Git { operation: "add the worktree", detail })?; // So a plain `git push` from the worktree publishes the branch under its own name, and the // pull request watch can tell where it went if has_remote(project, "origin").await { let _ = git(&path, &["config", &format!("branch.{branch}.remote"), "origin"]).await; let merge = format!("refs/heads/{branch}"); let _ = git(&path, &["config", &format!("branch.{branch}.merge"), &merge]).await; } Ok(SessionWorktree { path, branch: branch.to_string(), base: Some(base), created: true, fetch_failed, }) } /// Checks a pull request out in a worktree of its own, on a branch that tracks its head, so a plain /// `git push` lands on the pull request. /// /// A fork is reached by a remote pointing at it, found or added in the style this checkout reaches /// its own repository; `push_route::route_push` says where a push from the branch goes. A branch by /// that name holding other work is refused rather than moved, and a fetch that fails leaves nothing /// it added behind; a push route that cannot be written is an error, with the worktree in place. pub async fn check_out_pull_request( project: &Path, checkout: &PullRequestCheckout<'_>, ) -> Result { let head = checkout.head; let branch = head.local_branch.as_str(); if git(project, &["rev-parse", "--git-dir"]).await.is_err() { return Err(WorktreeError::NotARepository); } if git(project, &["check-ref-format", "--branch", branch]).await.is_err() { return Err(WorktreeError::InvalidBranch(branch.to_string())); } let path = worktree_path(project, branch); let _ = git(project, &["worktree", "prune"]).await; let listed = git(project, &["worktree", "list", "--porcelain"]).await.unwrap_or_default(); if let Some(at) = checked_out_at(&listed, branch) { if !same_path(&at, &path) { return Err(WorktreeError::CheckedOutElsewhere { branch: branch.to_string(), path: crate::paths::display(&at), }); } } let (remote, remote_added) = head_remote(project, checkout).await?; let tracking = format!("{remote}/{}", head.head_ref); let refspec = format!("+refs/heads/{}:refs/remotes/{tracking}", head.head_ref); if let Err(detail) = run(project, &["fetch", "--quiet", "--no-tags", &remote, &refspec], HEAD_FETCH_DEADLINE) .await { if remote_added { let _ = git(project, &["remote", "remove", &remote]).await; } return Err(WorktreeError::Git { operation: "fetch the pull request", detail }); } let found = checked_out_at(&listed, branch).is_some(); let exists = git(project, &["rev-parse", "--verify", "--quiet", &format!("refs/heads/{branch}")]) .await .is_ok(); let path_arg = crate::paths::display(&path); if exists { // Behind the head, it catches up; ahead of it, it keeps the commits not pushed yet let behind = is_ancestor(project, branch, &tracking).await; if !behind && !is_ancestor(project, &tracking, branch).await { return Err(WorktreeError::BranchTaken(branch.to_string())); } if !found { git(project, &["worktree", "add", &path_arg, branch]) .await .map_err(|detail| WorktreeError::Git { operation: "add the worktree", detail })?; } if behind { git(&path, &["merge", "--quiet", "--ff-only", &tracking]) .await .map_err(|detail| WorktreeError::Git { operation: "catch up with it", detail })?; } } else { git(project, &["worktree", "add", "--no-track", "-b", branch, &path_arg, &tracking]) .await .map_err(|detail| WorktreeError::Git { operation: "add the worktree", detail })?; } push_route::route_push(project, &remote, branch, &head.head_ref).await?; Ok(PullRequestWorktree { worktree: SessionWorktree { path, branch: branch.to_string(), base: Some(tracking), created: !found, fetch_failed: false, }, remote, remote_added, }) } /// The remote a pull request's head is reached by: this repository's own for a branch in it; for /// a fork, the remote pointing at it, else one added under the fork owner's name. async fn head_remote( project: &Path, checkout: &PullRequestCheckout<'_>, ) -> Result<(String, bool), WorktreeError> { let head = checkout.head; if !head.cross_repository { return Ok((checkout.base_remote.to_string(), false)); } if let Some(found) = crate::github::remote_pointing_at(project, checkout.host, &head.owner, &head.name).await { return Ok((found, false)); } // As configured, not as `insteadOf` rewrites it: the rewrite applies again to the fork's let key = format!("remote.{}.url", checkout.base_remote); let own = git(project, &["config", "--get", &key]).await.unwrap_or_default(); let url = crate::github::sibling_url(&own, &head.owner, &head.name) .ok_or_else(|| WorktreeError::NoForkRemote(checkout.base_remote.to_string()))?; // One this made before, found by the URL it was given, which `insteadOf` may display otherwise let configured = git(project, &["config", "--get-regexp", r"^remote\..*\.url$"]).await; let made_before = configured.unwrap_or_default().lines().find_map(|line| { let (key, value) = line.split_once(' ')?; (value == url) .then(|| key.strip_prefix("remote.")?.strip_suffix(".url").map(str::to_string))? }); if let Some(name) = made_before { return Ok((name, false)); } let taken = git(project, &["remote"]).await.unwrap_or_default(); let taken: Vec<&str> = taken.lines().collect(); let name = std::iter::once(head.owner.clone()) .chain((2..).map(|n| format!("{}-{n}", head.owner))) .find(|name| !taken.contains(&name.as_str())) .expect("an unbounded sequence has a free name"); git(project, &["remote", "add", &name, &url]) .await .map_err(|detail| WorktreeError::Git { operation: "add a remote for the fork", detail })?; Ok((name, true)) } async fn is_ancestor(project: &Path, ancestor: &str, of: &str) -> bool { git(project, &["merge-base", "--is-ancestor", ancestor, of]).await.is_ok() } /// Removes a session's worktree, keeping its branch. /// /// Never forced: git itself refuses a worktree with changes not committed, which is the last word /// on whether anything would be lost. Run it from the project, not from inside the worktree. pub async fn remove(project: &Path, path: &Path) -> Result<(), WorktreeError> { let path = crate::paths::display(path); git(project, &["worktree", "remove", &path]) .await .map(|_| ()) .map_err(|detail| WorktreeError::Git { operation: "remove the worktree", detail }) } /// The remote's default branch after a bounded fetch, else `HEAD`; and whether the fetch failed. async fn default_base(project: &Path) -> (String, bool) { let Ok(symbolic) = git(project, &["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]).await else { return ("HEAD".to_string(), false); }; let Some(default) = symbolic.strip_prefix("refs/remotes/origin/").map(str::to_string) else { return ("HEAD".to_string(), false); }; let fetched = run( project, &["fetch", "--quiet", "--no-write-fetch-head", "origin", &default], FETCH_DEADLINE, ) .await .is_ok(); (format!("origin/{default}"), !fetched) } async fn has_remote(project: &Path, name: &str) -> bool { git(project, &["remote"]) .await .is_ok_and(|remotes| remotes.lines().any(|remote| remote == name)) } /// Where `branch` is checked out, from `git worktree list --porcelain`. fn checked_out_at(listing: &str, branch: &str) -> Option { let wanted = format!("branch refs/heads/{branch}"); let mut current = None; for line in listing.lines() { if let Some(path) = line.strip_prefix("worktree ") { current = Some(PathBuf::from(path)); } else if line == wanted { return current; } } None } /// Whether two paths name the same directory, however each was spelled. fn same_path(left: &Path, right: &Path) -> bool { match (std::fs::canonicalize(left), std::fs::canonicalize(right)) { (Ok(left), Ok(right)) => left == right, _ => left == right, } } async fn git(dir: &Path, args: &[&str]) -> Result { run(dir, args, GIT_DEADLINE).await } /// Git's stdout in `dir`, or the first lines of what it said when it failed. async fn run(dir: &Path, args: &[&str], deadline: Duration) -> Result { let program = resolve("git").unwrap_or_else(|| PathBuf::from("git")); let mut command = captured_command(program, args, dir); command.env("GIT_TERMINAL_PROMPT", "0").env("GCM_INTERACTIVE", "never"); let output = run_bounded(command, deadline).await.map_err(|error| error.to_string())?; if output.status.success() { return Ok(String::from_utf8_lossy(&output.stdout).trim().to_string()); } let said = String::from_utf8_lossy(&output.stderr); let lines: Vec<&str> = said.lines().map(str::trim).filter(|line| !line.is_empty()).take(3).collect(); Err(if lines.is_empty() { "no reason given".into() } else { lines.join(" ") }) } #[cfg(test)] mod tests;