Finishing A Development Branch

Finishing A Development Branch automation and integration

Category: productivity Source: obra/superpowers

Finishing A Development Branch is an AI skill that guides developers through the complete process of preparing, reviewing, and merging feature branches into the main codebase. It covers branch cleanup, commit squashing, conflict resolution, pull request preparation, and post-merge tasks that enable clean and traceable integration of completed work.

What Is This?

Overview

Finishing A Development Branch provides structured approaches to completing feature branch workflows. It handles rebasing or merging the latest main branch changes to resolve conflicts before review, squashing or organizing commits into logical units that tell a clear story, writing descriptive pull request titles and summaries that communicate the change purpose, running pre-merge checks including tests, linting, and build verification, addressing reviewer feedback through fixup commits, and cleaning up remote and local branches after merge.

Who Should Use This

This skill serves developers completing feature work and preparing for merge, team leads reviewing pull requests for merge readiness, DevOps engineers enforcing branch hygiene policies, and teams establishing consistent branch completion workflows.

Why Use It?

Problems It Solves

Messy commit histories with WIP messages make it difficult to understand changes during review. Stale branches that diverge significantly from main create large, risky merge conflicts. Incomplete pull request descriptions force reviewers to read every diff line for context. Orphaned remote branches accumulate when developers skip post-merge cleanup.

Core Highlights

Commit organization produces a clean history that documents the reasoning behind each change. Conflict resolution before review ensures reviewers evaluate the final integrated state. Pre-merge validation catches test failures and lint issues before they reach the main branch. Branch cleanup removes merged branches to keep the repository organized.

How to Use It?

Basic Usage

git checkout main && git pull origin main
git checkout feature/user-auth
git rebase main

git rebase -i main
npm test && npm run lint && npm run build

git push --force-with-lease origin feature/user-auth

gh pr create --title "Add user authentication" \
  --body "Implements login, registration, and session management"

git checkout main && git pull origin main
git branch -d feature/user-auth
git push origin --delete feature/user-auth

Real-World Examples

import subprocess

class BranchFinisher:
    def __init__(self, branch, base="main"):
        self.branch = branch
        self.base = base

    def run(self, cmd):
        result = subprocess.run(
            cmd, shell=True, capture_output=True, text=True
        )
        if result.returncode != 0:
            raise RuntimeError(f"Failed: {result.stderr}")
        return result.stdout.strip()

    def update_base(self):
        self.run(f"git checkout {self.base}")
        self.run(f"git pull origin {self.base}")
        self.run(f"git checkout {self.branch}")

    def rebase(self):
        self.run(f"git rebase {self.base}")

    def run_checks(self, commands):
        results = {}
        for cmd in commands:
            try:
                self.run(cmd)
                results[cmd] = "passed"
            except RuntimeError as e:
                results[cmd] = f"failed: {e}"
        return results

    def push(self):
        self.run(
            f"git push --force-with-lease origin {self.branch}"
        )

    def cleanup_after_merge(self):
        self.run(f"git checkout {self.base}")
        self.run(f"git pull origin {self.base}")
        self.run(f"git branch -d {self.branch}")
        self.run(
            f"git push origin --delete {self.branch}"
        )

    def finish(self, check_commands):
        self.update_base()
        self.rebase()
        results = self.run_checks(check_commands)
        failures = {
            k: v for k, v in results.items()
            if "failed" in v
        }
        if failures:
            return {"status": "blocked", "failures": failures}
        self.push()
        return {"status": "ready", "results": results}

finisher = BranchFinisher("feature/user-auth")
result = finisher.finish(["npm test", "npm run lint"])
print(result)

Advanced Tips

Use force-with-lease instead of force push to prevent overwriting changes pushed by collaborators. Add commit message templates that include ticket references for automated issue linking. Configure branch protection rules requiring passing CI checks before merge.

When to Use It?

Use Cases

Use Finishing A Development Branch when preparing feature branches for pull request review, when cleaning up commit history before merging into the main branch, when resolving conflicts with the latest main branch changes, or when automating post-merge branch cleanup.

Related Topics

Git rebase workflows, pull request best practices, branch protection rules, CI pre-merge checks, and commit message conventions complement branch finishing workflows.

Important Notes

Requirements

Git version supporting rebase and force-with-lease operations. CI pipeline for automated pre-merge checks. Repository hosting platform with pull request support.

Usage Recommendations

Do: rebase onto the latest main before creating a pull request to surface conflicts early. Write commit messages that explain why changes were made, not just what changed. Delete merged branches promptly to keep the repository clean.

Don't: force push shared branches that other developers are working on. Squash all commits into a single one when the branch contains logically distinct changes. Skip running tests before pushing, relying solely on CI to catch issues.

Limitations

Interactive rebase requires familiarity with git editor workflows. Complex merge conflicts may need manual resolution that cannot be fully automated. Force pushing rewrites history, which disrupts collaborators who based work on the original commits.