Git Branch PR Workflow

Expert guidance for branch management, pull request workflows, and GitHub integration using modern Git commands and linear history practices.

Core Expertise

Main-Branch Development: Work on main locally, push to remote feature branches for PRs
Modern Git Commands: Use git switch and git restore instead of checkout
Branch Naming: See git-branch-naming skill
Linear History: Rebase-first workflow, squash merging - see git-rebase-patterns for advanced patterns
GitHub MCP Integration: Use mcp__github__* tools instead of gh CLI

Main-Branch Development (Preferred)

Develop directly on main, push to remote feature branches for PRs. This eliminates local branch management overhead.

Basic Workflow

All work happens on main

git switch main git pull origin main

Make changes, commit on main

git add file.ts git commit -m "feat(auth): add OAuth2 support"

Push to remote feature branch (creates PR target)

git push origin main:feat/auth-oauth2

Create PR using GitHub MCP (head: feat/auth-oauth2, base: main)

Multi-PR Workflow (Sequential Commits)

When you have commits for multiple PRs on main, push specific commit ranges to different remote branches:

Commits on main:

abc1234 feat(auth): add OAuth2 support <- PR #1

def5678 feat(auth): add token refresh <- PR #1

ghi9012 fix(api): handle timeout edge case <- PR #2

Push first 2 commits to auth feature branch

git push origin abc1234^..def5678:feat/auth-oauth2

Push remaining commit to fix branch

git push origin ghi9012^..ghi9012:fix/api-timeout

Alternative: push from a specific commit to HEAD

git push origin def5678..HEAD:fix/api-timeout

Commit range patterns:

git push origin <start>^..<end>:<remote-branch>
Push commit range (inclusive)
git push origin <commit>..<commit>:<remote-branch>
Push range (exclusive start)
git push origin <commit>..HEAD:<remote-branch>
Push from commit to current HEAD
git push origin main:<remote-branch>
Push entire main to remote branch

Benefits

No local branch juggling - Always on main
Always on latest main - No branch drift
Clean local state - No stale branches to clean up
Remote branches are ephemeral - Deleted after PR merge
Simpler mental model - One local branch, many remote targets

Modern Git Commands (2025)

Switch vs Checkout

Modern Git uses specialized commands instead of multi-purpose git checkout :

Branch switching - NEW WAY (Git 2.23+)

git switch feature-branch # vs git checkout feature-branch git switch -c new-feature # vs git checkout -b new-feature git switch - # vs git checkout -

Creating branches with tracking

git switch -c feature --track origin/feature git switch -C force-recreate-branch

Restore vs Reset/Checkout

File restoration is now handled by git restore :

Unstaging files - NEW WAY

git restore --staged file.txt # vs git reset HEAD file.txt git restore --staged . # vs git reset HEAD .

Discarding changes - NEW WAY

git restore file.txt # vs git checkout -- file.txt git restore . # vs git checkout -- .

Restore from specific commit

git restore --source=HEAD~~2 file.txt # vs git checkout HEAD~~2 -- file.txt git restore --source=main --staged . # vs git reset main .

Command Migration Guide

Legacy Command Modern Alternative Purpose

git checkout branch

git switch branch

Switch branches

git checkout -b new

git switch -c new

Create & switch

git checkout -- file

git restore file

Discard changes

git reset HEAD file

git restore --staged file

Unstage file

git checkout HEAD~1 -- file

git restore --source=HEAD~1 file

Restore from commit

Branch Naming

For comprehensive branch naming conventions including type prefixes, issue linking, and validation patterns, see git-branch-naming.

Quick reference: {type}/{issue}-{description} (e.g., feat/123-user-auth )

Linear History Workflow

Trunk-Based Development

Preferred: Main-branch development (see above) - no local feature branches needed.

Alternative: Local feature branches for complex multi-day work:

Feature branch lifecycle (max 2 days)

git switch main git pull origin main git switch -c feat/user-auth

Daily rebase to stay current

git switch main && git pull git switch feat/user-auth git rebase main

Interactive cleanup before PR

