merge-upstream

Merge Upstream

Sync the current fork branch with upstream/<branch> using a merge commit by default. Preserve local commit hashes, keep push non-destructive, and never rewrite history.

Usage

Treat these as equivalent triggers:

/merge-upstream [--base=<branch>] [--ff-allow]
merge upstream [--base=<branch>] [--ff-allow]
sync fork with upstream

Options:

• --base=<branch>: use that upstream branch instead of auto-detecting the upstream default branch.
• --ff-allow: allow git merge --ff-only when the current branch has no unique local commits. Without this, use git merge --no-ff to leave an explicit sync commit.

Invariants

• Do not run git rebase.
• Do not run git push --force or git push --force-with-lease.
• Do not bypass hooks or signing with --no-verify or --no-gpg-sign.
• Ask before pushing.

Workflow

1. Validate the repository:

   git rev-parse --is-inside-work-tree
   git branch --show-current
   git remote get-url upstream
   git remote get-url origin
   

   Abort on detached HEAD or missing upstream. If origin is missing, continue locally and skip push.

2. Require a clean worktree:

   worktree_status=$(git status --porcelain) || exit 1
   test -z "$worktree_status"
   

   If dirty, stop and ask the user to clean or commit the changes, or use a clean task worktree.

3. Detect the upstream target branch:

   • If --base=<branch> is provided, fetch and verify upstream/<branch>.
   • Otherwise run git remote set-head upstream -a, then read refs/remotes/upstream/HEAD.
   • If detection fails, ask the user for --base=<branch>.

4. Fetch enough history for a reliable merge base:

   git rev-parse --is-shallow-repository
   git fetch --tags upstream "+refs/heads/${upstream_branch}:refs/remotes/upstream/${upstream_branch}"
   origin_branch_exists=false
   if git remote get-url origin >/dev/null 2>&1; then
     if ! origin_branch=$(git ls-remote --heads origin "refs/heads/${current_branch}"); then
       echo "failed to inspect origin/${current_branch}" >&2
       exit 1
     elif [ -n "$origin_branch" ]; then
       git fetch origin "+refs/heads/${current_branch}:refs/remotes/origin/${current_branch}" || exit 1
       origin_branch_exists=true
     else
       echo "origin/${current_branch} does not exist; current branch is unpublished"
     fi
   fi
   git merge-base HEAD "upstream/${upstream_branch}"