---
name: finishing-a-development-branch
description: Use when development is complete and verified — merges feature branch into main and cleans up worktree
---

# Finishing a Development Branch

Solo dev workflow — no PRs. Clean merge into main, push, cleanup.

## Step 1: Confirm tests pass

Run project test suite. If failing → stop, don't offer options.

## Step 2: Show diff summary

```bash
git log main..<branch-name> --oneline
git diff main..<branch-name> --stat
```

## Step 3: Present options

```
Development complete on <branch-name> (<N> commits). What next?

1. Merge into main and push  (recommended)
2. Keep branch as-is
3. Discard this work
```

## Step 4: Execute

### Option 1: Merge into main

```bash
git checkout main
git pull                          # sync with remote first
git merge <branch-name>           # fast-forward if clean, creates merge commit if diverged
git push
git branch -d <branch-name>
```

Verify tests pass on main after merge. If they fail → `git revert HEAD`, investigate.

Then: remove worktree (Step 5).

### Option 2: Keep as-is

Report: "Branch `<branch-name>` kept. Worktree at `.worktrees/<branch-name>`."

**Don't remove worktree.**

### Option 3: Discard

**Confirm first:**
```
This permanently deletes:
- Branch <branch-name>
- Commits: <list from git log>
- Worktree at .worktrees/<branch-name>

Type 'discard' to confirm.
```

Wait for exact "discard". Then:

```bash
git checkout main
git branch -D <branch-name>
```

Then: remove worktree (Step 5).

## Step 5: Remove worktree (Options 1 and 3 only)

```bash
git worktree remove .worktrees/<branch-name>
```

If worktree has uncommitted changes, use `--force` only after user confirms.

## Red Flags

**Never:**
- Merge with failing tests
- Force-remove worktree without checking for uncommitted work
- Delete branch without typed confirmation for Option 3
- Push before verifying tests pass on merged main

## Integration

**Called by:** `ship` — final step after push/deploy, before `learn-from-mistakes`
**Pairs with:** `using-git-worktrees` — cleanup for worktree it created