Skip to main content

What are Git Worktrees?

Git worktrees let one repository provide several working directories at the same time.

Introduction​

A Git worktree is a directory where Git checks out a commit so you can edit and test it. Every repository has a main worktree unless it is bare. git worktree add creates linked worktrees, so you can keep several branches open without a second clone.

Definition

Git Worktree

A working directory associated with a Git repository, containing checked-out files plus its own HEAD and index.

With worktrees you stop stashing unfinished work just to review a branch or patch production. Tools and coding agents running at the same time also get their own files to edit.

Understanding the Concept​

The main and linked worktrees share one object database and most refs. Each worktree gets its own HEAD, index, and working files. A linked worktree holds a .git file that points at its own admin directory, tucked inside the repository's common Git directory.

Definition

Main Worktree

The working directory created when a non-bare Git repository is initialized or cloned.

Definition

Linked Worktree

An additional worktree registered with the same Git repository through git worktree add.

Because the repository is shared, a commit made in one worktree is visible at once from all of them. Local branches, tags, remote-tracking refs, the stash, and most repository config are shared too.

Git stops you checking out the same local branch in two worktrees. Otherwise both directories could move one branch ref from different working states.

Applying It in Practice​

Create a hotfix branch from the latest remote main:

git fetch origin
git worktree add -b hotfix/payment ../repo-hotfix origin/main

Your first directory stays on its branch, with staged and unstaged changes untouched. The new one has an index of its own:

git worktree list
git -C ../repo-hotfix status

Remove the worktree after its changes are merged:

git worktree remove ../repo-hotfix
git branch -d hotfix/payment

Removing a worktree does not delete its branch. Deleting the branch stays a separate, deliberate step.

To look without changing anything, use a detached HEAD and skip the branch:

git worktree add --detach ../repo-review origin/feature/payment

For parallel agents, give each task one worktree and one branch. Separate working files stop one process from overwriting another's edits. Shared repository state still needs care around branch names, fetches, and maintenance.

Git Worktrees and Jujutsu Workspaces​

Jujutsu workspaces also attach several working directories to one repository. They track state differently. Git gives each worktree an index and a HEAD. Jujutsu stores each workspace's working copy as a commit that updates as files change.

Definition

Jujutsu Workspace

A working directory registered with a Jujutsu repository, with its working-copy state represented by a workspace-specific commit.

jj workspace add ../repo-hotfix
jj workspace list
jj workspace forget repo-hotfix

jj workspace forget drops the workspace record but leaves its directory on disk. Use Git worktrees in a Git workflow and Jujutsu workspaces in a Jujutsu workflow. Colocated repositories can show commits to both tools, but mixing their workspace commands without knowing what state is shared invites confusion.

Engineering Considerations​

Use worktrees when you want several checkouts inside one trust boundary. They fit reviews, hotfixes, long test runs, and agent tasks running side by side.

Worktrees are not separate repositories. A branch made in one shows up in the others, and a fetch updates the shared remote-tracking refs. Hooks and config apply across the whole repository, though Git lets you set some values per worktree through extensions.worktreeConfig.

Dependencies and ignored files are not shared. Each worktree may need its own node_modules, build directory, generated assets, and local env files. In many projects those files take up more disk than Git's object database.

Scaling and Operations​

Name them after a task or pull request ID so the names stay stable:

../repo-pr-1842
../repo-task-auth-timeout

Always use git worktree remove instead of deleting the directory. If something else deletes it first, fix up the records with:

git worktree prune

Automation has to cope with half-created worktrees and failed cleanup. Check that a branch is not already checked out before you assign it, and do not run repository maintenance while other Git processes are writing shared state.

Use separate clones when tasks need their own refs, remotes, or config. Use an OS sandbox when they need a real security boundary.

Next Steps​