> basics
One repository, several working directories: git worktree add gives every branch (or experiment) its own folder while all of them share the same history, objects, and remotes. No stashing to switch context, no second clone to keep in sync — a worktree is created in milliseconds and shows up in git worktree list alongside the rest. These commands cover creating worktrees from local branches, remote branches, tags, and bare paths.
// basics
8 commands$ git worktree add ../myapp-hotfix hotfix$ git worktree add -b feature-auth ../myapp-auth main$ git worktree add ../hotfix$ git fetch origin$ git worktree add -d ../scratch$ git worktree list$ git worktree add --force ../myapp-copy feature-x$ git worktree add --no-checkout -b agent-docs ../myapp-docs main// faq
How is a worktree different from a second clone?
A clone is an independent repository: its own object store, its own refs, syncing only through push and pull. A worktree is the same repository with an extra working directory — creation is instant, history isn't duplicated, a commit made in one worktree is immediately visible in all of them, and one fetch updates everything. The only things not shared are the working files, the index, and HEAD.
Why does Git say a branch is "already checked out" somewhere else?
Each branch can be checked out in at most one worktree. If two directories held the same branch, a commit in either would leave the other's files silently out of date, so Git blocks it. Check out a different branch, use a detached worktree (git worktree add -d) when you only need the files, or --force if you truly know what you're doing.
Where should I put my worktrees?
Anywhere outside the repository's own working tree. The two common conventions are siblings (../myapp-hotfix next to myapp/) or a dedicated container directory (~/worktrees/myapp/, ../myapp-worktrees/). Keeping them inside the repo (.worktrees/) also works, but the folder must be gitignored and excluded from your build, lint, and search tools, or every scan walks into it.
Do worktrees cost much disk space?
Only the checked-out files themselves. History and objects are shared, so a worktree of a repo with 2 GB of history and a 200 MB tree costs roughly 200 MB — plus whatever you generate inside it. In practice node_modules and build output are the real cost, not Git.