git rebase -i main

Squash, fixup, reword commits for clean history

Push and create PR

git push -u origin feat/user-auth

Use local branches only when:

Multi-day complex features requiring isolation
Experimental work that might be abandoned
Need to switch contexts frequently between unrelated work

Squash Merge Strategy

Maintain linear main branch history:

Manual squash merge

git switch main git merge --squash feat/user-auth git commit -m "feat: add user authentication system

Implement JWT token validation
Add login/logout endpoints
Create user session management

Closes #123"

Interactive Rebase Workflow

Clean up commits before sharing:

Rebase last 3 commits

git rebase -i HEAD~3

Common rebase commands:

pick = use commit as-is

squash = combine with previous commit

fixup = squash without editing message

reword = change commit message

drop = remove commit entirely

Example rebase todo list:

pick a1b2c3d feat: add login form fixup d4e5f6g fix typo in login form squash g7h8i9j add form validation reword j1k2l3m implement JWT tokens

Advanced Rebase Patterns

For advanced rebase techniques including --reapply-cherry-picks , --update-refs , --onto , stacked PR workflows, and combining flags, see git-rebase-patterns.

GitHub MCP Integration

Use GitHub MCP tools for all GitHub operations:

Get repository information

mcp__github__get_me() # Get authenticated user info

List and create PRs

mcp__github__list_pull_requests(owner="owner", repo="repo") mcp__github__create_pull_request( owner="owner", repo="repo", title="feat: add authentication", head="feat/auth", base="main", body="## Summary\n- JWT authentication\n- OAuth support\n\nCloses #123" )

Update PRs

mcp__github__update_pull_request( owner="owner", repo="repo", pullNumber=42, title="Updated title", state="open" )

List and create issues

mcp__github__list_issues(owner="owner", repo="repo")

Best Practices

Daily Integration Workflow

Start of day: sync with main

git switch main git pull origin main git switch feat/current-work git rebase main

End of day: push progress

git add . && git commit -m "wip: daily progress checkpoint" git push origin feat/current-work

Before PR: clean up history

git rebase -i main git push --force-with-lease origin feat/current-work

Conflict Resolution with Rebase

When rebase conflicts occur

git rebase main

Fix conflicts in editor

git add resolved-file.txt git rebase --continue

If rebase gets messy, abort and merge instead

git rebase --abort git merge main

Safe Force Pushing

Always use --force-with-lease to prevent overwriting others' work

git push --force-with-lease origin feat/branch-name

Never force push to main/shared branches

Use this alias for safety:

git config alias.pushf 'push --force-with-lease'

Main Branch Protection

Configure branch rules for linear history via GitHub MCP:

Require linear history (disable merge commits)

Configure via GitHub settings or MCP tools

- Require pull request reviews

- Require status checks to pass

- Enforce linear history (squash merge only)

Branch Comparison: Always Use origin/main

CRITICAL: When comparing branches for PR creation, always compare against origin/main (or origin/<base-branch> ), never local main . Local main may contain commits that haven't been merged to the remote, causing PRs to include unrelated changes.

Why This Matters

WRONG: compares against local main (may include unpushed commits)

git log main..HEAD --format='%s' git diff main...HEAD --stat

CORRECT: compares against remote main (matches what GitHub will show)

git fetch origin main git log origin/main..HEAD --format='%s' git diff origin/main...HEAD --stat

Common scenario: You commit changes on local main for one PR, push to a feature branch, then start working on a second PR. If you compare against local main , the second PR's diff looks correct. But if the first PR hasn't merged yet, origin/main is behind — and comparing against it reveals that both PRs' changes would be included.

Rules

Always fetch before comparing: git fetch origin main
Use origin/main in all diff/log commands for PR context
Base PRs on origin/main when creating branches: git switch -c feat/foo origin/main
The pr-context.sh script handles this automatically

PR Context Gathering (Recommended)

Before creating a PR, gather all context in one command:

Gather PR context (defaults to main as base, compares against origin/main)

bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh"

Specify different base branch (compares against origin/develop)

bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh" develop

The script fetches the latest remote state and compares against origin/<base> to ensure accurate PR context. Outputs: branch info, remote status, commit range and types, diff stats, issue references found in commits, existing PR detection, and CI check results. Use this output to compose the PR title and body. See scripts/pr-context.sh for details.

Pull Request Workflow

PR Title Format

Use conventional commit format in PR titles:

feat: add user authentication
fix: resolve login validation bug
docs: update API documentation
chore: update dependencies

PR Body Template

Summary

Brief description of changes

Changes

Bullet points of key changes
Link related work

Testing

How changes were tested

Issue References

Closes #123

Issue Reference Guidelines:

Use Closes #N / Fixes #N / Resolves #N to auto-close issues on merge
Use Refs #N / Related to #N for context without auto-closing
Cross-repo: Fixes owner/repo#N
Multiple: Fixes #1, fixes #2, fixes #3 (repeat keyword)

PR Creation Best Practices

One focus per PR - Single logical change
Small PRs - Easier to review (< 400 lines preferred)
ALWAYS link issues - Use GitHub autolink format for traceability:
Closing keywords: Closes #123 , Fixes #456 , Resolves #789
Reference without closing: Refs #234 , Related to #567
Cross-repository: Fixes owner/repo#123
Multiple issues: Fixes #1, fixes #2 (repeat keyword for each)
Add labels - Use GitHub labels for categorization
Request reviewers - Tag specific reviewers when needed

Troubleshooting

Branch Diverged from Remote

Pull with rebase to maintain linear history

git pull --rebase origin feat/branch-name

Note: git reset --hard is rarely needed. Most "diverged" states resolve cleanly with git pull .

Committed to Main (Expected Workflow)

With main-branch development, committing to main is the expected workflow:

Commits are already on main - just push to remote feature branch

git push origin main:feat/new-feature

Create PR using GitHub MCP (head: feat/new-feature, base: main)

After PR is merged, local main resolves itself:

git pull origin main # Fast-forward merge handles this cleanly

Why git pull works (no reset needed):

Commits exist on both local main and remote feature branch
When PR merges to remote main, your local main is behind by the same commits
git pull recognizes the commits and fast-forwards cleanly
No history rewriting, no data loss, no merge conflicts

After pushing to a PR branch: Wait for the PR to merge, then use git pull to sync automatically.

Rebase Conflicts Are Too Complex

Abort rebase and use merge instead

git rebase --abort git merge main

Safe Operations

Recognizing Normal States

These states are expected during development - proceed confidently:

State Meaning Action

Unstaged changes after pre-commit Formatters modified files Stage with git add -u and continue

Modified files after running formatters Expected auto-fix behavior Stage before committing

Pre-commit exit code 1 Files were modified Stage modifications, re-run pre-commit

Branch behind remote Remote has newer commits Pull or rebase as appropriate

Confirmation-Required Commands

Request user confirmation before running destructive commands:

These require explicit user approval:

git branch -d/-D # "Delete local branch X?" git push origin --delete # "Delete remote branch X?" git reset --hard # "Discard uncommitted changes?" git clean -fd # "Remove untracked files?"

When State is Unclear

When encountering unexpected state:

Run diagnostic commands (git status , git log --oneline -5 )
Report findings clearly
Present options and wait for guidance

Recovery Workflows

Pre-commit Modifies Files

This is normal formatter/linter behavior:

1. Check what changed

git status

2. Stage modified files

git add -u

3. Continue with commit

git commit -m "feat(feature): description"

Push Rejected (Non-Fast-Forward)

Remote has newer commits:

Option 1: Rebase local changes on top (preferred for linear history)

git pull --rebase origin <branch>

Option 2: Merge remote changes

git pull origin <branch>

Option 3: Overwrite remote (your branch only, use cautiously)

git push --force-with-lease

Commit Fails

Read the error message
Common causes:
Pre-commit hooks failed → Fix issues and retry
No staged changes → Stage files first
Empty commit message → Provide message
Fix the underlying issue and retry