gitbutler-complete-branch

# Complete GitButler Virtual Branch

Virtual branch ready → snapshot → merge to main → cleanup → return.

<when_to_use>

- Virtual branch work is complete and ready to ship
- Tests pass and code is reviewed (if required)
- Ready to merge changes into main branch
- Need to clean up completed branches

NOT for: ongoing work, branches needing more development, stacks (complete bottom-to-top)

</when_to_use>

## TL;DR

**Using `but publish`** (preferred): `but snapshot` -> `but publish -b <branch>` -> merge PR on GitHub -> `but branch rm <branch>`

**Direct merge**: `but snapshot` -> `git checkout main` -> `git pull` -> `git merge --no-ff refs/gitbutler/<branch>` -> `git push` -> `but branch rm <branch>` -> `git checkout gitbutler/workspace`

**Manual PR workflow**: `git push origin refs/gitbutler/<branch>:refs/heads/<branch>` -> `gh pr create` -> merge PR -> cleanup

See detailed workflows below.

## Pre-Integration Checklist

Run through before any integration:

| Check | Command | Expected |
|-------|---------|----------|
| GitButler running | `but --version` | Version output |
| Work committed | `but status` | Committed changes, no unassigned files |
| Tests passing | `bun test` (or project equivalent) | All green |
| Base updated | `but base update` | Up to date with main |
| Snapshot created | `but snapshot -m "Before integrating..."` | Snapshot ID returned |

## Integration Workflows

### A. Using `but publish` (Preferred)

```bash
# 1. Verify branch state
but status
but log

# 2. Create snapshot
but snapshot --message "Before publishing feature-auth"

# 3. Authenticate with forge (one-time)
but forge auth

# 4. Publish branch (pushes and creates PR)
but publish -b feature-auth

# 5. Review and merge PR on GitHub

# 6. Update local and clean up
but base update
but branch rm feature-auth
```

**Benefits:**
- Handles push and PR creation in one command
- Correct base branch set automatically for stacks
- Stays in GitButler workspace throughout

### B. Direct Merge