Sync Branch

Bring the current feature branch up to date by rebasing it onto its base. Follow the steps below in order. Stop and report rather than improvise if anything is ambiguous — a rebase rewrites history, so correctness matters more than speed.

Scope

If $ARGUMENTS is provided, treat it as the name of the base branch to rebase onto — supply a bare branch name without a remote prefix (for example main, develop, or release-2.0). If $ARGUMENTS is empty, auto-detect the base: prefer the remote's default branch, falling back to main, then master. Never assume the base — confirm which one you resolved before rebasing.

Step 1 — Confirm a clean working tree

A rebase must start from a clean tree. Check first.

git status --short
git rev-parse --abbrev-ref HEAD

• If git status --short prints nothing, the tree is clean — continue.
• If there are uncommitted changes, do not proceed silently. Either commit them first (use the commit workflow) or stash them, and tell the user which you did:

git stash push -u -m "sync-branch: pre-rebase stash"

Step 2 — Fetch the latest base

Update remote refs so you rebase onto current upstream, not a stale local copy.

git fetch --all --prune

Now resolve the base branch and record where you started, so you can recover if anything goes wrong.

# The remote's default branch, used when $ARGUMENTS is empty
git remote show origin | sed -n 's/.*HEAD branch: //p'
 
# Where HEAD is right now — note this hash for recovery
git rev-parse HEAD

Pick the base in this priority order: $ARGUMENTS → remote default branch → main → master. State the chosen base explicitly before continuing.

Step 3 — Rebase onto the base

Rebase the current branch onto the remote-tracking ref so you incorporate the freshly fetched commits.

# Replace <base> with the branch resolved in Step 2
git rebase origin/<base>

If the rebase applies cleanly, skip to Step 4. If it stops on a conflict, move to conflict resolution below.

Resolving conflicts

For each conflicted file, understand both sides before editing — do not blindly accept one.

# See which files are conflicted (covers all conflict types: UU, AA, DD, AU, etc.)
git diff --name-only --diff-filter=U
 
# Inspect a specific conflict, both sides at once
git diff <file>

• <<<<<<< HEAD is the version from the base you are rebasing onto.
• >>>>>>> <commit> is the change from the commit currently being replayed.

Read the surrounding code to grasp intent on each side, then write a resolution that preserves both behaviors where they are independent, or the correct one where they genuinely conflict. After editing a file to a coherent state:

git add <file>
git rebase --continue

Repeat until the rebase finishes. If a conflict is genuinely undecidable without product context, abort cleanly and hand it back rather than guessing:

git rebase --abort   # restores the pre-rebase state from Step 2

Step 4 — Verify the build and tests

A rebase can produce code that merges textually but breaks logically. Prove the branch still works.

# Adapt to the repo's actual scripts
npm run build
npm test

If the build or tests fail, the failure was introduced by the rebase — investigate and fix it now, then re-run until green. Do not report success on a red build.

Step 5 — Restore and report

If you stashed in Step 1, restore that work now:

git stash pop

Then summarize the outcome:

• The base branch you rebased onto and how many commits it pulled in.
• How many of your commits were replayed.
• Every conflict you resolved and the reasoning for each resolution.
• The build/test status (must be green).
• Whether a stash was used and successfully popped.

git push --force-with-lease