git worktree: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

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 prune

Options

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git worktree: Usage, Options & Common CI Errors?