Skip to content

Instantly share code, notes, and snippets.

@socketbox
Last active October 9, 2026 19:06
Show Gist options
  • Select an option

  • Save socketbox/7f2dcc68fda4885f3265e7bf85828b27 to your computer and use it in GitHub Desktop.

Select an option

Save socketbox/7f2dcc68fda4885f3265e7bf85828b27 to your computer and use it in GitHub Desktop.
Set up a local repository in which every branch is checked out in its own git worktree

Unless stated otherwise, run every command from the repository root: the directory that contains .bare.

Starting out

mkdir project_foo
cd project_foo
git init --bare .bare
echo "gitdir: ./.bare" > .git
git remote add origin git@github.com:yourorg/project_foo.git
git fetch origin
git remote set-head origin --auto

git remote add writes the fetch refspec (+refs/heads/*:refs/remotes/origin/*) to .bare/config, so there is nothing to edit by hand. Unlike git clone --bare, this creates no local branches: every remote branch exists only as a remote-tracking branch (origin/<name>) until you create a worktree for it. That keeps local branches from being stale copies of whatever the remote held on the day you cloned. git remote set-head creates origin/HEAD, which points at the remote's default branch.

Branches

Create the default branch's worktree

git worktree add main
Preparing worktree (new branch 'main')
branch 'main' set up to track 'origin/main'.
HEAD is now at cf5bfce6b creating the foobaz

When git worktree add is given only a path, it uses the last component of the path as the branch name. If no local branch of that name exists but origin/main does, git creates the local branch and sets it to track origin/main, so a plain git pull inside main works.

Create a new branch and worktree based on main

git fetch origin
git worktree add --no-track -b my-new-branch ./my-new-branch origin/main

Basing the branch on origin/main after a fetch means the local main worktree does not need to be up to date. --no-track keeps the new branch from tracking origin/main; give it its own upstream when you first push it:

cd my-new-branch
git push -u origin my-new-branch

Alternatively, run git config push.autoSetupRemote true once (Git 2.37 or later), after which a plain git push creates the remote branch and sets the upstream.

The -b is required: git worktree add accepts at most <path> [<commit-ish>], so passing both a path and a branch name as positional arguments is a usage error. Dropping -b and running git worktree add ./my-new-branch main doesn't work either, because main is already checked out in the main worktree and git refuses to check out the same branch twice.

Create a worktree for a branch that exists on the remote

git fetch --prune origin
git worktree add ./existing-branch-name existing-branch-name
Preparing worktree (new branch 'existing-branch-name')
branch 'existing-branch-name' set up to track 'origin/existing-branch-name'.
HEAD is now at cf5bfce6b creating the foobaz

When no local branch named existing-branch-name exists but origin/existing-branch-name does, git creates the local branch and sets up tracking. This happens only if exactly one remote has a branch of that name. If you add more remotes, run git config checkout.defaultRemote origin so that git still knows which one to use.

To fetch a single branch instead of all of them:

git fetch origin dockerfile-updates
From github.com:yourorg/project_foo
 * branch              dockerfile-updates -> FETCH_HEAD
 * [new branch]        dockerfile-updates -> origin/dockerfile-updates

Because of the fetch refspec, this also creates origin/dockerfile-updates, so git worktree add ./dockerfile-updates dockerfile-updates then works as shown above. Avoid git worktree add ./dockerfile-updates FETCH_HEAD: that leaves the new worktree on a detached HEAD with no branch and no upstream.

Create a worktree for a branch that already exists locally

git worktree add ./existing-branch-name existing-branch-name
Preparing worktree (checking out 'existing-branch-name')
HEAD is now at cf5bfce6b creating the foobaz

This leaves the branch's upstream configuration as it was. If the branch does not track the remote branch of the same name, set it from inside the worktree and confirm with git status:

cd existing-branch-name
git branch --set-upstream-to=origin/existing-branch-name
branch 'existing-branch-name' set up to track 'origin/existing-branch-name'.

Hints

To add a worktree whose local branch name differs from the remote branch it should track:

git fetch --prune origin
git worktree add --track -b new_worktree_branch ./new_worktree_path origin/existing_branch

Branch names containing a slash need no special handling; git creates and tracks them as described above. Choose a directory name without the slash to avoid a nested directory:

git fetch --prune origin
git worktree add ./local-dir-name "branch/name-with-slash"

Note that --guess-remote is not a solution here. It only takes effect when no <commit-ish> is given, in which case it guesses the branch from the last path component only. So git worktree add --guess-remote feat/slashy looks for a remote branch named slashy, fails to find one, and silently creates an untracked branch off of HEAD. Passing --guess-remote alongside a <commit-ish> is simply a no-op.

Maintenance

git worktree list                   # show every worktree and the branch it has checked out
git worktree remove ./my-new-branch # delete a worktree's directory (refuses if it has uncommitted changes)
git branch -d my-new-branch         # then delete the branch, if it is no longer needed
git worktree prune                  # clean up records of worktree directories deleted without "git worktree remove"
git fetch --prune origin            # delete remote-tracking branches whose remote branch was deleted

Credit

Much of this was borrowed from Alex Russell's https://infrequently.org/2021/07/worktrees-step-by-step/.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment