Git Worktree Manager

A shell-agnostic Ruby gem for managing git worktrees with isolated databases, unique ports for Rails and Vite servers, and separate environments.

Features

• ✅ Shell Agnostic - Works with bash, zsh, fish, or any POSIX shell
• ✅ Isolated Databases - Each worktree gets its own PostgreSQL database
• ✅ Automatic Port Assignment - Rails (3001+) and Vite (5174+) ports
• ✅ Environment Management - Copies and configures .env files
• ✅ Dependency Installation - Auto-runs bundle/yarn install
• ✅ Easy Cleanup - Remove worktrees and databases with one command

Installation

Add to your Gemfile:

gem 'git_worktree_manager'

Then run:

bundle install
rails generate git_worktree_manager:install

This will install the worktree command in your project's bin/ directory.

Shell Function (for cd functionality)

Add this to your shell config file:

For Bash/Zsh (~/.bashrc or ~/.zshrc):

worktree() {
  ./bin/worktree "$@"
  if [ -f /tmp/worktree_cd_$$ ]; then
    cd "$(cat /tmp/worktree_cd_$$)"
    rm /tmp/worktree_cd_$$
  fi
}

For Fish (~/.config/fish/config.fish):

function worktree
  ./bin/worktree $argv
  if test -f /tmp/worktree_cd_(echo %self)
    cd (cat /tmp/worktree_cd_(echo %self))
    rm /tmp/worktree_cd_(echo %self)
  end
end

Configuration

On first use, the gem will auto-detect your main database name from config/database.yml or .env files. You can view or change the configuration:

worktree config
worktree config --main-database=myapp_development
worktree config --database-prefix=myapp

The configuration is stored in .worktree_config.yml in your project root.

Usage

worktree create feature-branch-name
worktree list
worktree status feature-branch-name
worktree start feature-branch-name
worktree remove feature-branch-name
worktree cleanup
worktree config

Options

Create:

• --copy-data - Copy data from main database to worktree database
• --no-install - Skip bundle/yarn install

Requirements

• Ruby >= 3.0.0
• Git
• PostgreSQL (optional, only if using database features)
• Rails project

Recommendations

Add .worktree_config.yml to your .gitignore if you don't want to share worktree configuration with your team:

echo ".worktree_config.yml" >> .gitignore

License

MIT License