{"thread":{"id":"64218","subject":"What is the reason behind not hiding git worktrees from git?","startedAt":"2025-09-27T14:04:09Z","lastAt":"2026-01-20T20:38:47Z","messageCount":44,"participants":["Jakub T. Jankiewicz","Junio C Hamano","Michal Suchánek","Jason Cho","Ben Knoble","Sergey Organov","Eric Sunshine","Michal Suchanek","Kristoffer Haugsbakk","Jean-Noël AVILA","Johannes Schindelin"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"527479","messageId":"20250927152824.3132af88@jcubic","threadId":"64218","inReplyTo":null,"subject":"What is the reason behind not hiding git worktrees from git?","fromName":"Jakub T. Jankiewicz","fromEmail":"jcubic@jcubic.pl","sentAt":"2025-09-27T13:28:24Z","receivedAt":"2025-09-27T14:04:09Z","isPatch":false,"sender":{"key":"jcubic@jcubic.pl","avatar":null},"body":"Hi,\n\nI use git since 2010, but I've discovered git work trees recently.\n\nWhy git work trees are are not automatically ignored by git?\n\nIt would kind if silly to add the whole project on different branch to the\nmain repo.\n\nThis is an example:\n\ngit worktree add base\ngit status\n\n\nOn branch master\nYour branch is up to date with 'origin/master'.\n\nUntracked files:\n (use \"git add ...\" to include in what will be committed)\n base/\n\nnothing added to commit but untracked files present (use \"git add\" to track)\n\nWhat is the rationale for this. Why base/ is not automatically ignored and\nyou need to add it to the .gitignore by hand?\n\nI use git 2.51.0 from Fedora default repo.\n\n--\nJakub T. Jankiewicz, Senior Front-End Developer\nhttps://jakub.jankiewicz.org\nhttps://lips.js.org\nhttps://koduj.org\n"},{"id":"527492","messageId":"xmqq4isn96s7.fsf@gitster.g","threadId":"64218","inReplyTo":"20250927152824.3132af88@jcubic","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-27T16:52:56Z","receivedAt":"2025-09-27T16:52:58Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jakub T. Jankiewicz\" writes:\n\n> Why git work trees are are not automatically ignored by git?\n\nBecause there is no reason to ignore them, and ignoring them would\nbe annoyingly inconvenient. Worktrees are not special and treated\nthe same way as an ordinary Git working tree with embedded .git\ndirectory.\n\nThat is, if you \"git clone\" somebody else's project into your\ncurrent directory, when you are in the working tree of you git\nrepository, that working tree of the cloned repository would appear\nas an untracked content from the point of view of the containing\nrepository of yours. It is up to you to add it as a subproject, or\nleave it as an untracked directory.\n\nIf you do not want to see a new worktree as an untracked directory\nin another repository, do not do\n\n $ git worktree add base\n\nin the first place. You are creating the new worktree _inside_ an\nexisting repository's working tree, and it is no surprise that the\nnew directory appears as an untracked directory.\n\nIn other words, if it hurts, don't do it.\n\nInstead, you can create your additional worktree outside the working\ntree you are using. For example, I keep a handful of worktrees just\nnext to my primary working tree, by doing something like\n\n $ git worktree add --detach ../git.maint maint\n $ git worktree add --detach ../git.next next\n $ git worktree add --detach ../git.seen seen\n\nwhen I am in my primary working tree. Then I can leave some work in\nprogress in my primary working tree and then context switch out to\n\n $ cd ../git.next && git reset --hard next\n $ do stuff on next\n\nany one of these additional worktrees.\n\nHope this helps.\n\n\n\n"},{"id":"527493","messageId":"aNglDzeOT5_4ZbdV@kitsune.suse.cz","threadId":"64218","inReplyTo":"xmqq4isn96s7.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-09-27T17:55:27Z","receivedAt":"2025-09-27T17:55:30Z","isPatch":false,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Sat, Sep 27, 2025 at 09:52:56AM -0700, Junio C Hamano wrote:\n> \"Jakub T. Jankiewicz\" writes:\n> \n> > Why git work trees are are not automatically ignored by git?\n> \n> Because there is no reason to ignore them, and ignoring them would\n> be annoyingly inconvenient. Worktrees are not special and treated\n> the same way as an ordinary Git working tree with embedded .git\n> directory.\n\nSure, that's another repository.\n\nIt does not not show its own .git directory as untracked files although\nit is in the main worktree, though.\n\nSo why another worktree of the same repository is shown?\n\nThat can be seen as inconsistent.\n\nThanks\n\nMichal\n"},{"id":"527496","messageId":"KUIfhZpMUwujq7A0Qdiri2OEhWabUXUVVpHZb7o0A-iqAC_46qQd5acUqN9TlkFMGe2t-aY4IXFQCjs6gKsawBCGSazI3QDPigdI7KrRf_A=@proton.me","threadId":"64218","inReplyTo":"aNglDzeOT5_4ZbdV@kitsune.suse.cz","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Jason Cho","fromEmail":"jason11choca@proton.me","sentAt":"2025-09-27T21:08:44Z","receivedAt":"2025-09-27T21:09:01Z","isPatch":false,"sender":{"key":"jason11choca@proton.me","avatar":null},"body":"> It does not not show its own .git directory as untracked files\n> \n> That can be seen as inconsistent.\n\nWell, I see your point. Since the .git directory is from a git repo, the directory is ignored by git. Therefore, you want git to also ignore other items derived from the repo, including work trees.\n\nHowever, this is a minor improvement and I suspect your proposed feature may have an unknown impact. \n\nAnyway, what's your real use case? Do you really add hundreds of work trees within the same repo directory so that you hate to see them in git status?\n"},{"id":"527497","messageId":"GY1ni5SFkgBgVIHm9HoO9dtLuLWbUPCv5mjcsy5VGi09PyRLV_gv3MMw2zsinKpi5Aon9J-LESzTUuwMOUNLRRLqyXM7ON-98WTzhH7RIYY=@proton.me","threadId":"64218","inReplyTo":"KUIfhZpMUwujq7A0Qdiri2OEhWabUXUVVpHZb7o0A-iqAC_46qQd5acUqN9TlkFMGe2t-aY4IXFQCjs6gKsawBCGSazI3QDPigdI7KrRf_A=@proton.me","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Jason Cho","fromEmail":"jason11choca@proton.me","sentAt":"2025-09-27T21:26:54Z","receivedAt":"2025-09-27T21:27:01Z","isPatch":false,"sender":{"key":"jason11choca@proton.me","avatar":null},"body":"I think the best practice is to not add a work tre within the master work tree.\n\nSuppose a repo is at the master branch, and you export a work tree in the directory f.\n\nThen, you check out the main repo to another branch which so happens to have a file named f. In this case, the check-out will fail due to the name collision.\n\n\n"},{"id":"527626","messageId":"aNuxUqDMNcZZs68n@kitsune.suse.cz","threadId":"64218","inReplyTo":"GY1ni5SFkgBgVIHm9HoO9dtLuLWbUPCv5mjcsy5VGi09PyRLV_gv3MMw2zsinKpi5Aon9J-LESzTUuwMOUNLRRLqyXM7ON-98WTzhH7RIYY=@proton.me","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-09-30T10:30:42Z","receivedAt":"2025-09-30T10:30:46Z","isPatch":false,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:\n> I think the best practice is to not add a work tre within the master work tree.\n\nAnd is that best practice documented somewhere?\n\nIIRC there are some VCSs for which it is common practice to keep\ncheckouts of multiple branches side by side in the repository directory.\nIIRC the repository directory itself is not a checkout in this case.\nAnyway, there is no obvious reason for anyone not familiar with git\ninternals to not do this.\n\n> Suppose a repo is at the master branch, and you export a work tree in the directory f.\n> \n> Then, you check out the main repo to another branch which so happens to have a file named f. In this case, the check-out will fail due to the name collision.\n\nThat would not happen in this work style, each branch has a separate\ncheckout. If you want to checkout a branch you create a worktree for it.\n\nThanks\n\nMichal\n"},{"id":"527627","messageId":"aNuy1aab954D3rJ1@kitsune.suse.cz","threadId":"64218","inReplyTo":"KUIfhZpMUwujq7A0Qdiri2OEhWabUXUVVpHZb7o0A-iqAC_46qQd5acUqN9TlkFMGe2t-aY4IXFQCjs6gKsawBCGSazI3QDPigdI7KrRf_A=@proton.me","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-09-30T10:37:09Z","receivedAt":"2025-09-30T10:37:12Z","isPatch":false,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Sat, Sep 27, 2025 at 09:08:44PM +0000, Jason Cho wrote:\n> > It does not not show its own .git directory as untracked files\n> > \n> > That can be seen as inconsistent.\n> \n> Well, I see your point. Since the .git directory is from a git repo, the directory is ignored by git. Therefore, you want git to also ignore other items derived from the repo, including work trees.\n> \n> However, this is a minor improvement and I suspect your proposed feature may have an unknown impact.\n\nThe impact is that the list of worktrees would have to be read to get\nstatus. As status is not particularly cheap operation in any case I\nwould expect the problem to be minor.\n\n> Anyway, what's your real use case? Do you really add hundreds of work trees within the same repo directory so that you hate to see them in git status?\n\nWhat is the abstraction you are trying to propose here?\n\nOr do you suggest to eschew any intelligible abstraction in favor of\n(probably minor) implementation convenience?\n\nThanks\n\nMichal\n"},{"id":"527643","messageId":"xmqqzfac3pts.fsf@gitster.g","threadId":"64218","inReplyTo":"aNuxUqDMNcZZs68n@kitsune.suse.cz","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-30T15:47:11Z","receivedAt":"2025-09-30T15:47:14Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Suchánek writes:\n\n> On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:\n>> I think the best practice is to not add a work tre within the master work tree.\n>\n> And is that best practice documented somewhere?\n\nI do not think it is documented anywhere.\n\nIn fact, I do not think the inventors of the worktree feature ever\nexpected this end-user expectation that checking out multiple\nworktrees of the repository *INSIDE* a repository's checkout would\nbe any useful without confusing users.\n\nIOW, omission of the documentation is by an assumptionk that nobody\nwould imagine doing in any other way. \n\nWe can and should fix it retroactively, if the lack of documentation\nis not guiding our users in the right direction. Any takers?\n\n> IIRC there are some VCSs for which it is common practice to keep\n> checkouts of multiple branches side by side in the repository directory.\n\nI can understand \"side-by-side\" but not \"in\". Next to the primary\nworkree (aka \"initial clone\") would be more common.\n\n> IIRC the repository directory itself is not a checkout in this case.\n> Anyway, there is no obvious reason for anyone not familiar with git\n> internals to not do this.\n\nMeaning anybody not familiar with the tool would do any random thing\noutside of the usage pattern that the users of the tool have been\nestablishing over the years? I can certainly understand that. But\nthen, creating a set of worktrees, one per branch, next to the\nprimary worktree that checks out the 'main' branch, would also equally\nbe a likely layout, I would imagine.\n\nThanks.\n"},{"id":"527677","messageId":"E311F5BA-F88C-4C3D-88B5-F8508B106D41@gmail.com","threadId":"64218","inReplyTo":"aNuy1aab954D3rJ1@kitsune.suse.cz","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-01T12:16:25Z","receivedAt":"2025-10-01T12:16:37Z","isPatch":false,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 30 sept. 2025 à 06:41, Michal Suchánek a écrit :\n> \n> On Sat, Sep 27, 2025 at 09:08:44PM +0000, Jason Cho wrote:\n>>> It does not not show its own .git directory as untracked files\n>>> \n>>> That can be seen as inconsistent.\n>> \n>> Well, I see your point. Since the .git directory is from a git repo, the directory is ignored by git. Therefore, you want git to also ignore other items derived from the repo, including work trees.\n>> \n>> However, this is a minor improvement and I suspect your proposed feature may have an unknown impact.\n> \n> The impact is that the list of worktrees would have to be read to get\n> status. As status is not particularly cheap operation in any case I\n> would expect the problem to be minor.\n\nI believe status information is used for the shell prompt info, so performance hits there have a cost."},{"id":"527715","messageId":"xmqq3482312r.fsf@gitster.g","threadId":"64218","inReplyTo":"E311F5BA-F88C-4C3D-88B5-F8508B106D41@gmail.com","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-01T18:54:04Z","receivedAt":"2025-10-01T18:54:07Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Knoble writes:\n\n>> The impact is that the list of worktrees would have to be read to get\n>> status. As status is not particularly cheap operation in any case I\n>> would expect the problem to be minor.\n>\n> I believe status information is used for the shell prompt info, so\n> performance hits there have a cost.\n\nSure, but an embedded git-controlled working tree _should_ be\nflagged as an untracked entity, _unless_ it is ignore'd, no?\n\nThat is how you would add a new submodule to your project after all.\nSo, if you want to ignore them, just add them to .git/info/exclude\nor something, perhaps?\n\nWhy do people even want to have such a layout, unless they want to\nmake it a submodule (or deliberate subdirectory that is unrelated)?\n\n -+- README.md (your own branch, probably on main)\n |\n +-+ worktree-foo (worktree checkout of branch foo)\n | |\n | +-- README.md (a slight variant of the file in foo)\n |\n +-+ worktree-bar (worktree checkout of branch bar)\n | |\n | +-- README.md (a slight variant of the file in bar)\n |\n +-+ worktree-baz (worktree checkout of branch baz)\n | |\n | +-- README.md (a slight variant of the file in baz)\n\nWouldn't it be easier to manage if you had this instead?\n\n -+\n |\n +-+ my-project (the primary worktree, probably on main)\n | |\n | +-- README.md (the file from branch main)\n |\n +-+ worktree-foo (worktree checkout of branch foo)\n | |\n | +-- README.md (a slight variant of the file in foo)\n |\n +-+ worktree-bar (worktree checkout of branch bar)\n | |\n | +-- README.md (a slight variant of the file in bar)\n |\n +-+ worktree-baz (worktree checkout of branch baz)\n | |\n | +-- README.md (a slight variant of the file in baz)\n\nThat way, you can go up to the umbrella directory and ...\n\n $ cd ..\n $ ls\n my-project worktree-foo worktree-bar worktree-baz\n $ grep -e HowTo */README.md\n\n... do things you would do collectively to these worktrees with the\nprimary worktree included as well.\n\n"},{"id":"527721","messageId":"875xcyfk3k.fsf@osv.gnss.ru","threadId":"64218","inReplyTo":"xmqq3482312r.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2025-10-01T20:22:23Z","receivedAt":"2025-10-01T20:22:27Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Ben Knoble writes:\n>\n>>> The impact is that the list of worktrees would have to be read to get\n>>> status. As status is not particularly cheap operation in any case I\n>>> would expect the problem to be minor.\n>>\n>> I believe status information is used for the shell prompt info, so\n>> performance hits there have a cost.\n>\n> Sure, but an embedded git-controlled working tree _should_ be\n> flagged as an untracked entity, _unless_ it is ignore'd, no?\n>\n> That is how you would add a new submodule to your project after all.\n> So, if you want to ignore them, just add them to .git/info/exclude\n> or something, perhaps?\n>\n> Why do people even want to have such a layout, unless they want to\n> make it a submodule (or deliberate subdirectory that is unrelated)?\n>\n> -+- README.md (your own branch, probably on main)\n> |\n> +-+ worktree-foo (worktree checkout of branch foo)\n> | |\n> | +-- README.md (a slight variant of the file in foo)\n> |\n> +-+ worktree-bar (worktree checkout of branch bar)\n> | |\n> | +-- README.md (a slight variant of the file in bar)\n> |\n> +-+ worktree-baz (worktree checkout of branch baz)\n> | |\n> | +-- README.md (a slight variant of the file in baz)\n>\n> Wouldn't it be easier to manage if you had this instead?\n>\n> -+\n> |\n> +-+ my-project (the primary worktree, probably on main)\n> | |\n> | +-- README.md (the file from branch main)\n> |\n> +-+ worktree-foo (worktree checkout of branch foo)\n> | |\n> | +-- README.md (a slight variant of the file in foo)\n> |\n> +-+ worktree-bar (worktree checkout of branch bar)\n> | |\n> | +-- README.md (a slight variant of the file in bar)\n> |\n> +-+ worktree-baz (worktree checkout of branch baz)\n> | |\n> | +-- README.md (a slight variant of the file in baz)\n>\n> That way, you can go up to the umbrella directory and ...\n>\n> $ cd ..\n> $ ls\n> my-project worktree-foo worktree-bar worktree-baz\n> $ grep -e HowTo */README.md\n>\n> ... do things you would do collectively to these worktrees with the\n> primary worktree included as well.\n\nI suspect people rather expect support for repository with multiple\nequal worktrees (no \"primary\" one), like this:\n\nmyproject / .git\n / worktree-foo\n / worktree-bar\n\n\nAlso, I'm almost sure that the first thing almost every worktree novice\ndoes (I did), quite naturally, is:\n\n$ git wotktree add \n\nthat happily succeeds /anywhere/ inside primary worktree without any\nwarning for me. It probably should either have created $top/../\ninstead, or refuse to proceed without confirmation in the first place.\n\n-- Sergey Organov\n"},{"id":"527723","messageId":"xmqqa52a1h6x.fsf@gitster.g","threadId":"64218","inReplyTo":"875xcyfk3k.fsf@osv.gnss.ru","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-01T20:48:54Z","receivedAt":"2025-10-01T20:48:57Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Also, I'm almost sure that the first thing almost every worktree novice\n> does (I did), quite naturally, is:\n>\n> $ git wotktree add \n>\n> that happily succeeds /anywhere/ inside primary worktree without any\n> warning for me. It probably should either have created $top/../\n> instead, or refuse to proceed without confirmation in the first place.\n\nYeah, I almost never type 'git worktree add ' without\n\"../\" at the beginning of the directory, and every time I do so, I\ndo wonder if this is a UI pitfall that we should warn the users\nabout. Perhaps we should start from documentation updates and\npossibly a new warning or two?\n\nThanks.\n\n\n"},{"id":"527730","messageId":"20251001232718.7218e852@jcubic","threadId":"64218","inReplyTo":"xmqqa52a1h6x.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Jakub T. Jankiewicz","fromEmail":"jcubic@jcubic.pl","sentAt":"2025-10-01T21:27:18Z","receivedAt":"2025-10-01T21:27:28Z","isPatch":false,"sender":{"key":"jcubic@jcubic.pl","avatar":null},"body":"\n\nOn Wed, 01 Oct 2025 13:48:54 -0700\nJunio C Hamano wrote:\n\n> Sergey Organov writes:\n> \n> > Also, I'm almost sure that the first thing almost every worktree novice\n> > does (I did), quite naturally, is:\n> >\n> > $ git wotktree add \n> >\n> > that happily succeeds /anywhere/ inside primary worktree without any\n> > warning for me. It probably should either have created $top/../\n> > instead, or refuse to proceed without confirmation in the first place. \n> \n> Yeah, I almost never type 'git worktree add ' without\n> \"../\" at the beginning of the directory, and every time I do so, I\n> do wonder if this is a UI pitfall that we should warn the users\n> about. Perhaps we should start from documentation updates and\n> possibly a new warning or two?\n\nI discovered work trees recently, even that they are supported for years.\nAnd I though that the only way you use them is:\n\ngit worktree add branch\n\nIt just didn't occur to me, that you suppose to have them out outside the\nroot directory. The way I think about git is:\n\ndirectory/\n .git\n and all the stuff that belong that repo\n\nYou don't create submodules outside of your root directory. Didn't you?\n\n--\nJakub T. Jankiewicz, Senior Front-End Developer\nhttps://jakub.jankiewicz.org\nhttps://lips.js.org\nhttps://koduj.org\n"},{"id":"527731","messageId":"CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com","threadId":"64218","inReplyTo":"xmqqa52a1h6x.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-10-01T21:29:29Z","receivedAt":"2025-10-01T21:29:42Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Oct 1, 2025 at 4:49 PM Junio C Hamano wrote:\n> Sergey Organov writes:\n> > Also, I'm almost sure that the first thing almost every worktree novice\n> > does (I did), quite naturally, is:\n> >\n> > $ git wotktree add \n> >\n> > that happily succeeds /anywhere/ inside primary worktree without any\n> > warning for me. It probably should either have created $top/../\n> > instead, or refuse to proceed without confirmation in the first place.\n>\n> Yeah, I almost never type 'git worktree add ' without\n> \"../\" at the beginning of the directory, and every time I do so, I\n> do wonder if this is a UI pitfall that we should warn the users\n> about. Perhaps we should start from documentation updates and\n> possibly a new warning or two?\n\nEvery example in the git-worktree documentation which mentions a\nliteral path (as opposed to generic ) already uses the \"../\"\nprefix (and has from inception), including the example in the\nintroductory paragraphs:\n\n For instance, `git worktree add ../hotfix` creates new branch hotfix\n and checks it out at path `../hotfix`.\n\nand the \"real\" Example block toward the end of the man page:\n\n $ git worktree add -b emergency-fix ../temp master\n $ pushd ../temp\n # ... hack hack hack ...\n $ git commit -a -m 'emergency fix for boss'\n $ popd\n $ git worktree remove ../temp\n\nThere are exactly zero examples in the man page lacking the \"../\" prefix.\n\nIt would be possible, of course, to add a \"best practices\" section to\nthe introductory paragraphs advising against creating worktrees as\nsubdirectories of the \"main\" worktree (assuming people even agree that\na best practice is to place worktrees elsewhere). However, considering\nthat the existing examples using \"../\" have been ignored (in a\nfashion), one wonders how much a \"best practices\" discussion would\nhelp (assuming people aren't really reading the documentation anyhow,\nand may very well be cargo-culting git-worktree commands from blogs or\nexternal tutorials).\n\nRegarding issuing warnings: I'm not fond of the idea. There are plenty\nof people who already locate worktrees as subdirectories of the main\nworktree[*] and do so without problem, and for whom it is a preferred\nworkflow, so I don't see why we would want to penalize them by warning\nagainst doing so, especially since there is no technical reason to\navoid the practice (i.e. Git handles it just fine). The only minor\ndownside of the practice (if one considers it a downside) is an\naesthetic one: having to update \".gitignore\" or \".git/info/exclude\",\nor to simply consider them \"visual noise\" in git-status output and\nskip over them when scanning the output. Moreover, I think this is the\nfirst time that we have (on the list, at least) heard a complaint\nabout the \"noise\", which may suggest that this is a non-issue for most\npeople, and that a warning telling people to avoid the practice would\nbe unwelcome.\n\nAside: It might be valuable to extend the documentation to add a\ndiscussion about hanging worktrees off of a bare repository. People do\nuse such a workflow, and git-worktree officially supports it, but I\ndon't think there is any in-project documentation which mentions it.\n\nFOOTNOTES\n\n[*]: There have been numerous emails on the list showing that placing\nworktrees as subdirectories of the main worktree is common enough\npractice. And, as far as \"experienced users\" are concerned (not just\nnovices picking up the practice from blogs or tutorials), I recall an\nemail discussion in which Dscho has said that he locates worktrees as\nsubdirectories of the main worktree, as well. I, too, have done so on\noccasion.\n"},{"id":"527734","messageId":"xmqqqzvmz35u.fsf@gitster.g","threadId":"64218","inReplyTo":"20251001232718.7218e852@jcubic","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-01T22:07:57Z","receivedAt":"2025-10-01T22:08:00Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jakub T. Jankiewicz\" writes:\n\n> It just didn't occur to me, that you suppose to have them out outside the\n> root directory. The way I think about git is:\n>\n> directory/\n> .git\n> and all the stuff that belong that repo\n\nBut the point of additional worktrees is to have the stuff\nadditionally appear outside your normal working area, so that you\ncan continue working inside your primary checkout without getting\naffected by those extra directories. When you _do_ want to have\nthem _outside_ your primary working tree, you use them. That is the\nwhole point of having additional worktrees that lets you make the\ncontents of other branches materialize on the filesystem.\n\n> You don't create submodules outside of your root directory. Didn't you?\n\nSorry, but I do not get that question.\n\nSubmodule is attached to your superproject as part of it. A\nworktree is an additional and separate instantiation of the project\nitself, which is quite a different thing. They are apples and\noranges, as far as I can see.\n"},{"id":"527737","messageId":"xmqqms6az2a0.fsf@gitster.g","threadId":"64218","inReplyTo":"CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-01T22:27:03Z","receivedAt":"2025-10-01T22:27:06Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> skip over them when scanning the output. Moreover, I think this is the\n> first time that we have (on the list, at least) heard a complaint\n> about the \"noise\", which may suggest that this is a non-issue for most\n> people, and that a warning telling people to avoid the practice would\n> be unwelcome.\n\nAh, different people guess different reasons out of the same\nobservation. My interpretation of this is the first time about the\ncomplaint on \"noise\" was because everybody else would not even have\nadditional worktree in-tree.\n\n> Aside: It might be valuable to extend the documentation to add a\n> discussion about hanging worktrees off of a bare repository. People do\n> use such a workflow, and git-worktree officially supports it, but I\n> don't think there is any in-project documentation which mentions it.\n\nOh, that is an obvious thing to do, too, to attach \"additional\"\nworktrees to a bare repository (which does not have the primary\nworktree). I do not think anybody sane would add these worktrees\nin-tree if the repository is bare, though.\n"},{"id":"527746","messageId":"9052874F-AC8B-4321-9762-78FCCE498D8E@gmail.com","threadId":"64218","inReplyTo":"xmqq3482312r.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-02T02:33:56Z","receivedAt":"2025-10-02T02:34:08Z","isPatch":false,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 1 oct. 2025 à 14:54, Junio C Hamano a écrit :\n> \n> Ben Knoble writes:\n> \n>>> The impact is that the list of worktrees would have to be read to get\n>>> status. As status is not particularly cheap operation in any case I\n>>> would expect the problem to be minor.\n>> \n>> I believe status information is used for the shell prompt info, so\n>> performance hits there have a cost.\n> \n> Sure, but an embedded git-controlled working tree _should_ be\n> flagged as an untracked entity, _unless_ it is ignore'd, no?\n\nSorry, I’m not disagreeing with that here? Merely pointing out if that proposed changes affect git-status performance for the worse I will be disappointed :)\n\n> That is how you would add a new submodule to your project after all.\n> So, if you want to ignore them, just add them to .git/info/exclude\n> or something, perhaps?\n> \n> Why do people even want to have such a layout, unless they want to\n> make it a submodule (or deliberate subdirectory that is unrelated)?\n\n[snip: a better way]\n\nYep, I agree that’s easier, but I shouldn’t judge other’s workflows (I do it all the time 😅)."},{"id":"527771","messageId":"aN46GP7-yUfXB_lL@kitsune.suse.cz","threadId":"64218","inReplyTo":"xmqqms6az2a0.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T08:38:48Z","receivedAt":"2025-10-02T08:38:51Z","isPatch":false,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Wed, Oct 01, 2025 at 03:27:03PM -0700, Junio C Hamano wrote:\n> Eric Sunshine writes:\n> \n> > skip over them when scanning the output. Moreover, I think this is the\n> > first time that we have (on the list, at least) heard a complaint\n> > about the \"noise\", which may suggest that this is a non-issue for most\n> > people, and that a warning telling people to avoid the practice would\n> > be unwelcome.\n> \n> Ah, different people guess different reasons out of the same\n> observation. My interpretation of this is the first time about the\n> complaint on \"noise\" was because everybody else would not even have\n> additional worktree in-tree.\n\nI suppose a suggestion about not adding worktree in-tree in the add\ncommand description would be helpful to avoid the problem.\n\nThat's the part I would read if I wanted to learn about adding\nworktrees, and it has none of those examples you mention.\n\n> > Aside: It might be valuable to extend the documentation to add a\n> > discussion about hanging worktrees off of a bare repository. People do\n> > use such a workflow, and git-worktree officially supports it, but I\n> > don't think there is any in-project documentation which mentions it.\n> \n> Oh, that is an obvious thing to do, too, to attach \"additional\"\n> worktrees to a bare repository (which does not have the primary\n> worktree). I do not think anybody sane would add these worktrees\n> in-tree if the repository is bare, though.\n\nThat's exactly the part that is obvious only to people familiar with git\ninternals, not people reading the documentation. And it's what is needed\nto create the side-by-side layout for people that want to use that.\n\nThanks\n\nMichal\n"},{"id":"527800","messageId":"xmqqseg1xwc1.fsf@gitster.g","threadId":"64218","inReplyTo":"aN46GP7-yUfXB_lL@kitsune.suse.cz","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-02T13:33:02Z","receivedAt":"2025-10-02T13:33:04Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Suchánek writes:\n\n> On Wed, Oct 01, 2025 at 03:27:03PM -0700, Junio C Hamano wrote:\n>> Eric Sunshine writes:\n>> \n>> > skip over them when scanning the output. Moreover, I think this is the\n>> > first time that we have (on the list, at least) heard a complaint\n>> > about the \"noise\", which may suggest that this is a non-issue for most\n>> > people, and that a warning telling people to avoid the practice would\n>> > be unwelcome.\n>> \n>> Ah, different people guess different reasons out of the same\n>> observation. My interpretation of this is the first time about the\n>> complaint on \"noise\" was because everybody else would not even have\n>> additional worktree in-tree.\n>\n> I suppose a suggestion about not adding worktree in-tree in the add\n> command description would be helpful to avoid the problem.\n>\n> That's the part I would read if I wanted to learn about adding\n> worktrees, and it has none of those examples you mention.\n\nYeah, care to throw a patch or two at the documentation to help our\nusers and us?\n\nThanks.\n"},{"id":"527807","messageId":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","threadId":"64218","inReplyTo":"xmqqseg1xwc1.fsf@gitster.g","subject":"[PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Michal Suchanek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T15:51:34Z","receivedAt":"2025-10-02T15:51:52Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"Also add advice to put new worktrees outside of existing ones.\n\nSigned-off-by: Michal Suchanek \n---\n Documentation/git-worktree.adoc | 7 +++++--\n 1 file changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 389e669ac0..ec31863aec 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n $ git worktree add --track -b /\n ------------\n +\n+For best results it is advised to specify outside of the repository and\n+existing worktrees - see <>\n++\n If the branch exists in multiple remotes and one of them is named by\n the `checkout.defaultRemote` configuration variable, we'll use that\n one for the purposes of disambiguation, even if the `` isn't\n@@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n ...\n ------------\n \n-EXAMPLES\n---------\n+[[EXAMPLES]]EXAMPLES\n+--------------------\n You are in the middle of a refactoring session and your boss comes in and\n demands that you fix something immediately. You might typically use\n linkgit:git-stash[1] to store your changes away temporarily, however, your\n-- \n2.51.0\n\n"},{"id":"527808","messageId":"1d5b41562937d83be261d054989b04db6cb94a86.1759420102.git.msuchanek@suse.de","threadId":"64218","inReplyTo":"xmqqseg1xwc1.fsf@gitster.g","subject":"[PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchanek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T15:51:35Z","receivedAt":"2025-10-02T15:51:58Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"Signed-off-by: Michal Suchanek \n---\n Documentation/git-worktree.adoc | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex ec31863aec..122b191ff9 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -525,6 +525,16 @@ $ popd\n $ git worktree remove ../temp\n ------------\n \n+Side by side branch checkouts for a repository using multiple worktrees\n+\n+------------\n+mkdir some-repository\n+cd some-repository\n+git clone --bare gitforge@someforge.example.com:some-org/some-repository .git\n+git --git-dir=.git worktree add some-branch\n+git --git-dir=.git worktree add another-branch\n+------------\n+\n BUGS\n ----\n Multiple checkout in general is still experimental, and the support\n-- \n2.51.0\n\n"},{"id":"527816","messageId":"8fe29842-eb27-47ea-877b-2bfbb3a03bff@app.fastmail.com","threadId":"64218","inReplyTo":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","subject":"Re: [PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-02T17:42:42Z","receivedAt":"2025-10-02T17:43:04Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"> doc: git-worktree: Link to examples\n\nThe initial word after the colon should be lowercase unless it’s a\nproper noun.\n\nOn Thu, Oct 2, 2025, at 17:51, Michal Suchanek wrote:\n> Also add advice to put new worktrees outside of existing ones.\n>\n> Signed-off-by: Michal Suchanek \n> ---\n> Documentation/git-worktree.adoc | 7 +++++--\n> 1 file changed, 5 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> index 389e669ac0..ec31863aec 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> $ git worktree add --track -b /\n> ------------\n> +\n> +For best results it is advised to specify outside of the repository and\n> +existing worktrees - see <>\n\nThis is definitely an improvement. The current doc forces you to infer\nthat you shouldn’t put worktrees inside the repository... or just think\ntoo much.\n\nIt might also be nice to have a clause which hints at why? Maybe just\none or a few reasons, e.g. that you would have gitignore the worktree\ndirectory.\n\n> +existing worktrees - see <>\n\nI was about to recommend a `--` for en-dash but now I see that that\nproduces an em-dash instead.. :)\n\n>\n> ++\n> If the branch exists in multiple remotes and one of them is named by\n> the `checkout.defaultRemote` configuration variable, we'll use that\n> one for the purposes of disambiguation, even if the `` isn't\n> @@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n> ...\n> ------------\n>\n> -EXAMPLES\n> ---------\n> +[[EXAMPLES]]EXAMPLES\n> +--------------------\n\nApparently an anchor on the same line should not be used.\n\nhttps://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/#:~:text=Please%20do%20not%20put%20anchors\n\n> You are in the middle of a refactoring session and your boss comes in and\n> demands that you fix something immediately. You might typically use\n> linkgit:git-stash[1] to store your changes away temporarily, however, your\n> --\n> 2.51.0\n"},{"id":"527817","messageId":"xmqqo6qpw655.fsf@gitster.g","threadId":"64218","inReplyTo":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","subject":"Re: [PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-02T17:44:06Z","receivedAt":"2025-10-02T17:44:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Suchanek writes:\n\n> Also add advice to put new worktrees outside of existing ones.\n>\n> Signed-off-by: Michal Suchanek \n> ---\n> Documentation/git-worktree.adoc | 7 +++++--\n> 1 file changed, 5 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> index 389e669ac0..ec31863aec 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> $ git worktree add --track -b /\n> ------------\n> +\n> +For best results it is advised to specify outside of the repository and\n> +existing worktrees - see <>\n> ++\n\nI am wondering if we cram more information in \"For best results\", by\nadding the \"otherwise...\". Here is my (failed) attempt.\n\n Use outside of your working tree and existing worktrees\n (see <>); otherwise your new worktree will appear as\n an untracked directory.\n\nI say \"failed\" as the above phrasing makes it sound as if that\nuntracked-ness is the only downside, and also by omitting \"advised\",\nit makes it sound as if there is no upside (other than inertia) in\ndoing so.\n\nSo, I'll (atleast tentatively) queue yours as-is.\n\n> If the branch exists in multiple remotes and one of them is named by\n> the `checkout.defaultRemote` configuration variable, we'll use that\n> one for the purposes of disambiguation, even if the `` isn't\n> @@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n> ...\n> ------------\n> \n> -EXAMPLES\n> ---------\n> +[[EXAMPLES]]EXAMPLES\n> +--------------------\n\ncf. https://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/\n\nIOW, we probably should write this more like ...\n\n +[[EXAMPLES]]\n EXAMPLES\n --------\n\nThanks.\n"},{"id":"527818","messageId":"dd4027d1-4148-4171-bf17-b5c33881a446@app.fastmail.com","threadId":"64218","inReplyTo":"1d5b41562937d83be261d054989b04db6cb94a86.1759420102.git.msuchanek@suse.de","subject":"Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-02T17:51:20Z","receivedAt":"2025-10-02T17:51:42Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Thu, Oct 2, 2025, at 17:51, Michal Suchanek wrote:\n> Signed-off-by: Michal Suchanek \n\nI think this could do with more setup and motivation.\n\nI’ve seen a lot of questions on worktrees where they introduce the\nproblem with “I use a bare repository with worktrees”. And I was\npuzzled that they kept using bare repositories all the time. I’ve\nforgotten some of those details but I do seem to remember that they were\nmotivated to go all-in on making a ton of worktrees, and using the the\n“project root” to do it.\n\nIs that what the bare-setup is getting at? ;)\n\n> ---\n> Documentation/git-worktree.adoc | 10 ++++++++++\n> 1 file changed, 10 insertions(+)\n>\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> index ec31863aec..122b191ff9 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -525,6 +525,16 @@ $ popd\n> $ git worktree remove ../temp\n> ------------\n>\n> +Side by side branch checkouts for a repository using multiple worktrees\n> +\n> +------------\n> +mkdir some-repository\n> +cd some-repository\n> +git clone --bare gitforge@someforge.example.com:some-org/some-repository .git\n> +git --git-dir=.git worktree add some-branch\n> +git --git-dir=.git worktree add another-branch\n> +------------\n\nThis works for me. But why not this?\n\n git clone --bare some-repository\n cd some-repository\n git worktree add some-branch\n git worktree add another-branch\n\n> +\n> BUGS\n> ----\n> Multiple checkout in general is still experimental, and the support\n> --\n> 2.51.0\n"},{"id":"527819","messageId":"xmqqcy75w531.fsf@gitster.g","threadId":"64218","inReplyTo":"1d5b41562937d83be261d054989b04db6cb94a86.1759420102.git.msuchanek@suse.de","subject":"Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-02T18:06:58Z","receivedAt":"2025-10-02T18:07:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Suchanek writes:\n\n> Signed-off-by: Michal Suchanek \n> ---\n> Documentation/git-worktree.adoc | 10 ++++++++++\n> 1 file changed, 10 insertions(+)\n>\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> index ec31863aec..122b191ff9 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -525,6 +525,16 @@ $ popd\n> $ git worktree remove ../temp\n> ------------\n> \n> +Side by side branch checkouts for a repository using multiple worktrees\n> +\n> +------------\n> +mkdir some-repository\n> +cd some-repository\n> +git clone --bare gitforge@someforge.example.com:some-org/some-repository .git\n> +git --git-dir=.git worktree add some-branch\n> +git --git-dir=.git worktree add another-branch\n> +------------\n\nIt is a good example to have a bare clone and get worktrees attached\nto it, but I do not think that it is a great idea to call that bare\nclone \".git\". It makes it confusing if that some-repository/\ndirectory that has a \".git\" directory is a non-bare clone with no\nworking tree files, or if it is a directory that Git has no\nknowledge about, that happens to have a single bare repository plus\nworktrees. The answer is the latter, but I suspect that Git itself\nwould probably be confused (i.e. \"cd some-repository && git status\"\n---if you try it, what does it say?).\n\nNaming it after the project may make it more apparent what is going\non when the user goes into that top-level shell directory, perhaps\nlike this, if we were working with a \"bunny\" project:\n\n mkdir bunny\n cd bunny\n git clone --bare gitforge@someforge.example.com:some-org/bunny bunny.git\n git --git-dir=bunny.git worktree add some-branch\n git --git-dir=bunny.git worktree add another-branch\n\nThen when you \"cd bunny && ls\", you'd see the bare repository\nbunny.git with two checkouts.\n\nHaving said all that.\n\nI know some folks like such a layout for some (perhaps ideological)\nreason (i.e. no checkout is more special than others, everybody is\nequal), but I am not absolutely sure if it works better in a larger\nworkflow in practice than having a primary worktree that is not a\nbare repository. If you do the above with a non-bare repository in\nthe center, it would look like this:\n\n mkdir bunny-project\n cd bunny-project\n git clone gitforge@someforge.example.com:some-org/bunny main\n cd main\n git worktree add ../my-topic-1\n git worktree add ../my-topic-2\n\nand have my interaction with the upstream project only from inside\nthe primary worktree, i.e., \"main\". Additional worktrees are more\nor less ephemeral, and can go away.\n\n> +\n> BUGS\n> ----\n> Multiple checkout in general is still experimental, and the support\n"},{"id":"527822","messageId":"aN7G7p2LNUCSHlaY@kitsune.suse.cz","threadId":"64218","inReplyTo":"xmqqcy75w531.fsf@gitster.g","subject":"Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T18:39:42Z","receivedAt":"2025-10-02T18:39:46Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Thu, Oct 02, 2025 at 11:06:58AM -0700, Junio C Hamano wrote:\n> Michal Suchanek writes:\n> \n> > Signed-off-by: Michal Suchanek \n> > ---\n> > Documentation/git-worktree.adoc | 10 ++++++++++\n> > 1 file changed, 10 insertions(+)\n> >\n> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> > index ec31863aec..122b191ff9 100644\n> > --- a/Documentation/git-worktree.adoc\n> > +++ b/Documentation/git-worktree.adoc\n> > @@ -525,6 +525,16 @@ $ popd\n> > $ git worktree remove ../temp\n> > ------------\n> > \n> > +Side by side branch checkouts for a repository using multiple worktrees\n> > +\n> > +------------\n> > +mkdir some-repository\n> > +cd some-repository\n> > +git clone --bare gitforge@someforge.example.com:some-org/some-repository .git\n> > +git --git-dir=.git worktree add some-branch\n> > +git --git-dir=.git worktree add another-branch\n> > +------------\n> \n> It is a good example to have a bare clone and get worktrees attached\n> to it, but I do not think that it is a great idea to call that bare\n> clone \".git\". It makes it confusing if that some-repository/\n> directory that has a \".git\" directory is a non-bare clone with no\n> working tree files, or if it is a directory that Git has no\n> knowledge about, that happens to have a single bare repository plus\n> worktrees. The answer is the latter, but I suspect that Git itself\n> would probably be confused (i.e. \"cd some-repository && git status\"\n> ---if you try it, what does it say?).\n\ngit status\nfatal: this operation must be run in a work tree\n\n> Naming it after the project may make it more apparent what is going\n> on when the user goes into that top-level shell directory, perhaps\n> like this, if we were working with a \"bunny\" project:\n> \n> mkdir bunny\n> cd bunny\n> git clone --bare gitforge@someforge.example.com:some-org/bunny bunny.git\n> git --git-dir=bunny.git worktree add some-branch\n> git --git-dir=bunny.git worktree add another-branch\n> \n> Then when you \"cd bunny && ls\", you'd see the bare repository\n> bunny.git with two checkouts.\n\nThat also works.\n\n> \n> Having said all that.\n> \n> I know some folks like such a layout for some (perhaps ideological)\n> reason (i.e. no checkout is more special than others, everybody is\n> equal), but I am not absolutely sure if it works better in a larger\n> workflow in practice than having a primary worktree that is not a\n> bare repository. If you do the above with a non-bare repository in\n> the center, it would look like this:\n> \n> mkdir bunny-project\n> cd bunny-project\n> git clone gitforge@someforge.example.com:some-org/bunny main\n> cd main\n> git worktree add ../my-topic-1\n> git worktree add ../my-topic-2\n> \n> and have my interaction with the upstream project only from inside\n> the primary worktree, i.e., \"main\". Additional worktrees are more\n> or less ephemeral, and can go away.\n\nYes, that's a possible use case. Also git worktree add\n/dev/shm/do-some-testing\n\nHowever, that's not the intended use here. Rather it's one worktree per\nbranch, no branch switching as a result. I recall some VCSes had this\nas default or only way to work with different branches, and not\nswitching branches all the time certainly has its advantages.\n\nThanks\n\nMichal\n\n> \n> > +\n> > BUGS\n> > ----\n> > Multiple checkout in general is still experimental, and the support\n"},{"id":"527823","messageId":"aN7IcSmHCM-BBLjH@kitsune.suse.cz","threadId":"64218","inReplyTo":"dd4027d1-4148-4171-bf17-b5c33881a446@app.fastmail.com","subject":"Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T18:46:09Z","receivedAt":"2025-10-02T18:46:13Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Thu, Oct 02, 2025 at 07:51:20PM +0200, Kristoffer Haugsbakk wrote:\n> On Thu, Oct 2, 2025, at 17:51, Michal Suchanek wrote:\n> > Signed-off-by: Michal Suchanek \n> \n> I think this could do with more setup and motivation.\n> \n> I’ve seen a lot of questions on worktrees where they introduce the\n> problem with “I use a bare repository with worktrees”. And I was\n> puzzled that they kept using bare repositories all the time. I’ve\n> forgotten some of those details but I do seem to remember that they were\n> motivated to go all-in on making a ton of worktrees, and using the the\n> “project root” to do it.\n> \n> Is that what the bare-setup is getting at? ;)\n\nIt shows one way how to make a ton of worktrees without having them step\non each other, hopefully avoiding this pitfall at least in some cases.\n\n> > ---\n> > Documentation/git-worktree.adoc | 10 ++++++++++\n> > 1 file changed, 10 insertions(+)\n> >\n> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> > index ec31863aec..122b191ff9 100644\n> > --- a/Documentation/git-worktree.adoc\n> > +++ b/Documentation/git-worktree.adoc\n> > @@ -525,6 +525,16 @@ $ popd\n> > $ git worktree remove ../temp\n> > ------------\n> >\n> > +Side by side branch checkouts for a repository using multiple worktrees\n> > +\n> > +------------\n> > +mkdir some-repository\n> > +cd some-repository\n> > +git clone --bare gitforge@someforge.example.com:some-org/some-repository .git\n> > +git --git-dir=.git worktree add some-branch\n> > +git --git-dir=.git worktree add another-branch\n> > +------------\n> \n> This works for me. But why not this?\n> \n> git clone --bare some-repository\n> cd some-repository\n> git worktree add some-branch\n> git worktree add another-branch\n\nI would certainly not recommend that. There is great potential for\nconflicting with git internal structures of the bare repository.\n\nThanks\n\nMichal\n"},{"id":"527824","messageId":"xmqq3481w37x.fsf@gitster.g","threadId":"64218","inReplyTo":"dd4027d1-4148-4171-bf17-b5c33881a446@app.fastmail.com","subject":"Re: [PATCH 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-02T18:47:14Z","receivedAt":"2025-10-02T18:47:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> This works for me. But why not this?\n>\n> git clone --bare some-repository\n> cd some-repository\n> git worktree add some-branch\n> git worktree add another-branch\n\nDo you mean \"some-repository/config\" is the local configuration\nfile, next to it there are \"some-branch\" and \"another-branch\"\ndirectories, and you have to have some way to tell that, among\ndirect subdirectories of \"some-repository/\", \"some-branch/\" is a\nworktree while refs/ is not?\n\nNo thanks ;-).\n\n\n\n"},{"id":"527827","messageId":"aN7KrnF0KohlKtuN@kitsune.suse.cz","threadId":"64218","inReplyTo":"xmqqo6qpw655.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-02T18:55:42Z","receivedAt":"2025-10-02T18:55:45Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Thu, Oct 02, 2025 at 10:44:06AM -0700, Junio C Hamano wrote:\n> Michal Suchanek writes:\n> \n> > Also add advice to put new worktrees outside of existing ones.\n> >\n> > Signed-off-by: Michal Suchanek \n> > ---\n> > Documentation/git-worktree.adoc | 7 +++++--\n> > 1 file changed, 5 insertions(+), 2 deletions(-)\n> >\n> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> > index 389e669ac0..ec31863aec 100644\n> > --- a/Documentation/git-worktree.adoc\n> > +++ b/Documentation/git-worktree.adoc\n> > @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> > $ git worktree add --track -b /\n> > ------------\n> > +\n> > +For best results it is advised to specify outside of the repository and\n> > +existing worktrees - see <>\n> > ++\n> \n> I am wondering if we cram more information in \"For best results\", by\n> adding the \"otherwise...\". Here is my (failed) attempt.\n> \n> Use outside of your working tree and existing worktrees\n> (see <>); otherwise your new worktree will appear as\n> an untracked directory.\n> \n> I say \"failed\" as the above phrasing makes it sound as if that\n> untracked-ness is the only downside, and also by omitting \"advised\",\n> it makes it sound as if there is no upside (other than inertia) in\n> doing so.\n> \n> So, I'll (atleast tentatively) queue yours as-is.\n\nYes, I did not want to make this explanation too long. Spelling out all\nthe details would take multiple paragraphs but it's probably not worth\nbeing that verbose.\n\n> > If the branch exists in multiple remotes and one of them is named by\n> > the `checkout.defaultRemote` configuration variable, we'll use that\n> > one for the purposes of disambiguation, even if the `` isn't\n> > @@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n> > ...\n> > ------------\n> > \n> > -EXAMPLES\n> > ---------\n> > +[[EXAMPLES]]EXAMPLES\n> > +--------------------\n> \n> cf. https://lore.kernel.org/git/5044672.31r3eYUQgx@cayenne/\n> \n> IOW, we probably should write this more like ...\n> \n> +[[EXAMPLES]]\n> EXAMPLES\n> --------\n\nThat could use correcting in the the asciidoc documentation. The\nexamples there put the anchor on the same line.\n\nThat's probably where the repeated problem of this formatting is coming\nfrom.\n\nThe other thing is that if you used sections you would get anchors\nautomatically for free avoiding this problem altogether.\n\nThanks\n\nMichal\n"},{"id":"527948","messageId":"6043158.DvuYhMxLoT@cayenne","threadId":"64218","inReplyTo":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","subject":"Re: [PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Jean-Noël AVILA","fromEmail":"avila.jn@gmail.com","sentAt":"2025-10-05T20:52:51Z","receivedAt":"2025-10-05T21:02:31Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Thursday, 2 October 2025 17:51:34 CEST Michal Suchanek wrote:\n> Also add advice to put new worktrees outside of existing ones.\n> \n> Signed-off-by: Michal Suchanek \n> ---\n> Documentation/git-worktree.adoc | 7 +++++--\n> 1 file changed, 5 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-\nworktree.adoc\n> index 389e669ac0..ec31863aec 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> $ git worktree add --track -b /\n> ------------\n> +\n> +For best results it is advised to specify outside of the repository \nand\n> +existing worktrees - see <>\n\nPlease use the form <> in order to let the translators also \nchange the cross-link text in their language.\n\nAlso, the placeholder should be formatted as __. For your \ninformation, I'm right in the middle of pushing the conversion of git-\nworktree.adoc to the new synopsis style. \n\n> ++\n> If the branch exists in multiple remotes and one of them is named by\n> the `checkout.defaultRemote` configuration variable, we'll use that\n> one for the purposes of disambiguation, even if the `` isn't\n> @@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n> ...\n> ------------\n> \n> -EXAMPLES\n> ---------\n> +[[EXAMPLES]]EXAMPLES\n> +--------------------\n\nAs noted by others, please put the block anchors on a dedicated line, out of \nthe translation scope.\n\nThank you.\n\n\n"},{"id":"528524","messageId":"6477f32e23e732fdcc5a9585cc945db8f13d736e.1760115862.git.msuchanek@suse.de","threadId":"64218","inReplyTo":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","subject":"[PATCH v2 1/2] doc: git-worktree: Link to examples","fromName":"Michal Suchanek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-10T17:04:57Z","receivedAt":"2025-10-10T17:05:16Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"Also add advice to put new worktrees outside of existing ones.\n\nSigned-off-by: Michal Suchanek \n---\nv2: Improve formatting\n---\n Documentation/git-worktree.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 389e669ac0..a580f4c072 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n $ git worktree add --track -b /\n ------------\n +\n+For best results it is advised to specify __ outside of the repository\n+and existing worktrees - see <>\n++\n If the branch exists in multiple remotes and one of them is named by\n the `checkout.defaultRemote` configuration variable, we'll use that\n one for the purposes of disambiguation, even if the `` isn't\n@@ -502,6 +505,7 @@ locked \"reason\\nwhy is locked\"\n ...\n ------------\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n You are in the middle of a refactoring session and your boss comes in and\n-- \n2.51.0\n\n"},{"id":"528525","messageId":"0e11e6fb394ffa3a1286deea5a8ede5ba3e4bdf4.1760115862.git.msuchanek@suse.de","threadId":"64218","inReplyTo":"a203b35538847f3c9358a5ae26fb4ebea5734cfc.1759420102.git.msuchanek@suse.de","subject":"[PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchanek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-10T17:04:58Z","receivedAt":"2025-10-10T17:05:23Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"Signed-off-by: Michal Suchanek \n---\nv2: Do not make the checked out repository hidden\n---\n Documentation/git-worktree.adoc | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex a580f4c072..e7bf0ea8e0 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -526,6 +526,16 @@ $ popd\n $ git worktree remove ../temp\n ------------\n \n+Side by side branch checkouts for a repository using multiple worktrees\n+\n+------------\n+mkdir some-repository\n+cd some-repository\n+git clone --bare gitforge@someforge.example.com:some-org/some-repository some-repository.git\n+git --git-dir=some-repository.git worktree add some-branch\n+git --git-dir=some-repository.git worktree add another-branch\n+------------\n+\n BUGS\n ----\n Multiple checkout in general is still experimental, and the support\n-- \n2.51.0\n\n"},{"id":"528526","messageId":"aOk9-k7doFkQbgy8@kitsune.suse.cz","threadId":"64218","inReplyTo":"6043158.DvuYhMxLoT@cayenne","subject":"Re: [PATCH 1/2] doc: git-worktree: Link to examples","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-10T17:10:18Z","receivedAt":"2025-10-10T17:10:21Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"Hello,\n\nOn Sun, Oct 05, 2025 at 10:52:51PM +0200, Jean-Noël AVILA wrote:\n> On Thursday, 2 October 2025 17:51:34 CEST Michal Suchanek wrote:\n> > Also add advice to put new worktrees outside of existing ones.\n> > \n> > Signed-off-by: Michal Suchanek \n> > ---\n> > Documentation/git-worktree.adoc | 7 +++++--\n> > 1 file changed, 5 insertions(+), 2 deletions(-)\n> > \n> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-\n> worktree.adoc\n> > index 389e669ac0..ec31863aec 100644\n> > --- a/Documentation/git-worktree.adoc\n> > +++ b/Documentation/git-worktree.adoc\n> > @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> > $ git worktree add --track -b /\n> > ------------\n> > +\n> > +For best results it is advised to specify outside of the repository \n> and\n> > +existing worktrees - see <>\n> \n> Please use the form <> in order to let the translators also \n> change the cross-link text in their language.\n> \n> Also, the placeholder should be formatted as __. For your \n> information, I'm right in the middle of pushing the conversion of git-\n> worktree.adoc to the new synopsis style. \n\nSeems it would not conflict too badly, at least if your series is\napplied first.\n\nThanks\n\nMichal\n\n> \n> > ++\n> > If the branch exists in multiple remotes and one of them is named by\n> > the `checkout.defaultRemote` configuration variable, we'll use that\n> > one for the purposes of disambiguation, even if the `` isn't\n> > @@ -502,8 +505,8 @@ locked \"reason\\nwhy is locked\"\n> > ...\n> > ------------\n> > \n> > -EXAMPLES\n> > ---------\n> > +[[EXAMPLES]]EXAMPLES\n> > +--------------------\n> \n> As noted by others, please put the block anchors on a dedicated line, out of \n> the translation scope.\n> \n> Thank you.\n> \n> \n"},{"id":"528558","messageId":"CAPig+cQRHp7A=gtSkrVS4_EvZ9PyqBOdGGHcEajfLPE=qU4uDQ@mail.gmail.com","threadId":"64218","inReplyTo":"6477f32e23e732fdcc5a9585cc945db8f13d736e.1760115862.git.msuchanek@suse.de","subject":"Re: [PATCH v2 1/2] doc: git-worktree: Link to examples","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-10-11T04:40:03Z","receivedAt":"2025-10-11T04:40:15Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek wrote:\n> doc: git-worktree: Link to examples\n>\n> Also add advice to put new worktrees outside of existing ones.\n\nThe subject and body of the commit message are backward. The really\nimportant change made by this patch is that it is adding a new\nrecommendation; linking to the examples is just a handy byproduct of\nthat change. Hence, the subject of the patch should mention the new\nrecommendation, not the link to the examples. In fact, if you frame it\nthat way, then the commit message doesn't even need to talk about the\nlink to examples.\n\nAlso, a reviewer of v1 mentioned that the subject should use lowercase\n\"link\" rather than \"Link\".\n\n> Signed-off-by: Michal Suchanek \n> ---\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> @@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:\n> +For best results it is advised to specify __ outside of the repository\n> +and existing worktrees - see <>\n\nI'm quite negative toward this documentation change for the same\nreason[*] that I was very much against adding a warning message\n(reproduced here):\n\n Regarding issuing warnings: I'm not fond of the idea. There are\n plenty of people who already locate worktrees as subdirectories of\n the main worktree and do so without problem, and for whom it is a\n preferred workflow, so I don't see why we would want to penalize\n them by warning against doing so, especially since there is no\n technical reason to avoid the practice (i.e. Git handles it just\n fine). The only minor downside of the practice (if one considers\n it a downside) is an aesthetic one: having to update \".gitignore\"\n or \".git/info/exclude\", or to simply consider them \"visual noise\"\n in git-status output and skip over them when scanning the output.\n\nThe big problem I have with this change is that the newly-added advice\nis not backed up by concrete reasoning -- worse, it gives *no* reasons\nat all -- thus it leaves the reader hanging. As mentioned above, there\nis no technical reason to avoid creating new worktrees in the main\nworktree, which means that whatever reasons you might have for\nrecommending against the practice must be subjective, but the reader\nhas no way of guessing what those reasons might be.\n\nI *might* be a little less negative toward this documentation change\nif you presented the new recommendation accompanied by a list of pros\nand cons which, although subjective, are nevertheless somehow\nconvincing to the reader. However, aside from the very minor aesthetic\ninconvenience of seeing a linked worktree shown as untracked, I\npersonally can't come up with any list of pros and cons. Unless you or\nsomeone else can do better, I think this patch should be dropped\naltogether.\n\n[*]: https://lore.kernel.org/git/CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com/\n"},{"id":"528559","messageId":"CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com","threadId":"64218","inReplyTo":"0e11e6fb394ffa3a1286deea5a8ede5ba3e4bdf4.1760115862.git.msuchanek@suse.de","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-10-11T05:17:47Z","receivedAt":"2025-10-11T05:17:59Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek wrote:\n> doc: git-worktree: Add side by side branch checkout example\n\nThanks for taking my suggestion[*] regarding a possible git-worktree\ndocumentation update and turning it into an actual patch. This is a\nreasonable beginning, but I think it needs more work.\n\nTo begin, the idea was to document that worktrees can be used with\nbare repositories, but neither the subject of this patch nor the prose\nadded to the documentation itself mentions bare worktrees. Instead,\nthey mention only \"side by side branch checkouts\", but I'm not even\nsure what that means. I certainly wouldn't think of \"bare repository\"\nwhen given the phrase \"side by side branch checkouts\", and I'm pretty\nsure that phrase is not part of the existing Git lexicon, whereas\n\"bare repository\" is, and is well known and well understood. So, I\nthink both the commit message and the prose added to the documentation\nought to mention \"bare repository\" instead.\n\nNext, I think it is quite important that we spell out concretely in\nprose that worktrees can be used with a bare repository. It is not\nsufficient to merely infer it by giving an example, especially if the\nreader is primarily reading the git-worktree.txt introductory material\nwhich explains what worktrees are all about. So, for instance, we\ncould expand the \"The new worktree is called...\" introductory\nparagraph to instead say something like this:\n\n This new worktree is called a \"linked worktree\" as opposed to the\n \"main worktree\" prepared by git-init(1) or git-clone(1). A\n repository has one main worktree (if it’s not a bare repository)\n and zero or more linked worktrees. Linked worktrees can also be\n used with a bare repository, in which case there is no main\n worktree but *only* linked worktrees (see EXAMPLES).\n\nand also move the \"When you are done with...\" sentence from that\nparagraph down to the \"If a working tree is deleted...\" paragraph,\nwhich would become:\n\n When you are done with a linked worktree, remove it with `git\n worktree remove`. If a working tree is deleted without using `git\n worktree remove`, then its associated administrative files, which\n reside in the repository (see \"DETAILS\" below)...\n\n> Signed-off-by: Michal Suchanek \n> ---\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> @@ -526,6 +526,16 @@ $ popd\n> $ git worktree remove ../temp\n> ------------\n>\n> +Side by side branch checkouts for a repository using multiple worktrees\n> +\n> +------------\n> +mkdir some-repository\n> +cd some-repository\n> +git clone --bare gitforge@someforge.example.com:some-org/some-repository some-repository.git\n> +git --git-dir=some-repository.git worktree add some-branch\n> +git --git-dir=some-repository.git worktree add another-branch\n> +------------\n\nSeveral comments...\n\nFirst, as mentioned above, rather than using the phrasing \"side by\nside branch checkouts\", let's talk about this as being an example of\nusing worktrees with a bare repository.\n\nSecond, for consistency, let's follow the lead of the existing example\nin git-worktree.txt and show the \"$\" shell prompt preceding the\ncommands. For instance:\n\n $ mkdir ...\n $ git clone ...\n\nThird, the example seems overly complicated, especially with its use\nof `--git-dir`, which feels less discoverable (at least to me) than,\nsay `-C`. What I have in mind is an example more like this:\n\n $ git clone --bare myproj.git\n $ git -C myproj.git worktree add feature-a\n $ git -C myproj.git worktree add feature-b\n\nThat should be more than sufficient to get people up and running with\nassociating worktrees to a bare repository.\n\n[*] https://lore.kernel.org/git/CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com/\n"},{"id":"529522","messageId":"xmqqy0p1tnjj.fsf@gitster.g","threadId":"64218","inReplyTo":"CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-23T19:40:00Z","receivedAt":"2025-10-23T19:40:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek wrote:\n>> doc: git-worktree: Add side by side branch checkout example\n>\n> Thanks for taking my suggestion[*] regarding a possible git-worktree\n> documentation update and turning it into an actual patch. This is a\n> reasonable beginning, but I think it needs more work.\n>\n> To begin, the idea was to document that worktrees can be used with\n> bare repositories, but neither the subject of this patch nor the prose\n> added to the documentation itself mentions bare worktrees. Instead,\n> they mention only \"side by side branch checkouts\", but I'm not even\n> sure what that means.\n\nThis message by Eric was with many good points, including the above.\n\nShould I be expecting an update of these patches, hopefully bringing\nthem closer to the finish line? I'll tentatively mark the topic in\nmy \"What's cooking\" draft as expecting a reroll.\n\nThanks.\n\n"},{"id":"529597","messageId":"aPtRzTwVgVfqjaZT@kitsune.suse.cz","threadId":"64218","inReplyTo":"CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-10-24T10:15:41Z","receivedAt":"2025-10-24T10:15:52Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:\n> On Fri, Oct 10, 2025 at 1:05 PM Michal Suchanek wrote:\n> > doc: git-worktree: Add side by side branch checkout example\n> \n> Thanks for taking my suggestion[*] regarding a possible git-worktree\n> documentation update and turning it into an actual patch. This is a\n> reasonable beginning, but I think it needs more work.\n> \n> To begin, the idea was to document that worktrees can be used with\n> bare repositories, but neither the subject of this patch nor the prose\n> added to the documentation itself mentions bare worktrees. Instead,\n\nSo it's not documented to start with. I did not read the whole text,\nonly focused on the problem with adding worktrees in problematic places.\n\nThat sounds like more general update of the file is needed, also for\nthe prevoius patch.\n\n> they mention only \"side by side branch checkouts\", but I'm not even\n> sure what that means. I certainly wouldn't think of \"bare repository\"\n> when given the phrase \"side by side branch checkouts\", and I'm pretty\n> sure that phrase is not part of the existing Git lexicon, whereas\n> \"bare repository\" is, and is well known and well understood. So, I\n> think both the commit message and the prose added to the documentation\n> ought to mention \"bare repository\" instead.\n> \n> Next, I think it is quite important that we spell out concretely in\n> prose that worktrees can be used with a bare repository. It is not\n> sufficient to merely infer it by giving an example, especially if the\n> reader is primarily reading the git-worktree.txt introductory material\n> which explains what worktrees are all about. So, for instance, we\n> could expand the \"The new worktree is called...\" introductory\n> paragraph to instead say something like this:\n> \n> This new worktree is called a \"linked worktree\" as opposed to the\n> \"main worktree\" prepared by git-init(1) or git-clone(1). A\n> repository has one main worktree (if it’s not a bare repository)\n> and zero or more linked worktrees. Linked worktrees can also be\n> used with a bare repository, in which case there is no main\n> worktree but *only* linked worktrees (see EXAMPLES).\n> \n> and also move the \"When you are done with...\" sentence from that\n> paragraph down to the \"If a working tree is deleted...\" paragraph,\n> which would become:\n> \n> When you are done with a linked worktree, remove it with `git\n> worktree remove`. If a working tree is deleted without using `git\n> worktree remove`, then its associated administrative files, which\n> reside in the repository (see \"DETAILS\" below)...\n> \n> > Signed-off-by: Michal Suchanek \n> > ---\n> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> > @@ -526,6 +526,16 @@ $ popd\n> > $ git worktree remove ../temp\n> > ------------\n> >\n> > +Side by side branch checkouts for a repository using multiple worktrees\n> > +\n> > +------------\n> > +mkdir some-repository\n> > +cd some-repository\n> > +git clone --bare gitforge@someforge.example.com:some-org/some-repository some-repository.git\n> > +git --git-dir=some-repository.git worktree add some-branch\n> > +git --git-dir=some-repository.git worktree add another-branch\n> > +------------\n> \n> Several comments...\n> \n> First, as mentioned above, rather than using the phrasing \"side by\n> side branch checkouts\", let's talk about this as being an example of\n> using worktrees with a bare repository.\n> \n> Second, for consistency, let's follow the lead of the existing example\n> in git-worktree.txt and show the \"$\" shell prompt preceding the\n> commands. For instance:\n> \n> $ mkdir ...\n> $ git clone ...\n> \n> Third, the example seems overly complicated, especially with its use\n> of `--git-dir`, which feels less discoverable (at least to me) than,\n> say `-C`. What I have in mind is an example more like this:\n> \n> $ git clone --bare myproj.git\n> $ git -C myproj.git worktree add feature-a\n> $ git -C myproj.git worktree add feature-b\n> \n> That should be more than sufficient to get people up and running with\n> associating worktrees to a bare repository.\n\nThat creates a mess. First part is not creating the directory to contain\nthe worktrees related to the repository. Second is creating the\nworktrees inside the bare repository, contrary to any reasonabe usage\nadvice.\n\nThanks\n\nMichal\n\n> \n> [*] https://lore.kernel.org/git/CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com/\n"},{"id":"529617","messageId":"CAPig+cQoL_=WdNpcO_9mTLDRRDHCOC1-nYMwUyfaev3BZyzaow@mail.gmail.com","threadId":"64218","inReplyTo":"aPtRzTwVgVfqjaZT@kitsune.suse.cz","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-10-24T16:57:42Z","receivedAt":"2025-10-24T16:57:54Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Oct 24, 2025 at 6:15 AM Michal Suchánek wrote:\n> On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:\n> > Third, the example seems overly complicated, especially with its use\n> > of `--git-dir`, which feels less discoverable (at least to me) than,\n> > say `-C`. What I have in mind is an example more like this:\n> >\n> > $ git clone --bare myproj.git\n> > $ git -C myproj.git worktree add feature-a\n> > $ git -C myproj.git worktree add feature-b\n> >\n> > That should be more than sufficient to get people up and running with\n> > associating worktrees to a bare repository.\n>\n> That creates a mess. First part is not creating the directory to contain\n> the worktrees related to the repository. Second is creating the\n> worktrees inside the bare repository, contrary to any reasonabe usage\n> advice.\n\nSorry, I mistyped that. What I meant was:\n\n $ git -C myproj.git worktree add ../feature-a\n\nwhich makes the worktrees siblings of the bare repository.\n\nAs for first creating a directory to contain the repository and the\nworktrees, I purposely omitted that step in the example since I\nassume/hope that we don't need to hand-hold the user to that extent.\n"},{"id":"530860","messageId":"8cc4ca72-c87a-acc1-e200-53be14d649f8@gmx.de","threadId":"64218","inReplyTo":"CAPig+cQgZijWi8VV1_QScKPhm9cqhQVvow4N-VH00R4oO1m2xA@mail.gmail.com","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2025-11-17T22:36:06Z","receivedAt":"2025-11-17T22:36:12Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Eric,\n\nOn Wed, 1 Oct 2025, Eric Sunshine wrote:\n\n> [...] There are plenty of people who already locate worktrees as\n> subdirectories of the main worktree[*] and do so without problem, and\n> for whom it is a preferred workflow, so I don't see why we would want to\n> penalize them by warning against doing so, especially since there is no\n> technical reason to avoid the practice (i.e. Git handles it just fine).\n> [...]\n>\n> FOOTNOTES\n> \n> [*]: There have been numerous emails on the list showing that placing\n> worktrees as subdirectories of the main worktree is common enough\n> practice. And, as far as \"experienced users\" are concerned (not just\n> novices picking up the practice from blogs or tutorials), I recall an\n> email discussion in which Dscho has said that he locates worktrees as\n> subdirectories of the main worktree, as well. I, too, have done so on\n> occasion.\n\nAnd indeed I do, and continue to do so because the counter arguments in\nthat email discussion looked quite weak to me.\n\nIn the one instance where I heeded that well-meant advice to create\nworktrees outside of my main worktree, I lost work when I had cleaned up\nthat main worktree after verifying with `git status` that there was no\nunfinished business to take care of before deleting the repository.\nBecause that secondary worktree (which did contain unfinished business,\nincluding a carefully crafted series of commits) was now obviously no\nlonger a worktree but only a tree without a working `.git`.\n\nCiao,\nJohannes\n"},{"id":"530862","messageId":"xmqqikf8gtcq.fsf@gitster.g","threadId":"64218","inReplyTo":"8cc4ca72-c87a-acc1-e200-53be14d649f8@gmx.de","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-17T22:57:41Z","receivedAt":"2025-11-17T22:57:43Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin writes:\n\n> that main worktree after verifying with `git status` that there was no\n> unfinished business to take care of before deleting the repository.\n> Because that secondary worktree (which did contain unfinished business,\n> including a carefully crafted series of commits) was now obviously no\n> longer a worktree but only a tree without a working `.git`.\n\nOuch, that is a tough one. It is very hard to interfere and stop\nyour \"rm -fr\" based on what Git could find (in other words, your\n\"rm\" lacks the \"pre-something\" hook).\n\nOf course, an argument can be made that you should have also asked\n`git worktree list` if there are other worktrees, in addition to\nasking `git status`, but I wonder if it would have helped to have\nthe information in the `git status` output so that we can always\ntrust that it is sufficient to ask a single command without doing\nanything else? As \"separate worktrees\" is a feature to allow users\nto more or less independently work in each separate worktree,\nwithout having to worry about what they are doing in the other\nworktrees, cramming too much into `git status` would degrade the\nend-user experience and it takes a fine balance.\n\nI think that one of the reasons why the \"outside the working tree\"\nlayout is recommended is to prevent us from \"git add .\" (or other\noverly wide pathspec) to accidentally add these embedded worktrees\nto the main project, but such a mistake is at least not as\ndestructive as \"rm -fr\".\n\n\n"},{"id":"530901","messageId":"aRxgC7TAopqsrZen@kitsune.suse.cz","threadId":"64218","inReplyTo":"CAPig+cQoL_=WdNpcO_9mTLDRRDHCOC1-nYMwUyfaev3BZyzaow@mail.gmail.com","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-11-18T12:01:15Z","receivedAt":"2025-11-18T12:01:23Z","isPatch":true,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:\n> On Fri, Oct 24, 2025 at 6:15 AM Michal Suchánek wrote:\n> > On Sat, Oct 11, 2025 at 01:17:47AM -0400, Eric Sunshine wrote:\n> > > Third, the example seems overly complicated, especially with its use\n> > > of `--git-dir`, which feels less discoverable (at least to me) than,\n> > > say `-C`. What I have in mind is an example more like this:\n> > >\n> > > $ git clone --bare myproj.git\n> > > $ git -C myproj.git worktree add feature-a\n> > > $ git -C myproj.git worktree add feature-b\n> > >\n> > > That should be more than sufficient to get people up and running with\n> > > associating worktrees to a bare repository.\n> >\n> > That creates a mess. First part is not creating the directory to contain\n> > the worktrees related to the repository. Second is creating the\n> > worktrees inside the bare repository, contrary to any reasonabe usage\n> > advice.\n> \n> Sorry, I mistyped that. What I meant was:\n> \n> $ git -C myproj.git worktree add ../feature-a\n> \n> which makes the worktrees siblings of the bare repository.\n\nand requires the mental gymnastics of adjusting the paths passed to the\ncommand based on -C argument. Does not sound like a good example how to\nuse the command.\n\n> As for first creating a directory to contain the repository and the\n> worktrees, I purposely omitted that step in the example since I\n> assume/hope that we don't need to hand-hold the user to that extent.\n\nIts much easier to reove superluous parts from the example than adding\npatrs that were omitted.\n\nThanks\n\nMichal\n"},{"id":"530947","messageId":"CAPig+cTZ4WpO--jCFPZOK6POFzrux8m7Rhw-p1FkJR+NOD3J=A@mail.gmail.com","threadId":"64218","inReplyTo":"aRxgC7TAopqsrZen@kitsune.suse.cz","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-11-19T07:19:13Z","receivedAt":"2025-11-19T07:19:25Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Nov 18, 2025 at 7:01 AM Michal Suchánek wrote:\n> On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:\n> > Sorry, I mistyped that. What I meant was:\n> >\n> > $ git -C myproj.git worktree add ../feature-a\n> >\n> > which makes the worktrees siblings of the bare repository.\n>\n> and requires the mental gymnastics of adjusting the paths passed to the\n> command based on -C argument. Does not sound like a good example how to\n> use the command.\n\nFair enough. I happen to find the above easy to reason about, but I\nget your point, as well.\n\nSo the remaining actionable bit from the review[*] regards spelling\nout in prose that hanging worktrees off of a bare repository is an\nexplicitly supported mode of operation.\n\n[*]: https://lore.kernel.org/git/CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com/\n"},{"id":"530983","messageId":"aR18QQ03-Wg26oNJ@kitsune.suse.cz","threadId":"64218","inReplyTo":"xmqqzfac3pts.fsf@gitster.g","subject":"Re: What is the reason behind not hiding git worktrees from git?","fromName":"Michal Suchánek","fromEmail":"msuchanek@suse.de","sentAt":"2025-11-19T08:13:53Z","receivedAt":"2025-11-19T08:14:01Z","isPatch":false,"sender":{"key":"msuchanek@suse.de","avatar":"https://avatars.githubusercontent.com/u/787652?v=4"},"body":"On Tue, Sep 30, 2025 at 08:47:11AM -0700, Junio C Hamano wrote:\n> Michal Suchánek writes:\n> \n> > On Sat, Sep 27, 2025 at 09:26:54PM +0000, Jason Cho wrote:\n> >> I think the best practice is to not add a work tre within the master work tree.\n> >\n> > And is that best practice documented somewhere?\n> \n> I do not think it is documented anywhere.\n> \n> In fact, I do not think the inventors of the worktree feature ever\n> expected this end-user expectation that checking out multiple\n> worktrees of the repository *INSIDE* a repository's checkout would\n> be any useful without confusing users.\n> \n> IOW, omission of the documentation is by an assumptionk that nobody\n> would imagine doing in any other way. \n> \n> We can and should fix it retroactively, if the lack of documentation\n> is not guiding our users in the right direction. Any takers?\n> \n> > IIRC there are some VCSs for which it is common practice to keep\n> > checkouts of multiple branches side by side in the repository directory.\n> \n> I can understand \"side-by-side\" but not \"in\". Next to the primary\n> workree (aka \"initial clone\") would be more common.\n> \n> > IIRC the repository directory itself is not a checkout in this case.\n> > Anyway, there is no obvious reason for anyone not familiar with git\n> > internals to not do this.\n> \n> Meaning anybody not familiar with the tool would do any random thing\n> outside of the usage pattern that the users of the tool have been\n> establishing over the years? I can certainly understand that. But\n> then, creating a set of worktrees, one per branch, next to the\n> primary worktree that checks out the 'main' branch, would also equally\n> be a likely layout, I would imagine.\n\nAnd that's what the existing example shows.\n\nThanks\n\nMichal\n"},{"id":"534287","messageId":"xmqq7btcyq7f.fsf@gitster.g","threadId":"64218","inReplyTo":"CAPig+cTZ4WpO--jCFPZOK6POFzrux8m7Rhw-p1FkJR+NOD3J=A@mail.gmail.com","subject":"Re: [PATCH v2 2/2] doc: git-worktree: Add side by side branch checkout example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-20T20:38:44Z","receivedAt":"2026-01-20T20:38:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> On Tue, Nov 18, 2025 at 7:01 AM Michal Suchánek wrote:\n>> On Fri, Oct 24, 2025 at 12:57:42PM -0400, Eric Sunshine wrote:\n>> > Sorry, I mistyped that. What I meant was:\n>> >\n>> > $ git -C myproj.git worktree add ../feature-a\n>> >\n>> > which makes the worktrees siblings of the bare repository.\n>>\n>> and requires the mental gymnastics of adjusting the paths passed to the\n>> command based on -C argument. Does not sound like a good example how to\n>> use the command.\n>\n> Fair enough. I happen to find the above easy to reason about, but I\n> get your point, as well.\n>\n> So the remaining actionable bit from the review[*] regards spelling\n> out in prose that hanging worktrees off of a bare repository is an\n> explicitly supported mode of operation.\n>\n> [*]: https://lore.kernel.org/git/CAPig+cSNesf0UwS4=Bxe-Qn+G9y3YYPyOK+7y3q8QJk+o7jaVg@mail.gmail.com/\n\nThe discussion stalled after the above message, and the topic has\nbeen dormant for full two months. I'd drop the topic from 'seen'\nsoonish but that does not mean an improved version of this patch is\nunwelcome.\n\nThanks.\n"}]}