Skip to content
Skills Library
Programming · Automation

git-worktree

/git-worktree

Use this skill whenever a task involves running parallel work on a git repository without conflicts — e.g. "fix this bug while I keep working on my feature", "run Claude on two branches at once", "work on this task in isolation", "create a throwaway branch for this experiment", or anything where two agents or sessions might edit the same files. Also trigger when the user asks to use worktrees directly, or when an agent needs its own isolated checkout so it can work without disturbing the main branch. Even if the user just says "do this in parallel" or "don't mess up my current work", consider

Licence
MIT
Last repository change
26.09.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 26.09.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

Use this skill whenever a task involves running parallel work on a git repository without conflicts — e.g. "fix this bug while I keep working on my feature", "run Claude on two branches at once", "work on this task in isolation", "create a throwaway branch for this experiment", or anything where two agents or sessions might edit the same files. Also trigger when the user asks to use worktrees directly, or when an agent needs its own isolated checkout so it can work without disturbing the main branch. Even if the user just says "do this in parallel" or "don't mess up my current work", consider

Triggers from the description

fix this bug while I keep working on my featurerun Claude on two branches at oncework on this task in isolationcreate a throwaway branch for this experimentdo this in paralleldon
Original author description

Use this skill whenever a task involves running parallel work on a git repository without conflicts — e.g. "fix this bug while I keep working on my feature", "run Claude on two branches at once", "work on this task in isolation", "create a throwaway branch for this experiment", or anything where two agents or sessions might edit the same files. Also trigger when the user asks to use worktrees directly, or when an agent needs its own isolated checkout so it can work without disturbing the main branch. Even if the user just says "do this in parallel" or "don't mess up my current work", consider

How it works

  1. When to reach for worktrees
  2. Core commands
  3. Recommended layout for agents
  4. Agent workflow
  5. Safety rules
  6. Troubleshooting
Original SKILL.md headings · 164 lines, 747 words
SKILL.md preview
---
name: git-worktree
description: >
  Use this skill whenever a task involves running parallel work on a git
  repository without conflicts — e.g. "fix this bug while I keep working on
  my feature", "run Claude on two branches at once", "work on this task in
  isolation", "create a throwaway branch for this experiment", or anything
  where two agents or sessions might edit the same files. Also trigger when
  the user asks to use worktrees directly, or when an agent needs its own
  isolated checkout so it can work without disturbing the main branch. Even
  if the user just says "do this in parallel" or "don't mess up my current
  work", consider worktrees.
---

# Git Worktree Skill

Git worktrees let you check out multiple branches of the same repository into
separate directories simultaneously. Each directory is a fully independent
working tree — its own HEAD, index, and files — but all share the same `.git`
history and objects, so they stay lightweight.

Use this skill to give each agent or parallel task its own isolated workspace.

---

## When to reach for worktrees

- Two or more agents might edit the same files simultaneously
- A task should not disturb the current branch's working state
- You need a throwaway sandbox that can be discarded cleanly if things go wrong
- The user asks to work on multiple features or fixes in parallel
- You want to run tests on one branch while editing another

---

## Core commands

### Create a worktree

```bash
# New branch from current HEAD
git worktree add ../my-task -b my-task-branch

# From a specific commit or existing branch
git worktree add ../hotfix -b hotfix origin/main

# Detached HEAD (no branch)
git worktree add --detach ../scratch HEAD

# Empty worktree on an unborn branch (blank slate)
git worktree add --orphan ../experiment -b experiment
```

The new directory is ready to use immediately. `cd` into it and work normally.

### List all worktrees

```bash
git worktree list
# /path/to/main        abc1234 [main]
# /path/to/my-task     def5678 [my-task-branch]
```

### Remove a worktree when done

```bash
# Clean remove (fails if the worktree has uncommitted changes)
git worktree remove ../my-task

# Force remove (discard dirty worktree)
git worktree remove --force ../my-task

# If you deleted the directory manually, clean up the metadata
git worktree prune
```

### Move a worktree

```bash
git worktree move ../my-task ../new-location
```

### Lock / unlock (for portable drives or network shares)

```bash
git worktree lock ../my-task --reason "on external drive"
git worktree unlock ../my-task
```

