blob: ada30c86a7c2139cccd1315370dc2f63c4472e26 [file] [log] [blame]
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +07001git-worktree(1)
2===============
3
4NAME
5----
Michael Haggertybc483282015-07-20 01:29:18 -04006git-worktree - Manage multiple working trees
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +07007
8
9SYNOPSIS
10--------
11[verse]
Stephen Manz0db49612021-07-15 02:32:30 +000012'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
Phillip Woodd97eb302022-03-31 16:21:28 +000013'git worktree list' [-v | --porcelain [-z]]
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +070014'git worktree lock' [--reason <string>] <worktree>
Nguyễn Thái Ngọc Duy9f792bb2018-02-12 16:49:36 +070015'git worktree move' <worktree> <new-path>
Nguyễn Thái Ngọc Duy7b722d92016-05-22 16:33:53 +070016'git worktree prune' [-n] [-v] [--expire <expire>]
Stefan Bellerd228eea2018-04-17 11:19:39 -070017'git worktree remove' [-f] <worktree>
Eric Sunshineb214ab52020-08-31 02:57:58 -040018'git worktree repair' [<path>...]
Nguyễn Thái Ngọc Duy6d308622016-06-13 19:18:25 +070019'git worktree unlock' <worktree>
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +070020
21DESCRIPTION
22-----------
23
Michael Haggertybc483282015-07-20 01:29:18 -040024Manage multiple working trees attached to the same repository.
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +070025
Eric Sunshine93a36492015-07-06 13:30:40 -040026A git repository can support multiple working trees, allowing you to check
Eric Sunshine4d5a3c52015-07-16 18:09:43 -040027out more than one branch at a time. With `git worktree add` a new working
Derrick Stoleec57bf8c2022-02-23 14:29:13 +000028tree is associated with the repository, along with additional metadata
29that differentiates that working tree from others in the same repository.
30The working tree, along with this metadata, is called a "worktree".
31
32This new worktree is called a "linked worktree" as opposed to the "main
33worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1].
34A repository has one main worktree (if it's not a bare repository) and
35zero or more linked worktrees. When you are done with a linked worktree,
36remove it with `git worktree remove`.
Eric Sunshine93a36492015-07-06 13:30:40 -040037
Eric Sunshinedccadad2020-09-06 20:02:22 -040038In its simplest form, `git worktree add <path>` automatically creates a
39new branch whose name is the final component of `<path>`, which is
40convenient if you plan to work on a new topic. For instance, `git
41worktree add ../hotfix` creates new branch `hotfix` and checks it out at
Derrick Stoleec57bf8c2022-02-23 14:29:13 +000042path `../hotfix`. To instead work on an existing branch in a new worktree,
43use `git worktree add <path> <branch>`. On the other hand, if you just
44plan to make some experimental changes or do testing without disturbing
45existing development, it is often convenient to create a 'throwaway'
46worktree not associated with any branch. For instance,
47`git worktree add -d <path>` creates a new worktree with a detached `HEAD`
48at the same commit as the current branch.
Eric Sunshinedccadad2020-09-06 20:02:22 -040049
Eric Sunshine3f0b42b2018-04-09 03:33:59 -040050If a working tree is deleted without using `git worktree remove`, then
51its associated administrative files, which reside in the repository
52(see "DETAILS" below), will eventually be removed automatically (see
Eric Sunshine5f5f5532015-07-24 00:00:52 -040053`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
Derrick Stoleec57bf8c2022-02-23 14:29:13 +000054`git worktree prune` in the main or any linked worktree to clean up any
55stale administrative files.
Eric Sunshine93a36492015-07-06 13:30:40 -040056
Derrick Stoleec57bf8c2022-02-23 14:29:13 +000057If the working tree for a linked worktree is stored on a portable device
58or network share which is not always mounted, you can prevent its
59administrative files from being pruned by issuing the `git worktree lock`
60command, optionally specifying `--reason` to explain why the worktree is
61locked.
Eric Sunshine93a36492015-07-06 13:30:40 -040062
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +070063COMMANDS
64--------
Thomas Gummererc4738ae2017-11-26 19:43:52 +000065add <path> [<commit-ish>]::
Eric Sunshinefc563612015-07-06 13:30:50 -040066
Derrick Stoleec57bf8c2022-02-23 14:29:13 +000067Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree
68is linked to the current repository, sharing everything except per-worktree
69files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may
70be a bare "`-`", which is synonymous with `@{-1}`.
Eric Sunshine1eb07d82015-07-06 13:30:59 -040071+
Eric Sunshinee79e3132020-08-03 20:55:31 -040072If `<commit-ish>` is a branch name (call it `<branch>`) and is not found,
Thomas Gummerer4e853332017-11-26 19:43:54 +000073and neither `-b` nor `-B` nor `--detach` are used, but there does
74exist a tracking branch in exactly one remote (call it `<remote>`)
Eric Sunshine661a5a32018-02-16 15:44:51 -050075with a matching name, treat as equivalent to:
Eric Sunshined023df12018-02-16 15:44:52 -050076+
Thomas Gummerer4e853332017-11-26 19:43:54 +000077------------
78$ git worktree add --track -b <branch> <path> <remote>/<branch>
79------------
80+
Ævar Arnfjörð Bjarmason8d7b5582018-06-05 14:40:49 +000081If the branch exists in multiple remotes and one of them is named by
82the `checkout.defaultRemote` configuration variable, we'll use that
83one for the purposes of disambiguation, even if the `<branch>` isn't
84unique across all remotes. Set it to
85e.g. `checkout.defaultRemote=origin` to always checkout remote
86branches from there if `<branch>` is ambiguous but exists on the
Eric Sunshinee79e3132020-08-03 20:55:31 -040087`origin` remote. See also `checkout.defaultRemote` in
Ævar Arnfjörð Bjarmason8d7b5582018-06-05 14:40:49 +000088linkgit:git-config[1].
89+
Thomas Gummererc4738ae2017-11-26 19:43:52 +000090If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
Derrick Stolee59970142022-02-23 14:29:14 +000091then, as a convenience, the new worktree is associated with a branch (call
92it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't
93exist, a new branch based on `HEAD` is automatically created as if
94`-b <branch>` was given. If `<branch>` does exist, it will be checked out
95in the new worktree, if it's not checked out anywhere else, otherwise the
96command will refuse to create the worktree (unless `--force` is used).
Eric Sunshinefc563612015-07-06 13:30:50 -040097
Michael Rappazzobb9c03b2015-10-08 13:01:05 -040098list::
99
Derrick Stolee59970142022-02-23 14:29:14 +0000100List details of each worktree. The main worktree is listed first,
101followed by each of the linked worktrees. The output details include
102whether the worktree is bare, the revision currently checked out, the
Rafael Silva9b19a582021-01-27 09:03:09 +0100103branch currently checked out (or "detached HEAD" if none), "locked" if
Derrick Stolee59970142022-02-23 14:29:14 +0000104the worktree is locked, "prunable" if the worktree can be pruned by the
105`prune` command.
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400106
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700107lock::
108
Derrick Stolee59970142022-02-23 14:29:14 +0000109If a worktree is on a portable device or network share which is not always
110mounted, lock it to prevent its administrative files from being pruned
111automatically. This also prevents it from being moved or deleted.
112Optionally, specify a reason for the lock with `--reason`.
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700113
Nguyễn Thái Ngọc Duy9f792bb2018-02-12 16:49:36 +0700114move::
115
Derrick Stolee59970142022-02-23 14:29:14 +0000116Move a worktree to a new location. Note that the main worktree or linked
117worktrees containing submodules cannot be moved with this command. (The
118`git worktree repair` command, however, can reestablish the connection
119with linked worktrees if you move the main worktree manually.)
Nguyễn Thái Ngọc Duy9f792bb2018-02-12 16:49:36 +0700120
Nguyễn Thái Ngọc Duy7b722d92016-05-22 16:33:53 +0700121prune::
122
Derrick Stolee59970142022-02-23 14:29:14 +0000123Prune worktree information in `$GIT_DIR/worktrees`.
Nguyễn Thái Ngọc Duy7b722d92016-05-22 16:33:53 +0700124
Nguyễn Thái Ngọc Duycc733852018-02-12 16:49:39 +0700125remove::
126
Derrick Stolee59970142022-02-23 14:29:14 +0000127Remove a worktree. Only clean worktrees (no untracked files and no
128modification in tracked files) can be removed. Unclean worktrees or ones
129with submodules can be removed with `--force`. The main worktree cannot be
130removed.
Nguyễn Thái Ngọc Duycc733852018-02-12 16:49:39 +0700131
Eric Sunshineb214ab52020-08-31 02:57:58 -0400132repair [<path>...]::
Eric Sunshinee8e1ff22020-08-27 04:21:25 -0400133
Derrick Stolee59970142022-02-23 14:29:14 +0000134Repair worktree administrative files, if possible, if they have become
135corrupted or outdated due to external factors.
Eric Sunshinebdd1f3e2020-08-31 02:57:57 -0400136+
Derrick Stolee59970142022-02-23 14:29:14 +0000137For instance, if the main worktree (or bare repository) is moved, linked
138worktrees will be unable to locate it. Running `repair` in the main
139worktree will reestablish the connection from linked worktrees back to the
140main worktree.
Eric Sunshineb214ab52020-08-31 02:57:58 -0400141+
Derrick Stolee59970142022-02-23 14:29:14 +0000142Similarly, if the working tree for a linked worktree is moved without
143using `git worktree move`, the main worktree (or bare repository) will be
144unable to locate it. Running `repair` within the recently-moved worktree
145will reestablish the connection. If multiple linked worktrees are moved,
146running `repair` from any worktree with each tree's new `<path>` as an
147argument, will reestablish the connection to all the specified paths.
Eric Sunshinecf76bae2020-12-21 03:16:01 -0500148+
Derrick Stolee59970142022-02-23 14:29:14 +0000149If both the main worktree and linked worktrees have been moved manually,
150then running `repair` in the main worktree and specifying the new `<path>`
151of each linked worktree will reestablish all connections in both
152directions.
Eric Sunshinee8e1ff22020-08-27 04:21:25 -0400153
Nguyễn Thái Ngọc Duy6d308622016-06-13 19:18:25 +0700154unlock::
155
Derrick Stolee59970142022-02-23 14:29:14 +0000156Unlock a worktree, allowing it to be pruned, moved or deleted.
Nguyễn Thái Ngọc Duy6d308622016-06-13 19:18:25 +0700157
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700158OPTIONS
159-------
160
Eric Sunshinef4325442015-07-06 13:30:51 -0400161-f::
162--force::
Derrick Stolee6036be12022-02-23 14:29:15 +0000163 By default, `add` refuses to create a new worktree when
Nguyễn Thái Ngọc Duycc733852018-02-12 16:49:39 +0700164 `<commit-ish>` is a branch name and is already checked out by
Derrick Stolee6036be12022-02-23 14:29:15 +0000165 another worktree, or if `<path>` is already assigned to some
166 worktree but is missing (for instance, if `<path>` was deleted
Eric Sunshinee19831c2018-08-28 17:20:23 -0400167 manually). This option overrides these safeguards. To add a missing but
Derrick Stolee6036be12022-02-23 14:29:15 +0000168 locked worktree path, specify `--force` twice.
Eric Sunshinee19831c2018-08-28 17:20:23 -0400169+
Derrick Stolee6036be12022-02-23 14:29:15 +0000170`move` refuses to move a locked worktree unless `--force` is specified
171twice. If the destination is already assigned to some other worktree but is
Eric Sunshine810382e2020-06-10 02:30:49 -0400172missing (for instance, if `<new-path>` was deleted manually), then `--force`
Eric Sunshinee79e3132020-08-03 20:55:31 -0400173allows the move to proceed; use `--force` twice if the destination is locked.
Eric Sunshine68a6b3a2018-08-28 17:20:24 -0400174+
Derrick Stolee6036be12022-02-23 14:29:15 +0000175`remove` refuses to remove an unclean worktree unless `--force` is used.
176To remove a locked worktree, specify `--force` twice.
Eric Sunshinef4325442015-07-06 13:30:51 -0400177
Eric Sunshinecbdf60f2015-07-06 13:30:53 -0400178-b <new-branch>::
179-B <new-branch>::
180 With `add`, create a new branch named `<new-branch>` starting at
Derrick Stolee6036be12022-02-23 14:29:15 +0000181 `<commit-ish>`, and check out `<new-branch>` into the new worktree.
Eric Sunshinee79e3132020-08-03 20:55:31 -0400182 If `<commit-ish>` is omitted, it defaults to `HEAD`.
Eric Sunshinecbdf60f2015-07-06 13:30:53 -0400183 By default, `-b` refuses to create a new branch if it already
184 exists. `-B` overrides this safeguard, resetting `<new-branch>` to
Thomas Gummererc4738ae2017-11-26 19:43:52 +0000185 `<commit-ish>`.
Eric Sunshinecbdf60f2015-07-06 13:30:53 -0400186
Eric Sunshinec670aa42020-09-06 20:02:21 -0400187-d::
Eric Sunshine39ecb272015-07-06 13:30:52 -0400188--detach::
Derrick Stolee6036be12022-02-23 14:29:15 +0000189 With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD"
Michael Haggertybc483282015-07-20 01:29:18 -0400190 in linkgit:git-checkout[1].
Eric Sunshine39ecb272015-07-06 13:30:52 -0400191
Ray Zhangef2a0ac2016-03-29 10:11:01 +0000192--[no-]checkout::
Thomas Gummererc4738ae2017-11-26 19:43:52 +0000193 By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
Ray Zhangef2a0ac2016-03-29 10:11:01 +0000194 be used to suppress checkout in order to make customizations,
195 such as configuring sparse-checkout. See "Sparse checkout"
196 in linkgit:git-read-tree[1].
197
Thomas Gummerer71d66822017-11-29 20:04:50 +0000198--[no-]guess-remote::
199 With `worktree add <path>`, without `<commit-ish>`, instead
Eric Sunshinee79e3132020-08-03 20:55:31 -0400200 of creating a new branch from `HEAD`, if there exists a tracking
Ralf Thielow50fdf7b2018-01-11 19:18:21 +0100201 branch in exactly one remote matching the basename of `<path>`,
Thomas Gummerer71d66822017-11-29 20:04:50 +0000202 base the new branch on the remote-tracking branch, and mark
203 the remote-tracking branch as "upstream" from the new branch.
Thomas Gummerere92445a2017-11-29 20:04:51 +0000204+
205This can also be set up as the default behaviour by using the
206`worktree.guessRemote` config option.
Thomas Gummerer71d66822017-11-29 20:04:50 +0000207
Thomas Gummerere284e892017-11-26 19:43:53 +0000208--[no-]track::
209 When creating a new branch, if `<commit-ish>` is a branch,
210 mark it as "upstream" from the new branch. This is the
211 default if `<commit-ish>` is a remote-tracking branch. See
Eric Sunshinee79e3132020-08-03 20:55:31 -0400212 `--track` in linkgit:git-branch[1] for details.
Thomas Gummerere284e892017-11-26 19:43:53 +0000213
Nguyễn Thái Ngọc Duy507e6e92017-04-12 20:58:05 +0700214--lock::
Derrick Stolee6036be12022-02-23 14:29:15 +0000215 Keep the worktree locked after creation. This is the
Nguyễn Thái Ngọc Duy507e6e92017-04-12 20:58:05 +0700216 equivalent of `git worktree lock` after `git worktree add`,
Eric Sunshineff1ce502020-08-03 20:55:33 -0400217 but without a race condition.
Nguyễn Thái Ngọc Duy507e6e92017-04-12 20:58:05 +0700218
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700219-n::
220--dry-run::
Eric Sunshine4f098252015-07-06 13:30:39 -0400221 With `prune`, do not remove anything; just report what it would
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700222 remove.
223
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400224--porcelain::
225 With `list`, output in an easy-to-parse format for scripts.
226 This format will remain stable across Git versions and regardless of user
Phillip Woodd97eb302022-03-31 16:21:28 +0000227 configuration. It is recommended to combine this with `-z`.
228 See below for details.
229
230-z::
231 Terminate each line with a NUL rather than a newline when
232 `--porcelain` is specified with `list`. This makes it possible
233 to parse the output when a worktree path contains a newline
234 character.
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400235
Elia Pinto371979c2018-08-15 20:56:30 +0000236-q::
237--quiet::
Eric Sunshinee79e3132020-08-03 20:55:31 -0400238 With `add`, suppress feedback messages.
Elia Pinto371979c2018-08-15 20:56:30 +0000239
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700240-v::
241--verbose::
Eric Sunshine4f098252015-07-06 13:30:39 -0400242 With `prune`, report all removals.
Rafael Silva076b4442021-01-27 09:03:10 +0100243+
244With `list`, output additional information about worktrees (see below).
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700245
246--expire <time>::
Derrick Stolee6036be12022-02-23 14:29:15 +0000247 With `prune`, only expire unused worktrees older than `<time>`.
Rafael Silva9b19a582021-01-27 09:03:09 +0100248+
Derrick Stolee6036be12022-02-23 14:29:15 +0000249With `list`, annotate missing worktrees as prunable if they are older than
250`<time>`.
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700251
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700252--reason <string>::
Derrick Stolee6036be12022-02-23 14:29:15 +0000253 With `lock` or with `add --lock`, an explanation why the worktree
254 is locked.
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700255
256<worktree>::
Derrick Stolee6036be12022-02-23 14:29:15 +0000257 Worktrees can be identified by path, either relative or absolute.
Nguyễn Thái Ngọc Duy080739b2016-06-13 19:18:26 +0700258+
Derrick Stolee6036be12022-02-23 14:29:15 +0000259If the last path components in the worktree's path is unique among
260worktrees, it can be used to identify a worktree. For example if you only
261have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or
262`def/ghi` is enough to point to the former worktree.
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700263
Nguyễn Thái Ngọc Duy8aff1a92018-09-29 21:10:23 +0200264REFS
265----
Derrick Stoleea777d4c2022-02-23 14:29:16 +0000266When using multiple worktrees, some refs are shared between all worktrees,
267but others are specific to an individual worktree. One example is `HEAD`,
268which is different for each worktree. This section is about the sharing
269rules and how to access refs of one worktree from another.
Nguyễn Thái Ngọc Duy8aff1a92018-09-29 21:10:23 +0200270
Derrick Stoleea777d4c2022-02-23 14:29:16 +0000271In general, all pseudo refs are per-worktree and all refs starting with
272`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly
273under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,
274however: refs inside `refs/bisect` and `refs/worktree` are not shared.
Nguyễn Thái Ngọc Duy8aff1a92018-09-29 21:10:23 +0200275
Derrick Stoleea777d4c2022-02-23 14:29:16 +0000276Refs that are per-worktree can still be accessed from another worktree via
277two special paths, `main-worktree` and `worktrees`. The former gives
278access to per-worktree refs of the main worktree, while the latter to all
279linked worktrees.
Nguyễn Thái Ngọc Duy3a3b9d82018-10-21 10:08:54 +0200280
Eric Sunshinee79e3132020-08-03 20:55:31 -0400281For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good`
Derrick Stoleea777d4c2022-02-23 14:29:16 +0000282resolve to the same value as the main worktree's `HEAD` and
Eric Sunshinee79e3132020-08-03 20:55:31 -0400283`refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or
284`worktrees/bar/refs/bisect/bad` are the same as
285`$GIT_COMMON_DIR/worktrees/foo/HEAD` and
286`$GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad`.
Nguyễn Thái Ngọc Duy3a3b9d82018-10-21 10:08:54 +0200287
Eric Sunshinee79e3132020-08-03 20:55:31 -0400288To access refs, it's best not to look inside `$GIT_DIR` directly. Instead
Nguyễn Thái Ngọc Duy14f74d52018-11-03 06:14:18 +0100289use commands such as linkgit:git-rev-parse[1] or linkgit:git-update-ref[1]
Nguyễn Thái Ngọc Duy8aff1a92018-09-29 21:10:23 +0200290which will handle refs correctly.
291
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200292CONFIGURATION FILE
293------------------
Derrick Stolee7b215822022-02-23 14:29:17 +0000294By default, the repository `config` file is shared across all worktrees.
295If the config variables `core.bare` or `core.worktree` are present in the
296common config file and `extensions.worktreeConfig` is disabled, then they
297will be applied to the main worktree only.
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200298
Derrick Stolee7b215822022-02-23 14:29:17 +0000299In order to have worktree-specific configuration, you can turn on the
300`worktreeConfig` extension, e.g.:
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200301
302------------
303$ git config extensions.worktreeConfig true
304------------
305
306In this mode, specific configuration stays in the path pointed by `git
307rev-parse --git-path config.worktree`. You can add or update
308configuration in this file with `git config --worktree`. Older Git
309versions will refuse to access repositories with this extension.
310
311Note that in this file, the exception for `core.bare` and `core.worktree`
Eric Sunshineff1ce502020-08-03 20:55:33 -0400312is gone. If they exist in `$GIT_DIR/config`, you must move
Derrick Stolee7b215822022-02-23 14:29:17 +0000313them to the `config.worktree` of the main worktree. You may also take this
314opportunity to review and move other configuration that you do not want to
315share to all worktrees:
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200316
Derrick Stolee5c11c0d2022-02-07 21:32:58 +0000317 - `core.worktree` should never be shared.
318
319 - `core.bare` should not be shared if the value is `core.bare=true`.
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200320
Derrick Stolee7b215822022-02-23 14:29:17 +0000321 - `core.sparseCheckout` should not be shared, unless you are sure you
322 always use sparse checkout for all worktrees.
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200323
Derrick Stolee5c11c0d2022-02-07 21:32:58 +0000324See the documentation of `extensions.worktreeConfig` in
325linkgit:git-config[1] for more details.
326
Eric Sunshineaf189b42015-07-06 13:30:42 -0400327DETAILS
328-------
Derrick Stoleef13a1462022-02-23 14:29:18 +0000329Each linked worktree has a private sub-directory in the repository's
Eric Sunshinee79e3132020-08-03 20:55:31 -0400330`$GIT_DIR/worktrees` directory. The private sub-directory's name is usually
Derrick Stoleef13a1462022-02-23 14:29:18 +0000331the base name of the linked worktree's path, possibly appended with a
Eric Sunshineaf189b42015-07-06 13:30:42 -0400332number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
Eric Sunshine4d5a3c52015-07-16 18:09:43 -0400333command `git worktree add /path/other/test-next next` creates the linked
Derrick Stoleef13a1462022-02-23 14:29:18 +0000334worktree in `/path/other/test-next` and also creates a
Eric Sunshineaf189b42015-07-06 13:30:42 -0400335`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
336if `test-next` is already taken).
337
Derrick Stoleef13a1462022-02-23 14:29:18 +0000338Within a linked worktree, `$GIT_DIR` is set to point to this private
Eric Sunshineaf189b42015-07-06 13:30:42 -0400339directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
Derrick Stoleef13a1462022-02-23 14:29:18 +0000340`$GIT_COMMON_DIR` is set to point back to the main worktree's `$GIT_DIR`
Eric Sunshineaf189b42015-07-06 13:30:42 -0400341(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
Derrick Stoleef13a1462022-02-23 14:29:18 +0000342the top directory of the linked worktree.
Eric Sunshineaf189b42015-07-06 13:30:42 -0400343
344Path resolution via `git rev-parse --git-path` uses either
Eric Sunshinee79e3132020-08-03 20:55:31 -0400345`$GIT_DIR` or `$GIT_COMMON_DIR` depending on the path. For example, in the
Derrick Stoleef13a1462022-02-23 14:29:18 +0000346linked worktree `git rev-parse --git-path HEAD` returns
Eric Sunshineaf189b42015-07-06 13:30:42 -0400347`/path/main/.git/worktrees/test-next/HEAD` (not
348`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
349rev-parse --git-path refs/heads/master` uses
Eric Sunshinee79e3132020-08-03 20:55:31 -0400350`$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`,
Derrick Stoleef13a1462022-02-23 14:29:18 +0000351since refs are shared across all worktrees, except `refs/bisect` and
Eric Sunshinee79e3132020-08-03 20:55:31 -0400352`refs/worktree`.
Eric Sunshineaf189b42015-07-06 13:30:42 -0400353
354See linkgit:gitrepository-layout[5] for more information. The rule of
355thumb is do not make any assumption about whether a path belongs to
Eric Sunshinee79e3132020-08-03 20:55:31 -0400356`$GIT_DIR` or `$GIT_COMMON_DIR` when you need to directly access something
357inside `$GIT_DIR`. Use `git rev-parse --git-path` to get the final path.
Eric Sunshineaf189b42015-07-06 13:30:42 -0400358
Derrick Stoleef13a1462022-02-23 14:29:18 +0000359If you manually move a linked worktree, you need to update the `gitdir` file
360in the entry's directory. For example, if a linked worktree is moved
Nguyễn Thái Ngọc Duy618244e2016-01-22 15:35:49 +0700361to `/newpath/test-next` and its `.git` file points to
362`/path/main/.git/worktrees/test-next`, then update
363`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
Eric Sunshineb214ab52020-08-31 02:57:58 -0400364instead. Better yet, run `git worktree repair` to reestablish the connection
365automatically.
Nguyễn Thái Ngọc Duy618244e2016-01-22 15:35:49 +0700366
Eric Sunshinee79e3132020-08-03 20:55:31 -0400367To prevent a `$GIT_DIR/worktrees` entry from being pruned (which
Eric Sunshinea8ba5dd2015-07-06 13:30:43 -0400368can be useful in some situations, such as when the
Derrick Stoleef13a1462022-02-23 14:29:18 +0000369entry's worktree is stored on a portable device), use the
Nguyễn Thái Ngọc Duy58142c02016-06-13 19:18:24 +0700370`git worktree lock` command, which adds a file named
Eric Sunshinee79e3132020-08-03 20:55:31 -0400371`locked` to the entry's directory. The file contains the reason in
Derrick Stoleef13a1462022-02-23 14:29:18 +0000372plain text. For example, if a linked worktree's `.git` file points
Eric Sunshinea8ba5dd2015-07-06 13:30:43 -0400373to `/path/main/.git/worktrees/test-next` then a file named
374`/path/main/.git/worktrees/test-next/locked` will prevent the
375`test-next` entry from being pruned. See
376linkgit:gitrepository-layout[5] for details.
377
Eric Sunshinee79e3132020-08-03 20:55:31 -0400378When `extensions.worktreeConfig` is enabled, the config file
Nguyễn Thái Ngọc Duy58b284a2018-10-21 16:02:28 +0200379`.git/worktrees/<id>/config.worktree` is read after `.git/config` is.
380
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400381LIST OUTPUT FORMAT
382------------------
Eric Sunshinee79e3132020-08-03 20:55:31 -0400383The `worktree list` command has two output formats. The default format shows the
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400384details on a single line with columns. For example:
385
386------------
Eric Sunshine22d11a62018-04-09 03:34:00 -0400387$ git worktree list
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400388/path/to/bare-source (bare)
389/path/to/linked-worktree abcd1234 [master]
390/path/to/other-linked-worktree 1234abc (detached HEAD)
391------------
392
Derrick Stolee07d85382022-02-23 14:29:19 +0000393The command also shows annotations for each worktree, according to its state.
Rafael Silva9b19a582021-01-27 09:03:09 +0100394These annotations are:
395
Derrick Stolee07d85382022-02-23 14:29:19 +0000396 * `locked`, if the worktree is locked.
397 * `prunable`, if the worktree can be pruned via `git worktree prune`.
Rafael Silva9b19a582021-01-27 09:03:09 +0100398
399------------
400$ git worktree list
401/path/to/linked-worktree abcd1234 [master]
Andrei Rybak98c76562021-06-25 21:38:51 +0200402/path/to/locked-worktree acbd5678 (brancha) locked
Rafael Silva9b19a582021-01-27 09:03:09 +0100403/path/to/prunable-worktree 5678abc (detached HEAD) prunable
404------------
405
Rafael Silva076b4442021-01-27 09:03:10 +0100406For these annotations, a reason might also be available and this can be
407seen using the verbose mode. The annotation is then moved to the next line
408indented followed by the additional information.
409
410------------
411$ git worktree list --verbose
412/path/to/linked-worktree abcd1234 [master]
413/path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked
414/path/to/locked-worktree-with-reason 1234abcd (brancha)
Derrick Stolee07d85382022-02-23 14:29:19 +0000415 locked: worktree path is mounted on a portable device
Rafael Silva076b4442021-01-27 09:03:10 +0100416/path/to/prunable-worktree 5678abc1 (detached HEAD)
417 prunable: gitdir file points to non-existent location
418------------
419
420Note that the annotation is moved to the next line if the additional
421information is available, otherwise it stays on the same line as the
Derrick Stolee07d85382022-02-23 14:29:19 +0000422worktree itself.
Rafael Silva076b4442021-01-27 09:03:10 +0100423
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400424Porcelain Format
425~~~~~~~~~~~~~~~~
Phillip Woodd97eb302022-03-31 16:21:28 +0000426The porcelain format has a line per attribute. If `-z` is given then the lines
427are terminated with NUL rather than a newline. Attributes are listed with a
Eric Sunshinee79e3132020-08-03 20:55:31 -0400428label and value separated by a single space. Boolean attributes (like `bare`
Eric Sunshineff1ce502020-08-03 20:55:33 -0400429and `detached`) are listed as a label only, and are present only
Rafael Silva862c7232021-01-27 09:03:08 +0100430if the value is true. Some attributes (like `locked`) can be listed as a label
431only or with a value depending upon whether a reason is available. The first
Derrick Stolee07d85382022-02-23 14:29:19 +0000432attribute of a worktree is always `worktree`, an empty line indicates the
Rafael Silva862c7232021-01-27 09:03:08 +0100433end of the record. For example:
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400434
435------------
Eric Sunshine22d11a62018-04-09 03:34:00 -0400436$ git worktree list --porcelain
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400437worktree /path/to/bare-source
438bare
439
440worktree /path/to/linked-worktree
441HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
442branch refs/heads/master
443
444worktree /path/to/other-linked-worktree
445HEAD 1234abc1234abc1234abc1234abc1234abc1234a
446detached
447
Rafael Silva862c7232021-01-27 09:03:08 +0100448worktree /path/to/linked-worktree-locked-no-reason
449HEAD 5678abc5678abc5678abc5678abc5678abc5678c
450branch refs/heads/locked-no-reason
451locked
452
453worktree /path/to/linked-worktree-locked-with-reason
454HEAD 3456def3456def3456def3456def3456def3456b
455branch refs/heads/locked-with-reason
456locked reason why is locked
457
Rafael Silva9b19a582021-01-27 09:03:09 +0100458worktree /path/to/linked-worktree-prunable
459HEAD 1233def1234def1234def1234def1234def1234b
460detached
461prunable gitdir file points to non-existent location
462
Rafael Silva862c7232021-01-27 09:03:08 +0100463------------
464
Phillip Woodd97eb302022-03-31 16:21:28 +0000465Unless `-z` is used any "unusual" characters in the lock reason such as newlines
Rafael Silva862c7232021-01-27 09:03:08 +0100466are escaped and the entire reason is quoted as explained for the
467configuration variable `core.quotePath` (see linkgit:git-config[1]).
468For Example:
469
470------------
471$ git worktree list --porcelain
472...
473locked "reason\nwhy is locked"
474...
Michael Rappazzobb9c03b2015-10-08 13:01:05 -0400475------------
476
Eric Sunshine96454592015-07-06 13:30:44 -0400477EXAMPLES
478--------
479You are in the middle of a refactoring session and your boss comes in and
480demands that you fix something immediately. You might typically use
481linkgit:git-stash[1] to store your changes away temporarily, however, your
Michael Haggertybc483282015-07-20 01:29:18 -0400482working tree is in such a state of disarray (with new, moved, and removed
483files, and other bits and pieces strewn around) that you don't want to risk
Derrick Stolee07d85382022-02-23 14:29:19 +0000484disturbing any of it. Instead, you create a temporary linked worktree to
Eric Sunshine96454592015-07-06 13:30:44 -0400485make the emergency fix, remove it when done, and then resume your earlier
486refactoring session.
487
488------------
Eric Sunshinecbdf60f2015-07-06 13:30:53 -0400489$ git worktree add -b emergency-fix ../temp master
Eric Sunshine96454592015-07-06 13:30:44 -0400490$ pushd ../temp
491# ... hack hack hack ...
492$ git commit -a -m 'emergency fix for boss'
493$ popd
Eric Sunshine3f0b42b2018-04-09 03:33:59 -0400494$ git worktree remove ../temp
Eric Sunshine96454592015-07-06 13:30:44 -0400495------------
496
Eric Sunshine6d3824c2015-07-06 13:30:41 -0400497BUGS
498----
Junio C Hamano18b22db2015-07-16 15:59:48 -0700499Multiple checkout in general is still experimental, and the support
500for submodules is incomplete. It is NOT recommended to make multiple
501checkouts of a superproject.
Eric Sunshine6d3824c2015-07-06 13:30:41 -0400502
Nguyễn Thái Ngọc Duydf0b6cf2015-06-29 19:51:18 +0700503GIT
504---
505Part of the linkgit:git[1] suite