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

quoted

[…]
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)