Subject: Re: [PATCH] worktree: stop supporting moving worktrees manually

From: Eric Sunshine <[email-masked]>
Date: Mon, 28 Dec 2015 01:22:06 -0500

On Sun, Dec 27, 2015 at 10:43:16AM +0700, Nguyễn Thái Ngọc Duy wrote:
> The current update_linked_gitdir() has a bug that can create "gitdir"
> file in non-multi-worktree setup. Instead of fixing this, we step back a
> bit. The original design was probably not well thought out. For now, if
> the user manually moves a worktree, they have to fix up "gitdir" file
> manually or the worktree will get pruned. In future, we probably will
> add "git worktree mv" to support this use case.
> 
> Signed-off-by: Nguyễn Thái Ngọc Duy <[email-masked]>
> ---
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> @@ -33,10 +33,8 @@ The working tree's administrative files in the repository (see
>  If you move a linked working tree to another file system, or
> -within a file system that does not support hard links, you need to run
> -at least one git command inside the linked working tree
> -(e.g. `git status`) in order to update its administrative files in the
> -repository so that they do not get automatically pruned.
> +within a file system that does not support hard links, you need to update

Hmm, is this "hard links" feature implemented? If not, then this
documentation is a bit outdated.

> +$GIT_DIR/worktrees/<id>/gitdir so that they do not get automatically pruned.

Following the example of af189b4 (Documentation/git-worktree: split
technical info from general description, 2015-07-06), it might be a
good idea to keep this high-level overview free of such low-level
details and instead mention $GIT_DIR/worktrees/<id>/gitdir in the
"DETAILS" section.

Perhaps something like this, on top of your patch (assuming that the
"hard links" feature is not implemented):

--- 8< ---
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 4814f48..62c76c1 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -32,9 +32,9 @@ The working tree's administrative files in the repository (see
 `git worktree prune` in the main or any linked working tree to
 clean up any stale administrative files.
 
-If you move a linked working tree to another file system, or
-within a file system that does not support hard links, you need to update
-$GIT_DIR/worktrees/<id>/gitdir so that they do not get automatically pruned.
+If you move a linked working tree, you need to manually update the
+administrative files so that they do not get pruned automatically. See
+section "DETAILS" for more information.
 
 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
@@ -135,6 +135,13 @@ 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.
 
+If you move a linked working tree, you need to update the 'gitdir' file
+in the entry's directory. For example, if a linked working tree is moved
+to `/newpath/test-next` and its `.git` file points to
+`/path/main/.git/worktrees/test-next`, then update
+`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
+instead.
+
 To prevent a $GIT_DIR/worktrees entry 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
--- 8< ---