Cascade Merge

Propagate changes from a source branch through all dependent branches in a PR chain.

Workflow

1. Identify Downstream Branches

gh pr list --state open --json number,title,headRefName,baseRefName --limit 50 | jq -r '.[] | "\(.baseRefName)\t\(.headRefName)"'

Build the dependency chain by finding PRs where baseRefName matches the current branch, then recursively find PRs based on those branches.

2. Merge and Push Each Branch

Fetch first, then for each downstream branch in order:

git fetch origin
git checkout <downstream-branch>
git merge origin/<upstream-branch> --no-edit
git push origin <downstream-branch>

A hook allows git merge only for the remote-tracking branch of the PR's base, so merge origin/<upstream-branch>, not the local branch. Pushing the upstream branch updates origin/<upstream-branch> before the next downstream merge.

Do not cherry-pick into a downstream branch, even when the merge is blocked or only one commit is needed. A cherry-picked commit gets a new hash, so git cannot tell it is the same change as the upstream commit. Every later change upstream has to be picked again by hand, and each round leaves duplicate commits and conflicts in the downstream history. When the PR targets a branch other than the default branch, a hook blocks git cherry-pick of any commit that an upstream branch already holds. Upstream branches are the base, its own PR bases up the chain, and the default branch. If the merge you need is blocked, report it to the user instead of looking for another route.

3. Handle Conflicts

If a merge conflict occurs:

1. Report the conflict to the user
2. Ask how to proceed (resolve manually, skip branch, or abort)

Example

Given this PR chain:

main
 └── feature-1
      └── feature-2
           └── feature-3

When feature-1 is updated, cascade merge will:

1. Merge feature-1 into feature-2, push
2. Merge feature-2 into feature-3, push

Output

Report results as a table:

Branch	Merged From	Status
feature-2	feature-1	Done
feature-3	feature-2	Done