Back to Details

worktree

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Worktree for Rails

适用于Rails的Git Worktree

Create isolated git worktrees for feature development with automatic Rails credential symlinking.
为功能开发创建独立的git工作树，并自动处理Rails凭证的符号链接。

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.
工作树会创建在同级目录中，以保持项目根目录整洁：
parent/
  project/              # 主仓库
  project-worktrees/    # 工作树容器
    25-01-22-feature/   # 单个工作树
容器目录相对于项目根目录为
../<project-name>-worktrees/
。

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
格式：
YY-MM-DD-feature-description
示例：
  • 25-01-22-add-password-reset
  • 25-01-22-fix-api-timeout
  • 25-01-22-refactor-auth-module

Workflow

工作流程

Step 1: Get Feature Name

步骤1：获取功能名称

If no feature name provided, ask:
What feature are you working on? (e.g., "add password reset", "fix checkout bug")
如果未提供功能名称，询问：
你正在开发什么功能？（例如：“添加密码重置功能”、“修复结账bug”）

Step 2: Create Worktree

步骤2：创建工作树

bash
undefined
bash
undefined

Get project info

Get project info

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

Format branch name: YY-MM-DD-feature-description

Format branch name: YY-MM-DD-feature-description

DATE=$(date +%y-%m-%d) BRANCH_NAME="${DATE}-<feature-slug>"
DATE=$(date +%y-%m-%d) BRANCH_NAME="${DATE}-<feature-slug>"

Create worktrees directory if needed

Create worktrees directory if needed

mkdir -p "$WORKTREES_DIR"
mkdir -p "$WORKTREES_DIR"

Create worktree with new branch

Create worktree with new branch

git worktree add "$WORKTREES_DIR/$BRANCH_NAME" -b "$BRANCH_NAME"
undefined
git worktree add "$WORKTREES_DIR/$BRANCH_NAME" -b "$BRANCH_NAME"
undefined

Step 3: Symlink Rails Credentials

步骤3：创建Rails凭证的符号链接

Rails credentials must be symlinked so the worktree can decrypt secrets:
bash
WORKTREE_PATH="$WORKTREES_DIR/$BRANCH_NAME"
Rails凭证需要创建符号链接，这样工作树才能解密密钥：
bash
WORKTREE_PATH="$WORKTREES_DIR/$BRANCH_NAME"

master.key

master.key

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

development.key (if exists)

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
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)

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.
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

符号链接请使用完整的绝对路径。

Step 4: Report Success

步骤4：报告创建成功

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
工作树已创建：
  分支：25-01-22-add-password-reset
  位置：../project-worktrees/25-01-22-add-password-reset

Rails凭证已创建符号链接：
  - config/master.key
  - config/credentials/development.key
  - config/credentials/test.key

开始工作请执行：
  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
列出工作树：
bash
git worktree list
删除工作树：
bash
git worktree remove ../project-worktrees/25-01-22-feature-name
清理过期工作树：
bash
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
用户：创建一个用于添加Stripe Webhooks的工作树

正在创建工作树...
  项目：vc-matcher-app
  功能：添加Stripe Webhooks
  分支：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

正在创建Rails凭证的符号链接...
$ ln -sf /Users/avi/Development/code/project/config/master.key ../vc-matcher-app-worktrees/25-01-22-add-stripe-webhooks/config/master.key
[其他符号链接...]

完成！工作树已准备就绪，路径：
  ../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
  • 凭证的符号链接请始终使用绝对路径
  • 工作树与主仓库共享Git历史
  • 工作树中的提交在主仓库中可见
  • 如果需要，删除工作树后请单独删除分支
  • 如果Gemfile有差异，请在新工作树中运行
    bundle install