Skip to content
Skills Library
Programming · Automation

worktree-ops

/worktree-ops

Manages git worktrees for isolated parallel work, with safety checks for uncommitted changes and unpushed commits. Use to work on several branches at once, run parallel sessions, or isolate experiments.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Manages git worktrees for isolated parallel work, with safety checks for uncommitted changes and unpushed commits. Use to work on several branches at once, run parallel sessions, or isolate experiments.

Arguments

/worktree-ops [command: create, list, switch, remove] [optional: worktree-name]
Original author description

Manages git worktrees for isolated parallel work, with safety checks for uncommitted changes and unpushed commits. Use to work on several branches at once, run parallel sessions, or isolate experiments.

How it works

  1. Core Principles
  2. Quick reference
  3. Create
  4. List
  5. Switch
  6. Remove
  7. Troubleshooting
  8. Integration with Other Skills
Original SKILL.md headings · 175 lines, 1,168 words
SKILL.md preview
---
name: worktree-ops
description: Manages git worktrees for isolated parallel work, with safety checks for uncommitted changes and unpushed commits. Use to work on several branches at once, run parallel sessions, or isolate experiments.
user-invocable: true
argument-hint: "[command: create, list, switch, remove] [optional: worktree-name]"
---

# Worktree Management

Git worktrees let you check out several branches of one repository into separate directories at the same time. Each worktree has its own working directory and index, and all of them share the same `.git` object store and history. This is useful for parallel development sessions, for reviewing a PR while mid-feature, and for isolating experimental changes without stashing or committing half-finished work.

## Core Principles

| Principle | Meaning |
|---|---|
| **Isolation without duplication** | Worktrees share git history but keep working directories separate, so you do not clone the repo again |
| **Safety first** | Always check for uncommitted changes and unpushed commits before removing a worktree |
| **Clean up after yourself** | Stale worktree entries and orphaned branches pile up, so prune regularly |
| **Convention over configuration** | Use a consistent directory layout (`.worktrees/<name>/`) and branch naming (`worktree-<name>`) |

## Quick reference

| Command | What it does | When to use |
|---|---|---|
| `git worktree add <path> -b <branch>` | Create a new worktree with a new branch | Starting parallel work on a new task |
| `git worktree list` | Show all worktrees with their branches and paths | Checking what is active |
| `git worktree list --porcelain` | Machine-readable worktree listing | Scripting or enriching with status info |
| `git worktree remove <path>` | Remove a worktree directory and its admin files | Done with a parallel task |
| `git worktree remove <path> --force` | Force-remove even with uncommitted changes | After explicit user confirmation |
| `git worktree prune` | Clean up stale worktree entries | After manual directory deletion or errors |
| `git branch -D worktree-<name>` | Delete the orphaned branch after worktree removal | Keeping branches clean |

## Create

Create a new worktree for an isolated parallel development session.

### Workflow

1. Confirm the current directory is a git repository.
2. Confirm the current session is NOT already inside a worktree:
   ```bash
   git rev-parse --is-inside-work-tree && git worktree list
   ```
   If the current working directory is already a worktree (not the main working tree), warn the user and stop.
