complete-branch_skill

Overview

This skill guides completing GitButler virtual branches safely and predictably. It walks through snapshot creation, integration into main (via CLI, direct merge, or PR), conflict recovery, and cleanup so you can ship features with preserved history and minimal risk.

How this skill works

The skill inspects branch state, enforces a pre-integration checklist, and recommends a snapshot before any merge. It provides three integration workflows (CLI preferred, direct merge, and manual PR), plus stacked-branch ordering, error recovery steps, and post-integration cleanup commands.

When to use it

• A virtual branch is finished and ready to ship
• Tests pass and code review is complete (if required)
• You need to merge changes into main and preserve history
• You want a safe rollback snapshot before integrating
• You need to clean up completed GitButler virtual branches

Best practices

• Always create a snapshot first: but oplog snapshot --message "..."
• Use git merge --no-ff to preserve branch history
• Run the full test suite and update base (but pull) before integrating
• Complete stacked branches bottom-to-top to avoid dependency conflicts
• Return to gitbutler/workspace after git operations

Example use cases

• Ship a finished feature branch using the CLI: snapshot, but push, but pr new, merge on GitHub, then but branch delete
• Directly merge a branch to main for fast fixes: snapshot, git checkout main, git merge --no-ff refs/gitbutler/<branch>, git push, cleanup
• Create a remote branch and PR manually when you prefer GitHub flow: git push refs/gitbutler/<branch>:refs/heads/<branch>, gh pr create, merge, then cleanup
• Integrate stacked branches in order: merge base first, delete it, pull updates, then merge dependent branches
• Recover from a bad integration by using but oplog undo or git revert depending on whether the merge was pushed