@@ -9,39 +9,166 @@ git-worktree - Manage multiple worktrees
99SYNOPSIS
1010--------
1111[verse]
12+ 'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>]
1213'git worktree prune' [-n] [-v] [--expire <expire>]
1314
1415DESCRIPTION
1516-----------
1617
17- Manage multiple worktrees attached to the same repository. These are
18- created by the command `git checkout --to`.
18+ Manage multiple worktrees 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 checkout --to` 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.pruneworktreesexpire` 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 directory 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 directory
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 'lock' alongside the other
43+ administrative files, optionally containing a plain text reason that
44+ pruning should be suppressed. See section "DETAILS" for more information.
1945
2046COMMANDS
2147--------
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` is used, then, as a
55+ convenience, a new branch based at HEAD is created automatically, as if
56+ `-b $(basename <path>)` was specified.
57+
2258prune::
2359
2460Prune working tree information in $GIT_DIR/worktrees.
2561
2662OPTIONS
2763-------
2864
65+ -f::
66+ --force::
67+ By default, `add` refuses to create a new worktree when `<branch>`
68+ is already checked out by another worktree. 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 worktree.
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 worktree. See "DETACHED HEAD" in
82+ linkgit:git-checkout[1].
83+
2984-n::
3085--dry-run::
31- Do not remove anything; just report what it would
86+ With `prune`, do not remove anything; just report what it would
3287 remove.
3388
3489-v::
3590--verbose::
36- Report all removals.
91+ With `prune`, report all removals.
3792
3893--expire <time>::
39- Only expire unused worktrees older than <time>.
94+ With `prune`, only expire unused worktrees older than <time>.
4095
41- SEE ALSO
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 checkout --to /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 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
42138--------
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+ worktree is in such a state of disarray (with new, moved, and removed files,
143+ 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 worktree 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 support for submodules is incomplete. It is NOT
161+ recommended to make multiple checkouts of a superproject.
162+
163+ git-worktree could provide more automation for tasks currently
164+ performed manually, such as:
43165
44- linkgit:git-checkout[1]
166+ - `remove` to remove a linked worktree and its administrative files (and
167+ warn if the worktree is dirty)
168+ - `mv` to move or rename a worktree and update its administrative files
169+ - `list` to list linked worktrees
170+ - `lock` to prevent automatic pruning of administrative files (for instance,
171+ for a worktree on a portable device)
45172
46173GIT
47174---
0 commit comments