Git Hooks

pgbranch can install a git hook that automatically switches database branches when you switch git branches.

How It Works

When you switch git branches with git checkout or git switch, the post-checkout hook runs pgbranch checkout <branch-name>.

git checkout feature-auth
        │
        ▼
    post-checkout hook
        │
        ▼
pgbranch checkout feature-auth
        │
        ▼
Database now matches git branch

If a matching pgbranch branch doesn’t exist, the hook silently continues without error.

Installing the Hook

pgbranch hook install

Output:

Git hook installed successfully!
Database branches will now switch automatically with git branches.

This creates a post-checkout script in .git/hooks/.

Uninstalling the Hook

pgbranch hook uninstall

Output:

Git hook removed.

How the Hook Works

The installed hook script:

#!/bin/sh
# pgbranch post-checkout hook

# Get the new branch name
BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)

# Skip if not on a branch (e.g., detached HEAD)
if [ -z "$BRANCH" ]; then
  exit 0
fi

# Try to checkout the matching pgbranch branch
pgbranch checkout "$BRANCH" 2>/dev/null || true

Key behaviors:

• Runs after every git checkout
• Silently fails if no matching branch exists
• Doesn’t block git operations on error

Branch Naming Strategy

For automatic switching to work well, use matching names:

# Git branch
git checkout -b feature-user-auth

# pgbranch branch (same name)
pgbranch branch feature-user-auth

Naming Convention Tips

Git Branch	pgbranch Branch
main	main
develop	develop
feature/user-auth	feature-user-auth
feature/api-v2	feature-api-v2

Note

If your git branches use / (like feature/name), create pgbranch branches with - instead (like feature-name), as / can cause issues in database names.

Workflow Example

Initial Setup

# Initialize pgbranch
pgbranch init -d myapp_dev

# Create main branch from clean state
git checkout main
pgbranch branch main

# Install the hook
pgbranch hook install

Daily Workflow

# Start feature work
git checkout -b feature-new-api
# (hook runs, but no pgbranch branch exists yet)

# Create database branch
pgbranch branch feature-new-api

# Work on feature, make changes...

# Switch to fix a bug on main
git checkout main
# Hook automatically runs: pgbranch checkout main
# Database is now in main state!

# Back to feature
git checkout feature-new-api
# Hook automatically runs: pgbranch checkout feature-new-api
# Database restored to feature state!

Handling Missing Branches

When the hook tries to checkout a non-existent branch:

git checkout feature-new
# Hook: pgbranch checkout feature-new
# pgbranch: branch 'feature-new' doesn't exist (silent)
# Git checkout completes normally

Your git checkout succeeds, and the database stays on the previous branch.

Creating Missing Branches Automatically

You can modify the hook to create branches automatically:

#!/bin/sh
BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
if [ -z "$BRANCH" ]; then
  exit 0
fi

# Try checkout, or create if doesn't exist
if ! pgbranch checkout "$BRANCH" 2>/dev/null; then
  pgbranch branch "$BRANCH" 2>/dev/null || true
fi

Caution

Auto-creating branches can lead to many branches. Use with care.

Existing Hooks

If you already have a post-checkout hook:

pgbranch hook install

Output:

Warning: post-checkout hook already exists
Do you want to:
  1. Append pgbranch to existing hook
  2. Replace existing hook
  3. Cancel

Choice [1/2/3]:

Choose option 1 to keep both hooks working.

Hook Location

The hook is installed at:

.git/hooks/post-checkout

You can edit it manually if needed.

Disabling Temporarily

To skip the hook for one checkout:

git checkout --no-verify main

Or temporarily uninstall:

pgbranch hook uninstall
git checkout main
pgbranch hook install

Performance

The hook adds a small delay to git checkouts:

• Fast (no matching branch): ~50ms
• With branch switch: 1-5 seconds (depends on DB size)

For large databases, consider disabling the hook and switching manually when needed.

Troubleshooting

Hook Not Running

Check if the hook is executable:

ls -la .git/hooks/post-checkout
# Should show: -rwxr-xr-x

Make executable if needed:

chmod +x .git/hooks/post-checkout

Wrong Branch After Checkout

If the database doesn’t match after git checkout:

1. Check if pgbranch branch exists:

   pgbranch branch

2. Manually checkout:

   pgbranch checkout <branch-name>

Hook Errors

If the hook shows errors, check:

1. pgbranch is in PATH
2. pgbranch is initialized in the directory
3. Database is accessible

Integration with CI/CD

In CI/CD environments, you typically don’t want the hook:

# Clone without hooks
git clone --no-checkout repo.git
cd repo
git checkout main

Or disable hooks:

git config core.hooksPath /dev/null

Related Commands

• checkout - Manual branch switching
• branch - Create branches
• status - Check current branch