Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix: use headRefName directly for fork PR branches (#706)
Maximilian Roosd33174a9ac59
diff --git a/.claude-plugin/skills/worktrunk/reference/switch.md b/.claude-plugin/skills/worktrunk/reference/switch.mdindex d793fef53..8f7be0c6c 100644--- a/.claude-plugin/skills/worktrunk/reference/switch.md+++ b/.claude-plugin/skills/worktrunk/reference/switch.md@@ -62,7 +62,7 @@ wt switch pr:101 # Checkout PR #101Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:` syntax since the branch already exists.-**Fork PRs:** To push changes, use `git push HEAD:<branch-name>` where `<branch-name>` is the PR's head branch (e.g., `feature-fix`). The local branch is named `<owner>/<branch>` to avoid collisions, so plain `git push` won't work with default settings.+**Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.## When wt switch failsdiff --git a/docs/content/switch.md b/docs/content/switch.mdindex bbbd5c020..66df3d68d 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -76,7 +76,7 @@ wt switch pr:101 # Checkout PR #101Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:` syntax since the branch already exists.-**Fork PRs:** To push changes, use `git push HEAD:<branch-name>` where `<branch-name>` is the PR's head branch (e.g., `feature-fix`). The local branch is named `<owner>/<branch>` to avoid collisions, so plain `git push` won't work with default settings.+**Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.## When wt switch failsdiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 5728fdb95..89c199e32 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -307,7 +307,7 @@ wt switch pr:101 # Checkout PR #101Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:` syntax since the branch already exists.-**Fork PRs:** To push changes, use `git push HEAD:<branch-name>` where `<branch-name>` is the PR's head branch (e.g., `feature-fix`). The local branch is named `<owner>/<branch>` to avoid collisions, so plain `git push` won't work with default settings.+**Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.## When wt switch failsdiff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rsindex d757c14ac..aa661e151 100644--- a/src/commands/worktree/switch.rs+++ b/src/commands/worktree/switch.rs@@ -57,7 +57,7 @@ fn resolve_switch_target(let pr_info = fetch_pr_info(pr_number, &repo_root)?;if pr_info.is_cross_repository {- // Fork PR: use owner/branch naming, will need fetch + config+ // Fork PR: will need fetch + pushRemote config (see pr_ref module docs)let local_branch = local_branch_name(&pr_info);// Check if branch already exists and is tracking this PRdiff --git a/src/git/error.rs b/src/git/error.rsindex bb5547d56..9fd778e58 100644--- a/src/git/error.rs+++ b/src/git/error.rs@@ -611,14 +611,17 @@ impl std::fmt::Display for GitError {}GitError::BranchTracksDifferentPr { branch, pr_number } => {+ // The PR's branch name conflicts with an existing local branch.+ // We can't use a different local name because git push requires+ // the local and remote branch names to match (with push.default=current).write!(f,"{}\n{}",error_message(cformat!(- "Branch <bold>{branch}</> exists but is not tracking PR #{pr_number}"+ "Branch <bold>{branch}</> exists but doesn't track PR #{pr_number}")),hint_message(cformat!(- "Delete the branch first: <bright-black>git branch -D {branch}</>"+ "To free the name, run <bright-black>git branch -m {branch} {branch}-old</>")))}diff --git a/src/git/pr_ref.rs b/src/git/pr_ref.rsindex 5f3ef965a..33342317e 100644--- a/src/git/pr_ref.rs+++ b/src/git/pr_ref.rs@@ -62,16 +62,23 @@//!//! When `isCrossRepository` is `true`, the branch exists in a fork, not `origin`.//!-//! ## The Problem+//! ## The Problem: PR Refs Are Read-Only//!-//! GitHub's `refs/pull/<N>/head` refs are **read-only**. You cannot push to them:+//! GitHub's `refs/pull/<N>/head` refs are **read-only** and cannot be pushed to.+//! This is explicitly documented by GitHub — the `refs/pull/` namespace is a+//! "hidden ref" that GitHub manages automatically://!//! ```text//! $ git push origin HEAD:refs/pull/101/head-//! error: cannot lock ref 'refs/pull/101/head': unable to resolve reference+//! ! [remote rejected] HEAD -> refs/pull/101/head (deny updating a hidden ref)//! ```//!-//! To update a fork PR, you must push to the **fork's branch**, not the PR ref.+//! There is no alternative writable ref on the base repo. The only way to update+//! a fork PR is to push directly to the fork's branch.+//!+//! The "Allow edits from maintainers" feature grants push access to the fork's+//! branch itself — it's a permission change on the fork, not a proxy through+//! the base repo's refs.//!//! ## Push Strategy (No Remote Required)//!@@ -79,9 +86,9 @@//! named remote. This means we can set up push tracking without adding remotes://!//! ```text-//! branch.contributor/feature.remote = origin-//! branch.contributor/feature.merge = refs/pull/101/head-//! branch.contributor/feature.pushRemote = [email protected]:contributor/repo.git+//! branch.feature.remote = origin+//! branch.feature.merge = refs/pull/101/head+//! branch.feature.pushRemote = [email protected]:contributor/repo.git//! ```//!//! This configuration gives us:@@ -114,14 +121,26 @@//!//! ## Local Branch Naming//!-//! To avoid collisions when multiple PRs have the same branch name (common with-//! branches like `fix`, `update`, etc.), we use a naming scheme:+//! **The local branch name must match the fork's branch name** for `git push`+//! to work. With `push.default = current` (the common default), git pushes to+//! a same-named branch on the pushRemote. If the names differ, push fails:+//!+//! ```text+//! # If local branch is "contributor/feature" but fork has "feature":+//! $ git push+//! error: src refspec contributor/feature does not match any+//! ```+//!+//! Git has no per-branch configuration for "push to a differently-named branch."+//! The only options are explicit refspecs (`git push HEAD:feature`) or matching+//! names. We choose matching names so `git push` "just works."//!//! - **Same-repo PR**: Use `headRefName` directly (e.g., `feature-auth`)-//! - **Fork PR**: Use `<owner>/<headRefName>` (e.g., `contributor/feature-auth`)+//! - **Fork PR**: Use `headRefName` directly (e.g., `feature-auth`)//!-//! The `<owner>/` prefix ensures uniqueness and makes it clear which fork the-//! branch comes from.+//! This means two fork PRs with the same branch name would conflict. The+//! `branch_tracks_pr()` check handles this by erroring if a branch exists+//! but tracks a different PR.//!//! ## Push Behavior//!@@ -172,10 +191,10 @@//!//! ## Branch Name Collisions//!-//! If user already has a local branch named `contributor/feature`:+//! If user already has a local branch with the same name as the PR's branch://!//! - Check if it tracks the same PR ref → reuse it-//! - Otherwise → error with suggestion to delete the branch or use a different name+//! - Otherwise → error with suggestion to rename their branch first//!//! ## Worktree Already Exists//!@@ -427,14 +446,13 @@ pub fn fetch_pr_info(pr_number: u32, repo_root: &std::path::Path) -> anyhow::Res/// Generate the local branch name for a PR.///-/// - Same-repo PRs: use `headRefName` directly-/// - Fork PRs: use `<owner>/<headRefName>` to avoid collisions+/// Uses `headRefName` directly for both same-repo and fork PRs. This ensures+/// the local branch name matches the remote branch name, which is required for+/// `git push` to work correctly with `push.default = current`.+///+/// See module docs for why we can't use a prefixed name like `<owner>/<branch>`.pub fn local_branch_name(pr: &PrInfo) -> String {- if pr.is_cross_repository {- format!("{}/{}", pr.head_owner, pr.head_ref_name)- } else {- pr.head_ref_name.clone()- }+ pr.head_ref_name.clone()}/// Construct the remote URL for a fork, matching the protocol of the primary remote.@@ -522,6 +540,8 @@ mod tests {#[test]fn test_local_branch_name_fork() {+ // Fork PRs also use headRefName directly (not owner/branch) because+ // the local branch name must match the fork's branch for git push to worklet pr = PrInfo {number: 101,head_ref_name: "feature-auth".to_string(),@@ -530,7 +550,7 @@ mod tests {is_cross_repository: true,url: "https://github.com/owner/repo/pull/101".to_string(),};- assert_eq!(local_branch_name(&pr), "contributor/feature-auth");+ assert_eq!(local_branch_name(&pr), "feature-auth");}#[test]diff --git a/tests/integration_tests/switch.rs b/tests/integration_tests/switch.rsindex a7144a34c..9975976e9 100644--- a/tests/integration_tests/switch.rs+++ b/tests/integration_tests/switch.rs@@ -1431,7 +1431,8 @@ fn test_switch_pr_base_conflict(repo: TestRepo) {#[rstest]fn test_switch_pr_fork_existing_same_pr(#[from(repo_with_remote)] repo: TestRepo) {// First, manually create the branch with correct tracking config- let branch_name = "contributor/feature-fix";+ // Branch name matches headRefName (no owner prefix) so git push works+ let branch_name = "feature-fix";repo.run_git(&["branch", branch_name, "main"]);repo.run_git(&["config",@@ -1466,7 +1467,8 @@ fn test_switch_pr_fork_existing_same_pr(#[from(repo_with_remote)] repo: TestRepo#[rstest]fn test_switch_pr_fork_existing_different_pr(#[from(repo_with_remote)] repo: TestRepo) {// Create the branch with tracking config for a DIFFERENT PR- let branch_name = "contributor/feature-fix";+ // Branch name matches headRefName (no owner prefix) so git push works+ let branch_name = "feature-fix";repo.run_git(&["branch", branch_name, "main"]);repo.run_git(&["config",@@ -1501,7 +1503,8 @@ fn test_switch_pr_fork_existing_different_pr(#[from(repo_with_remote)] repo: Tes#[rstest]fn test_switch_pr_fork_existing_no_tracking(#[from(repo_with_remote)] repo: TestRepo) {// Create the branch without any tracking config- let branch_name = "contributor/feature-fix";+ // Branch name matches headRefName (no owner prefix) so git push works+ let branch_name = "feature-fix";repo.run_git(&["branch", branch_name, "main"]);// No config set - branch exists but doesn't track anythingdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex f916a322f..6f515ef10 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -136,7 +136,7 @@ The [2mpr:<number>[0m syntax resolves the branch for a GitHub pull request. FoRequires [2mgh[0m CLI to be installed and authenticated. The [2m--create[0m flag cannot be used with [2mpr:[0m syntax since the branch already exists.-[1mFork PRs:[0m To push changes, use [2mgit push HEAD:<branch-name>[0m where [2m<branch-name>[0m is the PR's head branch (e.g., [2mfeature-fix[0m). The local branch is named [2m<owner>/<branch>[0m to avoid collisions, so plain [2mgit push[0m won't work with default settings.+[1mFork PRs:[0m The local branch uses the PR's branch name directly (e.g., [2mfeature-fix[0m), so [2mgit push[0m works normally. If a local branch with that name already exists tracking something else, rename it first.[1m[32mWhen wt switch failsdiff --git a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snap b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snapindex 811037cc7..f762c595b 100644--- a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snap+++ b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snap@@ -35,6 +35,6 @@ exit_code: 0----- stderr -----[36m◎[39m [36mFetching PR #42 from [1morigin[22m...[39m[2m○[22m Push configured to fork: [90mhttps://github.com/contributor/test-repo.git[39m-[32m✓[39m [32mCreated branch [1mcontributor/feature-fix[22m (tracking [1mPR #42[22m) and worktree @ [1m_REPO_.contributor-feature-fix[22m[39m+[32m✓[39m [32mCreated branch [1mfeature-fix[22m (tracking [1mPR #42[22m) and worktree @ [1m_REPO_.feature-fix[22m[39m[33m▲[39m [33mCannot change directory — shell integration not installed[39m[2m↳[22m [2mTo enable automatic cd, run [90mwt config shell install[39m[22mdiff --git a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_different_pr.snap b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_different_pr.snapindex 67403d820..2389f67e7 100644--- a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_different_pr.snap+++ b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_different_pr.snap@@ -34,5 +34,5 @@ exit_code: 1----- stderr -----[36m◎[39m [36mFetching PR #42 from [1morigin[22m...[39m-[31m✗[39m [31mBranch [1mcontributor/feature-fix[22m exists but is not tracking PR #42[39m-[2m↳[22m [2mDelete the branch first: [90mgit branch -D contributor/feature-fix[39m[22m+[31m✗[39m [31mBranch [1mfeature-fix[22m exists but doesn't track PR #42[39m+[2m↳[22m [2mTo free the name, run [90mgit branch -m feature-fix feature-fix-old[39m[22mdiff --git a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_no_tracking.snap b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_no_tracking.snapindex 67403d820..2389f67e7 100644--- a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_no_tracking.snap+++ b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_no_tracking.snap@@ -34,5 +34,5 @@ exit_code: 1----- stderr -----[36m◎[39m [36mFetching PR #42 from [1morigin[22m...[39m-[31m✗[39m [31mBranch [1mcontributor/feature-fix[22m exists but is not tracking PR #42[39m-[2m↳[22m [2mDelete the branch first: [90mgit branch -D contributor/feature-fix[39m[22m+[31m✗[39m [31mBranch [1mfeature-fix[22m exists but doesn't track PR #42[39m+[2m↳[22m [2mTo free the name, run [90mgit branch -m feature-fix feature-fix-old[39m[22mdiff --git a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_same_pr.snap b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_same_pr.snapindex c68c33e16..1b9af035e 100644--- a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_same_pr.snap+++ b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork_existing_same_pr.snap@@ -34,7 +34,7 @@ exit_code: 0----- stderr -----[36m◎[39m [36mFetching PR #42 from [1morigin[22m...[39m-[2m○[22m Branch [1mcontributor/feature-fix[22m already configured for PR #42-[32m✓[39m [32mCreated worktree for [1mcontributor/feature-fix[22m @ [1m_REPO_.contributor-feature-fix[22m[39m+[2m○[22m Branch [1mfeature-fix[22m already configured for PR #42+[32m✓[39m [32mCreated worktree for [1mfeature-fix[22m @ [1m_REPO_.feature-fix[22m[39m[33m▲[39m [33mCannot change directory — shell integration not installed[39m[2m↳[22m [2mTo enable automatic cd, run [90mwt config shell install[39m[22m