From: Andy Koppe <andy.koppe@gmail.com>
Date: Sun, 01 Nov 2026 23:44:53 GMT
Subject: Re: [PATCH 3/5] doc: stop calling root refs pseudorefs
Message-ID: <CAHWeT-aa=6WByd4U9BB-6mMMUAxPQCC5GhyM1WMSSVVatvN0Tw@mail.gmail.com>
In-Reply-To: <atsPwpbD3YqmBds_@pks.im>

On Fri, 23 Oct 2026 at 08:42, Patrick Steinhardt <ps@pks.im> wrote:
> On Thu, Oct 22, 2026 at 10:28:51PM +0100, Andy Koppe wrote:
> > diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc
> > index 37a5019a8b..c775334230 100644
> > --- a/Documentation/git-update-ref.adoc
> > +++ b/Documentation/git-update-ref.adoc
> > @@ -163,13 +163,12 @@ still see a subset of the modifications.
> >
> >  LOGGING UPDATES
> >  ---------------
> > -If config parameter "core.logAllRefUpdates" is true and the ref is one
> > -under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
> > -like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
> > -`git update-ref` will append a line to the log file
> > -"$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
> > -the log name) describing the change in ref value.  Log lines are
> > -formatted as:
> > +If config parameter "core.logAllRefUpdates" is true and the ref is
> > +HEAD or one under "refs/heads/", "refs/remotes/" or "refs/notes/", or
> > +if the file "$GIT_DIR/logs/<ref>" exists, then `git update-ref` will
>
> It's kind of hard to understand how the ANDs and ORs play together.
> Like, does the config parameter extend to all subsequent ORs? That's not
> really a new issue though.
>
> > +append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all
>
> Also, this infomation about "$GIT_DIR/logs/<ref>" is out-of-date, as the
> reftable backend doesn't store its reflogs in there.
>
> I wonder whether we should maybe just stop explaining how
> "core.logAllRefUpdates" works and instead refer to git-config(1).

The whole LOGGING UPDATES section in git-update-ref(1) seems outdated
as it assumes ref files and SHA-256, but I think that's out of scope
of this patch series.

> > diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> > index e6e77252ab..f0eb6d4137 100644
> > --- a/Documentation/git-worktree.adoc
> > +++ b/Documentation/git-worktree.adoc
> > @@ -303,11 +303,10 @@ but others are specific to an individual worktree. One example is `HEAD`,
> >  which is different for each worktree. This section is about the sharing
> >  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`, `refs/worktree` and `refs/rewritten` are
> > -not shared.
> > +In general, all root refs and pseudorefs are per-worktree and all refs
> > +starting with `refs/` are shared. There are exceptions, however: refs
> > +inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are not
> > +shared.
>
> It might make sense to have a bulleted list here, same as I proposed in
> a preceding patch.

Yep. Done in v2.

Andy