# worktree-assistant

**Repository Path**: github-9819409/worktree-assistant

## Basic Information

- **Project Name**: worktree-assistant
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-12
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Worktree Assistant

![worktree-assistant](./images/readme/index.png)

中文 | [English](#english)

Worktree Assistant 是一个面向日常开发使用的 VS Code 扩展，用来在侧边栏里集中管理 Git worktree、Worktree 优先级、私有文件同步，以及每个 worktree 自己的 TODO 列表。

## 中文

### 这是什么

如果你经常需要同时处理多个分支，例如修 Bug、开发新功能、对比版本、临时切换任务，Git worktree 可以让你为同一个仓库创建多个独立工作目录，而不需要反复 stash、checkout 或复制项目。

Worktree Assistant 把这些操作直接放进 VS Code Explorer 里，尽量减少命令行切换，并且可以用颜色和标签快速区分当前各个 worktree 的优先级。

### 主要功能

- 在 Explorer 中查看当前工作区关联仓库下的所有 worktree
- 快速创建新 worktree，支持基于新分支或已有本地分支创建
- 为 worktree 设置优先级，并通过颜色图标与标签快速区分紧急程度
- 在内置 `Manage Worktree Priorities` 面板中管理优先级名称、颜色和排序，并与 `settings.json` 双向同步
- 右键打开 worktree、在终端中打开、复制项目路径、在系统文件管理器中定位
- 删除 worktree，并在存在未提交或未跟踪文件时提供强制删除入口
- 清理无效 worktree 元数据（Prune）
- 修复 worktree 元数据（Repair）
- 为每个 worktree 维护独立的 TODO 列表，支持子任务、排序、完成、取消、恢复
- 创建后或手动同步私有文件/目录，例如 `.env.local`、`config/private` 等，也支持临时添加文件、目录或手动输入相对路径
- 支持整个视图与单个 worktree 的 TODO 展开/收起
- 支持中英文运行时语言切换

### 使用前提

- 已安装 Git，并且 `git` 命令可在 VS Code 所在环境中直接使用
- 你打开的文件夹位于 Git 仓库中，或者当前工作区里至少有一个 Git 仓库

### 快速开始

1. 在 VS Code 中安装 `Worktree Assistant`
2. 打开一个 Git 仓库
3. 在 Explorer 中找到 `Worktrees` 视图
4. 点击视图标题栏里的 `Create Worktree`
5. 选择创建方式：
   - `New Branch`：创建新分支并同时创建 worktree
   - `Existing Branch`：基于已有本地分支创建 worktree
6. 确认 worktree 路径
7. 如果开启了私有文件同步，可勾选要同步的文件或目录，也可以在选择器里临时追加文件、目录或手动输入路径

创建完成后，你就可以从侧边栏继续管理这个 worktree。

### 视图中的常用操作

视图标题栏常用操作：

- `Create Worktree`：创建新的 worktree
- `Expand All / Collapse All`：展开或收起所有带 TODO 的 worktree
- `Settings`：打开扩展设置
- `Manage Priorities`：打开优先级管理面板

对 worktree 节点点击右键，可以看到这些常用操作：

- `Open Worktree`：在新窗口打开该 worktree
- `Open in Terminal`：以该 worktree 为当前目录打开 VS Code 集成终端
- `Copy Project Path`：复制该 worktree 的本地路径
- `Set Priority`：为该 worktree 设置优先级
- `Clear Priority`：清除当前优先级
- `Sync Private Files`：手动同步私有文件或目录
- `Expand / Collapse`：展开或收起该 worktree 下的 TODO
- `Add Todo`：给该 worktree 添加待办事项
- `Delete Worktree`：删除该 worktree
- `Reveal in File Explorer`：在系统文件管理器中定位该目录

说明：

- 单击 worktree 节点不会直接打开目录，而是保留树节点的展开/收起行为
- 只有存在 TODO 子项的 worktree 才会显示展开箭头
- 如果设置了优先级，worktree 描述区和图标颜色会一起显示对应优先级信息

### Worktree 优先级

你可以为每个 worktree 单独设置优先级，用来标识任务紧急程度。

- 默认提供四种优先级：`紧急`、`急`、`正常`、`低`
- 优先级会显示在 worktree 的描述信息里
- 如果优先级配置了颜色，树视图图标会同步显示对应颜色
- 优先级分配会按仓库根目录和 worktree 路径持久化保存

管理方式有两种：

- 在单个 worktree 上使用 `Set Priority / Clear Priority`
- 通过标题栏的 `Manage Priorities` 打开面板，统一管理优先级选项

在 `Manage Priorities` 面板中，你可以：

- 新增优先级
- 修改优先级名称
- 设置或清空十六进制颜色
- 调整优先级顺序
- 删除优先级（删除前会弹出确认）
- 一键恢复默认优先级配置

面板中的修改会直接回写到 `worktreeAssistant.worktreePriorityOptions`，如果你手动编辑 `settings.json`，面板也会立即同步最新结果。

### TODO 列表怎么用

每个 worktree 都可以维护一份独立 TODO 列表，适合记录当前分支要做的事情。

- `Add Todo`：新增一级任务
- `Add Sub-todo`：新增子任务
- 勾选复选框：标记完成或恢复为未完成
- `Cancel Todo`：将任务标记为取消
- `Resume Todo`：把已完成或已取消任务恢复为进行中
- `Move Up / Move Down`：调整同级任务顺序
- `Delete Todo`：删除任务及其子任务

父任务的状态会根据子任务自动同步。

### 私有文件同步

很多项目会有不适合提交到仓库的本地文件，例如：

- `.env.local`
- `.npmrc`
- `config/private`
- `secrets/dev.json`

你可以把这些路径配置到扩展设置里。创建新 worktree 时，扩展会让你选择要复制哪些文件；之后也可以通过 `Sync Private Files` 手动再次同步。

在选择器里：

- 设置中的 `privateFiles` 会默认勾选
- 可以临时从文件选择器追加文件
- 可以临时从目录选择器追加目录
- 也可以手动输入相对仓库根目录的路径，多个路径支持逗号、分号或换行分隔

路径需要相对于仓库根目录填写。

### 设置项

扩展提供以下设置：

- `worktreeAssistant.displayLanguage`
  - 控制扩展运行时提示语言
  - 可选：`auto`、`zh-CN`、`en`
- `worktreeAssistant.createBaseDir`
  - 新建 worktree 时的默认父目录
  - 留空时，默认使用仓库根目录的上一级目录
- `worktreeAssistant.openAfterCreate`
  - 创建完成后是否立即在新窗口打开该 worktree
- `worktreeAssistant.privateFiles`
  - 需要同步的私有文件或目录列表
  - 路径相对于仓库根目录
- `worktreeAssistant.autoSyncPrivateFiles`
  - 创建新 worktree 后是否自动进入私有文件选择并执行同步
- `worktreeAssistant.worktreePriorityOptions`
  - 配置 worktree 可选优先级列表
  - 每项支持 `id`、`label`、`color`
  - `color` 留空时使用默认图标颜色
  - 默认包含 `紧急 / 急 / 正常 / 低` 四种优先级

### 适合的使用场景

- 同时开发多个功能分支
- 修复线上问题时临时拉起独立目录
- 对比不同分支代码而不打断当前工作
- 给不同分支维护不同的待办清单
- 用颜色快速区分当前多个分支的优先级
- 快速复制本地私有配置到新 worktree

### 注意事项

- 删除 worktree 本质上会调用 Git 的 `worktree remove`
- 如果目标 worktree 中存在未提交或未跟踪文件，Git 可能拒绝删除；此时扩展会提示你是否强制删除
- 私有文件同步仅复制你选择的路径，不会自动推断敏感文件
- 优先级选项来自 `worktreeAssistant.worktreePriorityOptions`，已有 worktree 上保存的是优先级 `id`
- `displayLanguage` 只影响扩展运行时文本；VS Code 菜单中的静态文案仍跟随 VS Code 本身的显示语言

---

## English

### What It Does

Worktree Assistant is a VS Code extension for everyday development. It helps you manage Git worktrees, worktree priorities, private file sync, and a separate TODO list for each worktree directly from the Explorer sidebar.

If you often switch between feature work, bug fixes, release patches, or temporary experiments, Git worktrees let you keep multiple working directories for the same repository without constantly stashing or checking out branches.

### Key Features

- View all worktrees for the repositories detected in the current workspace
- Create a new worktree from either a new branch or an existing local branch
- Assign priorities to worktrees and distinguish them with labels and colored icons
- Manage priority labels, colors, and order in the built-in `Manage Worktree Priorities` panel, with two-way sync to `settings.json`
- Open a worktree, open it in the integrated terminal, copy its path, or reveal it in the OS file explorer
- Delete a worktree, with a force-delete retry when Git blocks removal because of modified or untracked files
- Prune invalid worktree metadata
- Repair worktree metadata
- Keep a separate TODO list for each worktree, including subtasks, reordering, done/cancel/resume states
- Sync private files or folders after creation or on demand, including temporary file or folder picks and manual relative-path input
- Expand or collapse TODOs for the whole view or a single worktree
- Switch runtime language between Chinese and English

### Requirements

- Git must be installed and available from the environment where VS Code runs
- Your opened folder must belong to a Git repository, or your workspace must contain at least one Git repository

### Quick Start

1. Install `Worktree Assistant`
2. Open a Git repository in VS Code
3. Find the `Worktrees` view in Explorer
4. Click `Create Worktree` in the view title bar
5. Choose how to create it:
   - `New Branch`: create a new branch and a new worktree together
   - `Existing Branch`: create a worktree from an existing local branch
6. Confirm the target path
7. If private file sync is enabled, select the files or folders you want to copy, or temporarily add extra paths in the picker

After that, you can continue managing the worktree from the sidebar.

### Common Actions

Common view toolbar actions:

- `Create Worktree`
- `Expand All / Collapse All`
- `Settings`
- `Manage Priorities`

Right-click a worktree node to access:

- `Open Worktree`
- `Open in Terminal`
- `Copy Project Path`
- `Set Priority`
- `Clear Priority`
- `Sync Private Files`
- `Expand / Collapse`
- `Add Todo`
- `Delete Worktree`
- `Reveal in File Explorer`

Notes:

- Single-click does not open a worktree directly; it keeps the normal expand/collapse behavior of the tree
- A worktree only shows an expand arrow when it has TODO children
- When a priority is set, its label appears in the description and its color can be reflected in the tree icon

### Worktree Priorities

Each worktree can have its own priority so you can quickly spot what matters most.

- Four default priorities are provided: `Urgent`, `High`, `Normal`, and `Low`
- The selected priority appears in the worktree description
- If a priority has a color, the tree icon uses that color as well
- Priority assignments are persisted per repository root and worktree path

You can manage priorities in two ways:

- Use `Set Priority / Clear Priority` on an individual worktree
- Open `Manage Priorities` from the view toolbar to edit the available options

Inside the `Manage Worktree Priorities` panel, you can:

- Add new priorities
- Rename priorities
- Set or clear hex colors
- Reorder priorities
- Delete priorities with a confirmation dialog
- Restore the default priority set

Changes made there are written back to `worktreeAssistant.worktreePriorityOptions`, and manual edits in `settings.json` are reflected in the panel immediately.

### TODO Lists

Each worktree can have its own TODO list so you can track branch-specific work.

- `Add Todo`: add a top-level task
- `Add Sub-todo`: add a child task
- Toggle the checkbox: mark done or move back to pending
- `Cancel Todo`: mark a task as cancelled
- `Resume Todo`: move a done or cancelled task back to pending
- `Move Up / Move Down`: reorder tasks within the same level
- `Delete Todo`: remove a task and its child tasks

Parent task status is synchronized automatically based on child task states.

### Private File Sync

This is useful for local-only files or folders such as:

- `.env.local`
- `.npmrc`
- `config/private`
- `secrets/dev.json`

Add those paths in the extension settings. When you create a new worktree, the extension can prompt you to choose which private files to copy. You can also run `Sync Private Files` later at any time.

Inside the picker:

- Items from `privateFiles` are selected by default
- You can temporarily add extra files from a file picker
- You can temporarily add folders from a folder picker
- You can manually enter relative repository paths, separated by commas, semicolons, or new lines

Paths should be configured relative to the repository root.

### Settings

- `worktreeAssistant.displayLanguage`
  - Runtime language used by the extension
  - Options: `auto`, `zh-CN`, `en`
- `worktreeAssistant.createBaseDir`
  - Default parent directory for new worktrees
  - If empty, the parent of the repository root is used
- `worktreeAssistant.openAfterCreate`
  - Open the newly created worktree in a new window immediately
- `worktreeAssistant.privateFiles`
  - List of private files or folders to sync
  - Paths are relative to the repository root
- `worktreeAssistant.autoSyncPrivateFiles`
  - Automatically prompt for and sync private files after creating a new worktree
- `worktreeAssistant.worktreePriorityOptions`
  - Configures the available worktree priority options
  - Each item supports `id`, `label`, and `color`
  - Leave `color` empty to use the default icon color
  - Defaults to `Urgent / High / Normal / Low`

### Good Fit For

- Working on multiple branches at the same time
- Spinning up an isolated directory for urgent fixes
- Comparing branches without interrupting your current work
- Keeping different TODO lists for different branches
- Visually separating urgent and low-priority branches in the sidebar
- Copying local-only configuration into a new worktree quickly

### Notes

- Deleting a worktree ultimately runs Git's `worktree remove`
- If the target worktree contains modified or untracked files, Git may refuse to remove it; the extension will then offer a force-delete option
- Private file sync only copies the paths you choose
- Priority options come from `worktreeAssistant.worktreePriorityOptions`, while saved worktree assignments reference the priority `id`
- `displayLanguage` affects extension runtime text only; static VS Code contribution text still follows the VS Code display language