man page for "git-worktree" is a bit confusing WRT "prune"

  once more, into the man pages ... "git worktree" seems like a fairly
simple command, but there is some confusion about the function of

  $ git worktree prune

the normal meaning of "prune" (certainly with git commands) is to actually delete some content, and the initial impression of this command is that it will delete an actual worktree. however, further reading reveals:

" ... or you can run git worktree prune in the main or any linked working tree to clean up any stale administrative files."

  ah, so one learns that the subcommand "prune" does *not* do any
actual pruning as people would *normally* understand it, it simply
deletes the administrative information about an already-deleted
worktree, do i read that correctly?

  that's emphasized further down in the actual definition of "prune":

    prune
        Prune working tree information in $GIT_DIR/worktrees.

but perhaps that explanation could be extended to say it only works on already-deleted trees, since that's certainly not clear from that single sentence.

  finally, the prune "--expire" option is truly confusing:

    --expire <time>
        With prune, only expire unused working trees older than <time>.

suddenly, we encounter the verb "expire", which means ... what? how does "expiring" a worktree differ from "pruning" a worktree? and what makes a worktree "unused"? the normal meaning of "unused" is that you haven't, you know, *used* it lately. in this context, though, does it mean deleted? and if it means deleted, what does it mean for it to be older than some time if it's already gone?

  thoughts?

rday

On Mon, Nov 13, 2017 at 9:48 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:

Yes. This usage is consistent with "git remote prune" which removes administrative information about local branches which have already been deleted on the remote side.

As originally implemented, git-worktree would detect deleted or relocated worktrees and prune or update the administrative information automatically. So, "prune" was more a behind-the-scenes implementation detail rather than an important user-facing command. However, the implementation and semantics of that automatic behavior were not quite robust and ended up leaving things in a slightly corrupted state (if I recall correctly), though the corruption was easily corrected by hand. As a consequence, the automatic behavior was retired while the general implementation of git-worktree "cooked", with the idea that it could be revisited later, with the result that "prune" became more user-facing than originally intended.

The above description could be extended with more information. An alternative would be to point the reader at the "DETAILS" section as is done already for "prune" in "DISCUSSION".

This dates back to the original behavior of automatically pruning administrative information for deleted worktrees. As discussed elsewhere in the document, a worktree may be placed on some removable device (USB drive, memory stick, etc.) or network share which isn't always mounted. The "expire time" provides such not-necessarily-mounted worktrees a grace period before being pruned automatically. You wouldn't want your worktree administrative information erased automatically when invoking some git-worktree command -- say "git worktree list" -- simply because you forgot to plug your memory stick back into the computer; the grace period protects against this sort of lossage. As with "prune", originally, the grace period was more a behind-the-scenes detail than a user-facing feature. Nevertheless, it's still useful; you might forget to plug in your memory stick before invoking "git worktree prune" manually.

The term "unused" is unfortunate. A better description would likely be welcome.

On Mon, 13 Nov 2017, Eric Sunshine wrote:

... snip ...

  how is this "expire time" measured? relative to what? i've looked
under .git/worktrees/<wtname>, and i see a bunch of files defining
that worktree, but it's not clear how a worktree stores the relevant
time to be used for the determination of when a worktree "expires".

  oh, and is it fair to assume that if a worktree is temporaily
missing, and is subsequently restored, the expire time counter is
reset? otherwise, it would get kind of weird.

rday

[+cc:Duy]

On Mon, Nov 13, 2017 at 4:06 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:

According to Documentation/gitrepository-layout.txt:

    worktrees/<id>/gitdir::
        A text file containing the absolute path back to the .git file
        that points to here. This is used to check if the linked
        repository has been manually removed and there is no need to
        keep this directory any more. The mtime of this file should be
        updated every time the linked repository is accessed.

So, the expire time is relative to the mtime of the 'gitdir' file for that worktree. Presumably (according to the documentation excerpt), mtime of 'gitdir' is supposed to be updated each time the linked repository is accessed, however, I haven't found the code which does that (and it's been too long since I dealt which this code to remember where/if it is being done); in practice, I don't actually see the timestamp on 'gitdir' being updated, so that may be a bug/problem.

If we believe the documentation, then, as long as you've invoked some Git command recently enough in the restored worktree, it should be safe from pruning.

On Mon, 13 Nov 2017, Eric Sunshine wrote:

... snip ...

  yup, that clears it up, thanks.

rday