[PATCH v2 06/23] Documentation/git-worktree: add high-level 'lock' overview
From: Eric Sunshine <hidden>
Date: 2016-06-15 23:05:38
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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 <redacted> --- Documentation/git-worktree.txt | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 2fdfb3e..410f0b4 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt@@ -37,15 +37,11 @@ at least one git command inside the linked working directory (e.g. `git status`) in order to update its administrative files in the repository so that they do not get automatically pruned. -To prevent a $GIT_DIR/worktrees entry from from being pruned (which -can be useful in some situations, such as when the -entry's working tree is stored on a portable device), add a file named -'locked' to the entry's directory. The file contains the reason in -plain text. For example, if a linked working tree's `.git` file points -to `/path/main/.git/worktrees/test-next` then a file named -`/path/main/.git/worktrees/test-next/locked` will prevent the -`test-next` entry from being pruned. See -linkgit:gitrepository-layout[5] for details. +If a linked working tree is stored on a portable device or network share +which is not always mounted, you can prevent its administrative files from +being pruned by creating a file named 'lock' alongside the other +administrative files, optionally containing a plain text reason that +pruning should be suppressed. See section "DETAILS" for more information. COMMANDS --------
@@ -99,6 +95,16 @@ thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. +To prevent a $GIT_DIR/worktrees entry from from being pruned (which +can be useful in some situations, such as when the +entry's working tree is stored on a portable device), add a file named +'locked' to the entry's directory. The file contains the reason in +plain text. For example, if a linked working tree's `.git` file points +to `/path/main/.git/worktrees/test-next` then a file named +`/path/main/.git/worktrees/test-next/locked` will prevent the +`test-next` entry from being pruned. See +linkgit:gitrepository-layout[5] for details. + BUGS ---- Multiple checkout support for submodules is incomplete. It is NOT
--
2.5.0.rc1.197.g417e668