super-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

super-worktree

A skill for managing isolated git worktrees for parallel feature development with monorepo-aware env file copying and node_modules symlinking.

一款用于管理独立Git工作树的工具，支持并行功能开发，可感知单体仓库并自动复制环境文件、创建node_modules符号链接。

Worktree Creation Overview

工作树创建概述

Git worktrees let you work on multiple branches simultaneously in a single repository. This skill enhances worktrees with:

Sensitive file copying: Automatically copies
```
.env
```
, credentials, and other sensitive files to new worktrees
node_modules symlinking: Saves disk space by symlinking
```
node_modules
```
directories
Configurable patterns: Define custom sync patterns per-project or globally
Dev tool trust: Automatically trusts Mise/direnv baseline when symlinking

Git工作树允许你在单个仓库中同时处理多个分支。本工具为工作树增加了以下增强功能：

敏感文件复制：自动将
```
.env
```
、凭证及其他敏感文件复制到新工作树
node_modules符号链接：通过创建
```
node_modules
```
目录的符号链接节省磁盘空间
可配置规则：按项目或全局定义自定义同步规则
开发工具信任：创建符号链接时自动信任Mise/direnv基准配置

Creating a worktree

创建工作树

bash

bash scripts/worktree-manager.sh create <branch> [from-branch] [--config <file>]

Parameters:

```
<branch>
```
- Name of the new branch/worktree (required)
```
[from-branch]
```
- Base branch to create from (defaults to
```
origin/HEAD
```
or
```
main
```
)
```
--config <file>
```
- Path to custom config file (optional)

Example:

bash

undefined

bash

bash scripts/worktree-manager.sh create <branch> [from-branch] [--config <file>]

参数说明：

```
<branch>
```
- 新分支/工作树的名称（必填）
```
[from-branch]
```
- 创建分支的基准分支（默认值为
```
origin/HEAD
```
或
```
main
```
）
```
--config <file>
```
- 自定义配置文件路径（可选）

示例：

bash

undefined

Create feature branch from main

从main分支创建功能分支

bash scripts/worktree-manager.sh create feature/new-login

Create from develop branch with custom config

使用自定义配置从develop分支创建

bash scripts/worktree-manager.sh create feature/payments --config .super-worktree.json

Create from a specific commit

从指定提交创建热修复分支

bash scripts/worktree-manager.sh create hotfix/urgent fix/abc123

undefined

bash scripts/worktree-manager.sh create hotfix/urgent fix/abc123

undefined

Deleting a worktree

删除工作树

bash

bash scripts/worktree-manager.sh delete <branch>

Removes the worktree and optionally deletes the branch (use with caution).

Example:

bash

bash scripts/worktree-manager.sh delete feature/new-login

bash

bash scripts/worktree-manager.sh delete <branch>

移除工作树，可选择删除对应分支（谨慎使用）。

示例：

bash

bash scripts/worktree-manager.sh delete feature/new-login

Cleaning up (merge)

清理（合并）

bash

bash scripts/worktree-manager.sh merge <branch>

Merges the branch into its upstream and then deletes the worktree. Use when feature is complete.

Example:

bash

bash scripts/worktree-manager.sh merge feature/new-login

bash

bash scripts/worktree-manager.sh merge <branch>

将分支合并到上游分支后删除工作树，适用于功能开发完成时。

示例：

bash

bash scripts/worktree-manager.sh merge feature/new-login

Configuration

配置

Create a

super-worktree.json

in your project root for custom patterns:

json

{
  "sync": {
    "copyFiles": [
      ".env",
      ".env.*",
      ".envrc",
      ".local.*",
      "*.secret",
      "*.key",
      ".secrets.*",
      "credentials.json",
      "credentials.yml",
      "credentials.env",
      "auth.json",
      "auth.yml",
      "auth.env",
      ".dev.vars",
      ".prod.vars",
      ".staging.vars"
    ],
    "symlinkDirs": [
      "node_modules"
    ],
    "exclude": [
      "node_modules",
      ".git",
      "dist",
      "build",
      ".next",
      "out",
      "coverage",
      ".turbo",
      ".vercel",
      ".worktrees"
    ]
  }
}

在项目根目录创建

super-worktree.json

文件来定义自定义规则：

json

{
  "sync": {
    "copyFiles": [
      ".env",
      ".env.*",
      ".envrc",
      ".local.*",
      "*.secret",
      "*.key",
      ".secrets.*",
      "credentials.json",
      "credentials.yml",
      "credentials.env",
      "auth.json",
      "auth.yml",
      "auth.env",
      ".dev.vars",
      ".prod.vars",
      ".staging.vars"
    ],
    "symlinkDirs": [
      "node_modules"
    ],
    "exclude": [
      "node_modules",
      ".git",
      "dist",
      "build",
      ".next",
      "out",
      "coverage",
      ".turbo",
      ".vercel",
      ".worktrees"
    ]
  }
}

Config Priority

配置优先级

Configuration is loaded in this order (later overrides earlier):

Built-in defaults - Always available
Global config -
```
~/.config/super-worktree/config.json
```
Project config -
```
.super-worktree.json
```
in repo root
CLI flag -
```
--config <file>
```
argument (highest priority)

配置按以下顺序加载（后续配置会覆盖之前的）：

内置默认值 - 始终生效
全局配置 -
```
~/.config/super-worktree/config.json
```
项目配置 - 仓库根目录下的
```
.super-worktree.json
```
CLI参数 -
```
--config <file>
```
参数（优先级最高）

