How do I rebase my branch on main?
Table of Contents
Working on a stale branch wastes a review round: the diff carries changes main already has, and CI runs against a base nobody else is on.
1. Question
How do I bring my feature branch up to date with origin/main, and what do
I do when the rebase stops on a conflict?
2. Answer
2.1. Rebase
./compass.sh pr sync
Compass fetches origin/main and rebases the current branch on it, then
reports how far ahead the branch now is. An up-to-date branch is reported as
such and nothing is rewritten.
2.2. Push the rebased branch
A rebase rewrites the branch's commits, so an ordinary push is refused.
./compass.sh pr sync --push
This pushes with --force-with-lease, which refuses if someone else has
pushed to the branch in the meantime. Prefer it to --force, which does
not check.
2.3. When the rebase conflicts
Compass stops where git stops, lists the conflicted files, and names the ways out. Resolve them in place, then continue:
git add <resolved-files> git rebase --continue
To back out and leave the branch as it was:
git rebase --abort
For an unattended run, ./compass.sh pr sync --abort-on-conflict aborts
rather than leaving the worktree mid-rebase for a human to find.
3. Script
projects/ores.compass/src/compass_pr.py implements pr sync.
4. Tested by
Manual. Exercised on every feature branch before its PR is raised.
5. See also
- How do I start a new feature branch phase? — starting from a fresh main instead.
- How do I work a task? — where syncing sits in the lifecycle.