{"thread":{"id":"60195","subject":"Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","startedAt":"2023-09-04T14:41:51Z","lastAt":"2023-09-07T20:12:16Z","messageCount":31,"participants":["Tao Klerks","Kristoffer Haugsbakk","Eric Sunshine","Junio C Hamano","Sergey Organov"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"481371","messageId":"CAPMMpoixKnr4BkKd8jeU+79Edhqtu4R7m8=BX4ZSYKdBHDzK=w@mail.gmail.com","threadId":"60195","inReplyTo":null,"subject":"Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-04T14:41:31Z","receivedAt":"2023-09-04T14:41:51Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"Hi folks,\n\nI work with a project that often, or typically, benefits from having\nmultiple worktrees where users are working with different versions of\nthe code.\n\nWorktrees make particular sense in this project for all the usual\nreasons, plus the fact that it is a very *large* repo - multiple gigs\nof repo, and very fast-moving; cloning and fetching less often is\nnice.\n\nOne problem that we found users to have, early on when we introduced\nworktrees, was that it was not obvious to users that there was (or why\nthere was) a \"main\" worktree, containing the actual \".git\" repo, and\n\"subsidiary\" worktrees, in the same directory location. Git by default\nmakes worktrees *subfolders* of the initial/main worktree/folder, but\nwe put them alongside each other to make other project tooling be able\nto treat all worktrees consistently; in daily use there is absolutely\nno difference between them, in all the \"project tooling\" there cannot\nbe a practical difference... but if you choose to delete a worktree,\nand it happens to be the \"special\" one that contains the repo...\nyou've just lost stuff that you didn't expect to lose (any local\nbranches and stashes, basically).\n\nBecause worktree use was so useful/widespread/critical on this\nproject, and we already had a custom cloning process that introduced\nselective refspecs etc, we introduced a special clone topology: the\ninitial clone is a bare repo, and that folder gets a specific clear\nname (ending in .git). Then we create worktrees attached to that bare\nrepo.\n\nGenerally speaking, this has worked *very* well: I would recommend it\ngenerally as a recognized/supported local-repo-setup. The most\nimportant thing that makes this *possible* is the fact that \"git\nrev-parse --is-bare-repository\" returns True in the bare repo folder,\nwhere the lack of index and HEAD shouldn't bother git, and it returns\nFalse in any one of the worktrees. It feels like things were designed\nto work this way, even though I can find no explicit mention of this\ntopology in the docs.\n\nHowever, from time to time something weird happens: Today I finally\nstarted to understand why I was seeing a crazy GC error about bitmaps,\nintermittently: It seems to be because \"git gc\" wants to create\nbitmaps in bare repos, but can't do so properly when we're in a\npartial clone... or something like that?\n\nEG repro:\n```\ngit clone --bare https://github.com/ksylor/ohshitgit dangit_shared.git\n--filter=blob:none\ngit -C dangit_shared.git worktree add $PWD/dangit_wt3\ncd dangit_wt3/\necho \"this is some new unique blob in the repo\" > new_blob.txt\ngit add new_blob.txt && git commit -m \"new blob\"\ncd ../dangit_shared.git/\ngit gc\n```\n\nThis yields, at the end of the GC run:\n```\nwarning: Failed to write bitmap index. Packfile doesn't have full\nclosure (object bf86ed1b2602ac3a8d4724bcdf6707b156673aac is missing)\nfatal: failed to write bitmap index\nfatal: failed to run repack\n```\n\nOn the other hand, running \"git gc\" in one of the worktrees works fine\n(except you first need to delete a couple of \".tmp-*\" files from the\n\"objects/pack\" folder, if you already got the error above).\n\nI at first thought this was a bug - but as I realized the problematic\nbehavior was tied to the \"core.bare\" setting (and its expression at\nruntime through \"git rev-parse --is-bare-repository\"), it became more\nobvious that maybe the system could/should be able to make assumptions\nabout the kind of repo that has this \"true\", and assume there are no\nlocal-object-derived non-promisor packfiles (or whatever it is about\nthis example that makes things unhappy).\n\nSo, I guess I'm confused as to what \"core.bare\" is supposed to mean:\nIs it intended to mean \"there is no index nor HEAD here, and that's\ngood, don't worry\" (in which case my setup is presumably \"supported\",\nand the gc behavior is buggy?), or is it intended to mean \"this is the\nkind of repository in which there are no worktrees\" (in which case I\nam abusing the system and get the errors I deserve)?\n\nCC Dscho, who made the worktree support that I rely on work about 16\nyears ago it seems, and Taylor Blau and Patrick Steinhardt, who I\nthink have made changes in the area of the code concerned with whether\nor not we try to create bitmaps, and might have an opinion as to\nwhether the assumptions made by \"gc\" at the moment are unsafe, or my\nuse or \"core.bare\" in this context is wrong.\n\nThanks for any feedback!\nTao\n"},{"id":"481372","messageId":"CAPMMpoj7s=ewXJfJyxvrcHjpmOOWEWBvZ94OOuVmYs2UQ482HA@mail.gmail.com","threadId":"60195","inReplyTo":"CAPMMpoixKnr4BkKd8jeU+79Edhqtu4R7m8=BX4ZSYKdBHDzK=w@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-04T14:59:20Z","receivedAt":"2023-09-04T14:59:36Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Mon, Sep 4, 2023 at 4:41 PM Tao Klerks wrote:\n>\n> we introduced a special clone topology: the\n> initial clone is a bare repo, and that folder gets a specific clear\n> name (ending in .git). Then we create worktrees attached to that bare\n> repo.\n>\n> Generally speaking, this has worked *very* well: I would recommend it\n> generally as a recognized/supported local-repo-setup. The most\n> important thing that makes this *possible* is the fact that \"git\n> rev-parse --is-bare-repository\" returns True in the bare repo folder,\n> where the lack of index and HEAD shouldn't bother git, and it returns\n> False in any one of the worktrees. It feels like things were designed\n> to work this way, even though I can find no explicit mention of this\n> topology in the docs.\n\nI should add that I only recently discovered \"git clone\n--separate-git-dir\", which I at first though was a formal expression\nof this setup... until I understood that the relationship between the\n\"GITDIR\" and the worktree that you end up with is not \"Bare repo vs\nworktree\", but rather... \"orphaned repo / repo that doesn't know about\nits worktree, vs worktree\".\n\nIt seems, to me, that \"my setup\" makes a lot more sense than what you\nend up with when you use \"--separate-git-dir\", and that the behavior\nthere predates the current \"mutual reference\" model of\nworktrees-to-their-repo. If \"my\" use of \"core.bare\" in the example\nabove is sound - then should the implementation of\n\"--separate-git-dir\" be changed to produce a bare repo with a\n\"worktrees\" folder, like you get if you clone bare and add a worktree\nin two separate steps?\n\n(I say \"change the implementation\", but I guess I really mean\nintroducing a new option for the new behavior, and deprecate the old\noption)\n\nDscho, I assume you would have the strongest opinion about this?\n"},{"id":"481373","messageId":"CAPMMpohpKJdopSpZu+ehE0MZrH8cksgtY1NEHFyZz2jj+LOKhA@mail.gmail.com","threadId":"60195","inReplyTo":"CAPMMpoj7s=ewXJfJyxvrcHjpmOOWEWBvZ94OOuVmYs2UQ482HA@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-04T15:29:16Z","receivedAt":"2023-09-04T15:29:33Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Mon, Sep 4, 2023 at 4:59 PM Tao Klerks wrote:\n>\n>\n> It seems, to me, that \"my setup\" makes a lot more sense than what you\n> end up with when you use \"--separate-git-dir\", and that the behavior\n> there predates the current \"mutual reference\" model of\n> worktrees-to-their-repo. If \"my\" use of \"core.bare\" in the example\n> above is sound - then should the implementation of\n> \"--separate-git-dir\" be changed to produce a bare repo with a\n> \"worktrees\" folder, like you get if you clone bare and add a worktree\n> in two separate steps?\n>\n\nAnd to confuse matters further, I just stumbled across\nhttps://github.com/git/git/blob/master/contrib/workdir/git-new-workdir\n- I don't understand when you would want to use that vs, again, a bare\nrepo with one or more worktrees properly attached via two-way\nreferences, their own indexes, their own reflogs, etc.\n\nIs it the case that this contrib script predates the current \"git\nworktree\" support?\n"},{"id":"481375","messageId":"fa25f0d3-392f-4fc5-826c-a19ed3cdb7ca@app.fastmail.com","threadId":"60195","inReplyTo":"CAPMMpohpKJdopSpZu+ehE0MZrH8cksgtY1NEHFyZz2jj+LOKhA@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-04T17:42:29Z","receivedAt":"2023-09-04T17:44:57Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Mon, Sep 4, 2023, at 17:29, Tao Klerks wrote:\n> On Mon, Sep 4, 2023 at 4:59 PM Tao Klerks wrote:\n>>\n>>\n>> [snip]\n>>\n>\n> And to confuse matters further, I just stumbled across\n> https://github.com/git/git/blob/master/contrib/workdir/git-new-workdir\n> - I don't understand when you would want to use that vs, again, a bare\n> repo with one or more worktrees properly attached via two-way\n> references, their own indexes, their own reflogs, etc.\n>\n> Is it the case that this contrib script predates the current \"git\n> worktree\" support?\n\nYes, according to VonC[1] and the 2.05 release notes.[2]\n\n🔗 1: https://stackoverflow.com/a/30185564/1725151\n🔗 2: https://github.com/git/git/blob/22aca1b3ac10af7188dccf033b44a36926f04d4b/Documentation/RelNotes/2.5.0.txt#L25-L27\n\n-- \nKristoffer Haugsbakk\n"},{"id":"481376","messageId":"b5833396-7e04-465f-96f6-69d5280fa023@app.fastmail.com","threadId":"60195","inReplyTo":"CAPMMpoixKnr4BkKd8jeU+79Edhqtu4R7m8=BX4ZSYKdBHDzK=w@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-04T17:56:33Z","receivedAt":"2023-09-04T17:57:36Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Hi Tao\n\nContext for my own use: I use the default clone (named the same as the\nupstream repository) as the main worktree and name worktrees according to\nsome topic. So if the repository is named `work-application` then I might\nhave worktrees named things like `deployment-work`, `next-version-work`,\nand things like that. All of them sibling directories since they are all\nIntellij projects (to your point about making tooling treat them the same\nway). I usually use the main worktree so I am fine with one worktree being\n*special* (that it contains the `.git` directory).\n\nI can understand that the main worktree/linked worktree dichotomy might\nfeel artificial if you use, say, ten different wotrkees equally often. Or\nmaybe one worktree per branch.\n\nAnd then from that vantage point it might feel wasteful to dedicate an\nunused main worktree—with its own working tree—to just sit somewhere for\nits `.git` directory, essentially.\n\nOn Mon, Sep 4, 2023, at 16:41, Tao Klerks wrote:\n> Because worktree use was so useful/widespread/critical on this project,\n> and we already had a custom cloning process that introduced selective\n> refspecs etc, we introduced a special clone topology: the initial clone\n> is a bare repo, and that folder gets a specific clear name (ending in\n> .git). Then we create worktrees attached to that bare repo.\n\nThis is interesting as a Git user. I've been encountering questions on\nStackOverflow where the questioner is using a bare repository which they\nmake (or try to make) worktrees from. I've been telling them that making\nworktrees from a bare repository is a contradiction:[1]\n\n> Bare repositories don’t have worktrees per definition. Or at least\n> that’s what `man gitglossary says`. Of course what `git worktree` allows\n> you to do trumps that. But it might be ill-defined.\n\nThe glossary says under “worktree” (on Git 2.42):\n\n> A repository can have zero (i.e. bare repository) or one or more\n> worktrees attached to it.\n\nAnd as someone who never has needed to use a bare repository + worktrees\nI've just left it at that.\n\n🔗 1: https://stackoverflow.com/a/76273222/1725151\n\nCheers\n"},{"id":"481379","messageId":"CAPig+cTeQDMpWQ-zCf6i9H-yhrdCndX6gs67sypuqmHZZcHm7w@mail.gmail.com","threadId":"60195","inReplyTo":"CAPMMpoixKnr4BkKd8jeU+79Edhqtu4R7m8=BX4ZSYKdBHDzK=w@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-09-05T00:26:10Z","receivedAt":"2023-09-05T00:26:35Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 4, 2023 at 10:41 AM Tao Klerks wrote:\n> I work with a project that often, or typically, benefits from having\n> multiple worktrees where users are working with different versions of\n> the code.\n>\n> Worktrees make particular sense in this project for all the usual\n> reasons, plus the fact that it is a very *large* repo - multiple gigs\n> of repo, and very fast-moving; cloning and fetching less often is\n> nice.\n>\n> One problem that we found users to have, early on when we introduced\n> worktrees, was that it was not obvious to users that there was (or why\n> there was) a \"main\" worktree, containing the actual \".git\" repo, and\n> \"subsidiary\" worktrees, in the same directory location. Git by default\n> makes worktrees *subfolders* of the initial/main worktree/folder, but\n\nThis is not accurate. There is no default location for new worktrees;\ngit-worktree creates the new worktree at the location specified by the\nuser:\n\n git worktree add [] []\n\nwhere -- the only mandatory argument -- specifies the location.\n\n> we put them alongside each other to make other project tooling be able\n> to treat all worktrees consistently; in daily use there is absolutely\n> no difference between them, in all the \"project tooling\" there cannot\n> be a practical difference... but if you choose to delete a worktree,\n> and it happens to be the \"special\" one that contains the repo...\n> you've just lost stuff that you didn't expect to lose (any local\n> branches and stashes, basically).\n>\n> Because worktree use was so useful/widespread/critical on this\n> project, and we already had a custom cloning process that introduced\n> selective refspecs etc, we introduced a special clone topology: the\n> initial clone is a bare repo, and that folder gets a specific clear\n> name (ending in .git). Then we create worktrees attached to that bare\n> repo.\n>\n> Generally speaking, this has worked *very* well: I would recommend it\n> generally as a recognized/supported local-repo-setup. The most\n> important thing that makes this *possible* is the fact that \"git\n> rev-parse --is-bare-repository\" returns True in the bare repo folder,\n> where the lack of index and HEAD shouldn't bother git, and it returns\n> False in any one of the worktrees. It feels like things were designed\n> to work this way, even though I can find no explicit mention of this\n> topology in the docs.\n\nIt indeed was designed to work this way. It is perfectly legitimate to\ncreate worktrees attached to a bare repository[1].\n\n[1]: Support for bare repositories in conjunction with multiple-\nworktrees, however, came after the initial implementation of multiple-\nworktrees. An unfortunate side-effect is that established terminology\nbecame somewhat confusing. In particular, in a bare repository\nscenario, the term \"main worktree\" refers to the bare repository, not\nto the \"blessed\" worktree containing the \".git/\" directory (since\nthere is no such worktree in this case).\n\n> However, from time to time something weird happens: Today I finally\n> started to understand why I was seeing a crazy GC error about bitmaps,\n> intermittently: It seems to be because \"git gc\" wants to create\n> bitmaps in bare repos, but can't do so properly when we're in a\n> partial clone... or something like that?\n>\n> EG repro:\n> ```\n> git clone --bare https://github.com/ksylor/ohshitgit dangit_shared.git\n> --filter=blob:none\n> git -C dangit_shared.git worktree add $PWD/dangit_wt3\n> cd dangit_wt3/\n> echo \"this is some new unique blob in the repo\" > new_blob.txt\n> git add new_blob.txt && git commit -m \"new blob\"\n> cd ../dangit_shared.git/\n> git gc\n> ```\n>\n> This yields, at the end of the GC run:\n> ```\n> warning: Failed to write bitmap index. Packfile doesn't have full\n> closure (object bf86ed1b2602ac3a8d4724bcdf6707b156673aac is missing)\n> fatal: failed to write bitmap index\n> fatal: failed to run repack\n> ```\n>\n> On the other hand, running \"git gc\" in one of the worktrees works fine\n> (except you first need to delete a couple of \".tmp-*\" files from the\n> \"objects/pack\" folder, if you already got the error above).\n\nWorktrees appear to be a red-herring. It's possible to reproduce this\nerror without them. For instance:\n\n % git clone --bare --filter=blob:none\nhttps://github.com/ksylor/ohshitgit dangit_shared.git\n % git clone dangit_shared.git foop\n % cd foop\n % echo nothing >nothing\n % git add nothing\n % git commit -m nothing\n fatal: unable to read dbbb0682a7690b62ccf51b2a8648fa71ac671348\n % git push origin master\n % cd ../dangit_shared.git\n % git gc\n ...\n warning: Failed to write bitmap index. Packfile doesn't have full\nclosure (object bf86ed1b2602ac3a8d4724bcdf6707b156673aac is missing)\n fatal: failed to write bitmap index\n fatal: failed to run repack\n\n> I at first thought this was a bug - but as I realized the problematic\n> behavior was tied to the \"core.bare\" setting (and its expression at\n> runtime through \"git rev-parse --is-bare-repository\"), it became more\n> obvious that maybe the system could/should be able to make assumptions\n> about the kind of repo that has this \"true\", and assume there are no\n> local-object-derived non-promisor packfiles (or whatever it is about\n> this example that makes things unhappy).\n>\n> So, I guess I'm confused as to what \"core.bare\" is supposed to mean:\n> Is it intended to mean \"there is no index nor HEAD here, and that's\n> good, don't worry\" (in which case my setup is presumably \"supported\",\n> and the gc behavior is buggy?), or is it intended to mean \"this is the\n> kind of repository in which there are no worktrees\" (in which case I\n> am abusing the system and get the errors I deserve)?\n\nThe former, meaning that your setup should be supported. Citing\ndocumentation for `core.bare`:\n\n If true this repository is assumed to be bare and has no working\n directory associated with it. If this is the case a number of\n commands that require a working directory will be disabled, such\n as git-add(1) or git-merge(1).\n\nOn Mon, Sep 4, 2023 at 10:59 AM Tao Klerks wrote:\n> I should add that I only recently discovered \"git clone\n> --separate-git-dir\", which I at first though was a formal expression\n> of this setup... until I understood that the relationship between the\n> \"GITDIR\" and the worktree that you end up with is not \"Bare repo vs\n> worktree\", but rather... \"orphaned repo / repo that doesn't know about\n> its worktree, vs worktree\".\n>\n> It seems, to me, that \"my setup\" makes a lot more sense than what you\n> end up with when you use \"--separate-git-dir\", and that the behavior\n> there predates the current \"mutual reference\" model of\n> worktrees-to-their-repo. If \"my\" use of \"core.bare\" in the example\n> above is sound - then should the implementation of\n> \"--separate-git-dir\" be changed to produce a bare repo with a\n> \"worktrees\" folder, like you get if you clone bare and add a worktree\n> in two separate steps?\n\n`--separate-git-dir` predates multiple-worktree support by several\nyears and is distinct in purpose from --bare and multiple-worktrees\n(in fact, a couple somewhat recent fixes [2,3] were needed to prevent\n--separate-git-dir from breaking worktree administrative data). My\nunderstand from scanning history is that --separate-git-dir was\nintroduced in aid of submodule support and perhaps other use-cases.\n\n[2]: 42264bc841 (init: teach --separate-git-dir to repair linked\nworktrees, 2020-08-31)\n[3]: 59d876ccd6 (init: make --separate-git-dir work from within linked\nworktree, 2020-08-31)\n\nOn Mon, Sep 4, 2023 at 11:29 AM Tao Klerks wrote:\n> And to confuse matters further, I just stumbled across\n> https://github.com/git/git/blob/master/contrib/workdir/git-new-workdir\n> - I don't understand when you would want to use that vs, again, a bare\n> repo with one or more worktrees properly attached via two-way\n> references, their own indexes, their own reflogs, etc.\n>\n> Is it the case that this contrib script predates the current \"git\n> worktree\" support?\n\ngit-new-workdir predates git-worktree by quite a few years and, as I\nunderstand it, remains in-tree because it fills a niche not entirely\nfilled by git-worktree.\n"},{"id":"481385","messageId":"CAPig+cRJhrGmnBRm2dporcXiRr4SzRmpM2LTMm0S7wo0XbOU9Q@mail.gmail.com","threadId":"60195","inReplyTo":"xmqqedjdtoh5.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-09-05T05:43:54Z","receivedAt":"2023-09-05T16:00:05Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 4, 2023 at 9:09 PM Junio C Hamano wrote:\n> Eric Sunshine writes:\n> > This is not accurate. There is no default location for new worktrees;\n> > git-worktree creates the new worktree at the location specified by the\n> > user:\n> >\n> > git worktree add [] []\n> >\n> > where -- the only mandatory argument -- specifies the location.\n>\n> All correct. The per-worktree part of the repository data does live\n> in a subdirectory of the \".git\" directory and that was probably what\n> Tao had in mind, though.\n\nThat could be. I read Tao's explanation as meaning that people do this:\n\n git clone foo.git foo\n cd foo\n git worktree add bar\n git worktree add baz\n\nrather than (perhaps) this:\n\n git clone foo.git foo\n cd foo\n git worktree add ../bar\n git worktree add ../baz\n\nBut it's possible I misunderstood.\n\n> >> Is it the case that this contrib script predates the current \"git\n> >> worktree\" support?\n> >\n> > git-new-workdir predates git-worktree by quite a few years and, as I\n> > understand it, remains in-tree because it fills a niche not entirely\n> > filled by git-worktree.\n>\n> I actually think there is no longer a valid workflow whose support\n> by \"worktree\" is still insufficient and the script has outlived its\n> usefulness. I have been a heavy user of the new-workdir script to\n> maintain my build environments, but I always have the HEAD of these\n> workdir's detached, so I can easily switch my arrangement to use the\n> \"git worktree\" without losing any flexibility.\n\nMy response was based upon my recollection of the periodic message\nwhich shows up on the mailing list reporting a bug or submitting an\nimprovement for git-new-workdir, accompanied by a statement that\ngit-new-workdir is still a better fit for the user's particular\nuse-case. But I've never used it myself, so it's good to hear from\nsomeone (you) who does use it.\n\n> Perhaps we should remove it, possibly leaving a tombstone file like\n> how we removed stuff from the contrib/examples directory.\n\nPerhaps.\n"},{"id":"481390","messageId":"xmqqmsy0slei.fsf@gitster.g","threadId":"60195","inReplyTo":"CAPig+cRJhrGmnBRm2dporcXiRr4SzRmpM2LTMm0S7wo0XbOU9Q@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-05T15:13:41Z","receivedAt":"2023-09-05T16:00:32Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n>> All correct. The per-worktree part of the repository data does live\n>> in a subdirectory of the \".git\" directory and that was probably what\n>> Tao had in mind, though.\n>\n> That could be. I read Tao's explanation as meaning that people do this:\n>\n> git clone foo.git foo\n> cd foo\n> git worktree add bar\n> git worktree add baz\n>\n> rather than (perhaps) this:\n>\n> git clone foo.git foo\n> cd foo\n> git worktree add ../bar\n> git worktree add ../baz\n\nAh, that reading does totally make sense.\n\nBut I am not sure it would lead to \"we need to carefully protect the\nprimary worktree\", because it is rather obvious, especially if you\nbypass \"git worktree remove\" and use \"rm -fr\", you would lose\neverybody underneath if you remove the \"foo\" in the \"worktrees are\nsubdirectories of the primary\" variant in the above examples.\n\nEven though deriving the worktree(s) from a separate and protected\nbare repositories does protect you from total disaster caused by\nremoving \"rm -fr\" and bypassing \"git worktree remove\", it still\nshould be discouraged, as the per-worktree states left behind in the\nrepository interfere with the operations in surviving worktrees.\nTeaching folks not to do \"rm -fr\" would be the first step to a more\npleasant end-user experience, I would think.\n\nThanks.\n\n"},{"id":"481393","messageId":"xmqqedjdtoh5.fsf@gitster.g","threadId":"60195","inReplyTo":"CAPig+cTeQDMpWQ-zCf6i9H-yhrdCndX6gs67sypuqmHZZcHm7w@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-05T01:09:42Z","receivedAt":"2023-09-05T16:00:38Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> This is not accurate. There is no default location for new worktrees;\n> git-worktree creates the new worktree at the location specified by the\n> user:\n>\n> git worktree add [] []\n>\n> where -- the only mandatory argument -- specifies the location.\n\nAll correct. The per-worktree part of the repository data does live\nin a subdirectory of the \".git\" directory and that was probably what\nTao had in mind, though.\n\n> It indeed was designed to work this way. It is perfectly legitimate to\n> create worktrees attached to a bare repository[1].\n>\n> [1]: Support for bare repositories in conjunction with multiple-\n> worktrees, however, came after the initial implementation of multiple-\n> worktrees. An unfortunate side-effect is that established terminology\n> became somewhat confusing. In particular, in a bare repository\n> scenario, the term \"main worktree\" refers to the bare repository, not\n> to the \"blessed\" worktree containing the \".git/\" directory (since\n> there is no such worktree in this case).\n\nAgain all correct.\n\n>> Is it the case that this contrib script predates the current \"git\n>> worktree\" support?\n>\n> git-new-workdir predates git-worktree by quite a few years and, as I\n> understand it, remains in-tree because it fills a niche not entirely\n> filled by git-worktree.\n\nI actually think there is no longer a valid workflow whose support\nby \"worktree\" is still insufficient and the script has outlived its\nusefulness. I have been a heavy user of the new-workdir script to\nmaintain my build environments, but I always have the HEAD of these\nworkdir's detached, so I can easily switch my arrangement to use the\n\"git worktree\" without losing any flexibility.\n\nPerhaps we should remove it, possibly leaving a tombstone file like\nhow we removed stuff from the contrib/examples directory.\n"},{"id":"481394","messageId":"CAPig+cQoiqeZF52Jr45an+cZF+ZQbHPXtLVn+VmyegjMQaJqCg@mail.gmail.com","threadId":"60195","inReplyTo":"b5833396-7e04-465f-96f6-69d5280fa023@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-09-05T00:38:52Z","receivedAt":"2023-09-05T16:00:40Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Sep 4, 2023 at 1:57 PM Kristoffer Haugsbakk\n wrote:\n> On Mon, Sep 4, 2023, at 16:41, Tao Klerks wrote:\n> > Because worktree use was so useful/widespread/critical on this project,\n> > and we already had a custom cloning process that introduced selective\n> > refspecs etc, we introduced a special clone topology: the initial clone\n> > is a bare repo, and that folder gets a specific clear name (ending in\n> > .git). Then we create worktrees attached to that bare repo.\n>\n> This is interesting as a Git user. I've been encountering questions on\n> StackOverflow where the questioner is using a bare repository which they\n> make (or try to make) worktrees from. I've been telling them that making\n> worktrees from a bare repository is a contradiction:[1]\n\nNot at all. The combination of bare repository and multiple-worktrees\nis legitimate and supported intentionally. (There are tests in the Git\ntest suite validating support of this feature.) For people who\nregularly work with multiple worktrees, it is quite natural to have\nall the worktrees hanging off a bare repository, each with equal\nimportance, rather than having a single \"blessed\" worktree which has\npriority over all others.\n\n> > Bare repositories don’t have worktrees per definition. Or at least\n> > that’s what `man gitglossary says`. Of course what `git worktree` allows\n> > you to do trumps that. But it might be ill-defined.\n>\n> The glossary says under “worktree” (on Git 2.42):\n>\n> > A repository can have zero (i.e. bare repository) or one or more\n> > worktrees attached to it.\n\nSpeaking as a person involved in the implementation of worktrees,\nincluding support for them in combination with bare repositories, my\nreading of this is perhaps biased so that I understand its intent.\nHowever, if I squint hard, I suppose I can see how you could read it\nas meaning that a bare repository can't have any worktrees associated\nwith it. So, perhaps, the documentation could use a bit of touch up.\n"},{"id":"481396","messageId":"CAPMMpohc-pOD33NE_wSwYnMYKQYEtAQ64B2qwKZmUM38Euk9mw@mail.gmail.com","threadId":"60195","inReplyTo":"b5833396-7e04-465f-96f6-69d5280fa023@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-05T15:48:09Z","receivedAt":"2023-09-05T16:00:50Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Mon, Sep 4, 2023 at 7:57 PM Kristoffer Haugsbakk\n wrote:\n>\n> And then from that vantage point it might feel wasteful to dedicate an\n> unused main worktree—with its own working tree—to just sit somewhere for\n> its `.git` directory, essentially.\n\nYep, especially in my case where a worktree contains 200,000 files and\n5GB; especially on Windows, that's a high tax to pay pointlessly.\n\n>\n> The glossary says under “worktree” (on Git 2.42):\n>\n> > A repository can have zero (i.e. bare repository) or one or more\n> > worktrees attached to it.\n>\n> And as someone who never has needed to use a bare repository + worktrees\n> I've just left it at that.\n>\n\nThank you for this reference - given Eric's later answers I'll aim to\nchange the text rather than respect its current implication, but\nknowing what needs to change is hugely helpful :)\n\n(not that I know what to change the text *to*, but I guess there's\ntime to think about that)\n"},{"id":"481402","messageId":"CAPMMpog3o=DtOrC9L6ED42XkegdObkh3rGm617q4u2oofBC1TA@mail.gmail.com","threadId":"60195","inReplyTo":"CAPig+cTeQDMpWQ-zCf6i9H-yhrdCndX6gs67sypuqmHZZcHm7w@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-05T16:10:50Z","receivedAt":"2023-09-05T16:45:11Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Tue, Sep 5, 2023 at 2:26 AM Eric Sunshine wrote:\n>\n> On Mon, Sep 4, 2023 at 10:41 AM Tao Klerks wrote:\n> >\n> > One problem that we found users to have, early on when we introduced\n> > worktrees, was that it was not obvious to users that there was (or why\n> > there was) a \"main\" worktree, containing the actual \".git\" repo, and\n> > \"subsidiary\" worktrees, in the same directory location. Git by default\n> > makes worktrees *subfolders* of the initial/main worktree/folder, but\n>\n> This is not accurate. There is no default location for new worktrees;\n> git-worktree creates the new worktree at the location specified by the\n> user:\n>\n> git worktree add [] []\n>\n> where -- the only mandatory argument -- specifies the location.\n>\n\nRight - I know you *can* create worktrees in the \"parent path\", and\nnow that I revisit the doc I see there are even a couple examples that\ndo exactly that - but whenever I've talked with people who've tried\n\"git worktree add\" independently, they ended up with the nested\nworktrees and wondering why things work this weird way.\n\nThe idea that the \"most trivial\" example of creating a worktree would\nbe \"git worktree add ../my_new_worktree\" is, I believe, very\nnon-obvious.\n\nThe other thing that is I believe is non-obvious, in the current\nsolution, is that *if* you end up placing multiple worktrees at the\nsame level, *and* you end up using them \"interchangeably\" as you\npresumably would in some or most scenarios, even though their *usage*\nis identical, their \"importance\", or \"lifetime\" is very much not.\n\n>\n> It indeed was designed to work this way. It is perfectly legitimate to\n> create worktrees attached to a bare repository[1].\n>\n\nAwesome, thx for confirming!\n\n> in a bare repository\n> scenario, the term \"main worktree\" refers to the bare repository, not\n> to the \"blessed\" worktree containing the \".git/\" directory (since\n> there is no such worktree in this case).\n\nNoted, thank you. We have been using the word \"repository\" vs worktree\n- the (main) GITDIR is the repo, the worktrees are all just worktrees.\nThere is no \"main worktree\" in the way we talk about things, although\nclearly the official nomenclature doesn't square with that, which I\nmight need to address at some point.\n\n\n> Worktrees appear to be a red-herring. It's possible to reproduce this\n> error without them. For instance:\n>\n> % git clone --bare --filter=blob:none\n> https://github.com/ksylor/ohshitgit dangit_shared.git\n> % git clone dangit_shared.git foop\n> % cd foop\n> % echo nothing >nothing\n> % git add nothing\n> % git commit -m nothing\n> fatal: unable to read dbbb0682a7690b62ccf51b2a8648fa71ac671348\n> % git push origin master\n> % cd ../dangit_shared.git\n> % git gc\n> ...\n> warning: Failed to write bitmap index. Packfile doesn't have full\n> closure (object bf86ed1b2602ac3a8d4724bcdf6707b156673aac is missing)\n> fatal: failed to write bitmap index\n> fatal: failed to run repack\n>\n\nHmm, I don't really understand what happened there, but it looks to me\nlike you went *much* further off the beaten path by cloning from a\npartial clone. Afaik that's hard-not-supported...?\n\n>\n> The former, meaning that your setup should be supported. Citing\n> documentation for `core.bare`:\n>\n> If true this repository is assumed to be bare and has no working\n> directory associated with it. If this is the case a number of\n> commands that require a working directory will be disabled, such\n> as git-add(1) or git-merge(1).\n>\n\nThanks again!\n\n>\n> `--separate-git-dir` predates multiple-worktree support by several\n> years and is distinct in purpose from --bare and multiple-worktrees\n> (in fact, a couple somewhat recent fixes [2,3] were needed to prevent\n> --separate-git-dir from breaking worktree administrative data). My\n> understand from scanning history is that --separate-git-dir was\n> introduced in aid of submodule support and perhaps other use-cases.\n\nOK, so if it is legitimate as-is... why doesn't it set\n\"core.worktree\"? At least that way there'd be a solid two-way\nreference like with \"git worktree\" worktrees.\n\nOr is the *point* of the submodule and/or other use-cases that the\ngitdir can't \"know\" its worktree??\n\n> git-new-workdir predates git-worktree by quite a few years and, as I\n> understand it, remains in-tree because it fills a niche not entirely\n> filled by git-worktree.\n\nOK, I'll keep my nose out of this one entirely either way, thx :)\n"},{"id":"481403","messageId":"CAPMMpogm2tr0dy1nsV9NtF4O8-JS=_L3J0+yKRc7KbyAJ-PNbQ@mail.gmail.com","threadId":"60195","inReplyTo":"xmqqmsy0slei.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-05T16:25:14Z","receivedAt":"2023-09-05T17:56:21Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Tue, Sep 5, 2023 at 5:13 PM Junio C Hamano wrote:\n>\n> Eric Sunshine writes:\n>\n> >> All correct. The per-worktree part of the repository data does live\n> >> in a subdirectory of the \".git\" directory and that was probably what\n> >> Tao had in mind, though.\n> >\n> > That could be. I read Tao's explanation as meaning that people do this:\n> >\n> > git clone foo.git foo\n> > cd foo\n> > git worktree add bar\n> > git worktree add baz\n> >\n> > rather than (perhaps) this:\n> >\n> > git clone foo.git foo\n> > cd foo\n> > git worktree add ../bar\n> > git worktree add ../baz\n>\n> Ah, that reading does totally make sense.\n>\n\nFwiw, Eric's reading was my intended one. The people I have spoken\nwith, as well as myself, have started using \"git worktree\" by doing\nthe former, and only later felt really transgressive when placing the\nworktrees explicitly on a higher level, on equal footing with the\n\"main worktree\". To me it seemed natural that the \"nested worktrees\"\napproach was the expected one, as otherwise it gets even harder to\nexplain/justify the operational difference between the \"main worktree\"\nand the other worktrees - then leading to the bare+worktrees approach\nto eliminate that operational difference.\n\n> But I am not sure it would lead to \"we need to carefully protect the\n> primary worktree\", because it is rather obvious, especially if you\n> bypass \"git worktree remove\" and use \"rm -fr\", you would lose\n> everybody underneath if you remove the \"foo\" in the \"worktrees are\n> subdirectories of the primary\" variant in the above examples.\n\nRight, sorry, too many poorly-expressed thoughts crammed together.\n\nWe need to start carefully protecting main worktree *when we start to\nget clever* and actually add the worktrees as siblings to the main\nworktree. That protection is indeed \"implicit\" before you start using\n\"../\"... but then you have other issues of\ngit-worktree-within-git-worktree confusion.\n\nIs there a manual for \"expected typical usage of git worktree\" somewhere?\n\n>\n> Even though deriving the worktree(s) from a separate and protected\n> bare repositories does protect you from total disaster caused by\n> removing \"rm -fr\" and bypassing \"git worktree remove\", it still\n> should be discouraged, as the per-worktree states left behind in the\n> repository interfere with the operations in surviving worktrees.\n\nRight, that's fine. Of course you're going to encourage deleting the\nworktrees carefully... but equally of-course, some people *will* do\n\"rm -fr that-worktree-I-dont-know-how-to-clean\", and when they do,\ntelling them \"just 'git worktree repair'\" is much easier than telling\nthem to \"recover deleted files 'cause your local branches just\nevaporated\"\n\n> Teaching folks not to do \"rm -fr\" would be the first step to a more\n> pleasant end-user experience, I would think.\n\nThe less arcane trivia you *need* to teach users for them to be\neffective, the better the experience is for everyone.\n\nThe fact that \"deleting a standalone git repo only deletes what's in\nthat standalone git repo the way you've done your whole life, but in\nthis environment what look like multiple repos are actually\n'worktrees', if you ever delete one your life *might*, if you choose\nthe wrong one, suddenly be very unpleasant\" is arcane trivia, in my\nopinion. Better to set things up so they *can't* shoot themselves in\nthe foot with a bullet of that caliber.\n"},{"id":"481441","messageId":"2ba66542-9ae2-4b13-ae6b-f37dec6b72c7@app.fastmail.com","threadId":"60195","inReplyTo":"CAPig+cQoiqeZF52Jr45an+cZF+ZQbHPXtLVn+VmyegjMQaJqCg@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-06T16:00:26Z","receivedAt":"2023-09-06T16:02:52Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Tue, Sep 5, 2023, at 02:38, Eric Sunshine wrote:\n> Speaking as a person involved in the implementation of worktrees,\n> including support for them in combination with bare repositories, my\n> reading of this is perhaps biased so that I understand its intent.\n> However, if I squint hard, I suppose I can see how you could read it\n> as meaning that a bare repository can't have any worktrees associated\n> with it. So, perhaps, the documentation could use a bit of touch up.\n\nMy interpretation of the documentation leads to contradictions. So I\nthought of another one: A bare repository *can* have worktrees, but if it\ndoes will in that case only have *linked* worktrees, since the\n`repository.git` directory by definition does not have a working tree and\nit therefore cannot be considered a worktree itself. By extension, a\nlinked worktree might be linked to a bare repository. Thus there is no\ncontradiction.\n\nFor example: there are four directory trees associated with the `repo`\nrepository:\n\n1. `repo.git`: the directory tree with the bare repository; no worktree in\n *that* directory tree\n2. `a`: worktree with a gitfile that points to `repo.git`\n3. `b`: worktree with a gitfile that points to `repo.git`\n4. `c`: worktree with a gitfile that points to `repo.git`\n\nSo you have:\n\n• One repository\n• Four directory trees\n• Three worktrees\n\nThis interpretation seems completely in line with “bare repository” in the\nglossary:\n\n “ A bare repository is normally an appropriately named directory with a\n .git suffix that does not have a locally checked-out copy of any of\n the files under revision control. That is, all of the Git\n administrative and control files that would normally be present in the\n hidden .git sub-directory are directly present in the repository.git\n directory instead, and no other files are present and checked\n out. Usually publishers of public repositories make bare repositories\n available.\n\nBut not with “worktree”:\n\n “ A repository can have zero (i.e. bare repository) or one or more\n worktrees attached to it. ...\n\nSince this entry claims that “bare repository” and “zero worktrees” are\nequivalent.\n\nNothwithstanding any implementation/documentation disagreement, I think\nthat this interpretation at least is coherent.\n\nBut note how (for me) it is a bit awkward to refer to a “bare repository”\nin this context since I need to add “the directory tree” in order to\nemphasize that we are talking about `repo.git`; normally you can kind of\nloosely talk about “the repository” and still get the precise meaning that\nyou intend across, but in this case we have four directory trees which are\nall *the same repository*. (Right?) So just saying “the bare repository”\ncan be misleading since it might hint that the three worktrees are not\npart of the repository. (Perhaps there isn't enough nomenclature to\nclearly talk about this particular case/setup?)\n\nBut with all of that in mind, perhaps the glossary could read something\nlike this instead (no reflowing):[1][2]\n\n(`man git-worktree` might also need to be updated.)\n\n† 1: Applied onto 1fc548b2d6 (The sixth batch, 2023-09-05)\n🔗 2: https://github.com/git/git/compare/master...LemmingAvalanche:git:bare-and-worktrees?expand=1\n\nCheers\n\nKristoffer\n\n-- >8 --\nSubject: [PATCH] Try to reword what a worktree is\n\n---\n Documentation/glossary-content.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 5a537268e2..5e192fb5dc 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -694,10 +694,14 @@ The most notable example is `HEAD`.\n \tplus any local changes that you have made but not yet committed.\n\n [[def_worktree]]worktree::\n-\tA repository can have zero (i.e. bare repository) or one or\n+\tA repository can have zero or one or\n \tmore worktrees attached to it. One \"worktree\" consists of a\n \t\"working tree\" and repository metadata, most of which are\n \tshared among other worktrees of a single repository, and\n \tsome of which are maintained separately per worktree\n \t(e.g. the index, HEAD and pseudorefs like MERGE_HEAD,\n \tper-worktree refs and per-worktree configuration file).\n++\n+Note that the directory tree of a <>\n+may have linked worktrees, but cannot itself be a worktree since it has no\n+working tree.\n--\n2.42.0\n"},{"id":"481442","messageId":"87edjbuugw.fsf@osv.gnss.ru","threadId":"60195","inReplyTo":"2ba66542-9ae2-4b13-ae6b-f37dec6b72c7@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T16:39:27Z","receivedAt":"2023-09-06T16:39:34Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n\n[...]\n\n> -- >8 --\n> Subject: [PATCH] Try to reword what a worktree is\n>\n> ---\n> Documentation/glossary-content.txt | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 5a537268e2..5e192fb5dc 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -694,10 +694,14 @@ The most notable example is `HEAD`.\n> \tplus any local changes that you have made but not yet committed.\n>\n> [[def_worktree]]worktree::\n> -\tA repository can have zero (i.e. bare repository) or one or\n> +\tA repository can have zero or one or\n> \tmore worktrees attached to it. One \"worktree\" consists of a\n> \t\"working tree\" and repository metadata, most of which are\n> \tshared among other worktrees of a single repository, and\n> \tsome of which are maintained separately per worktree\n> \t(e.g. the index, HEAD and pseudorefs like MERGE_HEAD,\n> \tper-worktree refs and per-worktree configuration file).\n> ++\n> +Note that the directory tree of a <>\n> +may have linked worktrees, but cannot itself be a worktree since it has no\n> +working tree.\n\nReading this with a fresh eye, I wonder if we'd better distinguish\nbetween \"inline\" worktree and \"attached\" worktrees?\n\nAs I see it, in fact a repository can have zero (i.e. bare repository)\nor one inline worktree, as well as zero or more attached worktrees.\n\n-- \nSergey Organov\n"},{"id":"481446","messageId":"f782d554-d588-467e-806f-420549ed2f5a@app.fastmail.com","threadId":"60195","inReplyTo":"CAPMMpogm2tr0dy1nsV9NtF4O8-JS=_L3J0+yKRc7KbyAJ-PNbQ@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-06T17:29:27Z","receivedAt":"2023-09-06T17:31:36Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Tue, Sep 5, 2023, at 18:25, Tao Klerks wrote:\n> Fwiw, Eric's reading was my intended one. The people I have spoken\n> with, as well as myself, have started using \"git worktree\" by doing\n> the former, and only later felt really transgressive when placing the\n> worktrees explicitly on a higher level, on equal footing with the\n> \"main worktree\". To me it seemed natural that the \"nested worktrees\"\n> approach was the expected one, as otherwise it gets even harder to\n> explain/justify the operational difference between the \"main worktree\"\n> and the other worktrees - then leading to the bare+worktrees approach\n> to eliminate that operational difference.\n\nLet's consider a use-case that `git-worktrees` can replace: just cloning\nthe repository again to do some particular task.\n\nMy coworkers have to work on some branch `divergent` which requires a\ncomplete rebuild of the project compared to the main branch. But they also\nneed to work on small derivative branches of the main branch. In order to\nnot rebuild all the time they simply cloned the project again and work in\n*that* repository when working on `divergent`. And since this is an\nIntellij project it was cloned in the same directory as the original\nclone.\n\nReplacing this use-case with `git worktrees` would be:\n\n git worktree ../divergent-project\n\nIn this case, `git worktrees` is a more streamlined and better version of\ncloning a separate repository:\n\n1. Only one object store\n2. No need to remember to fetch from both\n3. No risk of forgetting that you have some n-iary clone on your machine\n with original work\n\nBut crucially they also had the luxury of just cloning the project again\nsince it is less than 1GB; people with larger repositories (like\nyourself) might have to immediately use the streamlined approaches like\n`git worktree` since the straightforward approaches are too costly.\n\nSo I think the sibling directory tree makes sense when you arrive at this\ncommand/workflow from the brute-force approach. But maybe that's not the\ncase when you have to design the proper way of doing it up-front(?)\n\n> Is there a manual for \"expected typical usage of git worktree\" somewhere?\n\nThe example in “Description” of `man git-worktree` uses a sibling\ndirectory: `git worktree ../hotfix`.\n\n>> Even though deriving the worktree(s) from a separate and protected\n>> bare repositories does protect you from total disaster caused by\n>> removing \"rm -fr\" and bypassing \"git worktree remove\", it still\n>> should be discouraged, as the per-worktree states left behind in the\n>> repository interfere with the operations in surviving worktrees.\n>\n> Right, that's fine. Of course you're going to encourage deleting the\n> worktrees carefully... but equally of-course, some people *will* do\n> \"rm -fr that-worktree-I-dont-know-how-to-clean\", and when they do,\n> telling them \"just 'git worktree repair'\" is much easier than telling\n> them to \"recover deleted files 'cause your local branches just\n> evaporated\"\n>\n>> Teaching folks not to do \"rm -fr\" would be the first step to a more\n>> pleasant end-user experience, I would think.\n>\n> The less arcane trivia you *need* to teach users for them to be\n> effective, the better the experience is for everyone.\n>\n> The fact that \"deleting a standalone git repo only deletes what's in\n> that standalone git repo the way you've done your whole life, but in\n> this environment what look like multiple repos are actually\n> 'worktrees', if you ever delete one your life *might*, if you choose\n> the wrong one, suddenly be very unpleasant\" is arcane trivia, in my\n> opinion. Better to set things up so they *can't* shoot themselves in\n> the foot with a bullet of that caliber.\n\nI don't see how the principle of respecting the level of abstraction\ndoesn't apply here.\n\nBefore you might be able to delete a branch `b` by doing `git rm\n.git/refs/heads/b` and be content when that either finishes successfully\nor when it complains that the file doesn't exist; you can feel confident\nthat there is no more `b` branch. Now though the ref `b` might be a\n*packed ref*, so you cannot do that and be sure that the ref was removed.\n\nSo if you create a worktree with `git worktree`, you should probably\nremove it with the same command.\n\n(Am I missing something? I probably am. I might not have understood the\ncontext for wanting to run rm(1) on these directories.)\n\nPersonally I like to conceptualize worktrees as having equal status to\neach other as far as me (the user) is concerned, since there isn't\nanything you can do in the main worktree–or at least I haven't found\nanything like that—that I *can't* do in a worktree *at that level of\nabstraction* (directly manipulating files in the `.git` or\n`repository.git` directory doesn't apply to this level of abstraction, so\nthat the linked worktrees only have a gitfile is irrelevant here).\n\n-- \nKristoffer Haugsbakk\n"},{"id":"481447","messageId":"xmqq5y4nnq9b.fsf@gitster.g","threadId":"60195","inReplyTo":"2ba66542-9ae2-4b13-ae6b-f37dec6b72c7@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-06T17:52:16Z","receivedAt":"2023-09-06T17:52:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> But not with “worktree”:\n>\n> “ A repository can have zero (i.e. bare repository) or one or more\n> worktrees attached to it. ...\n>\n> Since this entry claims that “bare repository” and “zero worktrees” are\n> equivalent.\n\nI wrote that \"(i.e. bare repository)\" in 2df5387e (glossary:\ndescribe \"worktree\", 2022-02-09) but did not mean that way. \n\nA non-bare repository can reduce the number of its worktrees, but it\ncannot go below one, because the directory with working tree files\nand the .git/ subdirectory, i.e. its primary worktree, must exist\nfor it to be a non-bare repository. Consequently a repository with\nzero worktree is by definition a bare repository.\n\nBut that does not have to mean all bare repositories can have no\nworktrees.\n\n"},{"id":"481448","messageId":"c0a10738-86ba-4b3a-9e74-2568cc407621@app.fastmail.com","threadId":"60195","inReplyTo":"87edjbuugw.fsf@osv.gnss.ru","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-06T17:59:11Z","receivedAt":"2023-09-06T18:00:14Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, Sep 6, 2023, at 18:39, Sergey Organov wrote:\n>> -- >8 --\n>> Subject: [PATCH] Try to reword what a worktree is\n>>\n>> ---\n>> Documentation/glossary-content.txt | 6 +++++-\n>> 1 file changed, 5 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index 5a537268e2..5e192fb5dc 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -694,10 +694,14 @@ The most notable example is `HEAD`.\n>> \tplus any local changes that you have made but not yet committed.\n>>\n>> [[def_worktree]]worktree::\n>> -\tA repository can have zero (i.e. bare repository) or one or\n>> +\tA repository can have zero or one or\n>> \tmore worktrees attached to it. One \"worktree\" consists of a\n>> \t\"working tree\" and repository metadata, most of which are\n>> \tshared among other worktrees of a single repository, and\n>> \tsome of which are maintained separately per worktree\n>> \t(e.g. the index, HEAD and pseudorefs like MERGE_HEAD,\n>> \tper-worktree refs and per-worktree configuration file).\n>> ++\n>> +Note that the directory tree of a <>\n>> +may have linked worktrees, but cannot itself be a worktree since it has no\n>> +working tree.\n>\n> Reading this with a fresh eye, I wonder if we'd better distinguish\n> between \"inline\" worktree and \"attached\" worktrees?\n>\n> As I see it, in fact a repository can have zero (i.e. bare repository)\n> or one inline worktree, as well as zero or more attached worktrees.\n\nAh, thank you. I felt like the glossary/nomenclature was missing a few\nwords and these ones seem to fill things in nicely.\n\nNow I'm just skeptical of the other wording issue about “bare repository”,\nwhich might be somewhat out of place in the face of zero-to-multiple\nworktrees. Going back to my example in the previous email:\n\n• `repository.git` is a *bare repository* which has no *inline worktree*\n and three *attached worktrees* [I really like how inline/attached work\n here]\n• `a` is an *attached worktree* of `repository.git`\n• `a`, `b`, `c` are all the *worktrees* of the *bare repository*\n `repository.git` [“bare” here just emphasizes that `repository.git` does\n not have a worktree (“what about the worktree in `repository.git`?”)]\n\nDoes that sound right? (Asking no one in particular.) Personally I think\nthat it sounds more coherent than before I wrote it (than I thought it \nwould).\n\n-- \nKristoffer Haugsbakk\n"},{"id":"481449","messageId":"CAPMMpohgkH3h1zC_Q7O-07gYw8_7mdSsyX7vu1K1u5+CxKUaUQ@mail.gmail.com","threadId":"60195","inReplyTo":"c0a10738-86ba-4b3a-9e74-2568cc407621@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-06T18:04:17Z","receivedAt":"2023-09-06T18:04:34Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Wed, Sep 6, 2023 at 8:00 PM Kristoffer Haugsbakk\n wrote:\n>\n> On Wed, Sep 6, 2023, at 18:39, Sergey Organov wrote:\n\n> >\n> > As I see it, in fact a repository can have zero (i.e. bare repository)\n> > or one inline worktree, as well as zero or more attached worktrees.\n>\n> Ah, thank you. I felt like the glossary/nomenclature was missing a few\n> words and these ones seem to fill things in nicely.\n>\n\nYes, I agree!!\n\nI like the nomenclature, I like the simple \"zero (i.e. bare) or one\ninline worktree, zero or more attached worktrees\" explanation.\n"},{"id":"481450","messageId":"c3e11a9c-071a-42a9-83ca-b2b078495a45@app.fastmail.com","threadId":"60195","inReplyTo":"xmqq5y4nnq9b.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-06T18:08:22Z","receivedAt":"2023-09-06T18:08:49Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, Sep 6, 2023, at 19:52, Junio C Hamano wrote:\n> I wrote that \"(i.e. bare repository)\" in 2df5387e (glossary:\n> describe \"worktree\", 2022-02-09) but did not mean that way.\n>\n> A non-bare repository can reduce the number of its worktrees, but it\n> cannot go below one, because the directory with working tree files\n> and the .git/ subdirectory, i.e. its primary worktree, must exist\n> for it to be a non-bare repository. Consequently a repository with\n> zero worktree is by definition a bare repository.\n>\n> But that does not have to mean all bare repositories can have no\n> worktrees.\n\nI see. Zero worktrees implies bare repository, but bare repository does\nnot imply zero worktrees. I got my logical connectives mixed up.\n\nThanks\n\n-- \nKristoffer Haugsbakk\n"},{"id":"481451","messageId":"xmqqwmx3m82l.fsf@gitster.g","threadId":"60195","inReplyTo":"xmqq5y4nnq9b.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-06T19:10:26Z","receivedAt":"2023-09-06T19:10:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> \"Kristoffer Haugsbakk\" writes:\n>\n>> But not with “worktree”:\n>>\n>> “ A repository can have zero (i.e. bare repository) or one or more\n>> worktrees attached to it. ...\n>>\n>> Since this entry claims that “bare repository” and “zero worktrees” are\n>> equivalent.\n>\n> I wrote that \"(i.e. bare repository)\" in 2df5387e (glossary:\n> describe \"worktree\", 2022-02-09) but did not mean that way. \n>\n> A non-bare repository can reduce the number of its worktrees, but it\n> cannot go below one, because the directory with working tree files\n> and the .git/ subdirectory, i.e. its primary worktree, must exist\n> for it to be a non-bare repository. Consequently a repository with\n> zero worktree is by definition a bare repository.\n>\n> But that does not have to mean all bare repositories can have no\n> worktrees.\n\nI re-read the glossary entry and I think the current text is mostly\nOK, except that it does not even have to mention \"bare\" at that\nposition in the sentence. A bare repository with zero worktrees is\ntotally uninteresting in the explanation of the worktree.\n\nWe need to say that the repository data (configuration, refs and\nobjecs) are mostly shared among worktrees while some data are kept\nper-worktree, which the current text adequately covers, and what is\nmissing with respect to a bare repository is that we do not say\nworktrees can be attached after the fact to a repository that was\ncreated bare.\n\nSo, perhaps something along this line?\n\n Documentation/glossary-content.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt\nindex 5a537268e2..6dba68ffc0 100644\n--- c/Documentation/glossary-content.txt\n+++ w/Documentation/glossary-content.txt\n@@ -694,10 +694,12 @@ The most notable example is `HEAD`.\n \tplus any local changes that you have made but not yet committed.\n \n [[def_worktree]]worktree::\n-\tA repository can have zero (i.e. bare repository) or one or\n-\tmore worktrees attached to it. One \"worktree\" consists of a\n-\t\"working tree\" and repository metadata, most of which are\n-\tshared among other worktrees of a single repository, and\n-\tsome of which are maintained separately per worktree\n-\t(e.g. the index, HEAD and pseudorefs like MERGE_HEAD,\n-\tper-worktree refs and per-worktree configuration file).\n+\tA repository can have zero or more worktrees attached to it.\n+\tOne \"worktree\" consists of a \"working tree\" and repository\n+\tmetadata, most of which are shared among other worktrees of\n+\ta single repository, and some of which are maintained\n+\tseparately per worktree (e.g. the index, HEAD and pseudorefs\n+\tlike MERGE_HEAD, per-worktree refs and per-worktree\n+\tconfiguration file).\n++\n+Note that worktrees can be attached to an existing bare repository.\n"},{"id":"481452","messageId":"xmqqledjm4k2.fsf@gitster.g","threadId":"60195","inReplyTo":"CAPMMpohgkH3h1zC_Q7O-07gYw8_7mdSsyX7vu1K1u5+CxKUaUQ@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-06T20:26:21Z","receivedAt":"2023-09-06T20:26:28Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tao Klerks writes:\n\n> I like the nomenclature, I like the simple \"zero (i.e. bare) or one\n> inline worktree, zero or more attached worktrees\" explanation.\n\nWe have used \"main worktree\" to refer to the working tree part (plus\nthe repository) of a non-bare repository. And it makes sense to\nexplain it together with the concept of \"worktree\", as the primary\none is very much special in that it cannot be removed. You can see\nthat \"git worktree remove\" would stop you from removing it with an\nerror message:\n\n\tfatal: '../there' is a main working tree.\n\nIt probably does not add much value to introduce a new term\n\"inline\". Here is what \"git worktree --help\" has to say about it.\n\n A repository has one main worktree (if it's not a bare repository) and\n zero or more linked worktrees.\n\nI applaud whoever wrote this sentence for packing so much good\ninformation in a concise and easy-to-understand description.\n\nWe can read that (1) a non-bare repository itself is considered\nits \"main worktree\", (2) a bare repository, by inference, has no\nmain worktree (otherwise we wouldn't have said \"if it's not\"), and\n(3) both bare and non-bare repositories can have linked worktrees\n(again, otherwise we wouldn't have brought up a bare repository in\nthe description).\n\nPerhaps we should borrow it to update the glossary, like so?\n\n\n Documentation/glossary-content.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt\nindex 5a537268e2..d9ba3bab88 100644\n--- c/Documentation/glossary-content.txt\n+++ w/Documentation/glossary-content.txt\n@@ -694,8 +694,8 @@ The most notable example is `HEAD`.\n \tplus any local changes that you have made but not yet committed.\n \n [[def_worktree]]worktree::\n-\tA repository can have zero (i.e. bare repository) or one or\n-\tmore worktrees attached to it. One \"worktree\" consists of a\n+\tA repository has one main worktree (if it's not a bare\n+\trepository) and zero or more linked worktrees. One \"worktree\" consists of a\n \t\"working tree\" and repository metadata, most of which are\n \tshared among other worktrees of a single repository, and\n \tsome of which are maintained separately per worktree\n"},{"id":"481455","messageId":"878r9juflz.fsf@osv.gnss.ru","threadId":"60195","inReplyTo":"xmqqledjm4k2.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T22:00:24Z","receivedAt":"2023-09-06T22:00:38Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Tao Klerks writes:\n>\n>> I like the nomenclature, I like the simple \"zero (i.e. bare) or one\n>> inline worktree, zero or more attached worktrees\" explanation.\n>\n\n[...]\n\n> It probably does not add much value to introduce a new term\n> \"inline\". Here is what \"git worktree --help\" has to say about it.\n>\n> A repository has one main worktree (if it's not a bare repository) and\n> zero or more linked worktrees.\n>\n> I applaud whoever wrote this sentence for packing so much good\n> information in a concise and easy-to-understand description.\n\nI agree \"inline\" is not much better than \"main\", nor \"attached\" is\nbetter than \"linked\". I just pulled mine out of thin air, and what's\nalready there is probably fine. That said, to be picky, \"main\" suggests\nthat linked worktrees are somehow inferior. Are they?\n\n-- \nSergey Organov\n"},{"id":"481456","messageId":"874jk7uf3a.fsf@osv.gnss.ru","threadId":"60195","inReplyTo":"xmqqwmx3m82l.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T22:11:37Z","receivedAt":"2023-09-06T22:11:47Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> \"Kristoffer Haugsbakk\" writes:\n>>\n>>> But not with “worktree”:\n>>>\n>>> “ A repository can have zero (i.e. bare repository) or one or more\n>>> worktrees attached to it. ...\n>>>\n>>> Since this entry claims that “bare repository” and “zero worktrees” are\n>>> equivalent.\n>>\n>> I wrote that \"(i.e. bare repository)\" in 2df5387e (glossary:\n>> describe \"worktree\", 2022-02-09) but did not mean that way. \n>>\n>> A non-bare repository can reduce the number of its worktrees, but it\n>> cannot go below one, because the directory with working tree files\n>> and the .git/ subdirectory, i.e. its primary worktree, must exist\n>> for it to be a non-bare repository. Consequently a repository with\n>> zero worktree is by definition a bare repository.\n>>\n>> But that does not have to mean all bare repositories can have no\n>> worktrees.\n>\n> I re-read the glossary entry and I think the current text is mostly\n> OK, except that it does not even have to mention \"bare\" at that\n> position in the sentence. A bare repository with zero worktrees is\n> totally uninteresting in the explanation of the worktree.\n\nSounds reasonable.\n\n>\n> We need to say that the repository data (configuration, refs and\n> objecs) are mostly shared among worktrees while some data are kept\n> per-worktree, which the current text adequately covers, and what is\n> missing with respect to a bare repository is that we do not say\n> worktrees can be attached after the fact to a repository that was\n> created bare.\n\nWhy? Worktree could be attached after the fact to any repository. I\ndon't see why we need to mention bareness here, as it's not special in\nthis regard.\n\n>\n> So, perhaps something along this line?\n>\n> Documentation/glossary-content.txt | 16 +++++++++-------\n> 1 file changed, 9 insertions(+), 7 deletions(-)\n>\n> diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt\n> index 5a537268e2..6dba68ffc0 100644\n> --- c/Documentation/glossary-content.txt\n> +++ w/Documentation/glossary-content.txt\n> @@ -694,10 +694,12 @@ The most notable example is `HEAD`.\n> \tplus any local changes that you have made but not yet committed.\n> \n> [[def_worktree]]worktree::\n> -\tA repository can have zero (i.e. bare repository) or one or\n> -\tmore worktrees attached to it. One \"worktree\" consists of a\n> -\t\"working tree\" and repository metadata, most of which are\n> -\tshared among other worktrees of a single repository, and\n> -\tsome of which are maintained separately per worktree\n> -\t(e.g. the index, HEAD and pseudorefs like MERGE_HEAD,\n> -\tper-worktree refs and per-worktree configuration file).\n> +\tA repository can have zero or more worktrees attached to it.\n> +\tOne \"worktree\" consists of a \"working tree\" and repository\n> +\tmetadata, most of which are shared among other worktrees of\n> +\ta single repository, and some of which are maintained\n> +\tseparately per worktree (e.g. the index, HEAD and pseudorefs\n> +\tlike MERGE_HEAD, per-worktree refs and per-worktree\n> +\tconfiguration file).\n> ++\n> +Note that worktrees can be attached to an existing bare repository.\n\n\"shared among other worktrees\" -> \"shared among all worktrees\"?\n\nAlso, if we do have \"main worktree\" and \"linked worktree\" as concepts,\nthey need to be at least mentioned in the glossary, I believe.\n\nFinally, if we do have \"linked worktrees\", then the phrasing should\nbetter use \"linked\" instead of \"attached\"? Alternatively, if \"attached\"\nfits better, let's call them \"attached worktrees\"?\n\n-- \nSergey Organov\n"},{"id":"481457","messageId":"xmqqy1hjkkxc.fsf@gitster.g","threadId":"60195","inReplyTo":"878r9juflz.fsf@osv.gnss.ru","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-06T22:15:43Z","receivedAt":"2023-09-06T22:15:48Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> I agree \"inline\" is not much better than \"main\", nor \"attached\" is\n> better than \"linked\". I just pulled mine out of thin air, and what's\n> already there is probably fine.\n\nHeh, the initial draft of my message you are responding to used\n\"primary\" (and \"attached\"), because they are the word I am\naccustomed to use (out of thin air) on the list a few times, before\nchecking with the existing documentation to realize that we use\n\"main\" for that.\n\n> That said, to be picky, \"main\" suggests\n> that linked worktrees are somehow inferior. Are they?\n\nI'd say that 'main' is different, not necessarily superiour, from\nall others and they are equally useful and usable. The difference\nis that it cannot be removed. There may be other differences I am\nforgetting, but I do not think it is about which is superiour and\nwhich is inferiour.\n"},{"id":"481458","messageId":"87y1hjszgu.fsf@osv.gnss.ru","threadId":"60195","inReplyTo":"xmqqy1hjkkxc.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T22:34:25Z","receivedAt":"2023-09-06T22:34:32Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> I agree \"inline\" is not much better than \"main\", nor \"attached\" is\n>> better than \"linked\". I just pulled mine out of thin air, and what's\n>> already there is probably fine.\n>\n> Heh, the initial draft of my message you are responding to used\n> \"primary\" (and \"attached\"), because they are the word I am\n> accustomed to use (out of thin air) on the list a few times, before\n> checking with the existing documentation to realize that we use\n> \"main\" for that.\n>\n>> That said, to be picky, \"main\" suggests\n>> that linked worktrees are somehow inferior. Are they?\n>\n> I'd say that 'main' is different, not necessarily superiour, from\n> all others and they are equally useful and usable. The difference\n> is that it cannot be removed. There may be other differences I am\n> forgetting, but I do not think it is about which is superiour and\n> which is inferiour.\n\nWell, if worktree created by \"git clone/init\" is not superior compared\nto that created by \"git worktree\", just different, then \"main\" might be\nnot the best choice, but then, provided it's already in use, it's\nprobably not that big deal either.\n\nAs a note, \"primary\" also suggests the rest are \"secondary\", and then\n\"primary\" one might not be there in the first place, leaving us with a\nset of \"secondary\" without \"primary\", that is a bit confusing.\n\n\"Embedded\", \"integrated\", or even \"default\" come to mind as\nalternatives. However, if \"attached\" is decided upon, \"inline\" just\nfollows naturally.\n"},{"id":"481459","messageId":"CAPMMpojTLswqubRk0Ly3RQqkrnpx_9Hiu_TRK1=ASPbPNz4ApQ@mail.gmail.com","threadId":"60195","inReplyTo":"xmqqledjm4k2.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Tao Klerks","fromEmail":"tao@klerks.biz","sentAt":"2023-09-07T04:53:58Z","receivedAt":"2023-09-07T04:54:11Z","isPatch":false,"sender":{"key":"tao@klerks.biz","avatar":"https://avatars.githubusercontent.com/u/531704?v=4"},"body":"On Wed, Sep 6, 2023 at 10:26 PM Junio C Hamano wrote:\n>\n> Tao Klerks writes:\n>\n> > I like the nomenclature, I like the simple \"zero (i.e. bare) or one\n> > inline worktree, zero or more attached worktrees\" explanation.\n>\n> We have used \"main worktree\" to refer to the working tree part (plus\n> the repository) of a non-bare repository. And it makes sense to\n> explain it together with the concept of \"worktree\", as the primary\n> one is very much special in that it cannot be removed. You can see\n> that \"git worktree remove\" would stop you from removing it with an\n> error message:\n>\n> fatal: '../there' is a main working tree.\n>\n> It probably does not add much value to introduce a new term\n> \"inline\". Here is what \"git worktree --help\" has to say about it.\n>\n> A repository has one main worktree (if it's not a bare repository) and\n> zero or more linked worktrees.\n\nI've definitely changed my mind about \"inline\", I agree \"main\" is\nbetter. I'm not convinced it's the best word we could come up with,\nbut if it's well-established, I'm happy with it.\n\nThe problem I (now) see with \"inline\" is that it seems to imply a\nspatial proximity that doesn't necessarily hold true, with\n\"--separate-git-dir\" or other ways to separate the main worktree from\nits usual \"just above the .git directory\" location. \"Inline\" is still\na reasonable qualification of the main worktree's *metadata* in that\nsituation (index, etc), but I think the word would not be sufficiently\nclear/representative overall.\n\n>\n> I applaud whoever wrote this sentence for packing so much good\n> information in a concise and easy-to-understand description.\n\nI also like this sentence, it's basically equivalent to Sergey's sentence above.\n\n>\n> We can read that (1) a non-bare repository itself is considered\n> its \"main worktree\", (2) a bare repository, by inference, has no\n> main worktree (otherwise we wouldn't have said \"if it's not\"), and\n> (3) both bare and non-bare repositories can have linked worktrees\n> (again, otherwise we wouldn't have brought up a bare repository in\n> the description).\n>\n> Perhaps we should borrow it to update the glossary, like so?\n>\n\nLooks good to me, but that leaves me with a different nitpick: we say\n'One \"worktree\" consists of a \"working tree\" and repository metadata,\nmost of which are shared among other worktrees of a single repository,\nand some of which are maintained separately per worktree'\n\nThis claims that the *shared metadata* (presumably the refs, the\nbranch reflogs, the objects, the config, etc) are *part of the\nworktree* (a worktree \"consists of\" them and other things). That seems\nlike a very strange way to conceive of things, to me.\n\nI would find it reasonable to state that the main worktree is part of\nthe repo - certainly that's now most everyday users would think of it,\nif they were made to think of the worktree concept at all - but not\nthat the shared repo metadata is part of the worktree, and especially\nnot that the shared repo metadata is part of the attached worktrees.\n\nI imagine that this weird phrasing intends to allude to the fact that\na worktree is \"broken\" without the repository metadata folder that\ncontains both its worktree-specific metadata and the shared metadata\nthat it depends just as much on... but can we come up with better\n\"relationship words here?\n\n* A repository \"has\" zero or more worktrees\n* If it \"has\" a \"main\" worktree it is not a bare repository, otherwise it is.\n* It can have any number of \"attached\" worktrees\n\nIf a repo \"has\" these worktrees, is it in the sense that I \"have\" arms\nand legs, and I \"consist of\" a person with arms and legs and other\nbody parts, or is it in the sense that I \"have\" a lifetime, opinions,\nlegal rights, and other things that I have as a consequence of being a\nperson, but are not \"part of\" me?\n\nSimilarly, do we have a term for \"the directory that contains the\n'refs' and 'objects' folders and stuff\", regardless of whether it is\nin fact the entire bare repository, typically with a name other than\n\".git\", or it is nested in a main worktree in the usual fashion as\n\".git\", or it is separated (and again, typically differently-named) in\na \"--separate-git-dir\" topology? I called it a \"repository metadata\nfolder\" above, but I'm not sure whether there is a correct, succinct\nterm for it.\n\nWrt to the \"shared among other worktrees\" bit specifically, I agree\nwith Sergey that \"shared among all\" would be clearer, but it's still\nweird, because all of that shared metadata is \"inherent to the repo\"\nbeyond any and all worktrees. If this happens to be a bare repo, and\nwe remove all the attached worktrees, the metadata is still just as\nmeaningful - so saying that it was \"shared among the worktrees\", while\ntrue, seems to be unnecessarily implying a smaller purpose/meaning\nthan appropriate.\n\nSorry to continue nitpicking - I would love to see a clear\nnomenclature and description of these parts and their relationships\nfor people (with less git experience) to \"get it\" more easily.\n\n>\n> Documentation/glossary-content.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt\n> index 5a537268e2..d9ba3bab88 100644\n> --- c/Documentation/glossary-content.txt\n> +++ w/Documentation/glossary-content.txt\n> @@ -694,8 +694,8 @@ The most notable example is `HEAD`.\n> plus any local changes that you have made but not yet committed.\n>\n> [[def_worktree]]worktree::\n> - A repository can have zero (i.e. bare repository) or one or\n> - more worktrees attached to it. One \"worktree\" consists of a\n> + A repository has one main worktree (if it's not a bare\n> + repository) and zero or more linked worktrees. One \"worktree\" consists of a\n> \"working tree\" and repository metadata, most of which are\n> shared among other worktrees of a single repository, and\n> some of which are maintained separately per worktree\n"},{"id":"481471","messageId":"d59a97e7-81fd-472b-9a18-32d993f8c1c8@app.fastmail.com","threadId":"60195","inReplyTo":"xmqqledjm4k2.fsf@gitster.g","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-07T15:07:01Z","receivedAt":"2023-09-07T16:17:24Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Hi again Junio\n\nOn Wed, Sep 6, 2023, at 22:26, Junio C Hamano wrote:\n> Tao Klerks writes:\n>\n>> I like the nomenclature, I like the simple \"zero (i.e. bare) or one\n>> inline worktree, zero or more attached worktrees\" explanation.\n>\n> We have used \"main worktree\" to refer to the working tree part (plus\n> the repository) of a non-bare repository. And it makes sense to\n> explain it together with the concept of \"worktree\", as the primary\n> one is very much special in that it cannot be removed. You can see\n> that \"git worktree remove\" would stop you from removing it with an\n> error message:\n>\n> \tfatal: '../there' is a main working tree.\n\nThis gives the same error if `there` is a bare repository. Is that\nintended?\n\nThis goes back to my point about missing nomenclature: it's weird if the\n“main working tree” can be a bare repository.\n\nPS: Is it correct that the error message says “main working tree” instead\nof “main worktree”? (See cc73385cf6 (worktree remove: new command,\n2018-02-12.) I was thinking of spelunking the history further but thought\nthat I would quickly ask in case I'm missing something obvious.\n\n> It probably does not add much value to introduce a new term\n> \"inline\".\n\nThe reason that I like it is because it lets you describe a bare\nrepository with linked worktrees. Not because it would replace “main\nworktree”.\n\nAlthough in light of Sergey's post about inline/attached, the “main\nworktree” term *might* start to look a bit anachronistic. But I'm not\nsure.\n\n> Here is what \"git worktree --help\" has to say about it.\n>\n> A repository has one main worktree (if it's not a bare repository) and\n> zero or more linked worktrees.\n>\n> I applaud whoever wrote this sentence for packing so much good\n> information in a concise and easy-to-understand description.\n\nI agree that it is very elegant.\n\n> Perhaps we should borrow it to update the glossary, like so?\n\nCertainly. But although this looks like it completely describes everything\nthat you want, I still think it is good to explicitly mention something\nlike:\n\n “ Note that a bare repository may have ...\n\nSince although this can certainly be inferred from the text, it's good to\nhave some redundancy when it comes to non-obvious cases.\n\nCheers\n\n-- \nKristoffer Haugsbakk\n"},{"id":"481489","messageId":"87h6o6ebm3.fsf@osv.gnss.ru","threadId":"60195","inReplyTo":"CAPMMpojTLswqubRk0Ly3RQqkrnpx_9Hiu_TRK1=ASPbPNz4ApQ@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-07T06:33:24Z","receivedAt":"2023-09-07T17:41:46Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Tao Klerks writes:\n\n> On Wed, Sep 6, 2023 at 10:26 PM Junio C Hamano wrote:\n>>\n>> Tao Klerks writes:\n>>\n>> > I like the nomenclature, I like the simple \"zero (i.e. bare) or one\n>> > inline worktree, zero or more attached worktrees\" explanation.\n>>\n>> We have used \"main worktree\" to refer to the working tree part (plus\n>> the repository) of a non-bare repository. And it makes sense to\n>> explain it together with the concept of \"worktree\", as the primary\n>> one is very much special in that it cannot be removed. You can see\n>> that \"git worktree remove\" would stop you from removing it with an\n>> error message:\n>>\n>> fatal: '../there' is a main working tree.\n>>\n>> It probably does not add much value to introduce a new term\n>> \"inline\". Here is what \"git worktree --help\" has to say about it.\n>>\n>> A repository has one main worktree (if it's not a bare repository) and\n>> zero or more linked worktrees.\n>\n> I've definitely changed my mind about \"inline\", I agree \"main\" is\n> better. I'm not convinced it's the best word we could come up with,\n> but if it's well-established, I'm happy with it.\n>\n> The problem I (now) see with \"inline\" is that it seems to imply a\n> spatial proximity that doesn't necessarily hold true, with\n> \"--separate-git-dir\" or other ways to separate the main worktree from\n> its usual \"just above the .git directory\" location. \"Inline\" is still\n> a reasonable qualification of the main worktree's *metadata* in that\n> situation (index, etc), but I think the word would not be sufficiently\n> clear/representative overall.\n\nIt's not to argue in favor of \"inline\", just to clarify: I took it from\ninline-vs-attached as used in e-mail, where \"inline\" means that you see\nattachment right here, inline with the rest of text.\n\nI also admit I didn't happen to consider --separate-git-dir at the\ntime.\n"},{"id":"481499","messageId":"xmqqv8clkfli.fsf@gitster.g","threadId":"60195","inReplyTo":"d59a97e7-81fd-472b-9a18-32d993f8c1c8@app.fastmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-07T18:23:05Z","receivedAt":"2023-09-07T18:24:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n>> \tfatal: '../there' is a main working tree.\n>\n> This gives the same error if `there` is a bare repository. Is that\n> intended?\n\nI do not think so. The above is from \"git worktree remove\" and the\ncandidates to be removed is listed by \"git worktree list\". I do not\nknow if it is sensible to include the bare repository that the\nworktrees are attached to in the \"list\" output, and I do not think\nit makes sense to accept the path to the directory that is such a\nbare repository and let the code proceed that far. It should just\nreject it saying it is *not* a worktree.\n\n> PS: Is it correct that the error message says “main working tree” instead\n> of “main worktree”? (See cc73385cf6 (worktree remove: new command,\n> 2018-02-12.) I was thinking of spelunking the history further but thought\n> that I would quickly ask in case I'm missing something obvious.\n\nMy understanding is that \"working tree\" refers to what \"git\ncheckout\" would give you to your \"make\" and compilers. The\n\"worktree\" is a mechanism to allow you to have multiple \"working\ntree\"s that are connected to a single repository (be it a bare or a\nnon-bare one).\n\n> Certainly. But although this looks like it completely describes everything\n> that you want, I still think it is good to explicitly mention something\n> like:\n>\n> “ Note that a bare repository may have ...\n>\n> Since although this can certainly be inferred from the text, it's good to\n> have some redundancy when it comes to non-obvious cases.\n\nThat is fine.\n\nI think I've already said everything that I think should be in the\nfinal text, and I do not mind if there are anything extra for\nhelping new readers that may be more than absolute minimum.\n\nThanks.\n"},{"id":"481511","messageId":"d65e5407-df82-4a86-8050-854caf0f8058@app.fastmail.com","threadId":"60195","inReplyTo":"CAPMMpojTLswqubRk0Ly3RQqkrnpx_9Hiu_TRK1=ASPbPNz4ApQ@mail.gmail.com","subject":"Re: Is \"bare\"ness in the context of multiple worktrees weird? Bitmap error in git gc.","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-09-07T20:11:48Z","receivedAt":"2023-09-07T20:12:16Z","isPatch":false,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Hi again Tao\n\nOn Thu, Sep 7, 2023, at 06:53, Tao Klerks wrote:\n> I've definitely changed my mind about \"inline\", I agree \"main\" is\n> better. I'm not convinced it's the best word we could come up with,\n> but if it's well-established, I'm happy with it.\n\nNote that the conversation was forked:\n\n1. New nomenclature to describe things more precisely\n2. How good those words in themselves are at describing these things\n\nI liked “inline” since it helped to clarify the case of a bare repository\nwith linked worktrees. Sure, emphasizing that it has no “inline worktree”\nmight be redundant (it can be inferred, perhaps), it's nice to be able to\nemphasize things for pedagogical purposes.\n\n(I'm less sure if “attached” is needed.)\n\nThis is what we can say for certain about a repository:\n\n• There definitely is a repository somewhere (maybe not in whatever\n worktree you are in right now though)\n• It has zero or more worktrees\n\nSo “main worktree” is optional. And that optionality makes things awkward\nsince it also used to describe where the repository lives—even when the\nrepository has no *inline worktree* (it is bare).\n\nThe bottom line is that it's nice if one can avoid having to get into\nsituations like this made-up conversation:\n\nA: — I'm in the deployment worktree now. Where's the main\n worktree in our workflow? [I don't know how to use `git worktree`]\nB: — That's `repository.git`.\nA: — Okay nice. Is that worktree used for the mainline development?\nB: — No, it has no worktree. It's bare.\nA: — What? But didn't you say that it was the main worktree?\nB: — Yes, in the sense that it's where the repository is. But it has no\n worktree itself.\n\n>> We can read that (1) a non-bare repository itself is considered\n>> its \"main worktree\", (2) a bare repository, by inference, has no\n>> main worktree (otherwise we wouldn't have said \"if it's not\"), and\n>> (3) both bare and non-bare repositories can have linked worktrees\n>> (again, otherwise we wouldn't have brought up a bare repository in\n>> the description).\n>>\n>> Perhaps we should borrow it to update the glossary, like so?\n>>\n>\n> Looks good to me, but that leaves me with a different nitpick: we say\n> 'One \"worktree\" consists of a \"working tree\" and repository metadata,\n> most of which are shared among other worktrees of a single repository,\n> and some of which are maintained separately per worktree'\n>\n> This claims that the *shared metadata* (presumably the refs, the\n> branch reflogs, the objects, the config, etc) are *part of the\n> worktree* (a worktree \"consists of\" them and other things). That seems\n> like a very strange way to conceive of things, to me.\n>\n> I would find it reasonable to state that the main worktree is part of\n> the repo - certainly that's now most everyday users would think of it,\n> if they were made to think of the worktree concept at all - but not\n> that the shared repo metadata is part of the worktree, and especially\n> not that the shared repo metadata is part of the attached worktrees.\n\nWithout getting into the subtle distinctions between is-a and has-a: I\nthink it could make sense to think of this in terms of which one needs the\nother one. A worktree needs a repository, so one could say that a worktree\n“consists of” that. A repository on the other hand doesn't need to have\nany worktrees.\n\n(But the vice-versa also makes sense.)\n\n> I imagine that this weird phrasing intends to allude to the fact that\n> a worktree is \"broken\" without the repository metadata folder that\n> contains both its worktree-specific metadata and the shared metadata\n> that it depends just as much on... but can we come up with better\n> \"relationship words here?\n\nI don't see why one needs to phrase or define things in terms of what\nwould make it corrupted or not-that-thing any more. Like, a “working tree”\nwithout a Git repository is just a directory tree—it's got nothing to do\nwith Git whatsoever.\n\n> Sorry to continue nitpicking - I would love to see a clear\n> nomenclature and description of these parts and their relationships\n> for people (with less git experience) to \"get it\" more easily.\n\nAs a Git user I think this is a very productive topic.\n\nCheers\n\n-- \nKristoffer Haugsbakk\n"}]}