Re: [PATCH v2 6/7] Documentation: put blame/log -L in sticked form

From: Thomas Rast <tr@thomasrast.ch>
Date: Oct 30, 2013, 18:59 UTC
Message-ID: <874n7ywpnd.fsf@thomasrast.ch>
In-Reply-To: <xmqqiowed6t3.fsf@gitster.dls.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 24 quoted lines

> Thomas Rast <tr@thomasrast.ch> writes:
>
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> I agree that this patch may reduce confusion locally, but if we were
>>> to go in this direction, we should be consistent and enforce "stuck"
>>> form everywhere,
>>
>> Hmm.  Do you want to go there?
>
> Absolutely not ;-)
>
> But that unpleasant place would be the logical conclusion where this
> patch leads us to, I would have to say. I was hoping that there is
> an alternative solution to avoid that.
>
> For example, gitk's parseviewargs is very well aware of the options
> it supports, and it goes through the argument list one by one,
> acting on what option it is looking at. Couldn't it be extended to
> handle options with stuck and unstuck form?  After all, it has to
> know that "-L" and "-S" are supported options; it wouldn't be too
> much to ask for the parser to also know that "-L" eats the next
> token (i.e. pass the pair <"-L", next token> intact as two separate
> args to the underlying "log") while it can pass "-L?*" as is, no?

It's not quite that easy because gitk does two-stage processing, and the big switch you are discussing here is only the second one. The first one is git-rev-parse, and while it happens to know about '-n 1', it does not recognize any other unstuck option arguments. (I haven't stared too long, but I think git-rev-parse is important to distinguish revisions from paths.)

I actually burned some train time today looking into this, and the situation is much worse than I thought. There is absolutely no consistency in any dimension:

a) many commands use parse_options internally, where mandatory args can
   be stuck or unstuck, but optional args must be stuck

   a1) git branch --{contains,merged,no-merged} take a mandatory arg,
       except if they are last on the command line, in which case the
       option reverts to the default (HEAD).  Effectively this means the
       argument is half-optional but the spelling seen in the wild is
       usually unstuck.

   a2) git-rev-parse (at least) still handrolls its parsing, so no
       --default=HEAD

   a3) git-commit-tree does not understand any of its short options in
       stuck form (!)

b) the perl scripts mostly seem to be using Getopt::Long which handles
   things similarly, though I can't quote chapter&verse

   b1) just to prove a point: git-add--interactive.  I'm sure there's a
       user-facing exception somewhere too...

c) shell scripts mostly go through git-sh-setup, using parseopt
   internally

   c1) git-filter-branch

d) gitk doesn't do *un*stuck as explained above

On top of that, documentation is a wild mash of styles, sometimes even in the same manpage. For example, git-describe(1) tells the poor user about --candidates=<n> and four paragraphs further down about --match <pattern>.

So my short-term plan just became: document instead of fix; clean up manpages towards the stuck form for long options; have gitk only parse -Lstuck.

Medium term we can move gitk to a different option parser, resolving at least that inconsistency.

Longer term we can see about moving some more of the remaining craziness towards parseopt, getting consistency for free.

-- 
Thomas Rast
tr@thomasrast.ch