Create a Git Worktree

Create a new Git worktree from HEAD, an existing branch, a tag, or a historical commit. WorktreeWise provides integrated provisioning tools including automated pre/post hooks, sparse directory checkouts, dependency symlinking (node_modules), and multi-source environment variable isolation.

To open the creation modal:

Select Add Worktree in the Worktrees panel toolbar.
Or press the global keyboard shortcut Shift + W.

Create Worktree dialog

Creation Modes

WorktreeWise supports four creation modes:

Mode	Source Revision	Best Used For
From HEAD	Current commit of primary worktree	Starting a new branch from your active working state.
From Branch	Local branch or remote tracking reference	Continuing work on an existing branch or inspecting a remote pull request.
From Tag	Git tag or release milestone	Verifying a tagged release in an isolated directory.
From Commit	Historical commit hash selected in Git Log	Branching off an exact historical revision.

1. From HEAD (New Branch)

Creates a new branch and worktree rooted at the current HEAD commit:

Select From Head.
In the Name field, enter your branch name (e.g. feature-auth-flow or fix-memory-leak). WorktreeWise automatically sanitizes invalid characters.
Review the destination folder preview generated below.
Configure optional hooks, sparse checkout, or environment options.
Select Create Worktree.

Realistic name and generated path

2. From Branch (Local or Remote)

Attach a new worktree to an existing local branch or create a tracking branch from an upstream remote:

Local Branch: Select any branch already present in your local Git repository.
Remote Branch: Toggle the Remote switch to browse upstream branches (e.g. origin/feature-search). When selected, Git creates a local tracking branch pointing to the remote reference.

Create from a local branch

Create from a remote branch

If a recently pushed remote branch does not appear in the dropdown, click Refresh in the Worktrees toolbar or fetch changes from the primary worktree.

3. From Tag

Creates a worktree linked to a specific Git release or milestone tag:

Select From Tag and choose a tag from the searchable list.
WorktreeWise initializes a branch from the tag (converting dots to hyphens, e.g. v1.0.0 → v1-0-0), satisfying Git’s requirement that linked worktrees point to branch references rather than detached tag states.

Create from a tag

4. From a Git Commit

Create a worktree at an exact historical revision directly from the Git Log:

Open Git Log (Shift + G) and locate the target commit.
Open the commit’s context menu.
Select Create worktree here.
Complete the worktree name and configuration in the creation dialog.

Create a worktree from a selected Git commit

Destination Folder & Naming Patterns

Below the revision selector, WorktreeWise displays the target filesystem path where the new worktree folder will be created:

Directory Picker: Select the folder icon to customize the parent directory where worktrees reside on disk.
Pattern Resolution: Folder names are generated automatically using the template configured in Settings → Worktrees (default: {repo}__wt__{branch}).
Select Want to change it? to modify your naming pattern directly. For more details, see Git Worktree Naming Patterns.

Automation Hooks (Pre-Hook & Post-Hook)

WorktreeWise allows you to define shell commands that execute automatically before and after worktree provisioning:

Configured hooks

Hook	Execution Context	Common Use Cases
Pre-hook	Runs in the primary worktree before creation starts	`git fetch origin main:main` `git pull --rebase`
Post-hook	Runs inside the newly created worktree after checkout completes	`npm install` `pnpm install` `cargo build` `poetry install`

When hooks or environment isolation are enabled, WorktreeWise switches to workflow execution mode, allowing you to follow command output in real time inside the Log panel.

Sparse Checkout

For large monorepos or multi-package repositories, sparse checkouts allow you to checkout only the directories you need, saving disk space and speeding up index operations.

Sparse checkout with two folders selected

Select Folders

Under Repository checkout, select Selected folders (instead of Full repository).
WorktreeWise inspects the target revision using get-sparse-checkout-tree.
An interactive folder tree displays repository directories with exact byte sizes (e.g. 24.5 MB, 1.2 GB).
Select the checkboxes for the directories your task requires (e.g. packages/ui and apps/web).

Live Footprint Estimation

WorktreeWise calculates the estimated checkout footprint in real time:

Compares estimated size against full repository size.
Displays a percentage indicator (e.g. Estimated checkout: 420 MB (~24%)).
Minimizes sparse patterns automatically by removing redundant child paths when a parent folder is selected.

Shared Dependencies (`Share node_modules`)

In JavaScript and TypeScript projects, each worktree typically requires an independent node_modules directory, consuming gigabytes of disk space and requiring lengthy install steps.

How It Works

WorktreeWise scans existing worktrees to verify whether a valid node_modules directory exists in the primary worktree or any linked worktree.
Select Share node_modules to link dependencies.
Choose the source worktree from the dropdown (default: Primary worktree).
WorktreeWise creates a symbolic link in the new worktree pointing to the source node_modules.

Only share node_modules between branches with compatible dependency trees. If your new branch introduces new dependencies or native binary bindings, run a separate install instead.

Environment Isolation

Running multiple worktrees concurrently can cause port collisions (e.g. multiple services binding to port 3000) or database overwrites. WorktreeWise provides automated environment file isolation.

Environment isolation

Auto-Detection

WorktreeWise scans the repository for supported environment files:

.env, .env.local, .env.development, .env.test
Docker Compose configuration manifests

Variable Isolation Strategies

For each detected environment file, WorktreeWise displays an interactive strategy table:

Strategy	Behavior	Best Used For
Shared	Retains the exact variable value from the source file.	API keys, secret tokens, external third-party endpoints.
Suffix	Appends the worktree or branch identifier to the value. (Disabled for purely numeric values)	Database names (`db_feature_auth`), Redis keys, storage bucket names.
Auto Port	Scans system network ports and assigns the next available unused port. (Disabled for non-numeric values)	Server ports (`PORT`, `VITE_PORT`, `NEXT_PUBLIC_PORT`, `3001`, `3002`).

Security & Preview

Secret Masking: Sensitive variables (passwords, tokens, credentials) are masked with ******** in the preview table.
Generated Value Preview: The table displays a real-time preview arrow (→ 3002 or → app_wt_auth) showing what will be written to the new worktree’s environment file.
Remember Choices: Select Remember these choices for future worktrees to save your preferred isolation strategies as defaults.

Git Worktree Naming Patterns: Learn how folder naming templates work.
Worktree Overview Dashboard: Monitor all created worktrees.
Workflows: Automate post-creation commands across worktrees.
Delete a Worktree: Safely remove worktrees when work is finished.