{"thread":{"id":"60337","subject":"[PATCH] doc/git-worktree: mention \"refs/rewritten\" as per-worktree refs","startedAt":"2023-10-10T11:01:42Z","lastAt":"2023-10-10T17:49:36Z","messageCount":2,"participants":["Patrick Steinhardt","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"482957","messageId":"985ac850eb6e60ae76601acc8bfbcd56f99348b4.1696935657.git.ps@pks.im","threadId":"60337","inReplyTo":null,"subject":"[PATCH] doc/git-worktree: mention \"refs/rewritten\" as per-worktree refs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-10-10T11:01:26Z","receivedAt":"2023-10-10T11:01:42Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Some references are special in the context of worktrees as they are\nconsidered to be per-worktree instead of shared across all of the\nworktrees. Most importantly, this includes \"refs/worktree/\" that have\nexplicitly been designed such that users can create per-woorktree refs.\nBut there are also special references that have an associated meaning\nlike \"refs/bisect/\", which is used to track state of git-bisect(1).\n\nThese special per-worktree references are documented in git-worktree(1),\nbut one instance is missing. In a9be29c9817 (sequencer: make refs\ngenerated by the `label` command worktree-local, 2018-04-25), we have\nconverted \"refs/rewritten/\" to be a per-worktree reference as well.\nThese references are used by our sequencer infrastructure to generate\nlabels for rebased commits. So in order to allow for multiple concurrent\nrebases to happen in different worktrees, these references need to be\ntracked per worktree.\n\nWe forgot to update our documentation to mention these new per-worktree\nreferences, which is fixed by this patch.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/git-worktree.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex a4fbf5e838..93d76f5d66 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -286,7 +286,8 @@ rules and how to access refs of one worktree from another.\n In general, all pseudo refs are per-worktree and all refs starting with\n `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly\n under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,\n-however: refs inside `refs/bisect` and `refs/worktree` are not shared.\n+however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are\n+not shared.\n \n Refs that are per-worktree can still be accessed from another worktree via\n two special paths, `main-worktree` and `worktrees`. The former gives\n@@ -363,8 +364,8 @@ linked worktree `git rev-parse --git-path HEAD` returns\n `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git\n rev-parse --git-path refs/heads/master` uses\n `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`,\n-since refs are shared across all worktrees, except `refs/bisect` and\n-`refs/worktree`.\n+since refs are shared across all worktrees, except `refs/bisect`,\n+`refs/worktree` and `refs/rewritten`.\n \n See linkgit:gitrepository-layout[5] for more information. The rule of\n thumb is do not make any assumption about whether a path belongs to\n-- \n2.42.0\n\n"},{"id":"482995","messageId":"CAPig+cTK4=w0+DnS025WbBDmV_wX-v3UkpcmEPhgSq6+-iaqJg@mail.gmail.com","threadId":"60337","inReplyTo":"985ac850eb6e60ae76601acc8bfbcd56f99348b4.1696935657.git.ps@pks.im","subject":"Re: [PATCH] doc/git-worktree: mention \"refs/rewritten\" as per-worktree refs","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-10-10T17:49:20Z","receivedAt":"2023-10-10T17:49:36Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Oct 10, 2023 at 7:01 AM Patrick Steinhardt <ps@pks.im> wrote:\n> Some references are special in the context of worktrees as they are\n> considered to be per-worktree instead of shared across all of the\n> worktrees. Most importantly, this includes \"refs/worktree/\" that have\n> explicitly been designed such that users can create per-woorktree refs.\n\ns/woorktree/worktree/\n\n> But there are also special references that have an associated meaning\n> like \"refs/bisect/\", which is used to track state of git-bisect(1).\n>\n> These special per-worktree references are documented in git-worktree(1),\n> but one instance is missing. In a9be29c9817 (sequencer: make refs\n> generated by the `label` command worktree-local, 2018-04-25), we have\n> converted \"refs/rewritten/\" to be a per-worktree reference as well.\n> These references are used by our sequencer infrastructure to generate\n> labels for rebased commits. So in order to allow for multiple concurrent\n> rebases to happen in different worktrees, these references need to be\n> tracked per worktree.\n>\n> We forgot to update our documentation to mention these new per-worktree\n> references, which is fixed by this patch.\n>\n> Signed-off-by: Patrick Steinhardt <ps@pks.im>\n> ---\n> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\n> @@ -286,7 +286,8 @@ rules and how to access refs of one worktree from another.\n>  In general, all pseudo refs are per-worktree and all refs starting with\n>  `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly\n>  under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,\n> -however: refs inside `refs/bisect` and `refs/worktree` are not shared.\n> +however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are\n> +not shared.\n\nTo simplify future maintenance, eventually we might want to turn this\ninto a bulleted list, but that doesn't necessarily have to be done by\nthis patch, which is fine as-is.\n\n> @@ -363,8 +364,8 @@ linked worktree `git rev-parse --git-path HEAD` returns\n>  `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`,\n> -since refs are shared across all worktrees, except `refs/bisect` and\n> -`refs/worktree`.\n> +since refs are shared across all worktrees, except `refs/bisect`,\n> +`refs/worktree` and `refs/rewritten`.\n\nDitto.\n"}]}