# 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-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Worktree Assistant

中文 | [English](#english)

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

## 中文

### 这是什么

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

Worktree Assistant 把这些操作直接放进 VS Code Explorer 里，尽量减少命令行切换。

### 主要功能

- 在 Explorer 中查看当前工作区关联仓库下的所有 worktree
- 快速创建新 worktree，支持基于新分支或已有本地分支创建
- 右键打开 worktree、在终端中打开、复制项目路径、在系统文件管理器中定位
- 删除 worktree，并在存在未提交或未跟踪文件时提供强制删除入口
- 清理无效 worktree 元数据（Prune）
- 修复 worktree 元数据（Repair）
- 为每个 worktree 维护独立的 TODO 列表，支持子任务、排序、完成、取消、恢复
- 创建后或手动同步私有文件/目录，例如 `.env.local`、`config/private` 等
- 支持中英文运行时语言切换

### 使用前提

- 已安装 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。

### 视图中的常用操作

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

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

说明：

- 单击 worktree 节点不会直接打开目录，而是保留树节点的展开/收起行为
- 只有存在 TODO 子项的 worktree 才会显示展开箭头

### 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` 手动再次同步。

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

### 设置项

扩展提供以下设置：

- `worktreeAssistant.displayLanguage`
  - 控制扩展运行时提示语言
  - 可选：`auto`、`zh-CN`、`en`
- `worktreeAssistant.createBaseDir`
  - 新建 worktree 时的默认父目录
  - 留空时，默认使用仓库根目录的上一级目录
- `worktreeAssistant.openAfterCreate`
  - 创建完成后是否立即在新窗口打开该 worktree
- `worktreeAssistant.privateFiles`
  - 需要同步的私有文件或目录列表
  - 路径相对于仓库根目录
- `worktreeAssistant.autoSyncPrivateFiles`
  - 创建新 worktree 后是否自动进入私有文件选择并执行同步

### 适合的使用场景

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

### 注意事项

- 删除 worktree 本质上会调用 Git 的 `worktree remove`
- 如果目标 worktree 中存在未提交或未跟踪文件，Git 可能拒绝删除；此时扩展会提示你是否强制删除
- 私有文件同步仅复制你选择的路径，不会自动推断敏感文件
- `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, sync private files, and keep 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
- 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
- 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

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

### Common Actions

Right-click a worktree node to access:

- `Open Worktree`
- `Open in Terminal`
- `Copy Project Path`
- `Sync Private Files`
- `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

### 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.

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

### 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
- 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
- `displayLanguage` affects extension runtime text only; static VS Code contribution text still follows the VS Code display language