Re: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Oct 20, 2024, 12:30 UTC
Message-ID: <bcb0e2d8-ebee-4835-aa43-05107199ee62@app.fastmail.com>
In-Reply-To: <CAOLa=ZRAGmgfSHjAx6-1q9qV-aJ_Ciw=RZ6kpygqbSO+yAUEeg@mail.gmail.com>

On Sun, Oct 20, 2024, at 13:13, karthik nayak wrote:

Show 16 quoted lines

>> […]
>> These paragraphs don’t interrupt the flow of the document on that
>> revision since it is at the end.  Now though it is placed after the
>> description of `--no-deref` and before `-d` and `--stdin`.  Covering all
>> the options is more generally interesting than a safety note about a
>> naïve `HEAD` management.
>>
>> Such a safety warning is also much less relevant now, considering that
>> everyone who isn’t intentionally poking at the internal implementation
>> is using porcelain commands to manage `HEAD`.
>> […]
>
> In the new reftable backend, HEAD would simply exist as a placeholder.
> So either we do as you did and remove this entirely or double down to
> say that writing to HEAD directly is not supported. I don't have a
> preference here, so this looks good!

Great, thanks. :)

Here’s an attempted rewrite of the final paragraph for the possible next round:

  “ [Besides,] Writing to `HEAD` with `echo` is not allowed under the
    reftable implementation, so this part has become misleading.

But now it doesn’t make sense to write multiple paragraphs and then end with the most important part.

Maybe

  “ Remove paragraphs which explain that using this command is safer than
    echoing the branch name into `HEAD`.

    Evoking the echo strategy is wrong now under the reftable backend since
    such a file does not exist.  And these days people use porcelain
    commands to manage `HEAD` unless they are intentionally poking at what
    the ref files backend looks like.

    Maybe this warning was relevant for the usage patterns when it was
    added[1] but now it just takes up space.

    † 1: 129056370ab (Add missing documentation., 2005-10-04)