Skip to content

Git Worktree: Work on Another Branch Without Leaving the Current One#

You need a change on another branch, but the current one is busy: edited files, a running test, a terminal in the right folder. Stashing and switching loses all of that. A second clone copies the history and needs its own remotes.

A worktree is the middle ground: one more folder, the same .git.

add -> edit -> commit -> remove    branch kept, your checkout untouched

What It Is#

One repository can have several working folders at once. Each folder has its own branch, its own files, its own index and HEAD. Branches, commits, tags and remotes are shared.

%%{init: {"flowchart": {"wrappingWidth": 300}}}%%
flowchart LR
    subgraph Repo["one repository: shared branches + commits"]
        direction LR
        M(["main folder<br/><b>~/git/app</b><br/>branch <b>main</b>"])
        W(["new folder<br/><b>../app-fix</b><br/>branch <b>fix</b>"])
        W -- "2. edit + commit" --> M
        M -- "1. git worktree add<br/>-b fix<br/>../app-fix main" --> W
    end
    W -. "3. git worktree remove ../app-fix" .-> G(["folder <b>../app-fix</b> deleted<br/>branch <b>fix</b> stays"])

    classDef main fill:#dcfce7,stroke:#15803d,color:#14532d,stroke-width:1.5px;
    classDef work fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:1.5px;
    classDef gone fill:#ffedd5,stroke:#ea580c,color:#9a3412,stroke-width:1px;
    class M main;
    class W work;
    class G gone;
    style Repo fill:#f8fafc,stroke:#94a3b8,color:#475569,stroke-dasharray:4 3;

The Commands#

The template:

git worktree add -b <new-branch> <worktree-folder> <base-branch>

The same line with real values, then the rest of the flow:

git worktree add -b fix ../app-fix main   # 1. new folder + new branch from main
cd ../app-fix                             # 2. work here as usual
git add -A && git commit -m "fix: x"      # 3. commits land on branch fix
git worktree remove ../app-fix            # 4. folder gone, branch fix stays

After that, the branch is still there: git switch fix in the main checkout, or push it and open a PR.

Shared vs. Private#

Scope What
✅ shared branches, commits, tags, remotes
❌ private files, index, HEAD

The shared items exist once for the whole repository; the private items exist once per worktree. There is no sync step: a commit made in the worktree is already in the main repository, and the main checkout sees it immediately, without fetch or push.

The Point#

  • The current checkout keeps its branch, its edits and its running tests.
  • Another branch gets its own folder, so the two never fight over a file or index.lock.
  • Several tasks can run side by side, one folder each. This is why agents like worktrees: the main checkout is never touched, and the folder is thrown away at the end.
  • The folder is disposable; the branch is not.

Two Rules#

  • One worktree per branch. git worktree add refuses a branch already checked out elsewhere: fatal: 'fix' is already used by worktree at .... That includes the branch checked out in your main folder.
  • A dirty folder is not removed. git worktree remove stops with contains modified or untracked files. Commit first, or pass --force to throw the edits away.

If the Folder Is Already Gone#

When a worktree folder is deleted by hand (a /tmp cleanup, for example), git keeps the record:

git worktree list      # the missing one is marked prunable
git worktree prune -v  # drop the records

Until then, git branch still marks that branch with +, and switching to it elsewhere fails. prune only removes bookkeeping for folders that no longer exist: no branch, commit or tag is touched.

Comments