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

From: Junio C Hamano <gitster@pobox.com>
To: Kyle Lippincott <spectral@google.com>
Cc: Dragan Simic <dsimic@manjaro.org>,  git@vger.kernel.org
Subject: Re: [PATCH] branch: clarify <oldbranch> and <newbranch> terms further
Date: Mon, 05 Feb 2024 16:09:16 -0800	[thread overview]
Message-ID: <xmqqttmmlahf.fsf@gitster.g> (raw)
In-Reply-To: <CAO_smViHVZRObZjg0tEPXezJZb7wvs9LQdHUFJQTK4-ASCfrmw@mail.gmail.com> (Kyle Lippincott's message of "Mon, 5 Feb 2024 15:53:31 -0800")

Kyle Lippincott <spectral@google.com> writes:

> 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/