Unless stated otherwise, run every command from the repository root: the directory that contains .bare.
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.
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.
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.
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.
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'.
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.
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
Much of this was borrowed from Alex Russell's https://infrequently.org/2021/07/worktrees-step-by-step/.