{"thread":{"id":"47190","subject":"man page for \"git-worktree\" is a bit confusing WRT \"prune\"","startedAt":"2017-11-13T14:49:16Z","lastAt":"2017-11-14T08:47:42Z","messageCount":5,"participants":["Robert P. J. Day","Eric Sunshine"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"332416","messageId":"alpine.LFD.2.21.1711130938080.5262@DESKTOP-1GPMCEJ","threadId":"47190","inReplyTo":null,"subject":"man page for \"git-worktree\" is a bit confusing WRT \"prune\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-13T14:48:36Z","receivedAt":"2017-11-13T14:49:16Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n  once more, into the man pages ... \"git worktree\" seems like a fairly\nsimple command, but there is some confusion about the function of\n\n  $ git worktree prune\n\nthe normal meaning of \"prune\" (certainly with git commands) is to\nactually delete some content, and the initial impression of this\ncommand is that it will delete an actual worktree. however, further\nreading reveals:\n\n\" ... or you can run git worktree prune in the main or any linked\nworking tree to clean up any stale administrative files.\"\n\n  ah, so one learns that the subcommand \"prune\" does *not* do any\nactual pruning as people would *normally* understand it, it simply\ndeletes the administrative information about an already-deleted\nworktree, do i read that correctly?\n\n  that's emphasized further down in the actual definition of \"prune\":\n\n    prune\n        Prune working tree information in $GIT_DIR/worktrees.\n\nbut perhaps that explanation could be extended to say it only works on\nalready-deleted trees, since that's certainly not clear from that\nsingle sentence.\n\n  finally, the prune \"--expire\" option is truly confusing:\n\n    --expire <time>\n        With prune, only expire unused working trees older than <time>.\n\nsuddenly, we encounter the verb \"expire\", which means ... what? how\ndoes \"expiring\" a worktree differ from \"pruning\" a worktree? and what\nmakes a worktree \"unused\"? the normal meaning of \"unused\" is that you\nhaven't, you know, *used* it lately. in this context, though, does it\nmean deleted? and if it means deleted, what does it mean for it to be\nolder than some time if it's already gone?\n\n  thoughts?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"332427","messageId":"CAPig+cRLcJ2a=QKyKAkaNiewoWMQvKr_AWePKYVpGS5S9g-i1Q@mail.gmail.com","threadId":"47190","inReplyTo":"alpine.LFD.2.21.1711130938080.5262@DESKTOP-1GPMCEJ","subject":"Re: man page for \"git-worktree\" is a bit confusing WRT \"prune\"","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-13T17:39:05Z","receivedAt":"2017-11-13T17:39:12Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Nov 13, 2017 at 9:48 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n>   once more, into the man pages ... \"git worktree\" seems like a fairly\n> simple command, but there is some confusion about the function of\n>\n>   $ git worktree prune\n>\n> the normal meaning of \"prune\" (certainly with git commands) is to\n> actually delete some content, and the initial impression of this\n> command is that it will delete an actual worktree. however, further\n> reading reveals:\n>\n> \" ... or you can run git worktree prune in the main or any linked\n> working tree to clean up any stale administrative files.\"\n>\n>   ah, so one learns that the subcommand \"prune\" does *not* do any\n> actual pruning as people would *normally* understand it, it simply\n> deletes the administrative information about an already-deleted\n> worktree, do i read that correctly?\n\nYes. This usage is consistent with \"git remote prune\" which removes\nadministrative information about local branches which have already\nbeen deleted on the remote side.\n\n>   that's emphasized further down in the actual definition of \"prune\":\n>\n>     prune\n>         Prune working tree information in $GIT_DIR/worktrees.\n>\n> but perhaps that explanation could be extended to say it only works on\n> already-deleted trees, since that's certainly not clear from that\n> single sentence.\n\nAs originally implemented, git-worktree would detect deleted or\nrelocated worktrees and prune or update the administrative information\nautomatically. So, \"prune\" was more a behind-the-scenes implementation\ndetail rather than an important user-facing command. However, the\nimplementation and semantics of that automatic behavior were not quite\nrobust and ended up leaving things in a slightly corrupted state (if I\nrecall correctly), though the corruption was easily corrected by hand.\nAs a consequence, the automatic behavior was retired while the general\nimplementation of git-worktree \"cooked\", with the idea that it could\nbe revisited later, with the result that \"prune\" became more\nuser-facing than originally intended.\n\nThe above description could be extended with more information. An\nalternative would be to point the reader at the \"DETAILS\" section as\nis done already for \"prune\" in \"DISCUSSION\".\n\n>   finally, the prune \"--expire\" option is truly confusing:\n>\n>     --expire <time>\n>         With prune, only expire unused working trees older than <time>.\n>\n> suddenly, we encounter the verb \"expire\", which means ... what? how\n> does \"expiring\" a worktree differ from \"pruning\" a worktree? and what\n> makes a worktree \"unused\"? the normal meaning of \"unused\" is that you\n> haven't, you know, *used* it lately. in this context, though, does it\n> mean deleted? and if it means deleted, what does it mean for it to be\n> older than some time if it's already gone?\n>\n>   thoughts?\n\nThis dates back to the original behavior of automatically pruning\nadministrative information for deleted worktrees. As discussed\nelsewhere in the document, a worktree may be placed on some removable\ndevice (USB drive, memory stick, etc.) or network share which isn't\nalways mounted. The \"expire time\" provides such\nnot-necessarily-mounted worktrees a grace period before being pruned\nautomatically. You wouldn't want your worktree administrative\ninformation erased automatically when invoking some git-worktree\ncommand -- say \"git worktree list\" -- simply because you forgot to\nplug your memory stick back into the computer; the grace period\nprotects against this sort of lossage. As with \"prune\", originally,\nthe grace period was more a behind-the-scenes detail than a\nuser-facing feature. Nevertheless, it's still useful; you might forget\nto plug in your memory stick before invoking \"git worktree prune\"\nmanually.\n\nThe term \"unused\" is unfortunate. A better description would likely be welcome.\n"},{"id":"332446","messageId":"alpine.LFD.2.21.1711131603340.6299@localhost.localdomain","threadId":"47190","inReplyTo":"CAPig+cRLcJ2a=QKyKAkaNiewoWMQvKr_AWePKYVpGS5S9g-i1Q@mail.gmail.com","subject":"Re: man page for \"git-worktree\" is a bit confusing WRT \"prune\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-13T21:06:31Z","receivedAt":"2017-11-13T21:07:09Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Mon, 13 Nov 2017, Eric Sunshine wrote:\n\n> On Mon, Nov 13, 2017 at 9:48 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n\n... snip ...\n\n> >   finally, the prune \"--expire\" option is truly confusing:\n> >\n> >     --expire <time>\n> >         With prune, only expire unused working trees older than <time>.\n> >\n> > suddenly, we encounter the verb \"expire\", which means ... what?\n> > how does \"expiring\" a worktree differ from \"pruning\" a worktree?\n> > and what makes a worktree \"unused\"? the normal meaning of \"unused\"\n> > is that you haven't, you know, *used* it lately. in this context,\n> > though, does it mean deleted? and if it means deleted, what does\n> > it mean for it to be older than some time if it's already gone?\n>\n> This dates back to the original behavior of automatically pruning\n> administrative information for deleted worktrees. As discussed\n> elsewhere in the document, a worktree may be placed on some\n> removable device (USB drive, memory stick, etc.) or network share\n> which isn't always mounted. The \"expire time\" provides such\n> not-necessarily-mounted worktrees a grace period before being pruned\n> automatically.\n\n  how is this \"expire time\" measured? relative to what? i've looked\nunder .git/worktrees/<wtname>, and i see a bunch of files defining\nthat worktree, but it's not clear how a worktree stores the relevant\ntime to be used for the determination of when a worktree \"expires\".\n\n  oh, and is it fair to assume that if a worktree is temporaily\nmissing, and is subsequently restored, the expire time counter is\nreset? otherwise, it would get kind of weird.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"332499","messageId":"CAPig+cR2W2zKcjLYjd1E4jhMkad3O2ioncCZhkExGopxa_0_xg@mail.gmail.com","threadId":"47190","inReplyTo":"alpine.LFD.2.21.1711131603340.6299@localhost.localdomain","subject":"Re: man page for \"git-worktree\" is a bit confusing WRT \"prune\"","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-14T03:26:25Z","receivedAt":"2017-11-14T03:26:31Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"[+cc:Duy]\n\nOn Mon, Nov 13, 2017 at 4:06 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n> On Mon, 13 Nov 2017, Eric Sunshine wrote:\n>> On Mon, Nov 13, 2017 at 9:48 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n>> >   finally, the prune \"--expire\" option is truly confusing:\n>> >\n>> >     --expire <time>\n>> >         With prune, only expire unused working trees older than <time>.\n>> >\n>> > suddenly, we encounter the verb \"expire\", which means ... what?\n>> > how does \"expiring\" a worktree differ from \"pruning\" a worktree?\n>> > and what makes a worktree \"unused\"? the normal meaning of \"unused\"\n>> > is that you haven't, you know, *used* it lately. in this context,\n>> > though, does it mean deleted? and if it means deleted, what does\n>> > it mean for it to be older than some time if it's already gone?\n>>\n>> This dates back to the original behavior of automatically pruning\n>> administrative information for deleted worktrees. As discussed\n>> elsewhere in the document, a worktree may be placed on some\n>> removable device (USB drive, memory stick, etc.) or network share\n>> which isn't always mounted. The \"expire time\" provides such\n>> not-necessarily-mounted worktrees a grace period before being pruned\n>> automatically.\n>\n>   how is this \"expire time\" measured? relative to what? i've looked\n> under .git/worktrees/<wtname>, and i see a bunch of files defining\n> that worktree, but it's not clear how a worktree stores the relevant\n> time to be used for the determination of when a worktree \"expires\".\n\nAccording to Documentation/gitrepository-layout.txt:\n\n    worktrees/<id>/gitdir::\n        A text file containing the absolute path back to the .git file\n        that points to here. This is used to check if the linked\n        repository has been manually removed and there is no need to\n        keep this directory any more. The mtime of this file should be\n        updated every time the linked repository is accessed.\n\nSo, the expire time is relative to the mtime of the 'gitdir' file for\nthat worktree. Presumably (according to the documentation excerpt),\nmtime of  'gitdir' is supposed to be updated each time the linked\nrepository is accessed, however, I haven't found the code which does\nthat (and it's been too long since I dealt which this code to remember\nwhere/if it is being done); in practice, I don't actually see the\ntimestamp on 'gitdir' being updated, so that may be a bug/problem.\n\n>   oh, and is it fair to assume that if a worktree is temporaily\n> missing, and is subsequently restored, the expire time counter is\n> reset? otherwise, it would get kind of weird.\n\nIf we believe the documentation, then, as long as you've invoked some\nGit command recently enough in the restored worktree, it should be\nsafe from pruning.\n"},{"id":"332522","messageId":"alpine.LFD.2.21.1711140345430.12112@localhost.localdomain","threadId":"47190","inReplyTo":"CAPig+cR2W2zKcjLYjd1E4jhMkad3O2ioncCZhkExGopxa_0_xg@mail.gmail.com","subject":"Re: man page for \"git-worktree\" is a bit confusing WRT \"prune\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-14T08:47:05Z","receivedAt":"2017-11-14T08:47:42Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Mon, 13 Nov 2017, Eric Sunshine wrote:\n\n> On Mon, Nov 13, 2017 at 4:06 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n\n... snip ...\n\n> >   how is this \"expire time\" measured? relative to what? i've\n> > looked under .git/worktrees/<wtname>, and i see a bunch of files\n> > defining that worktree, but it's not clear how a worktree stores\n> > the relevant time to be used for the determination of when a\n> > worktree \"expires\".\n>\n> According to Documentation/gitrepository-layout.txt:\n>\n>     worktrees/<id>/gitdir::\n>         A text file containing the absolute path back to the .git file\n>         that points to here. This is used to check if the linked\n>         repository has been manually removed and there is no need to\n>         keep this directory any more. The mtime of this file should be\n>         updated every time the linked repository is accessed.\n>\n> So, the expire time is relative to the mtime of the 'gitdir' file for\n> that worktree...\n\n  yup, that clears it up, thanks.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"}]}