Prune

The prune command removes branches that haven’t been accessed recently, helping you manage disk space.

Usage

pgbranch prune [flags]

Flags

Flag	Short	Description	Default
--days	-d	Days after which a branch is stale	7
--force	-y	Skip confirmation, prune all stale	false

Examples

Interactive Pruning

pgbranch prune

Output:

Stale branches (not accessed in 7 days):

  1. feature-old-api
     Last accessed: 2024-01-05 14:30:00
     Size: 45 MB

  2. experiment-caching
     Last accessed: 2024-01-03 09:15:00
     Size: 52 MB

  3. bugfix-login
     Last accessed: 2024-01-02 16:45:00
     Size: 43 MB

Total: 3 branches, 140 MB

Enter branch numbers to KEEP (comma-separated), or press Enter to prune all:

• Enter 1,3 to keep branches 1 and 3, prune branch 2
• Press Enter to prune all listed branches

Custom Stale Threshold

pgbranch prune -d 14

This considers branches stale if not accessed in 14 days.

Automatic Pruning

pgbranch prune -d 7 -y

Prunes all stale branches without confirmation. Useful for automation.

Preview Only

To see what would be pruned without actually pruning:

pgbranch prune -d 7
# Then enter all branch numbers to keep them

How Staleness is Determined

A branch is considered stale if it hasn’t been:

• Checked out
• Created
• Updated (via merge or push/pull)

in the specified number of days.

The “last accessed” time is stored in branch metadata.

What Gets Deleted

When a branch is pruned:

1. Template database is dropped
2. Branch metadata is removed

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

Protected Branches

The current branch is never pruned, even if stale:

pgbranch prune

Stale branches (not accessed in 7 days):

Note: Current branch 'main' is excluded from pruning.

  1. feature-old
     ...

Disk Space Recovery

After pruning, check recovered space:

# Before pruning
psql -c "SELECT pg_size_pretty(sum(pg_database_size(datname)))
         FROM pg_database WHERE datname LIKE 'pgbranch_%'"

# Prune
pgbranch prune -d 7 -y

# After pruning
psql -c "SELECT pg_size_pretty(sum(pg_database_size(datname)))
         FROM pg_database WHERE datname LIKE 'pgbranch_%'"

Automated Cleanup

Cron Job

Set up automatic weekly cleanup:

# Edit crontab
crontab -e

# Add line (runs every Sunday at 3 AM)
0 3 * * 0 cd /path/to/project && pgbranch prune -d 14 -y >> /var/log/pgbranch-prune.log 2>&1

Pre-commit Hook

Clean up before commits:

.git/hooks/pre-commit

#!/bin/sh
pgbranch prune -d 7 -y

CI/CD Pipeline

Clean up in your pipeline:

# GitHub Actions example
- name: Cleanup old branches
  run: |
    pgbranch prune -d 3 -y

Best Practices

Regular Pruning

Run prune regularly to keep disk usage manageable:

# Weekly manual check
pgbranch prune -d 14

# Or automate
pgbranch prune -d 7 -y

Before Major Operations

Prune before operations that need disk space:

# Before pulling large branches
pgbranch prune -d 7 -y
pgbranch pull large-dataset

Project-Specific Thresholds

Different projects may need different thresholds:

Project Type	Suggested -d
Active development	7 days
Maintenance mode	30 days
Archived/reference	90 days

Recovering Pruned Branches

No Local Recovery

Pruned branches cannot be recovered locally.

If you have remotes configured, branches may be recoverable:

# Check if branch exists on remote
pgbranch remote ls-remote

# Pull if available
pgbranch pull feature-old

Backup Before Pruning

For important branches, push to remote first:

# Push all branches to remote
for branch in $(pgbranch branch); do
  pgbranch push "$branch" --force
done

# Then prune locally
pgbranch prune -d 7 -y

Troubleshooting

Cannot Prune Current Branch

Error: cannot prune current branch

Switch to a different branch first:

pgbranch checkout main
pgbranch prune

Database Connection Error

Error: could not connect to database

Ensure PostgreSQL is running and accessible.

Permission Denied

Error: permission denied to drop database

Your PostgreSQL user needs DROP DATABASE permission.

Related Commands

• delete - Delete specific branches
• branch - List branches
• log - View branch details
• push - Backup before pruning