dsh-worktrees

Readme

# DSH Worktrees

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

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

![Worktrees showcase](docs/worktrees-showcase.png)

## 功能

### 设置入口

安装后会在 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

创建区支持三种模式。

#### 新分支

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

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

实际执行类似：

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

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

#### 已有分支 / 引用

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

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

实际执行类似：

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

#### Detach

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

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

实际执行类似：

```powershell
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 自带命令：

```powershell
git worktree remove <path>
```

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

```powershell
git worktree remove --force <path>
```

主 worktree 不允许删除。

### Prune

页面里的 `Prune` 会执行：

```powershell
git worktree prune
```

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

## 安装

在插件目录里执行：

```powershell
dsh plugin --profile web add .
```

或者：

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

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

## 使用前确认

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

```powershell
git --version
```

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

## 安全边界

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

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

## 项目结构

```text
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