wtree

English | 简体中文

wtree 是一个本地工具，用于管理 git worktree。默认是交互式命令行模式，也支持一键启动 UI 页面 (TreeLab) 进行可视化操作。

特性

• 交互式创建与删除 worktree (支持强制删除未提交更改)
• UI 模式本地启动，浏览器可视化管理，支持浅色/深色模式切换以及中英文国际化
• 支持创建新分支、从已有分支/提交创建 worktree
• 支持在系统文件管理器或常用 IDE (Trae, Cursor, VS Code) 中一键打开
• 支持锁定 (Lock) / 解锁 (Unlock) 以及清理 (Prune) 无效的 worktree
• 非交互模式：支持通过命令行参数完全自动化操作，适合脚本和 AI Agent 调用
• 提供 Agent Skill，可被 Trae / Cursor / Claude Code 等 AI 编码工具直接使用
• 本地 API 执行 git 命令，数据不出机器

UI 截图

安装

可以通过 npm 全局安装（如果使用了私有源，请指定官方源）：

npm install -g @fatdoge/wtree --registry=https://registry.npmjs.org/

或者直接使用 npx 运行：

npx --registry=https://registry.npmjs.org/ @fatdoge/wtree

运行与使用

交互式 CLI

在 git 仓库目录中运行：

wtree

直接指定分支名跳过选择：

wtree feature/my-branch

查看 worktree 列表：

wtree list

UI 模式 (TreeLab)

wtree --ui

可选参数：

wtree --ui --repo /path/to/repo
wtree --ui --no-open
wtree --ui --port 0

CLI 参数

• --ui：启动本地 UI
• --repo <path>：指定仓库路径（默认使用当前目录）
• --no-open：不自动打开浏览器
• --port <number>：指定 UI 端口（0 表示自动分配）
• --json：以 JSON 格式输出（适合脚本和 Agent 使用）
• --yes, -y：自动确认所有提示
• --force, -f：强制操作（如强制删除有未提交更改的 worktree）
• --dir <path>：指定 worktree 目录路径（相对于 git 根目录）
• --base <ref>：创建新分支时的基准引用（如 main、origin/main）
• --editor <name>：创建后使用指定编辑器打开（trae、cursor、code、none）
• --no-editor：创建后不打开编辑器
• --no-install：创建后不自动安装依赖

CLI 命令

• wtree：交互式主菜单 (创建/删除/列表/打开/锁定/解锁/清理)
• wtree list：打印 worktree 列表
• wtree create [branch]：创建 worktree（支持交互式选择）
• wtree delete [branch|path ...]：删除 worktree（支持交互式选择和直接指定目标，支持强制删除）
• wtree open [path|branch]：打开 worktree
• wtree lock [path|branch]：锁定指定的 worktree，防止被移动或删除
• wtree unlock [path|branch]：解锁指定的 worktree
• wtree prune：清理本地不存在记录但被 Git 记录的无效 worktree
• wtree config：查看本地配置
• wtree config get <key>：读取配置项
• wtree config set <key> <value>：设置配置项
• wtree help：查看帮助

非交互模式

所有命令都支持通过参数完全非交互地执行，适合在脚本或 AI Agent 中使用：

# 查看 worktree 列表（JSON 输出）
wtree list --json

# 为已有分支创建 worktree
wtree create feature/my-branch --yes --no-editor --no-install --json

# 基于 main 创建新分支的 worktree
wtree create feature/new-thing --base main --yes --dir worktrees/new-thing --no-editor --no-install --json

# 删除指定 worktree
wtree delete feature/old-branch --yes --json

# 强制删除（即使有未提交更改）
wtree delete feature/dirty --yes --force --json

Agent Skill

wtree 提供了 Agent Skill，可以让 AI 编码工具（Trae、Cursor、Claude Code 等）直接管理 git worktree。

安装 Skill

# 安装到当前项目
npx skills add FatDoge/wtree --skill wtree

# 全局安装（所有项目可用）
npx skills add FatDoge/wtree --skill wtree -g

安装后，AI Agent 会自动识别 wtree skill，在你需要管理 worktree 时自动调用。

配置

UI 设置页会将配置写入本地文件：

• macOS/Linux：~/.config/wtree/config.json
• Windows：%USERPROFILE%\.config\wtree\config.json

配置字段：

{
  "baseDir": "worktrees",
  "openCommand": "open",
  "editorCommand": "code"
}

• baseDir：用于 UI 记录默认目录，当前不会自动拼接到创建路径
• openCommand：UI 点击“Folder”打开系统文件管理器时使用的命令（默认按平台使用系统命令，如 macOS 的 open）
• editorCommand：UI 点击“IDE”打开编辑器时使用的命令。若不设置，则会自动检测系统中是否安装了 Trae、Cursor 或 VS Code。

注意：UI 的主题模式（浅色/深色/跟随系统）和语言偏好独立存储在浏览器的 localStorage 中。

开发

pnpm install

常用脚本：

pnpm run wtree
pnpm run dev
pnpm run client:dev
pnpm run server:dev
pnpm run build
pnpm run lint
pnpm run test
pnpm run check

环境变量：

• WTUI_REPO_ROOT：本地 API 服务器运行时使用的 repo 根目录
• PORT：本地 API 服务器端口（默认 3001）

项目结构

• api/：CLI + 本地 API（git 执行与配置读写）
• src/：UI（React + Vite + Tailwind）
• shared/：前后端共享类型
• skills/：Agent Skill 定义