Push & Pull

Once you have a remote configured, you can push and pull branches to share with your team or sync across machines.

Push Command

Upload a local branch to remote storage.

Usage

pgbranch push <branch> [flags]

Flags

Flag	Short	Description	Default
--remote	-r	Specify remote name	default remote
--force	-f	Overwrite if exists on remote	false
--description	-d	Add a description	-

Examples

Basic Push

pgbranch push main

Output:

Archiving branch 'main'...
Archive size: 45 MB
Uploading to origin...
Upload complete!

Push to Specific Remote

pgbranch push main --remote backup

Push with Description

pgbranch push main --description "Schema v2.1 with user auth"

The description is shown when listing remote branches.

Force Overwrite

pgbranch push main --force

Without --force, pushing an existing branch fails:

Error: branch 'main' already exists on remote 'origin'
Use --force to overwrite

Pull Command

Download a branch from remote storage.

Usage

pgbranch pull <branch> [flags]

Flags

Flag	Short	Description	Default
--remote	-r	Specify remote name	default remote
--as	-	Use different local name	same as remote
--force	-f	Overwrite local branch	false

Examples

Basic Pull

pgbranch pull main

Output:

Downloading 'main' from origin...
Download complete (45 MB)
Extracting archive...
Branch 'main' created

Pull to Different Name

pgbranch pull main --as main-from-remote

Useful when you want to keep your local main and compare with remote.

Pull from Specific Remote

pgbranch pull seed-data --remote team

Force Overwrite Local

pgbranch pull main --force

Without --force, pulling an existing local branch fails:

Error: local branch 'main' already exists
Use --force to overwrite or --as to use a different name

Remote Branch Management

List Remote Branches

pgbranch remote ls-remote

Output:

main
  Pushed: 2024-01-15 10:30:00
  Size: 45 MB
  Description: Schema v2.1 with user auth

feature-auth
  Pushed: 2024-01-16 14:22:00
  Size: 48 MB

seed-data
  Pushed: 2024-01-14 09:00:00
  Size: 52 MB
  Description: Full test dataset

Delete from Remote

pgbranch remote delete <branch> [--remote <name>]

Example:

pgbranch remote delete old-feature --remote origin

This only deletes the remote copy; local branches are unaffected.

Workflow Examples

Team Onboarding

New developer setup:

# Clone the project
git clone https://github.com/team/project.git
cd project

# Initialize pgbranch
pgbranch init -d project_dev

# Pull the seed data branch
pgbranch pull seed-data

# Switch to it
pgbranch checkout seed-data

# Ready to work!

Sharing Feature Work

Share your database state for code review:

# Push your feature branch
pgbranch push feature-new-api --description "New API schema for review"

# Teammate pulls it
pgbranch pull feature-new-api --as review-new-api
pgbranch checkout review-new-api

# They can now test with your exact database state

Multi-Machine Sync

Working across machines:

# End of day at work
pgbranch push wip-feature --force

# At home
pgbranch pull wip-feature --force
pgbranch checkout wip-feature

# Continue working...

# End of day at home
pgbranch push wip-feature --force

Backup Important States

Before risky operations:

# Save to remote before major change
pgbranch push pre-migration --description "Before v3 migration"

# Run migration
npm run migrate

# If it fails badly, you can always recover
pgbranch pull pre-migration --force
pgbranch checkout pre-migration

Transfer Rates

Push and pull speed depends on:

• Database size
• Network bandwidth
• Storage backend latency

Typical times:

Database Size	Compressed	Upload Time*
100 MB	~30 MB	~5 seconds
1 GB	~300 MB	~30 seconds
10 GB	~3 GB	~5 minutes

*Assumes 100 Mbps upload speed

Optimizing Transfer

1. Prune before push: Remove unnecessary data
2. Use regional storage: Pick S3/R2 region close to you
3. Use filesystem remote: For LAN, much faster than cloud

Error Handling

Network Errors

Error: upload failed: connection timeout

• Check network connectivity
• Retry the command
• For large databases, use a stable connection

Storage Quota

Error: upload failed: storage quota exceeded

• Delete old remote branches
• Increase storage quota
• Use lifecycle policies for auto-cleanup

Corrupt Archive

Error: archive verification failed

• Re-push the branch
• If pulling, ask the pusher to re-upload

Best Practices

Naming Conventions

Use consistent branch names across the team:

main              # Production-like schema
seed-data         # Standard test dataset
feature-*         # Feature branches
hotfix-*          # Hotfix branches

Descriptions

Always add descriptions for shared branches:

pgbranch push main --description "v2.1 schema with auth tables"

Regular Cleanup

Periodically clean up remote branches:

# List remote branches
pgbranch remote ls-remote

# Delete old ones
pgbranch remote delete feature-old
pgbranch remote delete feature-completed

Separate Remotes for Different Uses

# Team collaboration
pgbranch remote add team s3://team-bucket/pgbranch

# Personal backup (faster, cheaper)
pgbranch remote add backup /mnt/backup/pgbranch

# Archive (infrequent access)
pgbranch remote add archive s3://archive-bucket/pgbranch

Related Commands

• remote add - Configure remotes
• branch - Manage local branches
• checkout - Switch branches