Git Worktree for Rails

Create isolated git worktrees for feature development with automatic Rails credential symlinking.

When to Use

•Starting work on a new feature that needs isolation
•Working on multiple features simultaneously
•Need a clean environment without stashing changes

Worktree Location

Worktrees are created in a sibling directory to keep the project root clean:

code

parent/
  project/              # main repo
  project-worktrees/    # worktree container
    25-01-22-feature/   # individual worktree

The container directory is ../<project-name>-worktrees/ relative to the project root.

Branch Naming Convention

Format: YY-MM-DD-feature-description

Examples:

•25-01-22-add-password-reset
•25-01-22-fix-api-timeout
•25-01-22-refactor-auth-module

Workflow

Step 1: Get Feature Name

If no feature name provided, ask:

code

What feature are you working on? (e.g., "add password reset", "fix checkout bug")

Step 2: Create Worktree

bash

# Get project info
PROJECT_ROOT=$(pwd)
PROJECT_NAME=$(basename "$PROJECT_ROOT")
WORKTREES_DIR="../${PROJECT_NAME}-worktrees"

# Format branch name: YY-MM-DD-feature-description
DATE=$(date +%y-%m-%d)
BRANCH_NAME="${DATE}-<feature-slug>"

# Create worktrees directory if needed
mkdir -p "$WORKTREES_DIR"

# Create worktree with new branch
git worktree add "$WORKTREES_DIR/$BRANCH_NAME" -b "$BRANCH_NAME"

Step 3: Symlink Rails Credentials

Rails credentials must be symlinked so the worktree can decrypt secrets:

bash

WORKTREE_PATH="$WORKTREES_DIR/$BRANCH_NAME"

# master.key
ln -sf "$PROJECT_ROOT/config/master.key" "$WORKTREE_PATH/config/master.key"

# development.key (if exists)
if [ -f "$PROJECT_ROOT/config/credentials/development.key" ]; then
  mkdir -p "$WORKTREE_PATH/config/credentials"
  ln -sf "$PROJECT_ROOT/config/credentials/development.key" "$WORKTREE_PATH/config/credentials/development.key"
fi

# test.key (if exists)
if [ -f "$PROJECT_ROOT/config/credentials/test.key" ]; then
  mkdir -p "$WORKTREE_PATH/config/credentials"
  ln -sf "$PROJECT_ROOT/config/credentials/test.key" "$WORKTREE_PATH/config/credentials/test.key"
fi

Use full absolute paths for symlinks.

Step 4: Report Success

code

Worktree created:
  Branch: 25-01-22-add-password-reset
  Location: ../project-worktrees/25-01-22-add-password-reset

Rails credentials symlinked:
  - config/master.key
  - config/credentials/development.key
  - config/credentials/test.key

To start working:
  cd ../project-worktrees/25-01-22-add-password-reset

Managing Worktrees

List worktrees:

bash

git worktree list

Remove worktree:

bash

git worktree remove ../project-worktrees/25-01-22-feature-name

Prune stale worktrees:

bash

git worktree prune

Example Session

code

User: create a worktree for adding stripe webhooks

Creating worktree...
  Project: vc-matcher-app
  Feature: adding stripe webhooks
  Branch: 25-01-22-add-stripe-webhooks

$ mkdir -p ../vc-matcher-app-worktrees
$ git worktree add ../vc-matcher-app-worktrees/25-01-22-add-stripe-webhooks -b 25-01-22-add-stripe-webhooks

Symlinking Rails credentials...
$ ln -sf /Users/avi/Development/code/project/config/master.key ../vc-matcher-app-worktrees/25-01-22-add-stripe-webhooks/config/master.key
[additional symlinks...]

Done! Worktree ready at:
  ../vc-matcher-app-worktrees/25-01-22-add-stripe-webhooks

Notes

•Always use absolute paths for credential symlinks
•The worktree shares git history with main repo
•Commits in worktree are visible from main repo
•Delete the branch separately after removing worktree if needed
•Run bundle install in new worktree if Gemfile differs