How to use git worktree: your first one, start to finish

To use git worktree, you add a second folder to the repository you already have, on its own branch: git worktree add ../app-hotfix -b hotfix/typo. Then you cd into that folder and work as usual: edit, commit, push. Your main folder stays exactly as you left it, half-finished changes included. When you’re done, merge the branch, then git worktree remove ../app-hotfix and git branch -d hotfix/typo. Below is that whole loop on a real repository, then the mistakes that catch everyone the first time.

This is the one-person, first-time version. If you want worktrees so that several AI coding agents can work at once, read git worktrees for Claude Code and Codex after this one.

The idea in one paragraph

Normally a repository has one folder, and that folder has one branch checked out. To look at another branch you switch, which means committing or stashing what you’re doing first. A worktree gives you a second folder for the same repository, with a different branch checked out. Both folders share one history: a commit made in one is visible from the other right away, with no push or pull between them.

Step 1: create a worktree

From your repository’s folder, pick a folder name and a new branch name:

$ git worktree add ../app-hotfix -b hotfix/typo
Preparing worktree (new branch 'hotfix/typo')
HEAD is now at de83596 Initial commit

That made the folder ../app-hotfix, next to the repository, and a new branch hotfix/typo starting from where you are now. To check out a branch that already exists, or one from the remote, see git worktree add, which covers every form of the command.

Step 2: list your worktrees

$ git worktree list
~/code/app         de83596 [main]
~/code/app-hotfix  de83596 [hotfix/typo]

The first line is your original folder, the main worktree. Every other line is a linked worktree: its path, its commit, its branch.

Step 3: go there and work

There’s no special command to “enter” a worktree. It’s a folder:

$ cd ../app-hotfix
$ git status
On branch hotfix/typo
nothing to commit, working tree clean
$ ls -a
.
..
.git
.gitignore
app.js
README.md

Look at what’s missing. My main folder had node_modules/ and a .env, both in .gitignore. A new worktree gets only the files Git tracks, so install dependencies and copy your config before you run anything here.

Edit and commit as you would anywhere:

$ echo '# my app' > README.md
$ git commit -qam 'Fix the title'
$ git log --oneline -1
d750101 Fix the title

Step 4: see the commit from your main folder

Back in the original folder, the new commit is already there, because both folders share one repository:

$ cd ../app
$ git log --oneline -1 hotfix/typo
d750101 Fix the title
$ git branch
+ hotfix/typo
* main

The + marks a branch that’s checked out in another worktree. The * is the one checked out here.

Moving between the two folders is just cd. If you have several worktrees and lose track, how to switch between git worktrees has a small shell function that jumps to one by branch name.

Step 5: merge, remove, delete the branch

Merge the branch like any other, then clean up in this order: the worktree first, then the branch.

$ git merge hotfix/typo
Updating de83596..d750101
Fast-forward
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git worktree remove ../app-hotfix
$ git branch -d hotfix/typo
Deleted branch hotfix/typo (was d750101).
$ git worktree list
~/code/app  d750101 [main]

Back to one folder. That’s the whole loop.

Five mistakes everyone makes once

1. Checking out a branch that’s already open

A branch can be checked out in one worktree at a time, and your main folder counts:

$ git worktree add ../app-main main
Preparing worktree (checking out 'main')
fatal: 'main' is already used by worktree at '~/code/app'

Make a new branch with -b, or use --detach if you only want to look around.

2. Leaving out the branch name

With only a path, Git invents a branch named after the folder:

$ git worktree add ../app-review
Preparing worktree (new branch 'app-review')
HEAD is now at d750101 Fix the title

Not wrong, but your branch list fills up with names like app-review. Pass -b with a name you chose.

3. Putting the worktree inside the repository

It works, but Git sees the new folder as untracked files:

$ git worktree add .worktrees/search -b feature/search
Preparing worktree (new branch 'feature/search')
HEAD is now at d750101 Fix the title
$ git status --short
?? .worktrees/

Add .worktrees/ to .gitignore, or keep worktrees next to the repository (../app-<task>) like the examples here.

4. Removing a worktree with work still in it

Git won’t throw away files you haven’t committed, not even one untracked file:

$ echo wip > ../app-review/notes.txt
$ git worktree remove ../app-review
fatal: '../app-review' contains modified or untracked files, use --force to delete it

--force deletes them for good. Commit anything you want to keep first.

5. Deleting the folder by hand, then the branch

rm -rf on a worktree folder leaves Git’s record of it behind, and the branch stays blocked with cannot delete branch … used by worktree. git worktree prune clears the record; that error has its own page with every case I could reproduce. For the rest of the cleanup commands (prune, lock, move, repair), see git worktree remove, prune and lock.

When a worktree is worth it

For a two-minute look at another branch, git switch or git stash is less work. A worktree pays off when both things need to stay open: a long test run on one branch while you keep coding on another, a review, a hotfix in the middle of a feature. git worktree vs branch, stash and clone runs the same hotfix all four ways if you want to compare.