This skill should be used when the user asks to "complete a branch", "merge to main", "finish my feature", "ship this branch", "integrate to main", "create a PR from GitButler", or when `--complete-branch` flag is mentioned. Guides completion of GitButler virtual branches with safety snapshots, integration workflows, and cleanup.
View on GitHubplugins/but/skills/complete-branch/SKILL.md
February 1, 2026
Select agents to install to:
npx add-skill https://github.com/outfitter-dev/agents/blob/main/plugins/but/skills/complete-branch/SKILL.md -a claude-code --skill gitbutler-complete-branchInstallation paths:
.claude/skills/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
Issues Found: