Skip to content

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.md
index 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 #101
Requires `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 fails
diff --git a/docs/content/switch.md b/docs/content/switch.md
index bbbd5c020..66df3d68d 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -76,7 +76,7 @@ wt switch pr:101 # Checkout PR #101
Requires `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 fails
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 5728fdb95..89c199e32 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -307,7 +307,7 @@ wt switch pr:101 # Checkout PR #101
Requires `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 fails
diff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rs
index 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 PR
diff --git a/src/git/error.rs b/src/git/error.rs
index 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.rs
index 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 work
let 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.rs
index 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 anything
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 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 pr:<number> syntax resolves the branch for a GitHub pull request. Fo
Requires 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 fails
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snap b/tests/snapshots/integration__integration_tests__switch__switch_pr_fork.snap
index 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 -----
◎ Fetching PR #42 from origin...
○ Push configured to fork: https://github.com/contributor/test-repo.git
-✓ Created branch contributor/feature-fix (tracking PR #42) and worktree @ _REPO_.contributor-feature-fix
+✓ Created branch feature-fix (tracking PR #42) and worktree @ _REPO_.feature-fix
▲ Cannot change directory — shell integration not installed
↳ To enable automatic cd, run wt config shell install
diff --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.snap
index 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 -----
◎ Fetching PR #42 from origin...
-✗ Branch contributor/feature-fix exists but is not tracking PR #42
-↳ Delete the branch first: git branch -D contributor/feature-fix
+✗ Branch feature-fix exists but doesn't track PR #42
+↳ To free the name, run git branch -m feature-fix feature-fix-old
diff --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.snap
index 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 -----
◎ Fetching PR #42 from origin...
-✗ Branch contributor/feature-fix exists but is not tracking PR #42
-↳ Delete the branch first: git branch -D contributor/feature-fix
+✗ Branch feature-fix exists but doesn't track PR #42
+↳ To free the name, run git branch -m feature-fix feature-fix-old
diff --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.snap
index 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 -----
◎ Fetching PR #42 from origin...
-○ Branch contributor/feature-fix already configured for PR #42
-✓ Created worktree for contributor/feature-fix @ _REPO_.contributor-feature-fix
+○ Branch feature-fix already configured for PR #42
+✓ Created worktree for feature-fix @ _REPO_.feature-fix
▲ Cannot change directory — shell integration not installed
↳ To enable automatic cd, run wt config shell install