lwklbb / dsh-worktrees

DSH Worktrees

一个给 DSH 用的 Git worktree 管理插件。入口在设置面板里的 Worktrees，会从当前 DSH 工作区扫描 Git 仓库，然后集中查看和管理这些仓库下面的 worktree。

我做这个主要是为了方便在 DSH 里同时处理同一个项目的多个分支：比如主线留在 main，另外开一个 feature/order-export 的 worktree 做功能开发，再开一个 fix/login-redirect 的 worktree 修线上问题。这样不用来回 stash，也不用频繁切分支。

功能

设置入口

安装后会在 DSH 设置面板里多一个 Worktrees 选项。页面会读取当前 DSH 的 Workspaces，然后只显示其中能识别为 Git 仓库的项目。普通文件夹会直接跳过，不会显示红色报错。

仓库扫描

插件会对当前 DSH Workspaces 做一次扫描：

• 识别每个 workspace 是否属于 Git 仓库；
• 同一个仓库如果被多个 workspace 命中，只保留一份；
• 展示仓库根目录、已有 worktree 数量、分支数量；
• 非 Git 目录静默忽略；
• Git 没装或不在 PATH 中时，会给出提示。

Worktree 列表

选中一个仓库后，可以看到该仓库下的 worktree：

• worktree 目录名；
• 完整路径；
• 当前分支；
• detached 状态；
• 是否是主 worktree；
• clean / changed 状态；
• ahead / behind 信息；
• 是否已经加入 DSH 工作区。

创建 worktree

创建区支持三种模式。

新分支

适合从当前主线开一个新功能分支：

目录名：feature-order-export
模式：新分支
分支名 / 引用：feature/order-export
起点：HEAD 或 origin/main

实际执行类似：

git worktree add -b feature/order-export ..\feature-order-export origin/main

如果不填分支名，会用目录名作为分支名。

已有分支 / 引用

适合把已经存在的分支 checkout 到单独目录：

目录名：fix-login-redirect
模式：已有分支 / 引用
分支名 / 引用：fix/login-redirect

实际执行类似：

git worktree add ..\fix-login-redirect fix/login-redirect

Detach

适合临时查看某个 commit、tag 或远端引用，不想创建本地分支：

目录名：review-v1.2.0
模式：Detach
起点：v1.2.0

实际执行类似：

git worktree add --detach ..\review-v1.2.0 v1.2.0

创建后加入 DSH 工作区

默认勾选 创建后加入 DSH 工作区。创建成功后，插件会调用 DSH 的 workspace 接口，把新 worktree 目录加入 DSH，这样左侧工作区里可以直接打开。

如果只想创建 Git worktree，不想加入 DSH，可以取消勾选。

打开目录

每个 worktree 都有 打开 按钮，会通过 DSH 的 openPath 打开对应目录。

删除 worktree

非主 worktree 可以删除。插件使用 Git 自带命令：

git worktree remove <path>

默认不强制删除，所以如果 worktree 里有未提交改动，Git 会拒绝。确实要删时，可以勾选 强制删除，这时会执行：

git worktree remove --force <path>

主 worktree 不允许删除。

Prune

页面里的 Prune 会执行：

git worktree prune

用于清理已经不存在的 worktree 记录。

安装

在插件目录里执行：

dsh plugin --profile web add .

或者：

dsh -- plugin --profile web add D:\desktop\plugins-test\dsh-worktrees

安装后重启或刷新 DSH，打开设置面板，可以看到 Worktrees。

使用前确认

这个插件依赖本机 Git 命令行：

git --version

如果 DSH 运行环境找不到 Git，页面会提示 Git 不可用。确认 Git 已安装，并且 git 在 PATH 中即可。

安全边界

这个插件不会自己递归删除目录。删除 worktree 时走的是 Git 官方命令，让 Git 判断是否允许删除。

另外，扫描时只会读取 DSH 当前 Workspaces 的路径，不会主动扫描整块磁盘。

项目结构

dsh-worktrees/
├─ cordis.patch.yml
├─ lib/
│  ├─ index.js      # host API，注册 /worktrees/api/*
│  ├─ git.js        # Git 命令调用、worktree 解析和安全校验
│  └─ client.js     # Settings 页面 UI
├─ test/
│  └─ git.test.mjs
├─ docs/
│  └─ worktrees-showcase.png
├─ package.json
├─ LICENSE
└─ README.md

DSH 接入方式

lib/index.js 是 host 侧入口，注册了 /worktrees/api/*：

• list：扫描 DSH workspace 路径里的 Git 仓库和 worktree；
• branches：列出仓库分支；
• create：创建 worktree；
• remove：删除 worktree；
• prune：清理失效 worktree 记录。

lib/client.js 通过 settings.section slot 增加 Settings 页面，id 是 worktrees。

lib/git.js 里是纯 Node 逻辑，主要处理：

• git worktree list --porcelain 解析；
• 非 Git 目录过滤；
• worktree 目录名和分支名的简单安全校验；
• git status --porcelain=v1 -b 状态摘要；
• 创建 / 删除 / prune 命令封装。

License

MIT © 2026 lwklbb