Documentation: move linked worktree description from checkout to worktree
Now that the git-worktree command exists, its documentation page is the natural place for the linked worktree description to reside. Relocate the "MULTIPLE WORKING TREES" description verbatim from git-checkout.txt to git-worktree.txt. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Eric Sunshine committed
Jul 6, 2015 at 13:30 UTC
93a36493e2c9478c496328118dc52f6b270c7408
2 files changed
+64
-67
Documentation/git-checkout.txt
+2
-67
@@ -229,8 +229,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
229
Check out a branch in a separate working directory at
230
`<path>`. A new working directory is linked to the current
231
repository, sharing everything except working directory
232
- specific files such as HEAD, index... See "MULTIPLE WORKING
233
- TREES" section for more information.
232
+ specific files such as HEAD, index, etc. See
233
+ linkgit:git-worktree[1] for a description of linked worktrees.
234
235
--ignore-other-worktrees::
236
`git checkout` refuses when the wanted ref is already checked
@@ -401,71 +401,6 @@ $ git reflog -2 HEAD # or
401
$ git log -g -2 HEAD
402
------------
403
404
-MULTIPLE WORKING TREES
405
-----------------------
406
-
407
-A git repository can support multiple working trees, allowing you to check
408
-out more than one branch at a time. With `git checkout --to` a new working
409
-tree is associated with the repository. This new working tree is called a
410
-"linked working tree" as opposed to the "main working tree" prepared by "git
411
-init" or "git clone". A repository has one main working tree (if it's not a
412
-bare repository) and zero or more linked working trees.
413
-
414
-Each linked working tree has a private sub-directory in the repository's
415
-$GIT_DIR/worktrees directory. The private sub-directory's name is usually
416
-the base name of the linked working tree's path, possibly appended with a
417
-number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
418
-command `git checkout --to /path/other/test-next next` creates the linked
419
-working tree in `/path/other/test-next` and also creates a
420
-`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
421
-if `test-next` is already taken).
422
-
423
-Within a linked working tree, $GIT_DIR is set to point to this private
424
-directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
425
-$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
426
-(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
427
-the top directory of the linked working tree.
428
-
429
-Path resolution via `git rev-parse --git-path` uses either
430
-$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
431
-linked working tree `git rev-parse --git-path HEAD` returns
432
-`/path/main/.git/worktrees/test-next/HEAD` (not
433
-`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
434
-rev-parse --git-path refs/heads/master` uses
435
-$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
436
-since refs are shared across all working trees.
437
-
438
-See linkgit:gitrepository-layout[5] for more information. The rule of
439
-thumb is do not make any assumption about whether a path belongs to
440
-$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
441
-inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
442
-
443
-When you are done with a linked working tree you can simply delete it.
444
-The working tree's entry in the repository's $GIT_DIR/worktrees
445
-directory will eventually be removed automatically (see
446
-`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run
447
-`git worktree prune` in the main or any linked working tree to
448
-clean up any stale entries in $GIT_DIR/worktrees.
449
-
450
-If you move a linked working directory to another file system, or
451
-within a file system that does not support hard links, you need to run
452
-at least one git command inside the linked working directory
453
-(e.g. `git status`) in order to update its entry in $GIT_DIR/worktrees
454
-so that it does not get automatically removed.
455
-
456
-To prevent a $GIT_DIR/worktrees entry from from being pruned (which
457
-can be useful in some situations, such as when the
458
-entry's working tree is stored on a portable device), add a file named
459
-'locked' to the entry's directory. The file contains the reason in
460
-plain text. For example, if a linked working tree's `.git` file points
461
-to `/path/main/.git/worktrees/test-next` then a file named
462
-`/path/main/.git/worktrees/test-next/locked` will prevent the
463
-`test-next` entry from being pruned. See
464
-linkgit:gitrepository-layout[5] for details.
465
-
466
-Multiple checkout support for submodules is incomplete. It is NOT
467
-recommended to make multiple checkouts of a superproject.
468
-
404
EXAMPLES
405
--------
406
Documentation/git-worktree.txt
+62
@@ -17,6 +17,68 @@ DESCRIPTION
17
Manage multiple worktrees attached to the same repository. These are
18
created by the command `git checkout --to`.
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
+Each linked working tree has a private sub-directory in the repository's
28
+$GIT_DIR/worktrees directory. The private sub-directory's name is usually
29
+the base name of the linked working tree's path, possibly appended with a
30
+number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
31
+command `git checkout --to /path/other/test-next next` creates the linked
32
+working tree in `/path/other/test-next` and also creates a
33
+`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
34
+if `test-next` is already taken).
35
+
36
+Within a linked working tree, $GIT_DIR is set to point to this private
37
+directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
38
+$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
39
+(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
40
+the top directory of the linked working tree.
41
+
42
+Path resolution via `git rev-parse --git-path` uses either
43
+$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
44
+linked working tree `git rev-parse --git-path HEAD` returns
45
+`/path/main/.git/worktrees/test-next/HEAD` (not
46
+`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
47
+rev-parse --git-path refs/heads/master` uses
48
+$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
49
+since refs are shared across all working trees.
50
+
51
+See linkgit:gitrepository-layout[5] for more information. The rule of
52
+thumb is do not make any assumption about whether a path belongs to
53
+$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
54
+inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
55
+
56
+When you are done with a linked working tree you can simply delete it.
57
+The working tree's entry in the repository's $GIT_DIR/worktrees
58
+directory will eventually be removed automatically (see
59
+`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run
60
+`git worktree prune` in the main or any linked working tree to
61
+clean up any stale entries in $GIT_DIR/worktrees.
62
+
63
+If you move a linked working directory to another file system, or
64
+within a file system that does not support hard links, you need to run
65
+at least one git command inside the linked working directory
66
+(e.g. `git status`) in order to update its entry in $GIT_DIR/worktrees
67
+so that it does not get automatically removed.
68
+
69
+To prevent a $GIT_DIR/worktrees entry from from being pruned (which
70
+can be useful in some situations, such as when the
71
+entry's working tree is stored on a portable device), add a file named
72
+'locked' to the entry's directory. The file contains the reason in
73
+plain text. For example, if a linked working tree's `.git` file points
74
+to `/path/main/.git/worktrees/test-next` then a file named
75
+`/path/main/.git/worktrees/test-next/locked` will prevent the
76
+`test-next` entry from being pruned. See
77
+linkgit:gitrepository-layout[5] for details.
78
+
79
+Multiple checkout support for submodules is incomplete. It is NOT
80
+recommended to make multiple checkouts of a superproject.
81
+
82
COMMANDS
83
--------
84
prune::