Documentation/git-worktree: add high-level 'lock' overview
Due to the (current) absence of a "git worktree lock" command, locking a worktree's administrative files to prevent automatic pruning is a manual task, necessarily requiring low-level understanding of linked worktree functionality. However, this level of detail does not belong in the high-level DESCRIPTION section, so add a generalized discussion of locking to DESCRIPTION and move the technical information to DETAILS. 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
a8ba5dd7b18ed3a3276ee23ab66569dbddc50913
1 file changed
+15
-9
Documentation/git-worktree.txt
+15
-9
@@ -37,15 +37,11 @@ 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
-To prevent a $GIT_DIR/worktrees entry from from being pruned (which
41
-can be useful in some situations, such as when the
42
-entry's working tree is stored on a portable device), add a file named
43
-'locked' to the entry's directory. The file contains the reason in
44
-plain text. For example, if a linked working tree's `.git` file points
45
-to `/path/main/.git/worktrees/test-next` then a file named
46
-`/path/main/.git/worktrees/test-next/locked` will prevent the
47
-`test-next` entry from being pruned. See
48
-linkgit:gitrepository-layout[5] for details.
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.
45
46
COMMANDS
47
--------
@@ -99,6 +95,16 @@ thumb is do not make any assumption about whether a path belongs to
95
$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
96
inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
97
98
+To prevent a $GIT_DIR/worktrees entry from from being pruned (which
99
+can be useful in some situations, such as when the
100
+entry's working tree is stored on a portable device), add a file named
101
+'locked' to the entry's directory. The file contains the reason in
102
+plain text. For example, if a linked working tree's `.git` file points
103
+to `/path/main/.git/worktrees/test-next` then a file named
104
+`/path/main/.git/worktrees/test-next/locked` will prevent the
105
+`test-next` entry from being pruned. See
106
+linkgit:gitrepository-layout[5] for details.
107
+
108
BUGS
109
----
110
Multiple checkout support for submodules is incomplete. It is NOT