git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 06/23] Documentation/git-worktree: add high-level 'lock' overview

From
Eric Sunshine <sunshine@sunshineco.com>
Date
Jul 4, 2015, 00:17 UTC
Message-ID
<1435969052-540-7-git-send-email-sunshine@sunshineco.com>
In-Reply-To
<1435969052-540-1-git-send-email-sunshine@sunshineco.com>

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>
---
 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
Previous: Eric SunshineNext: Eric Sunshine
Message 9 of 38 in “replace "checkout --to" with "worktree add"”
  1. 00/23 replace "checkout --to" with "worktree add"Eric Sunshine, Jul 4, 2015
  2. 01/23 Documentation/git-checkout: fix incorrect worktree prune commandEric Sunshine, Jul 4, 2015
  3. 02/23 Documentation/git-worktree: associate options with commandsEric Sunshine, Jul 4, 2015
  4. 03/23 Documentation: move linked worktree description from checkout to worktreeEric Sunshine, Jul 4, 2015
  5. 04/23 Documentation/git-worktree: add BUGS sectionEric Sunshine, Jul 4, 2015
  6. Duy NguyenJul 4, 2015
  7. Eric SunshineJul 4, 2015
  8. 05/23 Documentation/git-worktree: split technical info from general descriptionEric Sunshine, Jul 4, 2015
  9. 06/23 Documentation/git-worktree: add high-level 'lock' overviewEric Sunshine, Jul 4, 2015
  10. 07/23 Documentation/git-worktree: add EXAMPLES sectionEric Sunshine, Jul 4, 2015
  11. Eric SunshineJul 4, 2015
  12. 08/23 checkout: fix bug with --to and relative HEADEric Sunshine, Jul 4, 2015
  13. Duy NguyenJul 4, 2015
  14. Eric SunshineJul 4, 2015
  15. 09/23 checkout: relocate --to's "no branch specified" checkEric Sunshine, Jul 4, 2015
  16. 10/23 checkout: prepare_linked_checkout: drop now-unused 'new' argumentEric Sunshine, Jul 4, 2015
  17. 11/23 checkout: make --to unconditionally verboseEric Sunshine, Jul 4, 2015
  18. 12/23 checkout: drop 'checkout_opts' dependency from prepare_linked_checkoutEric Sunshine, Jul 4, 2015
  19. 13/23 worktree: introduce "add" commandEric Sunshine, Jul 4, 2015
  20. Duy NguyenJul 4, 2015
  21. Eric SunshineJul 4, 2015
  22. Duy NguyenJul 6, 2015
  23. 14/23 worktree: add --force optionEric Sunshine, Jul 4, 2015
  24. 15/23 worktree: add --detach optionEric Sunshine, Jul 4, 2015
  25. 16/23 worktree: add -b/-B optionsEric Sunshine, Jul 4, 2015
  26. Duy NguyenJul 4, 2015
  27. Eric SunshineJul 4, 2015
  28. 17/23 tests: worktree: retrofit "checkout --to" tests for "worktree add"Eric Sunshine, Jul 4, 2015
  29. 18/23 checkout: retire --to optionEric Sunshine, Jul 4, 2015
  30. Duy NguyenJul 4, 2015
  31. Eric SunshineJul 4, 2015
  32. 19/23 checkout: require worktree unconditionallyEric Sunshine, Jul 4, 2015
  33. Eric SunshineJul 4, 2015
  34. 20/23 worktree: extract basename computation to new functionEric Sunshine, Jul 4, 2015
  35. 21/23 worktree: add: make -b/-B default to HEAD when <branch> is omittedEric Sunshine, Jul 4, 2015
  36. Junio C HamanoJul 6, 2015
  37. 22/23 worktree: add: auto-vivify new branch when <branch> is omittedEric Sunshine, Jul 4, 2015
  38. 23/23 checkout: retire --ignore-other-worktrees in favor of --forceEric Sunshine, Jul 4, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.