Re: [PATCH] branch: clarify <oldbranch> and <newbranch> terms further

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 6, 2024, 00:09 UTC
Message-ID: <xmqqttmmlahf.fsf@gitster.g>
In-Reply-To: <CAO_smViHVZRObZjg0tEPXezJZb7wvs9LQdHUFJQTK4-ASCfrmw@mail.gmail.com>

Kyle Lippincott <spectral@google.com> writes:

Show 7 quoted lines

> I'm not super pleased with that second sentence, and maybe we
> shouldn't include it here. Maybe it belongs on the documentation for
> --move and --copy instead? It's sort of mentioned in the text at the
> top describing the -m/-M and -c/-C options, though it's not clear from
> that text what actually happens to the existing copy of <newbranch> if
> one uses --force. If we could include a better description of what
> happens to the existing branch when one uses --force, that'd be nice.

My preference is to limit the "OPTIONS" section to dashed options. If "--move" takes one or two arguments, update its description to talk about how these one or two arguments are used, perhaps like

	-m [<oldbranch>] <newbranch>::
	--move [<oldbranch>] <newbranch>::

		Rename an existing branch <oldbranch>, which
                defaults to the current branch, to <newbranch>.  The
                configuration variables about and the reflog of
                <oldbranch> are also renamed appropriately to be
                used with <newbranch>. It is an error if <newbranch>
                exists (you can use `--force` to clobber an existing
                <newbranch>).

or something like that.

Listing non-options in the list may have been a misguided attempt to "save" description on arguments that are common to multiple options, but it is not working. We can see the bad effect of that approach only by looking at the current description of the above option, which reads:

	-m::
	--move::
		Move/rename a branch, together with its config and reflog.

It does not mentioning what arguments "--move" takes, and does not even refer the readers to the entries for <newbranch> and <oldbranch>, so the only plausible way the users can learn what they want about this single option is by reading the page from top to bottom.

And trim the DESCRIPTION part. A lot. Because things are explained redundantly between there and the OPTIONS part, and their details are waiting to drift apart unless we are careful.

I think I laid all this out and more in a separate message.

https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/