nsheaps/update-branch

Update Branch

Synchronize a local branch with its remote counterpart and ensure the remote branch is up-to-date with its base branch.

Pre-fetched Context

Current branch: !git branch --show-current 2>/dev/null || echo "(not in a git repo)"

PR info for current branch: !gh pr view --json baseRefName,headRefName,number,title,state 2>/dev/null || echo "(no PR found or gh not authenticated)"

Overview

This skill handles the common workflow of keeping a feature branch synchronized:

1. Local branch may have unpushed commits
2. Remote branch may have commits not yet pulled
3. Base branch may have advanced since the feature branch was created

The goal: ensure the remote feature branch contains all local changes AND is current with its base branch.

Input Resolution

Default behavior (no arguments): Use the current directory, get the current branch via git branch --show-current, find the associated PR via gh pr list --head <branch>, and update from the PR's base branch.

Determine the target branch from the provided input. Accept any of:

| Input Type | Example | Resolution | | ----------- | -------------------------------------- | ------------------------------------------------------- | | No input | (empty) | Current directory → current branch → find PR → update | | PR number | 123, #123 | gh pr view 123 --json headRefName,baseRefName | | PR URL | https://github.com/org/repo/pull/123 | Parse number, use gh pr view | | Branch name | feature/my-branch | Use directly, find PR with gh pr list --head <branch> | | Directory | /path/to/repo | cd there, get current branch, find PR |

Critical: Always query the PR to determine the base branch. Never assume main or master.

# Get branch info from PR
gh pr view <number> --json headRefName,baseRefName,number,url

# Find PR for a branch
gh pr list --head <branch-name> --json number,baseRefName --limit 1

Synchronization Workflow

Execute these steps in order:

Step 1: Fetch All Remotes

git fetch --all --prune

Step 2: Get Base Branch from PR

# Extract base branch name
BASE_BRANCH=$(gh pr view <number> --json baseRefName --jq '.baseRefName')

If no PR exists for the branch, ask the user what the base branch should be.

Step 3: Ensure on Correct Branch

git checkout <feature-branch>

Step 4: Merge Base Branch into Feature Branch

git merge origin/$BASE_BRANCH --no-edit

If conflicts occur, see Conflict Resolution.

Step 5: Pull Remote Feature Branch

git pull origin <feature-branch> --no-edit

If conflicts occur, handle them before proceeding.

Step 6: Push to Remote

git push origin <feature-branch>

Step 7: Verify

Confirm the remote branch is updated:

gh pr view <number> --json commits,mergeable,mergeStateStatus

Conflict Resolution

When merge conflicts occur:

Obvious Conflicts

Resolve directly when the conflict is clearly one of:

• Formatting differences (whitespace, line endings)
• Simple additions that don't overlap semantically
• Deleted code that was also modified (usually keep the modification or deletion based on intent)
• Import statement ordering

Non-Obvious Conflicts

For conflicts requiring analysis, delegate to specialized agents:

1. Use Explore agent with haiku model to understand:

   • What each side of the conflict is trying to accomplish
   • The history of the conflicting changes
   • Related code that might inform the resolution

2. Use Plan agent to determine:

   • The correct resolution strategy
   • Whether both changes can coexist
   • If architectural decisions are needed

3. Execute the resolution - The executing agent owns the final resolution. Agent delegations are helpers, not decision-makers.

4. Verify the resolution - Run tests or builds to confirm the merge didn't break anything.

For detailed conflict resolution patterns, see references/conflict-resolution.md.

Safety Rules

Only modify the requested branch:

• ONLY update the specific PR/branch that was requested
• Do NOT recursively update parent PRs, even if the base branch is itself a feature branch that's out of date
• If the base branch is out of date, merge it as-is into the feature branch - updating the base is a separate operation
• Example: If PR #123 (feature-a) is based on PR #100 (feature-b), and feature-b is behind main, only update feature-a with current state of feature-b

Never rewrite history:

• Never use git push --force
• If force is absolutely required, use --force-with-lease or --force-if-includes
• Prefer merge over rebase

Preserve all changes:

• Local commits must end up on remote
• Remote commits must be preserved
• Base branch changes must be incorporated

CI/Remote Environment Usage

This skill works identically in CI and local environments:

• Use git directly for all operations
• Git identity configuration is outside this skill's scope
• The CI environment should configure user.name and user.email appropriately

Error Handling

| Error | Resolution | | -------------------------------- | -------------------------------------------- | | No PR found for branch | Ask user for base branch, or create PR first | | Merge conflicts | Follow conflict resolution workflow | | Push rejected (non-fast-forward) | Pull first, then push again | | Authentication failure | Ensure gh and git are authenticated |

Completion Messaging

When reporting completion, use clear language that doesn't imply the PR was merged:

Don't say: "PR #123 is now merged with main" (implies PR merged INTO main)

Do say: "Branch updated: merged base branch (main) into feature branch, synced local and remote"

Additional Resources

For detailed conflict resolution guidance, consult:

• references/conflict-resolution.md - Patterns for analyzing and resolving merge conflicts