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 CLI** (preferred): `but oplog snapshot` -> `but push <branch>` -> `but pr new <branch>` -> merge PR on GitHub -> `but branch delete <branch>` **Direct merge**: `but oplog snapshot` -> `git checkout main` -> `git pull` -> `git merge --no-ff refs/gitbutler/<branch>` -> `git push` -> `but branch delete <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 pull` | Up to date with main | | Snapshot created | `but oplog snapshot -m "Before integrating..."` | Snapshot ID returned | ## Integration Workflows ### A. Using CLI (Preferred) ```bash # 1. Verify branch state but status but show feature-auth # 2. Create snapshot but oplog snapshot --message "Before publishing feature-auth" # 3. Authenticate with forge (one-time) but config forge auth # 4. Push branch and create PR but push feature-auth but pr new feature-auth # 5. Review and merge PR on GitHub # 6. Update local and clean up but pull but branch delete feature-auth ``` **Benefits:** - Full CLI workflow, no GUI needed - Correct base branch set automatically for stacks - Stays in GitButler workspace throughout ### B. Direct Merge to Main ```bash # 1. Verify branch state but status but show feature-auth # 2. Create snapshot but oplog snapshot --message "Before integrating feature-auth" # 3. Switch to main git checkout main # 4. Update main git pull origin main # 5. Merge with --no-ff (preserves history) git merge --no-ff refs/gitbutler/feature-auth -m "feat: add user authentication" # 6. Push git push origin main # 7. Clean up but branch delete feature-auth git checkout gitbutler/workspace ``` ### C. Manual Pull Request Workflow ```bash # 1. Push branch to remote git push origin refs/gitbutler/feature-auth:refs/heads/feature-auth # 2. Create PR gh pr create --base main --head feature-auth \ --title "feat: add user authentication" \ --body "Description..." # 3. Wait for review and approval # 4. Merge PR (via GitHub UI or CLI) gh pr merge feature-auth --squash # 5. Update main and clean up git checkout main git pull origin main but branch delete feature-auth git checkout gitbutler/workspace ``` ### D. Stacked Branches (Bottom-Up) ```bash # Must merge in order: base → dependent → final # 1. Merge base branch first git checkout main && git pull git merge --no-ff refs/gitbutler/feature-base -m "feat: base feature" git push origin main but branch delete feature-base git checkout gitbutler/workspace # 2. Update remaining branches but pull # 3. Merge next level git checkout main && git pull git merge --no-ff refs/gitbutler/feature-api -m "feat: API feature" git push origin main but branch delete feature-api git checkout gitbutler/workspace # 4. Repeat for remaining stack levels ``` > For comprehensive stacked branch management, load the **gitbutler-stacks** skill. ## Error Recovery ### Merge Conflicts ```bash # View conflicted files git status # Resolve conflicts manually # Stage resolved files git add src/auth.ts # Complete merge git commit # Verify and push git push origin main # Clean up but branch delete feature-auth git checkout gitbutler/workspace ``` ### Push Rejected (Main Moved Ahead) ```bash git pull origin main # Resolve any conflicts if main diverged git push origin main ``` ### Undo Integration (Not Pushed Yet) ```bash git reset --hard HEAD~1 git checkout gitbutler/workspace ``` ### Undo Integration (Already Pushed) ```bash git revert -m 1 HEAD git push origin main ``` ## Post-Integration Cleanup ```bash # Delete integrated virtual branch but branch delete feature-auth # Clean up remote branch (if created for PR) git push origin --delete feature-auth # Verify workspace is clean but status # Should show remaining active branches only but status # Branch should be gone ``` <rules> ALWAYS: - Create snapshot before integration: `but oplog snapshot --message "..."` - Use `--no-ff` flag to preserve branch history - Return to workspace after git operations: `git checkout gitbutler/workspace` - Run tests before integrating - Complete stacked branches bottom-to-top NEVER: - Merge without snapshot backup - Skip updating main first (`git pull`) - Forget to return to `gitbutler/workspace` - Merge middle of stack before base - Force push to main without explicit confirmation </rules> ## Troubleshooting | Symptom | Cause | Solution | |---------|-------|----------| | Merge conflicts | Diverged from main | Resolve conflicts, stage, commit | | Push rejected | Main moved ahead | `git pull`, resolve, push | | Branch not found | Wrong ref path | Use `refs/gitbutler/<name>` | | Can't return to workspace | Integration branch issue | `git checkout gitbutler/workspace` | ## Emergency Recovery ```bash # If integration went wrong but oplog but undo # Restores pre-integration state # If stuck after git operations git checkout gitbutler/workspace ``` ## Best Practices **Keep branches small:** - Small branches = easier merges - Aim for single responsibility per branch **Update base regularly:** ```bash but pull ``` **Test before integrating:** - Always run full test suite before merging **Meaningful merge commits:** ```bash # Good: Describes what and why git merge --no-ff feature-auth -m "feat: add JWT-based user authentication" # Bad: Generic message git merge --no-ff feature-auth -m "Merge branch" ``` <references> ### Related Skills - [gitbutler-virtual-branches](../virtual-branches/SKILL.md) — Core GitButler workflows - [gitbutler-stacks](../stacks/SKILL.md) — Stacked branches ### Reference Files - [gitbutler-virtual-branches/references/reference.md](../virtual-branches/references/reference.md) — CLI reference and troubleshooting ### External - [GitButler GitHub Integration](https://docs.gitbutler.com/features/forge-integration/github-integration) </references>