Introduction

When handling multiple parallel tasks in DSH, if tasks share the same repository workspace, issues such as change pollution, unclear merge targets, and inconsistent cleanup are prone to occur. JohnXu22786/worktree-mgr is a dsh plugin that automatically creates isolated git worktree workspaces for tasks and manages the entire lifecycle of creation, synchronization, and cleanup.

Positioning

This plugin is maintained by JohnXu22786 and is licensed under MIT. It provides task-isolated workspaces for dsh, preventing parallel tasks from polluting the main workspace. The plugin provides 5 model tools and 1 CLI, and supports --json structured output. The runtime environment requires node >= 21, is pure Node ESM, and has no build steps.

Core Capabilities

  • Task-driven: Automatically generates branch names, workspace paths, and ledger records based on the task name.
  • Safe branch names: Normalizes task names into slugs and performs double ref validity checks; refuses creation if different tasks derive the same slug.
  • Uncommitted changes detection: Refuses to merge if the base branch has uncommitted changes; automatically snapshots commits in the task workspace by default.
  • Merge target consistency: Validates that the main workspace’s current branch matches the ledger base branch, and the task workspace’s current branch matches the ledger task branch; refuses operations if inconsistent.
  • Separation of sync and finish: wtm_merge only merges; wtm_finish commits, merges, deletes the workspace, deletes the branch, and cleans up records.
  • Bulk finish: wtm_purge can process multiple tasks in bulk; failure of a single task does not interrupt other tasks, and it returns a non-zero exit code on failure.
  • Concurrency safety: Uses a mutex for ledger writes; the lock includes a unique token and heartbeats, recycling old locks after a crash.
  • Failure recovery: Automatically rolls back worktrees and branches if creation fails; provides guidance for git merge --abort to recover from merge conflicts.
  • Cross-platform triggers: Supports Windows (cmd) and POSIX (sh), normalizing case and separators in path comparisons.
  • Repository-level configuration: .wtm.json supports branch prefixes, message templates, seed files (path escape protection), and lifecycle triggers (fixed working directory).

Installation and Usage

Install to a specific profile:

dsh plugin --profile demo add github:JohnXu22786/worktree-mgr

Remove:

dsh plugin --profile demo remove worktree-mgr

Local installation:

dsh plugin --profile demo add ./worktree-mgr

Declare dsh.bundle.patch as ./cordis.patch.yml in package.json.

Load overlay:

dsh --profile demo --patch ./examples/overlay.yml

Standalone CLI:

npm link
wtm begin "Add Search Box"

Typical Usage

Create task workspace:

wtm begin "Add Search Box"

View status:

wtm status

Merge only, without performing cleanup deletion:

wtm merge "Add Search Box"

Finish: commit, merge, delete workspace, delete branch, and clean up records:

wtm finish "Add Search Box"

Bulk finish:

wtm purge "Task A" "Task B"
wtm purge --all

Help:

wtm help

All commands support --json. WTM_* environment variables are also applicable to the CLI.

Security Boundaries

  • Refuses to merge if the base branch has uncommitted changes.
  • Refuses operations if the main workspace’s current branch is inconsistent with the ledger base branch, or the task workspace’s current branch is inconsistent with the ledger task branch.
  • Refuses creation if a task, branch, or workspace already exists, or if different tasks derive the same workspace path.
  • mode abandon discards all task changes, forcibly cleans up the workspace, and deletes the branch; it is irreversible.

Suitable Scenarios and Notes

Suitable for dsh use cases that require workspace isolation between multiple tasks and wish to unify merge and cleanup.

From a permissions perspective, the plugin runs with the permissions of the current dsh process; ensure that its access to the repository, file system, and configuration files meets expectations before execution. Before installation, check the source code, license, and configuration files such as .wtm.json; the license verified in this article is MIT.

References

  • GitHub: https://github.com/JohnXu22786/worktree-mgr
  • Directory Page: https://www.skillhub.cn/plugins/JohnXu22786/worktree-mgr