Merge branch 'maint'
[git/git.git] / Documentation / git-worktree.txt
1 git-worktree(1)
2 ===============
3
4 NAME
5 ----
6 git-worktree - Manage multiple working trees
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>]
13 'git worktree prune' [-n] [-v] [--expire <expire>]
14 'git worktree list' [--porcelain]
15
16 DESCRIPTION
17 -----------
18
19 Manage multiple working trees attached to the same repository.
20
21 A git repository can support multiple working trees, allowing you to check
22 out more than one branch at a time. With `git worktree add` a new working
23 tree is associated with the repository. This new working tree is called a
24 "linked working tree" as opposed to the "main working tree" prepared by "git
25 init" or "git clone". A repository has one main working tree (if it's not a
26 bare repository) and zero or more linked working trees.
27
28 When you are done with a linked working tree you can simply delete it.
29 The working tree's administrative files in the repository (see
30 "DETAILS" below) will eventually be removed automatically (see
31 `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
32 `git worktree prune` in the main or any linked working tree to
33 clean up any stale administrative files.
34
35 If you move a linked working tree to another file system, or
36 within a file system that does not support hard links, you need to run
37 at least one git command inside the linked working tree
38 (e.g. `git status`) in order to update its administrative files in the
39 repository so that they do not get automatically pruned.
40
41 If a linked working tree is stored on a portable device or network share
42 which is not always mounted, you can prevent its administrative files from
43 being pruned by creating a file named 'locked' alongside the other
44 administrative files, optionally containing a plain text reason that
45 pruning should be suppressed. See section "DETAILS" for more information.
46
47 COMMANDS
48 --------
49 add <path> [<branch>]::
50
51 Create `<path>` and checkout `<branch>` into it. The new working directory
52 is linked to the current repository, sharing everything except working
53 directory specific files such as HEAD, index, etc.
54 +
55 If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used,
56 then, as a convenience, a new branch based at HEAD is created automatically,
57 as if `-b $(basename <path>)` was specified.
58
59 prune::
60
61 Prune working tree information in $GIT_DIR/worktrees.
62
63 list::
64
65 List details of each worktree. The main worktree is listed first, followed by
66 each of the linked worktrees. The output details include if the worktree is
67 bare, the revision currently checked out, and the branch currently checked out
68 (or 'detached HEAD' if none).
69
70 OPTIONS
71 -------
72
73 -f::
74 --force::
75 By default, `add` refuses to create a new working tree when `<branch>`
76 is already checked out by another working tree. This option overrides
77 that safeguard.
78
79 -b <new-branch>::
80 -B <new-branch>::
81 With `add`, create a new branch named `<new-branch>` starting at
82 `<branch>`, and check out `<new-branch>` into the new working tree.
83 If `<branch>` is omitted, it defaults to HEAD.
84 By default, `-b` refuses to create a new branch if it already
85 exists. `-B` overrides this safeguard, resetting `<new-branch>` to
86 `<branch>`.
87
88 --detach::
89 With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
90 in linkgit:git-checkout[1].
91
92 -n::
93 --dry-run::
94 With `prune`, do not remove anything; just report what it would
95 remove.
96
97 --porcelain::
98 With `list`, output in an easy-to-parse format for scripts.
99 This format will remain stable across Git versions and regardless of user
100 configuration. See below for details.
101
102 -v::
103 --verbose::
104 With `prune`, report all removals.
105
106 --expire <time>::
107 With `prune`, only expire unused working trees older than <time>.
108
109 DETAILS
110 -------
111 Each linked working tree has a private sub-directory in the repository's
112 $GIT_DIR/worktrees directory. The private sub-directory's name is usually
113 the base name of the linked working tree's path, possibly appended with a
114 number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
115 command `git worktree add /path/other/test-next next` creates the linked
116 working tree in `/path/other/test-next` and also creates a
117 `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
118 if `test-next` is already taken).
119
120 Within a linked working tree, $GIT_DIR is set to point to this private
121 directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
122 $GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
123 (e.g. `/path/main/.git`). These settings are made in a `.git` file located at
124 the top directory of the linked working tree.
125
126 Path resolution via `git rev-parse --git-path` uses either
127 $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
128 linked working tree `git rev-parse --git-path HEAD` returns
129 `/path/main/.git/worktrees/test-next/HEAD` (not
130 `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
131 rev-parse --git-path refs/heads/master` uses
132 $GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
133 since refs are shared across all working trees.
134
135 See linkgit:gitrepository-layout[5] for more information. The rule of
136 thumb is do not make any assumption about whether a path belongs to
137 $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
138 inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
139
140 To prevent a $GIT_DIR/worktrees entry from being pruned (which
141 can be useful in some situations, such as when the
142 entry's working tree is stored on a portable device), add a file named
143 'locked' to the entry's directory. The file contains the reason in
144 plain text. For example, if a linked working tree's `.git` file points
145 to `/path/main/.git/worktrees/test-next` then a file named
146 `/path/main/.git/worktrees/test-next/locked` will prevent the
147 `test-next` entry from being pruned. See
148 linkgit:gitrepository-layout[5] for details.
149
150 LIST OUTPUT FORMAT
151 ------------------
152 The worktree list command has two output formats. The default format shows the
153 details on a single line with columns. For example:
154
155 ------------
156 S git worktree list
157 /path/to/bare-source (bare)
158 /path/to/linked-worktree abcd1234 [master]
159 /path/to/other-linked-worktree 1234abc (detached HEAD)
160 ------------
161
162 Porcelain Format
163 ~~~~~~~~~~~~~~~~
164 The porcelain format has a line per attribute. Attributes are listed with a
165 label and value separated by a single space. Boolean attributes (like 'bare'
166 and 'detached') are listed as a label only, and are only present if and only
167 if the value is true. An empty line indicates the end of a worktree. For
168 example:
169
170 ------------
171 S git worktree list --porcelain
172 worktree /path/to/bare-source
173 bare
174
175 worktree /path/to/linked-worktree
176 HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
177 branch refs/heads/master
178
179 worktree /path/to/other-linked-worktree
180 HEAD 1234abc1234abc1234abc1234abc1234abc1234a
181 detached
182
183 ------------
184
185 EXAMPLES
186 --------
187 You are in the middle of a refactoring session and your boss comes in and
188 demands that you fix something immediately. You might typically use
189 linkgit:git-stash[1] to store your changes away temporarily, however, your
190 working tree is in such a state of disarray (with new, moved, and removed
191 files, and other bits and pieces strewn around) that you don't want to risk
192 disturbing any of it. Instead, you create a temporary linked working tree to
193 make the emergency fix, remove it when done, and then resume your earlier
194 refactoring session.
195
196 ------------
197 $ git worktree add -b emergency-fix ../temp master
198 $ pushd ../temp
199 # ... hack hack hack ...
200 $ git commit -a -m 'emergency fix for boss'
201 $ popd
202 $ rm -rf ../temp
203 $ git worktree prune
204 ------------
205
206 BUGS
207 ----
208 Multiple checkout in general is still experimental, and the support
209 for submodules is incomplete. It is NOT recommended to make multiple
210 checkouts of a superproject.
211
212 git-worktree could provide more automation for tasks currently
213 performed manually, such as:
214
215 - `remove` to remove a linked working tree and its administrative files (and
216 warn if the working tree is dirty)
217 - `mv` to move or rename a working tree and update its administrative files
218 - `lock` to prevent automatic pruning of administrative files (for instance,
219 for a working tree on a portable device)
220
221 GIT
222 ---
223 Part of the linkgit:git[1] suite