fix: prune stale tracking refs before pushing so re-split branches are not rejected as stale

Author: vitali87

pr_split/cli.py

@@ -63,6 +63,7 @@
     fetch_fork_pr,
     is_worktree_clean,
     merge_base,
+    prune_remote_tracking_refs,
     push_branch,
     remove_worktree,
 )
@@ -463,6 +464,11 @@ def _push_and_create_prs(
     record_map = {r.group_id: r for r in branch_records}
     errors: list[tuple[str, Exception]] = []
 
+    # Branch names are reused across runs; drop tracking refs left by an
+    # earlier split whose remote branch was merged or deleted since, or
+    # force-with-lease rejects every push as stale.
+    prune_remote_tracking_refs()
+
     # Children target parent branches, so every branch is pushed before any PR opens.
     with ThreadPoolExecutor(max_workers=_PUSH_MAX_WORKERS) as executor:
         push_futures = {

pr_split/git_ops/__init__.py

@@ -28,6 +28,9 @@
 from .branches import (
     merge_base as merge_base,
 )
+from .branches import (
+    prune_remote_tracking_refs as prune_remote_tracking_refs,
+)
 from .branches import (
     push_branch as push_branch,
 )

pr_split/git_ops/branches.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import os
 import re
 import subprocess
@@ -110,10 +111,36 @@ def delete_branch(branch: str, *, remote: bool = False) -> None:
             if _REMOTE_REF_MISSING not in str(exc):
                 raise
             logger.info(logs.BRANCH_ALREADY_GONE.format(branch=branch, where=" on origin"))
+        # Either way the remote branch is gone; drop the local tracking ref
+        # too, or the next `push --force-with-lease` of a reused branch name
+        # is rejected as "stale info" against a ref origin no longer has.
+        forget_remote_tracking_ref(branch)
     if local_error is not None:
         raise local_error
 
 
+def forget_remote_tracking_ref(branch: str) -> None:
+    with contextlib.suppress(GitOperationError):
+        run_git("update-ref", "-d", f"refs/remotes/origin/{branch}")
+
+
+def prune_remote_tracking_refs() -> None:
+    """Drop tracking refs whose remote branch no longer exists.
+
+    Split branch names are reused across runs; after a merge or `clean` the
+    remote branch is gone but `refs/remotes/origin/pr-split/...` may still
+    point at the old head, and every `push --force-with-lease` would be
+    rejected as stale. Only *gone* refs are dropped (`git remote prune`, no
+    fetch): refreshing the refs that still exist would make the lease
+    compare against origin's current tip and silently force over commits
+    someone else pushed to a reused branch.
+    """
+    try:
+        run_git("remote", "prune", "origin")
+    except GitOperationError as exc:
+        logger.warning(logs.PRUNE_FAILED.format(error=exc))
+
+
 def merge_base(ref_a: str, ref_b: str) -> str:
     return run_git("merge-base", ref_a, ref_b)
 

pr_split/logs.py

@@ -74,3 +74,7 @@
 PR_SKIPPED_BASE_NOT_PUSHED = (
     "Skipping PR for group '{group}': its base branch '{base}' was not pushed"
 )
+PRUNE_FAILED = (
+    "Could not prune origin's tracking refs before pushing ({error}); "
+    "a reused branch name may be rejected as stale"
+)

tests/test_cli_helpers.py

@@ -627,3 +627,19 @@ def push(branch: str) -> None:
         with pytest.raises(PRSplitError):
             _push_and_create_prs(groups, records)
         assert mock_create.call_count == 0
+
+
+class TestPushPrunesFirst:
+    @patch("pr_split.cli.create_pr", return_value=(1, "https://github.com/pr/1"))
+    @patch("pr_split.cli.push_branch")
+    @patch("pr_split.cli.prune_remote_tracking_refs")
+    def test_tracking_refs_are_refreshed_before_any_push(
+        self, mock_prune: MagicMock, mock_push: MagicMock, mock_create: MagicMock
+    ) -> None:
+        order: list[str] = []
+        mock_prune.side_effect = lambda: order.append("prune")
+        mock_push.side_effect = lambda branch: order.append("push")
+        _push_and_create_prs(
+            [_group("pr-1", "feat: a")], [_branch_record("pr-1", "pr-split/ns/pr-1")]
+        )
+        assert order == ["prune", "push"]

tests/test_cli_new_features.py

@@ -401,6 +401,7 @@ def test_close_failure_warning_includes_the_reason(
 
 
 class TestCleanupAfterMergeDeletedBranches:
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.cli.get_pr_state", return_value={"state": "MERGED"})
     @patch("pr_split.cli.shutil.rmtree")
     @patch("pr_split.cli.Path")
@@ -413,6 +414,7 @@ def test_fully_merged_split_cleans_up_completely(
         mock_path: MagicMock,
         mock_rmtree: MagicMock,
         mock_state: MagicMock,
+        mock_forget: MagicMock,
     ) -> None:
         mock_path.return_value.exists.return_value = True
         # merge --delete-branch already removed both local and remote branches

tests/test_git_branches.py

@@ -125,14 +125,18 @@ def test_local_only(self, mock_git: MagicMock) -> None:
         delete_branch("pr-split/pr-1")
         mock_git.assert_called_once_with("branch", "-D", "pr-split/pr-1")
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_with_remote(self, mock_git: MagicMock) -> None:
+    def test_with_remote(self, mock_git: MagicMock, mock_forget: MagicMock) -> None:
         mock_git.return_value = ""
         delete_branch("pr-split/pr-1", remote=True)
         assert mock_git.call_count == 2
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_local_failure_still_deletes_remote(self, mock_git: MagicMock) -> None:
+    def test_local_failure_still_deletes_remote(
+        self, mock_git: MagicMock, mock_forget: MagicMock
+    ) -> None:
         mock_git.side_effect = [GitOperationError("checked out"), ""]
         with pytest.raises(GitOperationError, match="checked out"):
             delete_branch("pr-split/pr-1", remote=True)
@@ -145,15 +149,21 @@ def test_local_failure_without_remote_raises_immediately(self, mock_git: MagicMo
             delete_branch("pr-split/pr-1")
         mock_git.assert_called_once()
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_branch_already_deleted_locally_counts_as_deleted(self, mock_git: MagicMock) -> None:
+    def test_branch_already_deleted_locally_counts_as_deleted(
+        self, mock_git: MagicMock, mock_forget: MagicMock
+    ) -> None:
         # `pr-split merge` deletes the local branch; cleanup must not fail on it.
         mock_git.side_effect = [GitOperationError("error: branch 'pr-split/pr-1' not found."), ""]
         delete_branch("pr-split/pr-1", remote=True)
         mock_git.assert_any_call("push", "origin", "--delete", "pr-split/pr-1")
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_branch_already_deleted_on_origin_counts_as_deleted(self, mock_git: MagicMock) -> None:
+    def test_branch_already_deleted_on_origin_counts_as_deleted(
+        self, mock_git: MagicMock, mock_forget: MagicMock
+    ) -> None:
         mock_git.side_effect = [
             "",
             GitOperationError(
@@ -162,8 +172,11 @@ def test_branch_already_deleted_on_origin_counts_as_deleted(self, mock_git: Magi
         ]
         delete_branch("pr-split/pr-1", remote=True)
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_branch_gone_everywhere_counts_as_deleted(self, mock_git: MagicMock) -> None:
+    def test_branch_gone_everywhere_counts_as_deleted(
+        self, mock_git: MagicMock, mock_forget: MagicMock
+    ) -> None:
         mock_git.side_effect = [
             GitOperationError("error: branch 'pr-split/pr-1' not found."),
             GitOperationError(
@@ -177,8 +190,11 @@ def test_missing_local_branch_without_remote_is_fine(self, mock_git: MagicMock)
         mock_git.side_effect = GitOperationError("error: branch 'pr-split/pr-1' not found.")
         delete_branch("pr-split/pr-1")
 
+    @patch("pr_split.git_ops.branches.forget_remote_tracking_ref")
     @patch("pr_split.git_ops.branches.run_git")
-    def test_other_remote_failure_still_raises(self, mock_git: MagicMock) -> None:
+    def test_other_remote_failure_still_raises(
+        self, mock_git: MagicMock, mock_forget: MagicMock
+    ) -> None:
         mock_git.side_effect = ["", GitOperationError("fatal: could not read from remote")]
         with pytest.raises(GitOperationError, match="could not read from remote"):
             delete_branch("pr-split/pr-1", remote=True)
@@ -399,3 +415,159 @@ def test_localised_git_still_reports_already_deleted(
         monkeypatch.setenv("LANGUAGE", "de")
         # never existed: must be treated as already deleted, not as an error
         delete_branch("pr-split/ns/never")
+
+
+class TestStaleRemoteTrackingRefs:
+    def _repo_with_origin(self, tmp_path: Path) -> Path:
+        origin = tmp_path / "origin.git"
+        subprocess.run(["git", "init", "-q", "--bare", str(origin)], check=True)
+        repo = tmp_path / "repo"
+        subprocess.run(["git", "clone", "-q", str(origin), str(repo)], check=True)
+        subprocess.run(
+            [
+                "git",
+                "-c",
+                "user.name=t",
+                "-c",
+                "user.email=t@x",
+                "commit",
+                "-q",
+                "--allow-empty",
+                "-m",
+                "base",
+            ],
+            cwd=repo,
+            check=True,
+        )
+        subprocess.run(["git", "push", "-q", "-u", "origin", "HEAD:main"], cwd=repo, check=True)
+        return repo
+
+    def test_reused_branch_name_pushes_again_after_remote_deletion(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from pr_split.git_ops.branches import prune_remote_tracking_refs, push_branch
+
+        repo = self._repo_with_origin(tmp_path)
+        monkeypatch.chdir(repo)
+        subprocess.run(["git", "branch", "pr-split/ns/pr-1"], cwd=repo, check=True)
+        push_branch("pr-split/ns/pr-1")
+        # Simulate `gh pr merge --delete-branch` / GitHub deleting the head
+        # branch behind our back: the remote branch goes away but the local
+        # tracking ref still points at the old head.
+        subprocess.run(
+            ["git", "update-ref", "-d", "refs/heads/pr-split/ns/pr-1"],
+            cwd=tmp_path / "origin.git",
+            check=True,
+        )
+        subprocess.run(
+            [
+                "git",
+                "-c",
+                "user.name=t",
+                "-c",
+                "user.email=t@x",
+                "commit",
+                "-q",
+                "--allow-empty",
+                "-m",
+                "v2",
+            ],
+            cwd=repo,
+            check=True,
+        )
+        subprocess.run(["git", "branch", "-f", "pr-split/ns/pr-1", "HEAD"], cwd=repo, check=True)
+        with pytest.raises(GitOperationError, match="stale info"):
+            push_branch("pr-split/ns/pr-1")
+
+        prune_remote_tracking_refs()
+        push_branch("pr-split/ns/pr-1")
+
+    def test_prune_keeps_the_lease_against_third_party_pushes(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from pr_split.git_ops.branches import prune_remote_tracking_refs, push_branch
+
+        repo = self._repo_with_origin(tmp_path)
+        monkeypatch.chdir(repo)
+        subprocess.run(["git", "branch", "pr-split/ns/pr-9"], cwd=repo, check=True)
+        push_branch("pr-split/ns/pr-9")
+        # A reviewer pushes a fixup to the split branch from another clone.
+        other = tmp_path / "other"
+        subprocess.run(
+            ["git", "clone", "-q", str(tmp_path / "origin.git"), str(other)], check=True
+        )
+        subprocess.run(["git", "checkout", "-q", "pr-split/ns/pr-9"], cwd=other, check=True)
+        subprocess.run(
+            [
+                "git",
+                "-c",
+                "user.name=r",
+                "-c",
+                "user.email=r@x",
+                "commit",
+                "-q",
+                "--allow-empty",
+                "-m",
+                "fixup",
+            ],
+            cwd=other,
+            check=True,
+        )
+        subprocess.run(["git", "push", "-q", "origin", "pr-split/ns/pr-9"], cwd=other, check=True)
+        subprocess.run(
+            [
+                "git",
+                "-c",
+                "user.name=t",
+                "-c",
+                "user.email=t@x",
+                "commit",
+                "-q",
+                "--allow-empty",
+                "-m",
+                "resplit",
+            ],
+            cwd=repo,
+            check=True,
+        )
+        subprocess.run(["git", "branch", "-f", "pr-split/ns/pr-9", "HEAD"], cwd=repo, check=True)
+
+        prune_remote_tracking_refs()
+
+        # The lease must still protect the reviewer's commit.
+        with pytest.raises(GitOperationError, match="stale info"):
+            push_branch("pr-split/ns/pr-9")
+
+    def test_remote_delete_drops_the_tracking_ref(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from pr_split.git_ops.branches import push_branch
+
+        repo = self._repo_with_origin(tmp_path)
+        monkeypatch.chdir(repo)
+        subprocess.run(["git", "branch", "pr-split/ns/pr-2"], cwd=repo, check=True)
+        push_branch("pr-split/ns/pr-2")
+        assert branch_exists("refs/remotes/origin/pr-split/ns/pr-2")
+
+        delete_branch("pr-split/ns/pr-2", remote=True)
+
+        assert not branch_exists("refs/remotes/origin/pr-split/ns/pr-2")
+
+    def test_already_deleted_remote_still_drops_the_tracking_ref(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from pr_split.git_ops.branches import push_branch
+
+        repo = self._repo_with_origin(tmp_path)
+        monkeypatch.chdir(repo)
+        subprocess.run(["git", "branch", "pr-split/ns/pr-3"], cwd=repo, check=True)
+        push_branch("pr-split/ns/pr-3")
+        subprocess.run(
+            ["git", "update-ref", "-d", "refs/heads/pr-split/ns/pr-3"],
+            cwd=tmp_path / "origin.git",
+            check=True,
+        )
+
+        delete_branch("pr-split/ns/pr-3", remote=True)
+
+        assert not branch_exists("refs/remotes/origin/pr-split/ns/pr-3")