rebase-downstream

name	rebase-downstream
description	Rebase a tree of dependent branches (including siblings) after upstream changes. Auto-detects downstream branches and rebases each in order. Triggers on: rebase downstream, rebase chain, propagate changes downstream.
allowed-tools	Bash, Read, Grep, Glob

Rebase Downstream Tree

Rebase a tree of dependent branches after upstream changes have been made. Auto-detects the downstream branch tree (including sibling branches), rebases each branch in order, resolves conflicts when possible, and runs preflight checks on each branch.

Current State

• Branch: !git branch --show-current
• Status: !git status --short

Steps

1. Detect current branch

Get the current branch name. This is the branch that was just modified and whose changes need to propagate downstream.

git branch --show-current

2. Auto-detect downstream chain

Detect all downstream branches by examining local branch tracking relationships. For each local branch, check if its upstream tracking branch matches any other local branch:

# List all local branches with their upstream tracking branches
git for-each-ref --format='%(refname:short) %(upstream:short)' refs/heads/

From this output, build a parent-child tree:

• A branch B is a child of branch A if B's upstream tracking ref is A (or origin/A).
• Starting from the current branch, walk the tree depth-first to find all descendants.

Output the chain as branch:parent pairs in rebase order (depth-first pre-order). This handles both linear chains and trees with sibling branches.

If a branch tracks origin/<same-name> (i.e., it tracks itself on the remote), it is NOT a child -- it is an independent branch.

3. Confirm the chain

Display the detected chain to the user and ask for confirmation before proceeding.

If no downstream branches are detected, report this to the user and stop.

If branches are detected, show the tree visually:

<current-branch>
  -> <child1>
    -> <grandchild1>
  -> <child2> (sibling)

Ask the user to confirm before rebasing. If the user declines, stop.

4. Rebase each branch in order

For each downstream branch (closest to the current branch first):

1. Checkout the branch:

   git checkout <downstream-branch>
   

2. Rebase onto its parent (from the chain detection output):

   git rebase --fork-point <parent-branch>
   

   --fork-point uses the parent branch's reflog to find the actual fork point, so only the branch's own commits are replayed. Without it, if the parent was rebased/amended, git replays already-applied parent commits with different SHAs, causing duplicate commits and false conflicts.

   The parent for each branch comes from the chain detection. For sibling branches, both share the same parent.

3. Handle conflicts (if any):

   • Inspect each conflicted file to understand both sides
   • Attempt to resolve the conflict intelligently
   • After resolving, stage the files and continue:

     git add <resolved-files>
     git rebase --continue
     

   • If a conflict cannot be resolved, abort and stop:

     git rebase --abort
     

     Report which branch and files had unresolvable conflicts, then stop entirely. Do NOT continue to the next branch.

4. Run preflight checks on this branch. Look for the repository's standard checks by inspecting available tooling:

   # Detect and run whatever the repo uses:
   # - package.json scripts (lint, test, format, check)
   # - Makefile targets (lint, test, fmt, check)
   # - Cargo (cargo check, cargo clippy, cargo test)
   # - Python (ruff, black, pytest)
   # - Go (go vet, go test)
   # Look at CI config (.github/workflows/) to see what checks run
   

   If preflight fails, stop and report. Do NOT continue to the next branch.

5. Move to the next branch only after successful rebase and preflight.

5. Return to the original branch

After all branches are rebased successfully, checkout the original starting branch:

git checkout <original-branch>

6. Report results

Summarize the results:

• Rebased branches: List each branch that was successfully rebased
• Conflicts resolved: Note any conflicts that were auto-resolved and how
• Preflight results: Summary of preflight status for each branch
• Tree: Show the full rebased tree structure

Important

• NEVER skip preflight checks on any branch in the chain
• Stop immediately if a rebase conflict cannot be resolved
• Stop immediately if preflight fails on any branch
• Always return to the original branch at the end (even on failure)
• Do not force-push any branches -- the user will decide when to push