Git Reference ยท Branches and Tags
git worktree command
Reference for git worktree: add, list, remove, move, lock and prune linked working trees, use -b and --detach, and understand what is shared and what is not.
git worktree lets one repository have several working directories, each with its own checked-out branch. All of them share the same object database, refs and configuration, so a second worktree costs only the files on disk, not another clone.
Typical uses: reviewing a pull request while your own work stays untouched, running a long test on one branch while you edit another, or keeping a release checkout beside main. A branch can be checked out in only one worktree at a time.
git worktree add ../hotfix hotfix-branch git worktree list git worktree remove ../hotfix
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git worktree add [-f] [--detach] [--checkout | --no-checkout] [--lock [--reason <s>]] [-b <new-branch> | -B <new-branch>] <path> [<commit-ish>] git worktree list [--porcelain [-z]] [-v] git worktree remove [-f] <worktree> git worktree move <worktree> <new-path> git worktree lock [--reason <string>] <worktree> git worktree unlock <worktree> git worktree prune [-n] [-v] [--expire <time>] git worktree repair [<path>...]
| Name | Description |
|---|---|
add <path> [<commit-ish>] |
Create a new working tree at <path>. With a branch name it checks that branch out; with no commit-ish it creates a branch named after the directory. |
-b, -B |
Create (or reset) a new branch for the worktree. |
--detach |
Check out a commit with a detached HEAD. |
--no-checkout |
Create the directory without populating files (useful with sparse checkout). |
list |
Show all worktrees with their path, commit and branch. |
remove |
Delete a clean worktree and its administrative data; -f also removes one with changes. |
move |
Relocate a worktree. |
lock / unlock |
Prevent pruning or removal, for worktrees on removable media. |
prune |
Remove metadata for worktrees whose directory is gone. |
repair |
Fix links after the main repository or a worktree was moved by hand. |
Returns: add prints Preparing worktree ... (to standard error); list prints one line per worktree.
Errors: "fatal: '
Usage notes
- Shared: objects, refs, tags, remotes, and configuration (unless
extensions.worktreeConfigis on). Per worktree:HEAD, the index, and files likeMERGE_HEAD,rebase-mergeandrefs/bisect. - Layout: a linked worktree has a
.gitfile pointing to.git/worktrees/<name>in the main repository; see .git file and commondir. - Branch locking protects you from moving the same branch in two places.
--forceoverrides it for the rare cases you need it. - Do not delete the directory by hand. Use
git worktree remove; if you did delete it,git worktree prunecleans the records (they are also pruned bygit gc). - Moving the main repository breaks the links;
git worktree repairreconnects them. - Hooks and config such as
core.hooksPathapply to all worktrees; per-worktree values needgit config --worktree. - Submodules are not supported well in linked worktrees; avoid the combination for important work.
- Tooling tip: build output and
node_modulesare not shared, so each worktree needs its own installation.
Related
git switch,git branch,git stash,git gc, The .git directory- Lessons: Worktrees, Branch workflows