Re: [PATCH 4/6] doc: update-ref: remove confusing paragraph

From: Taylor Blau <me@ttaylorr.com>
Date: Oct 16, 2024, 20:51 UTC
Message-ID: <ZxAnO5zH1vtgRvLk@nand.local>
In-Reply-To: <dec48e2d37cc4edafb51476284ce3fece4718ce7.1729017728.git.code@khaugsbakk.name>

On Tue, Oct 15, 2024 at 09:03:13PM +0200, kristofferhaugsbakk@fastmail.com wrote:

Show 10 quoted lines

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> This paragraph interrupts the flow of this section by going into detail
> about what a symbolic ref file is and how it is implemented.  It is not
> clear what the purpose is since symbolic refs were already mentioned
> prior (“possibly dereferencing the symbolic refs”).  Worse, it can
> confuse the reader about what argument can be a symbolic ref since it
> just says “it” and not which of the parameters; in turn the reader can
> be lead to try `<new-oid>` and then get a confusing error since
> update-ref will just say that it is not a valid SHA1.

I think that it is worth saying that this concept is explained well throughout other parts of the documentation, including other parts of 'git-update-ref(1)', as well as the glossary content.

I don't think that you necessarily need to mention that here. But at least I was initially confused thinking that this patch proposed removing the only mention of the special "ref:" syntax for symbolic references.

But it does not, so I think that this patch as you wrote it is good. Let's keep reading...

Thanks, Taylor