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:

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:

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

Step 2: Create Worktree

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:

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

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:

git worktree list

Remove worktree:

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

Prune stale worktrees:

git worktree prune

Example Session

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