/git:upstream-pr

Submit clean, atomic PRs to upstream repositories from fork work.

When to Use This Skill

Context

• Current branch: !git branch --show-current
• Git status: !git status --porcelain=v2 --branch
• Remotes: !git remote -v
• Has upstream: !git remote -v
• Origin URL: !git remote -v
• Upstream URL: !git remote -v
• Recent commits: !git log --oneline --max-count=20
• Stash list: !git stash list

Parameters

Parse these from $ARGUMENTS:

Execution

Execute this fork-to-upstream PR workflow:

Step 1: Validate fork environment

1. Verify this is a git repository: git rev-parse --git-dir
2. Check if upstream remote exists (from context)
3. If no upstream remote:
   • Try to detect via gh repo view --json parent -q '.parent.nameWithOwner'
   • If found, add it: git remote add upstream https://github.com/<owner/repo>.git
   • If not found, ask user with AskUserQuestion for the upstream repo URL
4. Fetch upstream: git fetch upstream
5. Record the current branch name and check for uncommitted changes
6. If uncommitted changes exist, stash them: git stash push -m "upstream-pr: WIP before upstream PR"

Step 2: Assess fork state

Report the fork's divergence from upstream:

Fork status:
  Upstream: <upstream-repo>
  Behind upstream/main: N commits
  Ahead of upstream/main: M commits

If --dry-run is set, also show which commits would be selected and stop here.

Step 3: Select commits

If --commits provided:

• Parse the comma-separated SHA list
• Validate each SHA exists: git rev-parse --verify <sha>
• Show summary of selected commits

If --commits not provided:

• Show recent commits that are ahead of upstream/main:

  git log --oneline --format='%h %s (%cr)' upstream/main..HEAD
  

• Use AskUserQuestion to let the user select which commits to include
• Present commits as options with their subject lines

Step 4: Create clean branch from upstream/main

1. Generate branch name if --branch not provided:
   • Extract scope from first commit message (e.g., feat(auth): add OAuth -> feat/auth-add-oauth)
   • Fallback: upstream-pr/<date>
2. Create branch from upstream/main:

   git switch -c <branch-name> upstream/main
   

Step 5: Cherry-pick and squash

1. Cherry-pick each selected commit in order:

   git cherry-pick <sha1> <sha2> ...
   

2. If cherry-pick conflicts occur:
   • Report the conflict to the user
   • Reference git-conflicts for resolution
   • After resolution: git cherry-pick --continue
3. Squash all cherry-picked commits into one atomic commit:

   git reset --soft upstream/main
   git commit -m "<conventional commit message>"
   

4. Use AskUserQuestion to confirm or edit the commit message
   • Default message: derived from the cherry-picked commits
   • Format: conventional commit with scope

Step 6: Push to fork

git push -u origin <branch-name>

If --dry-run, show the command without executing.

Step 7: Create cross-fork PR

1. Determine the upstream repo (from --upstream or detected remote)
2. Determine the fork owner (from origin remote URL)
3. Create the PR:

   gh pr create \
     --repo <upstream-owner/upstream-repo> \
     --base main \
     --head <fork-owner>:<branch-name> \
     --title "<conventional commit title>" \
     --body "<PR description>"
   

   Add --draft if the flag was provided.
4. Report the PR URL to the user

Step 8: Restore working state

1. Switch back to the original branch:

   git switch <original-branch>
   

2. If changes were stashed in Step 1, pop them:

   git stash pop
   

3. Report completion summary:

   Upstream PR created:
     PR: <url>
     Branch: <branch-name>
     Commits: N cherry-picked, squashed into 1
     Original branch restored: <branch>
   

Error Handling

Agentic Optimizations

Related Skills

• git-fork-workflow - Fork management and sync strategies
• git-branch-pr-workflow - General branch and PR patterns
• git-conflicts - Resolve cherry-pick conflicts
• git-rebase-patterns - Advanced rebase techniques
• gh-cli-agentic - GitHub CLI cross-fork PR fields