git worktree: Usage, Options & Common CI Errors
git worktree lets one repository have several working directories, each on a different branch.
Worktrees avoid re-cloning when you need two branches checked out at once - handy for parallel CI builds.
What it does
git worktree creates additional working trees linked to the same repository, so you can have multiple branches checked out simultaneously without separate clones.
Common usage
Terminal
git worktree add ../hotfix hotfix
git worktree add -b release ../release origin/release
git worktree list
git worktree remove ../hotfix
git worktree pruneOptions
| Subcommand | What it does |
|---|---|
| add <path> [<branch>] | Create a worktree at path |
| add -b <new> <path> <ref> | Create a branch in a new worktree |
| list | List all worktrees |
| remove <path> | Delete a worktree |
| prune | Clean up stale worktree metadata |
Common errors in CI
fatal: 'X' is already checked out at '…' - a branch can be checked out in only one worktree at a time. Use a different branch, or --detach. After deleting a worktree directory manually, run git worktree prune to clear the dangling reference.
Related guides
git branch: Usage, Options & Common CI Errorsgit branch lists, creates, renames, and deletes branches. Reference for -d, -D, -m, --set-upstream-to, and th…
git switch: Usage, Options & Common CI Errorsgit switch changes branches with a focused, modern interface. Reference for -c, --detach, --track, and the er…
git clone: Usage, Options & Common CI Errorsgit clone copies a remote repository into a new local directory. Reference for depth, branch, and submodule f…
git gc: Usage, Options & Common CI Errorsgit gc compresses and prunes the object database to keep the repo fast and small. Reference for --aggressive,…