worktree duplicates, was: [PATCH] SubmittingPatches: mention doc-diff

[Jeff King <peff@peff.net>]

On Tue, Aug 21, 2018 at 03:23:21PM -0400, Jeff King wrote:

> We already advise people to make sure their documentation
> formats correctly. Let's point them at the doc-diff script,
> which can help with that.
> 
> Let's also put a brief note in the script about its purpose,
> since that otherwise can only be found in the original
> commit message. Along with the existing -h/usage text,
> that's hopefully enough for developers to make use of it.
> 
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> Just a finishing touch on the jk/diff-rendered-docs topic.

I noticed one other oddity with this script, but I actually think the
fix lies elsewhere.

The script does basically this to set up the temporary tree:

  test -d $tmp || git worktree add $tmp ...

The script never cleans up the worktree (since its results can often be
reused between runs), but you may do so with "rm" or "git clean". That
creates an interesting situation if the script is run again before
"worktree prune" runs. We identify the directory as a "new" worktree,
and add it to the list. So you may end up with several copies:

  $ git worktree list
  /home/peff/compile/git                                      eee785d2e0 [jk/doc-diff]
  /home/peff/compile/git/.git/tmp-ci                          290f16acda (detached HEAD)
  /home/peff/compile/git/Documentation/tmp-doc-diff/worktree  cc6237c051 (detached HEAD)
  /home/peff/compile/git/Documentation/tmp-doc-diff/worktree  e55de40950 (detached HEAD)
  /home/peff/compile/git/Documentation/tmp-doc-diff/worktree  e55de40950 (detached HEAD)

If I then run "git worktree prune", those duplicates don't go away
(because the directory is still there; it just corresponds to only the
final entry). If I delete the tmp-doc-diff directory and then run "git
worktree prune", they do all go away.

So I'm not sure:

  1. Should the script be doing something else to indicate that the
     worktree may be reused? I tried "git worktree remove", but it's
     unhappy that the directory doesn't exist. Should it quietly handle
     ignore that and remove any leftover cruft in $GIT_DIR/worktrees?

  2. Should "git worktree add" be more clever about realizing that an
     existing entry in $GIT_DIR/worktrees points to this directory? That
     would be fine for my use, but I wonder if there's some potential
     for loss (e.g., you blew away the work tree but until you do a
     "worktree prune", the refs are still there, objects reachable,
     etc).

  3. Should "git worktree prune" be more clever about dropping
     duplicates? I think it should be easy to identify them: they are
     entries in $GIT_DIR/worktrees for which:

       - the directory in $entry/gitdir does exist, but

       - $(cat $entry/gitdir)/.git does not point back to $entry

I could see any of them being plausible fixes, but people who have given
worktrees a lot of thought may have stronger opinions.

-Peff