Re: [PATCH] branch: fix usage string for specific git-branch options

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

Ralf Thielow <ralf.thielow@gmail.com> writes:

> The usage string of git-branch shows generic options and specific
> options. However, the specific options are called "actions".
> Call them both options.

I think this is a valid problem to address, but I do not know if the
proposed solution is the right one.

Originally, the word "action" there really meant to mean "action".
"git branch" can "list" existing ones, "create" new ones, "delete"
existing ones, "edit" upstream info or description for, etc.  These
are distinct actions.

For a single "action", there are various ways to perform it.
Different ways to affect "list", for example, are like "choosing
which ones are listed", "deciding if the output is colored", etc..
The "options" section was meant to cover these modifiers.

I think the real issues may be coming from one or both of the two:

 (1) some are grossly miscategorized.  "--all" is not an action.  It
     just affects how "listing" works.  "--no-merged" and "--merged"
     are the same way and should sit next to "--contains".

     "--set-upstream" and "--unset-upstream" on the other hand are
     not modifiers for some other actions, but are their own actions.

 (2) "Generic options" would need to show things like "-v/-q/-f"
     that would want to consistently apply to any action that you
     might want to invoke.  Because not all modifiers apply to all
     actions, there is no good place to put things like "-t" (that
     has no meaning when you are invoking "delete" action) that are
     specific to only a subset of available actions, i.e. "Not
     generic" ones.

So the real way forward would be probably to do three things.

 * Keep the same two categorization as we have, i.e. "generic
   options" and "specific actions";

 * Move the miscategorized non-actions to "generic options" section;

 * Move action-specific modifiers out of "generic options" and
   clearly state what action they work with to modify the behaviour
   of the action.