JSON Schema

A JSON Schema is provided for config validation:

json

{
  "$schema": "./schemas/super-worktree.schema.json",
  "sync": {
    "copyFiles": [".env", ".env.local"],
    "symlinkDirs": ["node_modules", ".pnpm-store"],
    "exclude": ["dist", "build"]
  }
}

提供了JSON Schema用于配置验证：

json

{
  "$schema": "./schemas/super-worktree.schema.json",
  "sync": {
    "copyFiles": [".env", ".env.local"],
    "symlinkDirs": ["node_modules", ".pnpm-store"],
    "exclude": ["dist", "build"]
  }
}

Default Patterns

默认规则

The skill includes sensible defaults that cover most projects:

本工具包含适用于大多数项目的合理默认规则：

copyFiles (copied to worktree)

copyFiles（复制到工作树的文件）

```
.env
```
,
```
.env.*
```
- Environment files
```
.envrc
```
- direnv config
```
.local.*
```
- Local overrides
```
*.secret
```
,
```
*.key
```
,
```
.secrets.*
```
- Secret files

credentials.json

credentials.yml

credentials.env

- Credentials

```
auth.json
```
,
```
auth.yml
```
,
```
auth.env
```
- Auth config
```
.dev.vars
```
,
```
.prod.vars
```
,
```
.staging.vars
```
- Environment-specific vars

```
.env
```
,
```
.env.*
```
- 环境文件
```
.envrc
```
- direnv配置文件
```
.local.*
```
- 本地覆盖配置
```
*.secret
```
,
```
*.key
```
,
```
.secrets.*
```
- 密钥文件

credentials.json

credentials.yml

credentials.env

- 凭证文件

```
auth.json
```
,
```
auth.yml
```
,
```
auth.env
```
- 认证配置
```
.dev.vars
```
,
```
.prod.vars
```
,
```
.staging.vars
```
- 环境特定变量文件

symlinkDirs (symlinked to save space)

symlinkDirs（创建符号链接以节省空间的目录）

```
node_modules
```
- Node dependencies

```
node_modules
```
- Node依赖目录

exclude (not copied or symlinked)

exclude（不复制也不创建符号链接的内容）

node_modules

.git

dist

build

.next

out

coverage

.turbo

.vercel

.worktrees

node_modules

.git

dist

build

.next

out

coverage

.turbo

.vercel

.worktrees

Troubleshooting

故障排除

"worktree already exists"

The branch already has a worktree. Delete it first:

bash

bash scripts/worktree-manager.sh delete <branch>

该分支已存在对应的工作树，请先删除：

bash

bash scripts/worktree-manager.sh delete <branch>

"jq not found"

The script uses

jq

for JSON parsing. Install with:

bash

undefined

脚本使用

jq

进行JSON解析，请安装：

bash

undefined

macOS

brew install jq

Ubuntu/Debian

sudo apt install jq

CentOS/RHEL

sudo yum install jq

undefined

sudo yum install jq

undefined

"python3 not found"

Fallback JSON parser requires Python 3. Ensure it's installed:

bash

undefined

备用JSON解析器需要Python 3，请确保已安装：

bash

undefined

Verify

验证版本

python3 --version

Install (macOS)

安装（macOS）

brew install python3

Install (Ubuntu)

安装（Ubuntu）

sudo apt install python3

undefined

sudo apt install python3

undefined

"cannot stat: No such file or directory"

The base branch or reference doesn't exist. Verify:

bash

git branch -a
git log --oneline -5

基准分支或引用不存在，请验证：

bash

git branch -a
git log --oneline -5

Permission denied

Make the script executable:

bash

chmod +x scripts/worktree-manager.sh

为脚本添加可执行权限：

bash

chmod +x scripts/worktree-manager.sh

symlink fails with "File exists"

Remove existing

node_modules

in worktree first:

bash

rm -rf .worktrees/<branch>/node_modules
bash scripts/worktree-manager.sh create <branch>

先删除工作树中已存在的

node_modules

：

bash

rm -rf .worktrees/<branch>/node_modules
bash scripts/worktree-manager.sh create <branch>

Installation

安装

Using npx (recommended)

使用npx（推荐）

bash

npx skills add owner/super-worktree

Note: This requires the skill to be published to npm or available in your skills directory.

bash

npx skills add owner/super-worktree

注意：此方式要求该工具已发布到npm或在你的工具目录中可用。

Manual installation

手动安装

Copy the skill files to your skills directory:

bash

undefined

将工具文件复制到你的工具目录：

bash

undefined

Find your skills directory

查找工具目录

ls -la ~/.config/opencode/skills/

Copy files

复制文件

cp -r super-worktree ~/.config/opencode/skills/

undefined

cp -r super-worktree ~/.config/opencode/skills/

undefined

Verify installation

验证安装

bash

bash scripts/worktree-manager.sh help

bash

bash scripts/worktree-manager.sh help

Requirements

要求

Git 2.5+ (worktree support)
Bash 4.0+
```
jq
```
(optional, for JSON config; Python 3 fallback available)
```
python3
```
(optional, for JSON config fallback)

(End of file - total 254 lines)

Git 2.5+（支持工作树功能）
Bash 4.0+
```
jq
```
（可选，用于JSON配置；提供Python 3作为备用解析器）
```
python3
```
（可选，作为JSON配置的备用解析器）

(End of file - total 254 lines)