git worktree add: Usage, Options & Common CI Errors
git worktree add gives you a second working directory backed by the same repository.
Worktrees let a pipeline build several branches in parallel without re-cloning. Each tree has its own checkout but shares the object store, saving time and disk.
What it does
git worktree add creates a new working directory linked to the current repository, checking out a branch or commit there. The new tree shares objects and refs with the main one.
Common usage
Terminal
git worktree add ../feature feature
git worktree add -b hotfix ../hotfix main
git worktree add --detach ../inspect <sha>
git worktree add --track -b local ../local origin/remoteOptions
| Flag | What it does |
|---|---|
| <path> [<branch>] | Create a worktree at path on a branch |
| -b <name> | Create a new branch for the worktree |
| --detach | Check out a commit in detached HEAD |
| --track | Set up upstream tracking |
| -f / --force | Allow an already-checked-out branch |
Common errors in CI
fatal: '<branch>' is already checked out at '<path>' - a branch can be checked out in only one worktree at a time; use a different branch or --force. fatal: '<path>' already exists means the target directory is non-empty; pick a clean path.
Related guides
git worktree list: Usage, Options & Common CI Errorsgit worktree list shows every working tree linked to the repo, with paths and branches. Reference for --porce…
git worktree remove: Usage, Options & Common CI Errorsgit worktree remove deletes a linked working tree and its admin files. Reference for --force, prune, and the…
git worktree: Usage, Options & Common CI Errorsgit worktree checks out multiple branches into separate directories from one repo. Reference for add, list, r…
git switch --detach: Usage, Options & Common CI Errorsgit switch --detach checks out a commit without attaching to a branch. Reference for detaching at a SHA or ta…