git-branch-pr-workflow

What this skill does

# Git Branch PR Workflow

## When to Use This Skill

| Use this skill when... | Use the alternative when... |
|---|---|
| Designing the overall branch + PR workflow (main-branch dev, MCP integration) | Use `git-branch-naming` to pick or audit a single branch name |
| Choosing between `git switch`, `git restore`, and feature-branch push patterns | Use `git-rebase-patterns` for linear-history cleanup and stacked PRs |
| Creating PRs through GitHub MCP tools rather than `gh pr create` | Use `git-pr` to create PRs from a pushed branch via the `gh` CLI |
| Coordinating commit -> push -> PR end-to-end | Use `git-commit-push-pr` for the consolidated commit+push+PR macro |

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](../git-branch-naming/SKILL.md) skill
- **Linear History**: Rebase-first workflow, squash merging - see [git-rebase-patterns](../git-rebase-patterns/SKILL.md) 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

```bash
# 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:

```bash
# 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`:

```bash
# 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`:

```bash
# 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](../git-branch-naming/SKILL.md).

**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:

```bash
# 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:

```bash
# 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:

```bash
# 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](../git-rebase-patterns/SKILL.md).

## GitHub MCP Integration

Use GitHub MCP tools for all GitHub operations:

```python
# 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

```bash
# 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 or