Re: [PATCH] branch: clarify <oldbranch> term

[Junio C Hamano <gitster@pobox.com>]

Rubén Justo <rjusto@gmail.com> writes:

> Since 52d59cc645 (branch: add a --copy (-c) option to go with --move
> (-m), 2017-06-18) <oldbranch> is used in more operations than just -m.
>
> Let's also clarify what we do if <oldbranch> is omitted.
>
> Signed-off-by: Rubén Justo <rjusto@gmail.com>
> ---
>  Documentation/git-branch.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 4395aa9354..233264549c 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -312,7 +312,8 @@ superproject's "origin/main", but tracks the submodule's "origin/main".
>  	option is omitted, the current HEAD will be used instead.
>  
>  <oldbranch>::
> -	The name of an existing branch to rename.
> +	The name of an existing branch.  If this option is omitted,
> +	the name of the current branch will be used instead.

Thanks.

Will queue this patch as is for now, but I suspect that in the
longer term it will help readers a lot to revamp the whole page.
The description for the "branch rename" operation, for example, is
split and partly repreated in three places, i.e. 

 * a paragraph in the DESCRIPTION that talks about <oldbranch>,
   where readers will be helped by the same clarification as this
   patch gives;

 * -m/-M option description which is very sketchy and does not even
    hint that they take <oldbranch> and <newbranch>; and

 * <oldbranch> description as a separate bullet item in the same
   list, which does not even hint that this is used by -m/-M.

which is unmanageable from writers' point of view, and hard to
follow from readers' point of view.

Such a rewrite may look like this:

 * Trim down the DESCRIPTION explanation to enumerate "features"
   offered, with pointers into the OPTIONS section using the option
   names as hints, e.g.,

     The command offers many features that work on branches,
     depending on the options.

     - The default mode of operation is to list (the --list option
       explicitly calls for it, or the lack of other options to
       trigger different mode).

     - ...

     - An existing branch can be renamed to a different name with
       "-m/-M" options.

     - ...

 * Enhance the description in the OPTIONS section so that each
   bullet item (e.g., "-m") gives everything the user wants to know
   about that option, e.g.,

       -m [<oldbranch>] <newbranch>::
       -M [<oldbranch>] <newbranch>::
            Rename <oldbranch> (defaults to the current branch) to
            <newbranch>.  If <newbranch> already exists, `-m` will error
            out and renaming must be forced by using `-M` (in other
            words, `-M` works as a short-hand for `-m --force`).
       +
       The contents reflog of the <oldbranch> will also be renamed to become
       the reflog of the <newbranch>, and a reflog entry is added for
       the renaming of the branch.

 * Remove the non-option entries from the OPTIONS bullet list.