Free developer reference
A practical reference for creating, listing, moving, locking, removing, cleaning up, and troubleshooting Git worktrees.
Native Git commands, examples, common problems, and WorktreeWise equivalents.
Start here
The commands developers reach for most often. Copy one directly or jump to its explanation.
git worktree list--verbose--porcelaingit worktree add <path> <branch>--lock--reason <text>--no-checkoutgit worktree add -b <branch> <path> <start-point>-B <branch>--track--lockgit worktree prune--dry-run--verbose--expire <time>git worktree repair [<path>...]One or more worktree pathsWorkflow comparison
Native Git provides the worktree primitives. WorktreeWise coordinates the practical steps around them.
Native Git
git worktree add ../feature-auth -b feature/auth main
cd ../feature-auth
cp ../main/.env .env
# configure environment if needed
idea .Git creates the linked checkout. Your setup files, environment, and editor launch remain separate workflow steps.
Reference
Concise syntax, examples, options, and the mistakes worth remembering.
Create a linked working directory from a branch, commit, or new branch.
git worktree add ../feature-auth feature/authSyntax: git worktree add <path> <branch>
Checks out an existing branch into a new linked working directory.
Note: A branch normally cannot be checked out in two worktrees at once.
Detailed git worktree add guide →git worktree add -b feature/auth ../feature-auth mainSyntax: git worktree add -b <branch> <path> <start-point>
Creates the branch from the chosen starting point and checks it out in the new worktree.
git worktree add -b investigate-bug ../investigate a1b2c3dSyntax: git worktree add -b <branch> <path> <commit>
Starts a new branch and worktree at a specific commit, tag, or other commit-ish.
Note: Use a new branch when you expect to commit changes.
Find, relocate, and protect linked working directories.
git worktree listSyntax: git worktree list [--verbose | --porcelain]
Shows the main working tree and every linked worktree with its commit and branch.
git worktree move ../feature-auth ../worktrees/feature-authSyntax: git worktree move <worktree> <new-path>
Moves a linked worktree and updates Git's administrative metadata.
Note: Use this command instead of moving the directory manually.
Learn about moving worktrees safely →git worktree lock --reason "External drive" ../client-demoSyntax: git worktree lock [--reason <string>] <worktree>
Prevents automatic pruning of a worktree that may be temporarily unavailable.
git worktree lock tutorial →git worktree unlock ../client-demoSyntax: git worktree unlock <worktree>
Removes the administrative lock so the worktree can be pruned normally.
git worktree unlock tutorial →Remove linked directories and clean stale administrative records safely.
git worktree remove ../feature-authSyntax: git worktree remove <worktree>
Removes a clean linked worktree and its administrative record.
Note: Commit, stash, or discard changes before removal.
Safe worktree removal guide →git worktree prune --dry-runSyntax: git worktree prune [--dry-run] [--verbose]
Cleans administrative records for linked worktrees that no longer exist.
git worktree repair ../moved-worktreeSyntax: git worktree repair [<path>...]
Repairs Git's administrative links after a worktree directory or the main repository was moved outside Git.
Note: Repair an existing moved directory; prune only when the worktree is permanently gone.
Learn how to repair a damaged worktree →Beyond native commands
Git provides the foundation. WorktreeWise adds organization, editor integration, and safer visual actions around it.
Rename a worktree and its associated branch together from one visual action.
Rename a Git Worktree →
Use repository and branch placeholders to keep worktree folders recognizable and organized.
Git Worktree Naming Pattern →
Configure your editors once, then launch any worktree with its familiar IDE configuration.
Opening a Worktree in an IDE →
Manage and open WorktreeWise worktrees directly from supported JetBrains IDEs.
WorktreeWise for JetBrains Plugin →Explore worktrees, integrations, workflows, Git operations, and AI-agent workspaces.
Automated worktree setup
Turn worktree creation into a repeatable developer workflow. WorktreeWise creates the linked worktree, runs your configured hooks, and opens the finished project in the correct editor with its worktree context ready.
Isolated development environments
Each Git worktree has its own working directory. Use WorktreeWise hooks to prepare the environment for that directory—install dependencies, create local configuration, and run setup commands without mixing files between branches.
Troubleshooting
Quick answers for the failure modes that most often interrupt parallel branch work.
Git normally protects a local branch from being checked out in two worktrees simultaneously. Use the existing worktree, choose another branch, create a new branch, or use detached mode when you only need to inspect a commit.
Worktrees and branches explained →The directory may be gone while its administrative record remains. Run git worktree prune --dry-run, review the result, then run git worktree prune to clean stale metadata.
Pruning stale worktrees →Normal removal refuses to discard modified or untracked files. Commit or stash wanted work first. Use --force only after confirming that losing the local files is acceptable.
Remove worktrees safely →If the repository or linked directory was moved outside Git, git worktree repair can reconnect the administrative metadata. Pass affected worktree paths when Git cannot discover them automatically.
Prefer git worktree move for a linked worktree. If a manual move already happened, run git worktree repair from the main repository and provide the new path when needed.
Beyond the CLI
Git handles the linked checkout. Developers still need to open the right tools, reproduce setup, run scripts, navigate worktrees, clean up, and inspect changes.
List, create, rename, move, delete, lock, unlock, and prune worktrees from one interface.
Open the correct worktree directly in your editor or terminal without navigating paths manually.
Run reusable setup commands and workflows sequentially or in parallel across selected worktrees.
Inspect history and compare worktrees, branches, tags, and commits without leaving the workflow.
Interactive tool
Use the dedicated visual generator to choose a path, branch strategy, and starting point without memorizing every flag.
Your selections stay in the browser. The generator creates command text and never executes anything on your machine.
Creating and managing worktrees frequently? WorktreeWise handles these workflows visually.
Try WorktreeWise →Git worktrees are powerful. WorktreeWise handles the repetitive workflow around them so you can focus on your branches and code.
Frequently asked questions
Short, technically accurate answers to common worktree questions.
A Git worktree is an additional working directory linked to the same repository, allowing another branch or commit to be checked out without another full clone.
Worktrees share the repository’s object database and configuration, so they use less space and make parallel branch work faster than maintaining several independent clones.
Normally no. Git prevents the same local branch from being checked out in more than one worktree to avoid conflicting updates.
Yes. Linked worktrees share the main repository’s object database and most repository-level data, while each worktree keeps its own HEAD, index, and working files.
The main repository stores linked-worktree administrative data under its git directory, typically in .git/worktrees/.
You can, but it leaves stale metadata. Prefer git worktree remove; if the directory is already gone, inspect and clean records with git worktree prune.
Commit or stash wanted changes, then run git worktree remove <worktree>. Git refuses normal removal when protected local changes are present.
It removes stale administrative records for linked worktrees that are no longer present. Use --dry-run to preview the cleanup.
It repairs administrative links after a linked worktree or the main repository has been moved manually.
No by default. Each worktree has its own files and typically needs its own node_modules unless you deliberately share or cache dependencies.
Only tracked environment files appear automatically. Ignored files such as .env.local usually need to be copied, generated, or linked for each worktree.
Git does not impose a small fixed limit. Practical limits are disk space, tooling overhead, and how many active branches your workflow can manage clearly.