]>
Commit | Line | Data |
---|---|---|
df0b6cfb NTND |
1 | git-worktree(1) |
2 | =============== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-worktree - Manage multiple worktrees | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
11 | [verse] | |
cbdf60fa | 12 | 'git worktree add' [-f] [--detach] [-b <new-branch>] <path> <branch> |
df0b6cfb NTND |
13 | 'git worktree prune' [-n] [-v] [--expire <expire>] |
14 | ||
15 | DESCRIPTION | |
16 | ----------- | |
17 | ||
fc56361f | 18 | Manage multiple worktrees attached to the same repository. |
df0b6cfb | 19 | |
93a36493 ES |
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 | ||
93a36493 | 27 | When you are done with a linked working tree you can simply delete it. |
af189b4c ES |
28 | The working tree's administrative files in the repository (see |
29 | "DETAILS" below) will eventually be removed automatically (see | |
93a36493 ES |
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 | |
af189b4c | 32 | clean up any stale administrative files. |
93a36493 ES |
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 | |
af189b4c ES |
37 | (e.g. `git status`) in order to update its administrative files in the |
38 | repository so that they do not get automatically pruned. | |
93a36493 | 39 | |
a8ba5dd7 ES |
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. | |
93a36493 | 45 | |
df0b6cfb NTND |
46 | COMMANDS |
47 | -------- | |
fc56361f ES |
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 | ||
df0b6cfb NTND |
54 | prune:: |
55 | ||
56 | Prune working tree information in $GIT_DIR/worktrees. | |
57 | ||
58 | OPTIONS | |
59 | ------- | |
60 | ||
f4325444 ES |
61 | -f:: |
62 | --force:: | |
63 | By default, `add` refuses to create a new worktree when `<branch>` | |
64 | is already checked out by another worktree. This option overrides | |
65 | that safeguard. | |
66 | ||
cbdf60fa ES |
67 | -b <new-branch>:: |
68 | -B <new-branch>:: | |
69 | With `add`, create a new branch named `<new-branch>` starting at | |
70 | `<branch>`, and check out `<new-branch>` into the new worktree. | |
71 | By default, `-b` refuses to create a new branch if it already | |
72 | exists. `-B` overrides this safeguard, resetting `<new-branch>` to | |
73 | `<branch>`. | |
74 | ||
39ecb274 ES |
75 | --detach:: |
76 | With `add`, detach HEAD in the new worktree. See "DETACHED HEAD" in | |
77 | linkgit:git-checkout[1]. | |
78 | ||
df0b6cfb NTND |
79 | -n:: |
80 | --dry-run:: | |
4f09825e | 81 | With `prune`, do not remove anything; just report what it would |
df0b6cfb NTND |
82 | remove. |
83 | ||
84 | -v:: | |
85 | --verbose:: | |
4f09825e | 86 | With `prune`, report all removals. |
df0b6cfb NTND |
87 | |
88 | --expire <time>:: | |
4f09825e | 89 | With `prune`, only expire unused worktrees older than <time>. |
df0b6cfb | 90 | |
af189b4c ES |
91 | DETAILS |
92 | ------- | |
93 | Each linked working tree has a private sub-directory in the repository's | |
94 | $GIT_DIR/worktrees directory. The private sub-directory's name is usually | |
95 | the base name of the linked working tree's path, possibly appended with a | |
96 | number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the | |
97 | command `git checkout --to /path/other/test-next next` creates the linked | |
98 | working tree in `/path/other/test-next` and also creates a | |
99 | `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` | |
100 | if `test-next` is already taken). | |
101 | ||
102 | Within a linked working tree, $GIT_DIR is set to point to this private | |
103 | directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and | |
104 | $GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR | |
105 | (e.g. `/path/main/.git`). These settings are made in a `.git` file located at | |
106 | the top directory of the linked working tree. | |
107 | ||
108 | Path resolution via `git rev-parse --git-path` uses either | |
109 | $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the | |
110 | linked working tree `git rev-parse --git-path HEAD` returns | |
111 | `/path/main/.git/worktrees/test-next/HEAD` (not | |
112 | `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git | |
113 | rev-parse --git-path refs/heads/master` uses | |
114 | $GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, | |
115 | since refs are shared across all working trees. | |
116 | ||
117 | See linkgit:gitrepository-layout[5] for more information. The rule of | |
118 | thumb is do not make any assumption about whether a path belongs to | |
119 | $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something | |
120 | inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. | |
121 | ||
a8ba5dd7 ES |
122 | To prevent a $GIT_DIR/worktrees entry from from being pruned (which |
123 | can be useful in some situations, such as when the | |
124 | entry's working tree is stored on a portable device), add a file named | |
125 | 'locked' to the entry's directory. The file contains the reason in | |
126 | plain text. For example, if a linked working tree's `.git` file points | |
127 | to `/path/main/.git/worktrees/test-next` then a file named | |
128 | `/path/main/.git/worktrees/test-next/locked` will prevent the | |
129 | `test-next` entry from being pruned. See | |
130 | linkgit:gitrepository-layout[5] for details. | |
131 | ||
96454597 ES |
132 | EXAMPLES |
133 | -------- | |
134 | You are in the middle of a refactoring session and your boss comes in and | |
135 | demands that you fix something immediately. You might typically use | |
136 | linkgit:git-stash[1] to store your changes away temporarily, however, your | |
137 | worktree is in such a state of disarray (with new, moved, and removed files, | |
138 | and other bits and pieces strewn around) that you don't want to risk | |
139 | disturbing any of it. Instead, you create a temporary linked worktree to | |
140 | make the emergency fix, remove it when done, and then resume your earlier | |
141 | refactoring session. | |
142 | ||
143 | ------------ | |
cbdf60fa | 144 | $ git worktree add -b emergency-fix ../temp master |
96454597 ES |
145 | $ pushd ../temp |
146 | # ... hack hack hack ... | |
147 | $ git commit -a -m 'emergency fix for boss' | |
148 | $ popd | |
149 | $ rm -rf ../temp | |
150 | $ git worktree prune | |
151 | ------------ | |
152 | ||
6d3824cf ES |
153 | BUGS |
154 | ---- | |
155 | Multiple checkout support for submodules is incomplete. It is NOT | |
156 | recommended to make multiple checkouts of a superproject. | |
157 | ||
158 | git-worktree could provide more automation for tasks currently | |
fc56361f | 159 | performed manually, such as: |
6d3824cf | 160 | |
6d3824cf ES |
161 | - `remove` to remove a linked worktree and its administrative files (and |
162 | warn if the worktree is dirty) | |
163 | - `mv` to move or rename a worktree and update its administrative files | |
164 | - `list` to list linked worktrees | |
165 | - `lock` to prevent automatic pruning of administrative files (for instance, | |
166 | for a worktree on a portable device) | |
167 | ||
df0b6cfb NTND |
168 | GIT |
169 | --- | |
170 | Part of the linkgit:git[1] suite |