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

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

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.