Merathon, home page

Git Cheat Sheet · Worktrees

Understand worktrees

git worktree list

git worktree adds a working copy to the same repository, in another folder and on another branch. Commits, branches, tags and stashes are shared, without push or fetch. Each worktree keeps its own files, index and current branch.

By , author of Merathon · published on

What it does

A worktree is an additional working copy of the same repository, in another folder and on another branch. They all share commits, branches, tags, remotes and stashes: a commit made in one is immediately visible in the others, without push or fetch. Each one keeps its own files, index and current branch. The original folder is the main worktree; in the others, .git is a simple file pointing to the main repository, with no second history.

A use case

You are in the middle of a feature when an urgent fix comes in: instead of stashing and switching branches, you open the fix in a second folder, without touching your ongoing work.

Warning: Only versioned files are present in a new worktree: ignored files (node_modules, .env, builds…) are not there, they must be reinstalled or copied.

On the command line

git worktree list
Lists worktrees, with their folder, commit and branch.
git worktree add <folder> <branch>
Checks out an existing branch in a new folder.
git worktree add -b <branch> <folder>
Creates a branch and checks it out in a new folder.
git worktree remove <folder>
Deletes a worktree. The branch stays.

In Merathon

  1. Expand the "Worktrees" section of the sidebar: each row shows the checked-out branch.
  2. The displayed worktree is highlighted, and the original one is marked "main".
  3. Hover a row to see its folder.

Frequently asked questions

What is the difference with a second clone?

A clone has its own history, to synchronize with fetch and push. A worktree shares the repository's history: a commit made there is immediately visible from the others, and nothing is downloaded twice.

What is the difference with a stash?

A stash sets your changes aside to free up the working copy. A worktree leaves them where they are and opens the other branch elsewhere: useful for a long build or for comparing two branches.

Why is my node_modules not in the worktree?

A new worktree contains only versioned files. Ignored files (node_modules, .env, builds) must be reinstalled or copied over.

See also