MAHDTech Update a Branch Against Its Base
Sync a feature branch with the base branch it will merge into, choosing the integration strategy deliberately and doing it without clobbering anyone's work.
When the update stops on conflicts, hand off to /git-resolve-conflicts.
1. Fetch and detect the base
Always fetch first so you integrate against the true remote tip, not a stale local copy:
git fetch origin --prune
Detect the base branch - do not assume main or master. If the user named one, use it. Otherwise try in order until one succeeds:
BASE=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)
BASE=${BASE:-$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p')}
BASE=${BASE:-$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')}
If a PR exists, its baseRefName is authoritative: gh pr view --json baseRefName -q '.baseRefName'. If detection fails, ask the user rather than guessing.
2. Secure the working tree
An update rewrites or moves your checkout, so start clean:
git status --short
If there are uncommitted changes, commit them or git stash push first, and restore with git stash pop after the update. Never start a rebase or merge with a dirty tree.
3. Choose rebase vs merge
| Factor | Rebase | Merge |
|---|---|---|
| History | Linear - replays your commits on top of the base | Preserves both histories, adds a merge commit |
| Shared-branch safety | Unsafe - rewrites your commit SHAs | Safe - never rewrites existing commits |
| Conflicts | May resurface per replayed commit | Resolved once, in the merge commit |
| Push after | Needs --force-with-lease |
Plain git push |
The golden rule: never rebase a branch other people have based work on or pulled. Rewriting shared history forces every collaborator to recover their copy by hand. If anyone else is building on this branch, merge.
Default: rebase a solo, unshared feature branch to keep history linear; merge when the branch is shared, or when preserving the exact integration history matters more than a clean line.
4. Integrate
Rebase onto the freshly fetched base tip:
git rebase "origin/$BASE"
Merge the base in:
git merge "origin/$BASE"
To bail out at any point and return to the pre-update state, use git rebase --abort or git merge --abort.
5. Handle conflicts
If the rebase or merge stops with conflicts, stop and invoke /git-resolve-conflicts to work through them. After it stages the resolutions, continue with git rebase --continue (repeat until the replay finishes) or git commit to seal the merge.
6. Push
After a merge, push normally:
git push
After a rebase, the remote branch and your rewritten local branch have diverged, so push with a lease - never a bare --force:
git push --force-with-lease
--force-with-lease refuses the push if the remote moved since your last fetch, protecting a collaborator's commits you have not seen; a plain --force overwrites them unconditionally. If the lease is rejected, re-fetch, reconcile, and only then push again.
Done when the branch contains the base's latest commits, the tree is clean, and the push succeeds.