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