From: Thomas Rast Date: Wed, 30 Oct 2013 18:59:50 GMT Subject: Re: [PATCH v2 6/7] Documentation: put blame/log -L in sticked form Message-ID: <874n7ywpnd.fsf@thomasrast.ch> In-Reply-To: Junio C Hamano writes: > Thomas Rast writes: > >> Junio C Hamano 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= and four paragraphs further down about --match . 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