Re: [PATCH] doc/git-worktree: mention "refs/rewritten" as per-worktree refs

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 10, 2023, 17:49 UTC
Message-ID: <CAPig+cTK4=w0+DnS025WbBDmV_wX-v3UkpcmEPhgSq6+-iaqJg@mail.gmail.com>
In-Reply-To: <985ac850eb6e60ae76601acc8bfbcd56f99348b4.1696935657.git.ps@pks.im>

On Tue, Oct 10, 2023 at 7:01 AM Patrick Steinhardt <ps@pks.im> wrote:

> Some references are special in the context of worktrees as they are
> considered to be per-worktree instead of shared across all of the
> worktrees. Most importantly, this includes "refs/worktree/" that have
> explicitly been designed such that users can create per-woorktree refs.

s/woorktree/worktree/

Show 25 quoted lines

> But there are also special references that have an associated meaning
> like "refs/bisect/", which is used to track state of git-bisect(1).
>
> These special per-worktree references are documented in git-worktree(1),
> but one instance is missing. In a9be29c9817 (sequencer: make refs
> generated by the `label` command worktree-local, 2018-04-25), we have
> converted "refs/rewritten/" to be a per-worktree reference as well.
> These references are used by our sequencer infrastructure to generate
> labels for rebased commits. So in order to allow for multiple concurrent
> rebases to happen in different worktrees, these references need to be
> tracked per worktree.
>
> We forgot to update our documentation to mention these new per-worktree
> references, which is fixed by this patch.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> @@ -286,7 +286,8 @@ rules and how to access refs of one worktree from another.
>  In general, all pseudo refs are per-worktree and all refs starting with
>  `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly
>  under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,
> -however: refs inside `refs/bisect` and `refs/worktree` are not shared.
> +however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are
> +not shared.

To simplify future maintenance, eventually we might want to turn this into a bulleted list, but that doesn't necessarily have to be done by this patch, which is fine as-is.

Show 6 quoted lines

> @@ -363,8 +364,8 @@ linked worktree `git rev-parse --git-path HEAD` returns
>  `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`,
> -since refs are shared across all worktrees, except `refs/bisect` and
> -`refs/worktree`.
> +since refs are shared across all worktrees, except `refs/bisect`,
> +`refs/worktree` and `refs/rewritten`.

Ditto.