delete

The delete command removes a branch and its associated database snapshot.

Usage

pgbranch delete <branch> [flags]

Alias: rm

pgbranch rm <branch>

Arguments

Argument	Description
`branch`	Name of the branch to delete (required)

Flags

Flag	Short	Description	Default
`--force`	`-f`	Force delete even if it’s the current branch	`false`

Examples

Delete a Branch

pgbranch delete feature-old

Output:

Branch 'feature-old' deleted

Using Alias

pgbranch rm feature-old

Force Delete Current Branch

pgbranch delete feature-current --force

Force deleting the current branch will leave you with no active branch. You’ll need to checkout another branch or create a new one.

What Gets Deleted

When you delete a branch:

Template database - The PostgreSQL template database (pgbranch_<name>_<hash>) is dropped
Branch metadata - The branch configuration file in .pgbranch/branches/ is removed

DELETE branch 'feature-old'
         │
         ├──▶ DROP DATABASE pgbranch_feature_old_abc123
         │
         └──▶ rm .pgbranch/branches/feature-old.json

Error Cases

Branch Doesn’t Exist

pgbranch delete nonexistent

Error: branch 'nonexistent' does not exist

Deleting Current Branch Without Force

pgbranch delete current-branch

Error: cannot delete current branch 'current-branch' without --force

Last Remaining Branch

Deleting all branches is allowed but will leave you without any snapshots:

pgbranch delete main --force

After this, you’ll need to create a new branch to continue using pgbranch.

Bulk Deletion

To delete multiple branches, use a loop:

# Delete all feature branches
for branch in $(pgbranch branch | grep feature); do
  pgbranch delete "$branch"
done

Or use the prune command for automatic cleanup:

# Delete branches not accessed in 7 days
pgbranch prune -d 7 -y

Recovering Deleted Branches

If you have remotes configured, you may be able to recover from remote storage:

pgbranch pull feature-old --remote origin

Best Practices

Before Deleting

Verify you don’t need the branch
Terminal window
```
pgbranch log  # Review all branches
```

Push to remote if needed

pgbranch push feature-old --remote origin

Check disk usage

psql -c "SELECT pg_size_pretty(pg_database_size('pgbranch_feature_old_abc123'))"

Regular Cleanup

Use prune for automated cleanup:

# Interactive pruning of stale branches
pgbranch prune -d 14

# Automatic pruning (skip confirmation)
pgbranch prune -d 14 -y

Remote Branch Deletion

To delete a branch from remote storage:

pgbranch remote delete feature-old --remote origin

This only removes the remote copy; the local branch remains.

branch - List or create branches
prune - Bulk delete stale branches
remote delete - Delete from remote storage