From: Taylor Blau <me@ttaylorr.com>
Date: Wed, 16 Oct 2024 20:51:07 GMT
Subject: Re: [PATCH 4/6] doc: update-ref: remove confusing paragraph
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:
> 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