### Repair after a manual move

```bash
# Run inside the moved worktree
git worktree repair

# Or from main, pointing at each moved worktree
git worktree repair ../new-location-1 ../new-location-2
```

---

## Recommended layout for agents

Place worktrees as siblings of the main repo directory so paths stay
predictable and `.gitignore` patterns do not need updating:

```
projects/
  my-app/           ← main repo  (agents work here by default)
  my-app-task-a/    ← worktree for task A
  my-app-task-b/    ← worktree for task B
```

Create them from the main repo root:

```bash
git worktree add ../my-app-task-a -b task-a
git worktree add ../my-app-task-b -b task-b
```

---

## Agent workflow

1. **Create** a worktree on a fresh branch before starting work.
2. **Work** entirely inside that directory — treat it like a normal repo.
3. **Commit** as usual; history is shared with the main repo.
4. **Verify** the result (tests, review, etc.).
5. **Merge or PR** the branch back via standard git workflow.
6. **Remove** the worktree once done.

```bash
# Step 1 — set up
git worktree add ../my-app-fix-login -b fix-login

# Step 2 — work
cd ../my-app-fix-login
# ... make changes ...

# Step 3 — commit
git add -A && git commit -m "fix: resolve login redirect loop"

# Step 4 — back in main repo, merge
cd ../my-app
git merge fix-login

# Step 5 — clean up
git worktree remove ../my-app-fix-login
git branch -d fix-login
```

---

## Safety rules

- **One branch per worktree.** Git prevents the same branch from being checked
  out in two worktrees at once. Use separate branch names for each worktree.
- **Do not share an index.** Never point two worktrees at the same directory.
- **Avoid submodules in moved worktrees.** `git worktree move` cannot move a
  worktree that contains submodules; handle those manually.
- **Discard freely.** If a worktree session goes wrong, `git worktree remove
  --force` discards it entirely with no impact on other branches.
- **Prune stale metadata.** After manually deleting a worktree directory, run
  `git worktree prune` in the main repo to remove orphaned administrative
  files.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `fatal: '<branch>' is already checked out` | Use a different branch name, or check `git worktree list` |
| Worktree directory deleted but `git worktree list` still shows it | Run `git worktree prune` |
| Moved worktree can no longer find the repo | Run `git worktree repair` inside the moved directory |
| Locked worktree blocks removal | `git worktree unlock <path>` then remove |
| Changes in worktree not visible in main | Changes are per-worktree until committed and merged |

Versions

RepositoryScoreLicence
This page · siva01c/claude-plugins100MIT
iliaal/ai-skills100MIT
marcusrbrown/systematic100MIT
davidondrej/skills100MIT
bahayonghang/my-ai-cli-toolkit100MIT
yuri-xyz/skills100MIT
julianobarbosa/claude-code-skills100MIT
NikiforovAll/claude-code-rules100Apache-2.0
v1truv1us/ai-eng-system100MIT

Database snapshot: 13.11.2026 · package version 2b94cd4597bc (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

  • 95dev_manage_git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch…
  • 100using-git-worktrees
    Use when starting feature work that needs isolation from current workspace, or setting up parallel development tracks. Triggers: 'worktree', 'separate branch', 'isolate this work', 'don't mess up current work', 'work on two things at once', 'parallel workstreams', 'new branch…
  • 100parallel-worktrees
    Run multiple AI coding agent sessions in parallel using git worktrees — each agent isolated in its own worktree, working on a separate branch. Use this skill whenever the user wants to: run two or more AI agents simultaneously on different features or bugs, set up isolated agent…
  • 90git-worktrees
    Isolates feature work in a dedicated git worktree with directory selection, gitignore checks, setup, and baseline tests. Use this skill when starting isolated feature work, before multi-task plans, parallel branches, or discardable experiments. Do not use when/for finishing and…
  • 100git-worktrees
    Isolated workspace creation for parallel development work. Use when starting feature work that needs isolation from the current workspace. Creates git worktrees with proper setup and safety verification.
  • 100using-git-worktrees
    Creates isolated git worktrees with smart directory selection and safety checks. Use when starting isolated feature work.

Feedback and reports

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