3. If a name was provided as an argument, use it. Otherwise, present an interactive prompt (or the platform's equivalent): "What name should I use for this worktree? (e.g., `feature-auth`, `bugfix-123`)"
4. Create the worktree:
   ```bash
   git worktree add .worktrees/<name> -b worktree-<name>
   ```
5. Change your working directory to the new worktree path.
6. Report to the user:
   ```
   Worktree created:
     Directory: .worktrees/<name>/
     Branch: worktree-<name>
     Based on: <current HEAD>
   ```
7. Remind the user:
   - Run your stack's dependency installation command (e.g., `composer install`, `npm install`, `pip install -r requirements.txt`)
   - The worktree shares git history with the main repo but has its own working directory
   - Use the `list` command to see all active worktrees
   - Use the `remove` command to clean up when done

## List

List all active worktrees with their branches, paths, and status.

### Workflow

1. Confirm the current directory is inside a git repository.
2. Run:
   ```bash
   git worktree list --porcelain
   ```
3. For each worktree, get the uncommitted change count:
   ```bash
   git -C <worktree-path> status --short 2>/dev/null
   ```
4. Display a table:
   ```
   Active worktrees:

   | # | Name         | Branch               | Path                          | Status        |
   |---|--------------|----------------------|-------------------------------|---------------|
   | 1 | (main)       | main                 | /path/to/repo                 | clean         |
   | 2 | feature-auth | worktree-feature-auth| .worktrees/feature-auth       | 3 uncommitted |
   | 3 | bugfix-123   | worktree-bugfix-123  | .worktrees/bugfix-123         | clean         |
   ```
5. If no worktrees exist beyond the main working tree, say: "No additional worktrees found. Use the `create` command to create one."

## Switch

Switch your working directory to a different existing worktree.

### Workflow

1. Confirm the current directory is inside a git repository.
2. Run:
   ```bash
   git worktree list
   ```
   If only the main working tree exists, say: "No worktrees available to switch to. Use the `create` command to create one." and stop.
3. If a name was provided as an argument, find the matching worktree path. Otherwise, show the list and present an interactive prompt (or the platform's equivalent): "Which worktree do you want to switch to?"
4. If the name does not match any existing worktree, say: "Worktree `<name>` not found." and show the available list.
5. Open a terminal in the worktree path, or switch your editor to the worktree directory.
6. Report to the user:
   ```
   Switched to worktree:
     Directory: <worktree-path>
     Branch: <branch-name>
   ```
7. Show a quick status:
   ```bash
   git status --short
   ```

## Remove

Remove one or all worktrees from the current repository.

### Workflow

1. Confirm the current directory is inside a git repository.
2. Run:
   ```bash
   git worktree list
   ```
   If no worktrees exist beyond the main working tree, say: "No worktrees to clean up." and stop.
3. Decide what to remove:
   - If the argument is `all`, remove all worktrees (except the main working tree).
   - If a specific name was provided, remove only that worktree.
   - If there is no argument, show the list and present an interactive prompt (or the platform's equivalent): "Which worktree should I remove? Enter the name, or type `all` to remove everything."
4. **Safety check.** For each worktree being removed:
   ```bash
   git -C <worktree-path> status --short
   git -C <worktree-path> log --oneline @{upstream}..HEAD 2>/dev/null
   ```
   If there are uncommitted changes or unpushed commits, warn the user:
   ```
   WARNING: Worktree "<name>" has uncommitted changes / unpushed commits:
     - 2 modified files
     - 1 unpushed commit
   These will be permanently lost. Continue? (yes/no)
   ```
   Wait for explicit confirmation before continuing.
5. For each worktree to remove:
   ```bash
   git worktree remove <path> --force
   git branch -D worktree-<name> 2>/dev/null
   ```
   Use `--force` only after the user has confirmed in step 4.
6. Prune stale entries:
   ```bash
   git worktree prune
   ```
7. Report what was removed:
   ```
   Removed worktrees:
     - feature-auth (branch worktree-feature-auth deleted)
     - bugfix-123 (branch worktree-bugfix-123 deleted)

   Remaining worktrees: 1 (main working tree only)
   ```

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| `fatal: '<path>' is a missing but locked worktree` | Worktree directory was deleted manually but the lock file remains | Run `git worktree unlock <path>` then `git worktree prune` |
| Stale entries in `git worktree list` | Worktree directory was deleted without using `git worktree remove` | Run `git worktree prune` to clean up admin files |
| `fatal: '<branch>' is already checked out` | Branch is active in another worktree | Switch the other worktree to a different branch first, or remove it |
| Worktree path exists but is empty | Interrupted creation or corrupted state | Run `git worktree remove <path> --force` then `git worktree prune` |

## Integration with Other Skills

| Situation | Recommended Skill |
|---|---|
| When managing branches and commits | `finishing-branch` |
| When executing a TDD implementation in an isolated worktree | `implementer` agent |
| When following a full ticket workflow that uses worktrees | `ticket-delivery` |

Versions

The database has no other skills named worktree-ops.

Database snapshot: 13.11.2026 · package version 76b243310f93 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90git-worktrees
    Create and manage isolated Git worktrees for parallel branches or temporary verification. Use when multiple tasks need separate working directories or when protecting uncommitted work during experiments.
  • 100git-worktree
    Manage Git worktrees for isolated parallel development. Use when creating, switching, or cleaning up worktrees for parallel bead work.
  • 100git-worktree
    Manage git worktrees for isolated parallel development. Use when running multiple sessions concurrently or working on parallel features.
  • 100git-worktree
    Use when work needs an isolated git worktree, such as parallel feature branches, reviewing a PR without disturbing the current checkout, or cleaning up old worktrees.
  • 100git-worktree
    Manage Git worktrees for parallel development. Use when creating isolated workspaces for parallel feature work, running multiple Claude sessions simultaneously, or managing concurrent development tasks.
  • 100worktree-open
    Create or reopen a git worktree for parallel development. Use when user wants to "open a worktree", "spin up a branch", "work on X separately", "work on this in parallel", "start a parallel task", "isolated environment for an agent", "side branch without switching", or mentions…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.