import DefinitionCard from "@site/src/components/DefinitionCard";

# 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.

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.

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`:

```bash
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:

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

Remove the worktree after its changes are merged:

```bash
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:

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

For [parallel agents](/learn/git-worktrees-for-ai), 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.

```bash
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:

```text
../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:

```bash
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](./git-worktrees-vs-clones) when tasks need their own refs, remotes, or config. Use an OS sandbox when they need a real security boundary.

## Next Steps

- [Git Worktrees vs Clones](./git-worktrees-vs-clones): choose the required level of repository isolation
- [What are Stacked PRs?](./stacked-prs): organize dependent branches into reviewable changes
- [Parallel Development Workflow](/learn/workflows/git/parallel-development): apply worktrees to concurrent tasks
- [What are Coding Agents?](/learn/concepts/ai-engineering/coding-agents): isolate agent changes in separate directories