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

[Eric Sunshine <sunshine@sunshineco.com>]

[+cc:Duy]

On Mon, Nov 13, 2017 at 4:06 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> On Mon, 13 Nov 2017, Eric Sunshine wrote:
>> On Mon, Nov 13, 2017 at 9:48 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>> >   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?
>>
>> 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.
>
>   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".

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.

>   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.

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.