From: Patrick Steinhardt <ps@pks.im>
Date: Fri, 23 Oct 2026 07:41:54 GMT
Subject: Re: [PATCH 3/5] doc: stop calling root refs pseudorefs
Message-ID: <atsPwpbD3YqmBds_@pks.im>
In-Reply-To: <20261022212903.177261-4-andy.koppe@gmail.com>

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).

> 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.

Patrick