I've created pr-shadow, a tool that maintains a shadow branch for GitHub pull requests (PR) that never requires force-pushing. This addresses pain points I described in Reflections on LLVM's switch to GitHub pull requests.

The problem

GitHub structures pull requests around branches, enforcing a branch-centric workflow. When you force-push a branch after a rebase, the UI displays "force-pushed the BB branch from X to Y". Clicking "compare" shows git diff X..Y, which includes unrelated upstream commits—not the actual patch difference. For a project like LLVM with 100+ commits daily, this makes the comparison essentially useless.

Inline comments suffer too: they may become "outdated" or misplaced after force pushes.

Additionally, if your commit message references an issue or another PR, each force push creates a new link on the referenced page, cluttering it with duplicate mentions. (You can work around this by adding backticks around the link text, but it is not ideal.)

Due to these difficulties, some recommendations suggest less flexible workflows that only append new commits and discourage rebases. When working with both the latest main branch and the pull request branch, switching between branches results in numerous rebuilds.

In a large repository, avoiding rebases isn't realistic—other commits frequently modify nearby lines, and rebasing is often the only way to discover that your patch needs adjustments due to interactions with other landed changes.

The solution

pr-shadow maintains a separate PR branch (e.g., pr/feature) that only receives commits—never force-pushed. You work freely on your local branch (rebase, amend, squash), then sync to the PR branch using git commit-tree to create a commit with the same tree but parented to the previous PR HEAD.

1
2
3
4
5
6

Local branch (feature)     PR branch (pr/feature)
        A                         A
        |                         |
        B (amend)                 C1 "Fix bug"
        |                         |
        C (rebase)                C2 "Address review"

Reviewers see clean diffs between C1 and C2, even though the underlying commits were rewritten.

When a rebase is detected (merge-base with main/master changed), the new PR commit is created as a merge commit with the new merge-base as the second parent. GitHub displays these as "condensed" merges, preserving the diff view for reviewers.

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

git checkout feature
prs init              
prs init --draft      


git rebase main
git commit --amend


prs push "Fix bug"
prs push --force "Rewrite"  


prs desc


prs gh view
prs gh checks

The tool supports both fork-based workflows (pushing to your fork) and same-repo workflows (for branches like user/<name>/feature). It also works with GitHub Enterprise, auto-detecting the host from the repository URL.

The name "prs" is a tribute to spr, which implements a similar shadow branch concept. However, spr pushes user branches to the main repository rather than a personal fork. While necessary for stacked pull requests, this approach is discouraged for single PRs as it clutters the upstream repository. pr-shadow avoids this by pushing to your fork by default.

I owe an apology to folks who receive users/MaskRay/feature branches (if they use the default fetch = +refs/heads/*:refs/remotes/origin/* to receive user branches). I had been abusing spr for a long time after LLVM's GitHub transition to avoid unnecessary rebuilds when switching between the main branch and PR branches.