Skip to main content
gx retarget moves a branch from one parent to another using git rebase --onto, updates the stack config, pushes the result, and optionally retargets the GitHub PR.

​
Usage

gx retarget [branch] <new-target> [flags]

​
Arguments

ArgumentDescription
branchBranch to retarget (default: current branch)
new-targetNew base branch to rebase onto
If only one argument is provided, it is treated as the new target and the current branch is retarget.

​
Flags

FlagDescription
--dry-runShow what would happen without making changes

​
What Happens

  1. Fetches the latest from remote
  2. Rebases the branch onto the new target using git rebase --onto origin/<new-target> <old-parent-head> <branch>
  3. Pushes with --force-with-lease
  4. Updates the stack config to record the new parent
  5. Retargets the PR via gh pr edit <branch> --base <new-target> (if gh is available)

​
Examples

$ gx retarget develop

Retargeting feature/auth onto develop...

  Old parent: main
  New parent: develop

Retarget feature/auth onto develop? [y/N] y

  Fetching latest from remote...
  Rebasing feature/auth onto origin/develop (using --onto)...
OK Rebased and pushed feature/auth
  Stack config updated: feature/auth -> develop (was: main)
OK PR for feature/auth automatically retargeted to develop

​
Auto PR Retarget

If the GitHub CLI (gh) is installed and authenticated, gx automatically runs: 
gh pr edit <branch> --base <new-target>
If this succeeds, you see OK PR for <branch> automatically retargeted to <new-target>. If it fails (no PR exists, or gh is not available), gx prints a reminder: WARN Remember to retarget the PR for <branch> to <new-target>.

​
Conflict Handling

If a rebase conflict occurs during retargeting: 
ERROR Rebase conflict encountered

  Conflicting files:
    src/auth.go

  To resolve:
    1. Fix the conflicts
    2. Run: git add . && git rebase --continue
    3. Run: gx retarget feature/auth develop
  • If the branch is already based on the new target, gx prints > <branch> is already based on <target>. Nothing to do.
  • If no saved parent exists in the stack config, gx falls back to using the merge base and prints a warning
  • The rebase uses origin/<new-target> when the remote branch exists, ensuring you rebase onto the latest remote state
  • Uses the stored parent_head SHA as the old base for --onto, which is more reliable than using the branch name when branches have been rebased