worktree: add --[no-]track option to the add subcommand
[git/git.git] / Documentation / git-worktree.txt
CommitLineData
df0b6cfb
NTND
1git-worktree(1)
2===============
3
4NAME
5----
bc483285 6git-worktree - Manage multiple working trees
df0b6cfb
NTND
7
8
9SYNOPSIS
10--------
11[verse]
c4738aed 12'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>]
bb9c03b8 13'git worktree list' [--porcelain]
58142c09 14'git worktree lock' [--reason <string>] <worktree>
7b722d90 15'git worktree prune' [-n] [-v] [--expire <expire>]
6d308627 16'git worktree unlock' <worktree>
df0b6cfb
NTND
17
18DESCRIPTION
19-----------
20
bc483285 21Manage multiple working trees attached to the same repository.
df0b6cfb 22
93a36493 23A git repository can support multiple working trees, allowing you to check
4d5a3c58 24out more than one branch at a time. With `git worktree add` a new working
93a36493
ES
25tree is associated with the repository. This new working tree is called a
26"linked working tree" as opposed to the "main working tree" prepared by "git
27init" or "git clone". A repository has one main working tree (if it's not a
28bare repository) and zero or more linked working trees.
29
93a36493 30When you are done with a linked working tree you can simply delete it.
af189b4c
ES
31The working tree's administrative files in the repository (see
32"DETAILS" below) will eventually be removed automatically (see
5f5f553f 33`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
93a36493 34`git worktree prune` in the main or any linked working tree to
af189b4c 35clean up any stale administrative files.
93a36493 36
618244e1
NTND
37If you move a linked working tree, you need to manually update the
38administrative files so that they do not get pruned automatically. See
39section "DETAILS" for more information.
93a36493 40
a8ba5dd7
ES
41If a linked working tree is stored on a portable device or network share
42which is not always mounted, you can prevent its administrative files from
58142c09
NTND
43being pruned by issuing the `git worktree lock` command, optionally
44specifying `--reason` to explain why the working tree is locked.
93a36493 45
df0b6cfb
NTND
46COMMANDS
47--------
c4738aed 48add <path> [<commit-ish>]::
fc56361f 49
c4738aed 50Create `<path>` and checkout `<commit-ish>` into it. The new working directory
fc56361f 51is linked to the current repository, sharing everything except working
1a450e2f 52directory specific files such as HEAD, index, etc. `-` may also be
c4738aed 53specified as `<commit-ish>`; it is synonymous with `@{-1}`.
1eb07d82 54+
c4738aed 55If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
5c942570
ES
56then, as a convenience, a new branch based at HEAD is created automatically,
57as if `-b $(basename <path>)` was specified.
fc56361f 58
bb9c03b8
MR
59list::
60
61List details of each worktree. The main worktree is listed first, followed by
62each of the linked worktrees. The output details include if the worktree is
63bare, the revision currently checked out, and the branch currently checked out
64(or 'detached HEAD' if none).
65
58142c09
NTND
66lock::
67
68If a working tree is on a portable device or network share which
69is not always mounted, lock it to prevent its administrative
70files from being pruned automatically. This also prevents it from
71being moved or deleted. Optionally, specify a reason for the lock
72with `--reason`.
73
7b722d90
NTND
74prune::
75
76Prune working tree information in $GIT_DIR/worktrees.
77
6d308627
NTND
78unlock::
79
80Unlock a working tree, allowing it to be pruned, moved or deleted.
81
df0b6cfb
NTND
82OPTIONS
83-------
84
f4325444
ES
85-f::
86--force::
c4738aed 87 By default, `add` refuses to create a new working tree when `<commit-ish>` is a branch name and
bc483285 88 is already checked out by another working tree. This option overrides
f4325444
ES
89 that safeguard.
90
cbdf60fa
ES
91-b <new-branch>::
92-B <new-branch>::
93 With `add`, create a new branch named `<new-branch>` starting at
c4738aed
TG
94 `<commit-ish>`, and check out `<new-branch>` into the new working tree.
95 If `<commit-ish>` is omitted, it defaults to HEAD.
cbdf60fa
ES
96 By default, `-b` refuses to create a new branch if it already
97 exists. `-B` overrides this safeguard, resetting `<new-branch>` to
c4738aed 98 `<commit-ish>`.
cbdf60fa 99
39ecb274 100--detach::
bc483285
MH
101 With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
102 in linkgit:git-checkout[1].
39ecb274 103
ef2a0ac9 104--[no-]checkout::
c4738aed 105 By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
ef2a0ac9
RZ
106 be used to suppress checkout in order to make customizations,
107 such as configuring sparse-checkout. See "Sparse checkout"
108 in linkgit:git-read-tree[1].
109
e284e892
TG
110--[no-]track::
111 When creating a new branch, if `<commit-ish>` is a branch,
112 mark it as "upstream" from the new branch. This is the
113 default if `<commit-ish>` is a remote-tracking branch. See
114 "--track" in linkgit:git-branch[1] for details.
115
507e6e9e
NTND
116--lock::
117 Keep the working tree locked after creation. This is the
118 equivalent of `git worktree lock` after `git worktree add`,
119 but without race condition.
120
df0b6cfb
NTND
121-n::
122--dry-run::
4f09825e 123 With `prune`, do not remove anything; just report what it would
df0b6cfb
NTND
124 remove.
125
bb9c03b8
MR
126--porcelain::
127 With `list`, output in an easy-to-parse format for scripts.
128 This format will remain stable across Git versions and regardless of user
129 configuration. See below for details.
130
df0b6cfb
NTND
131-v::
132--verbose::
4f09825e 133 With `prune`, report all removals.
df0b6cfb
NTND
134
135--expire <time>::
bc483285 136 With `prune`, only expire unused working trees older than <time>.
df0b6cfb 137
58142c09
NTND
138--reason <string>::
139 With `lock`, an explanation why the working tree is locked.
140
141<worktree>::
142 Working trees can be identified by path, either relative or
143 absolute.
080739ba
NTND
144+
145If the last path components in the working tree's path is unique among
146working trees, it can be used to identify worktrees. For example if
2b090822 147you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg",
080739ba 148then "ghi" or "def/ghi" is enough to point to the former working tree.
58142c09 149
af189b4c
ES
150DETAILS
151-------
152Each linked working tree has a private sub-directory in the repository's
153$GIT_DIR/worktrees directory. The private sub-directory's name is usually
154the base name of the linked working tree's path, possibly appended with a
155number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
4d5a3c58 156command `git worktree add /path/other/test-next next` creates the linked
af189b4c
ES
157working tree in `/path/other/test-next` and also creates a
158`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
159if `test-next` is already taken).
160
161Within a linked working tree, $GIT_DIR is set to point to this private
162directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
163$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
164(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
165the top directory of the linked working tree.
166
167Path resolution via `git rev-parse --git-path` uses either
168$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
169linked working tree `git rev-parse --git-path HEAD` returns
170`/path/main/.git/worktrees/test-next/HEAD` (not
171`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
172rev-parse --git-path refs/heads/master` uses
173$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
174since refs are shared across all working trees.
175
176See linkgit:gitrepository-layout[5] for more information. The rule of
177thumb is do not make any assumption about whether a path belongs to
178$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
179inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
180
618244e1
NTND
181If you move a linked working tree, you need to update the 'gitdir' file
182in the entry's directory. For example, if a linked working tree is moved
183to `/newpath/test-next` and its `.git` file points to
184`/path/main/.git/worktrees/test-next`, then update
185`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
186instead.
187
65f9b75d 188To prevent a $GIT_DIR/worktrees entry from being pruned (which
a8ba5dd7 189can be useful in some situations, such as when the
58142c09
NTND
190entry's working tree is stored on a portable device), use the
191`git worktree lock` command, which adds a file named
a8ba5dd7
ES
192'locked' to the entry's directory. The file contains the reason in
193plain text. For example, if a linked working tree's `.git` file points
194to `/path/main/.git/worktrees/test-next` then a file named
195`/path/main/.git/worktrees/test-next/locked` will prevent the
196`test-next` entry from being pruned. See
197linkgit:gitrepository-layout[5] for details.
198
bb9c03b8
MR
199LIST OUTPUT FORMAT
200------------------
201The worktree list command has two output formats. The default format shows the
202details on a single line with columns. For example:
203
204------------
205S git worktree list
206/path/to/bare-source (bare)
207/path/to/linked-worktree abcd1234 [master]
208/path/to/other-linked-worktree 1234abc (detached HEAD)
209------------
210
211Porcelain Format
212~~~~~~~~~~~~~~~~
213The porcelain format has a line per attribute. Attributes are listed with a
214label and value separated by a single space. Boolean attributes (like 'bare'
215and 'detached') are listed as a label only, and are only present if and only
216if the value is true. An empty line indicates the end of a worktree. For
217example:
218
219------------
220S git worktree list --porcelain
221worktree /path/to/bare-source
222bare
223
224worktree /path/to/linked-worktree
225HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
226branch refs/heads/master
227
228worktree /path/to/other-linked-worktree
229HEAD 1234abc1234abc1234abc1234abc1234abc1234a
230detached
231
232------------
233
96454597
ES
234EXAMPLES
235--------
236You are in the middle of a refactoring session and your boss comes in and
237demands that you fix something immediately. You might typically use
238linkgit:git-stash[1] to store your changes away temporarily, however, your
bc483285
MH
239working tree is in such a state of disarray (with new, moved, and removed
240files, and other bits and pieces strewn around) that you don't want to risk
241disturbing any of it. Instead, you create a temporary linked working tree to
96454597
ES
242make the emergency fix, remove it when done, and then resume your earlier
243refactoring session.
244
245------------
cbdf60fa 246$ git worktree add -b emergency-fix ../temp master
96454597
ES
247$ pushd ../temp
248# ... hack hack hack ...
249$ git commit -a -m 'emergency fix for boss'
250$ popd
251$ rm -rf ../temp
252$ git worktree prune
253------------
254
6d3824cf
ES
255BUGS
256----
18b22dbe
JH
257Multiple checkout in general is still experimental, and the support
258for submodules is incomplete. It is NOT recommended to make multiple
259checkouts of a superproject.
6d3824cf
ES
260
261git-worktree could provide more automation for tasks currently
fc56361f 262performed manually, such as:
6d3824cf 263
bc483285
MH
264- `remove` to remove a linked working tree and its administrative files (and
265 warn if the working tree is dirty)
266- `mv` to move or rename a working tree and update its administrative files
6d3824cf 267
df0b6cfb
NTND
268GIT
269---
270Part of the linkgit:git[1] suite