Unify subcommand structure; introduce double dashes for all subcommands?

Unify subcommand structure; introduce double dashes for all subcommands?

[Stefan Beller]

In the user survey 2012 question 23 ("In your opinion, which areas in
Git need improvement?"),
the most crucial point identified was the user interface.
I wonder if there are any more recent surveys, showing if this has changed.
Now when we want to improve the user interface, we're likely talking
about the porcelain
commands only, as that's what most users perceive as the commandline
user interface.

A git command is generally setup as:
	git <command> [<subcommand>] [<options>] ...

The subcommands vary wildly by the nature of the command. However all
subcommands
could at least follow one style. The commands bundle, notes, stash and
submodule
have subcommands without two leading dashes (i.e. git stash list) as
opposed to all
other commands (i.e. git tag --list).

So my proposal is to unify the structure of the subcommands to either
have always
leading dashes or never. This would need a longterm thinking of course
(e.g. introduce new options with(out) dashes, but support existing
commands until git 3.0
or such, then drop them.)

Was there a discussion about this topic already?
I'd like to read on these discussions, if any.

I could think about the following points being interesting
 * user interface (what is more appealing to a user?)
 * ease of transition (Is it really worth it? How long does it take to
pay off?)
 * ease of implementation (Could we reuse the option parser already in
   place for the double-dashed subcommands, i.e. have less LoC)
 * error-proneness of the transition

Thanks,
Stefan

Re: Unify subcommand structure; introduce double dashes for all subcommands?

[Junio C Hamano]

Stefan Beller <stefanbeller@gmail.com> writes:

> A git command is generally setup as:
> 	git <command> [<subcommand>] [<options>] ...
>
> The subcommands vary wildly by the nature of the command. However all
> subcommands
> could at least follow one style. The commands bundle, notes, stash and
> submodule
> have subcommands without two leading dashes (i.e. git stash list) as
> opposed to all
> other commands (i.e. git tag --list).

Sounds familiar.  E.g. here is a similar thread about a year ago.

  http://thread.gmane.org/gmane.comp.version-control.git/231376/focus=231478

Further discussions to make the plan more concrete is very much
welcomed.

Thanks.

Re: Unify subcommand structure; introduce double dashes for all subcommands?

[Stefan Beller]

On 23.07.2014 19:52, Junio C Hamano wrote:
> Stefan Beller <stefanbeller@gmail.com> writes:
> 
>> A git command is generally setup as:
>> 	git <command> [<subcommand>] [<options>] ...
>>
>> The subcommands vary wildly by the nature of the command. However all
>> subcommands
>> could at least follow one style. The commands bundle, notes, stash and
>> submodule
>> have subcommands without two leading dashes (i.e. git stash list) as
>> opposed to all
>> other commands (i.e. git tag --list).
> 
> Sounds familiar.  E.g. here is a similar thread about a year ago.
> 
>   http://thread.gmane.org/gmane.comp.version-control.git/231376/focus=231478
> 
> Further discussions to make the plan more concrete is very much
> welcomed.
> 
> Thanks.
> 

So I'd want to add have the subcommands without double dashes ideally.
It's just less typing and more english like, not cryptic with dashes. 
This may come handy for newcomers/beginners using git. It also benefits 
the powerusers of git as you spare the typing of 2 dashes on the subcommand.

I'm currently trying to understand the functions to parse options 
and I wonder if the following is possible:

If there is an option set by OPT_CMDMODE 
(such as git tag --delete / --verify) we want to add an internal option,
(such as PARSE_OPT_NODASH ?), 
that you can deliver this CMD_MODE option without leading 2 dashes. 
The current behavior with leading 2 dashes is still supported, 
but maybe a warning is printed about deprecating the option with 2 dashes.

Having this change in place will switch over revert, replace, tag and merge-base
to having sane subcommands without dashes possible.

Once this change is in, we can rewrite the other commands, 
which as of now don't require the dashes.
Coincidentally these commands heavily rely on option parsing themselves,
such as git-notes having this code in place:

	if (argc < 1 || !strcmp(argv[0], "list"))
		result = list(argc, argv, prefix);
	else if (!strcmp(argv[0], "add"))
		result = add(argc, argv, prefix);
	else if (!strcmp(argv[0], "copy"))
		result = copy(argc, argv, prefix);
	...

Does that make sense?
Stefan

Re: Unify subcommand structure; introduce double dashes for all subcommands?

[Junio C Hamano]

Stefan Beller <stefanbeller@gmail.com> writes:

> On 23.07.2014 19:52, Junio C Hamano wrote:
>
>> Sounds familiar.  E.g. here is a similar thread about a year ago.
>> 
>>   http://thread.gmane.org/gmane.comp.version-control.git/231376/focus=231478
>> 
>> Further discussions to make the plan more concrete is very much
>> welcomed.
>> 
>> Thanks.
>> 
>
> So I'd want to add have the subcommands without double dashes ideally.

That is not ideal at all, I am afraid.  A command that started only
with its "primary operating mode", e.g. "git tag [-s|-a] tagname
[object]", may have to gain "I do not want to create, I just want to
list" and the way to signal that has to be an option that cannot be
mistaken as its valid first argument (to avoid "git tag list" that
cannot create a tag called "list", we use "git tag --list").  You
could add an entirely new command "git foo" that always takes the
command-mode word, i.e. "git foo mode$n args", but you will be
typing the operating mode name all the time only to save --mode$n
for 2<=$n, which may not be a good economy in the end.

Please do not go there.

Re: Unify subcommand structure; introduce double dashes for all subcommands?

[Stefan Beller]

On 10.08.2014 20:13, Junio C Hamano wrote:
> Stefan Beller <stefanbeller@gmail.com> writes:
> 
>> On 23.07.2014 19:52, Junio C Hamano wrote:
>>
>>> Sounds familiar.  E.g. here is a similar thread about a year ago.
>>>
>>>   http://thread.gmane.org/gmane.comp.version-control.git/231376/focus=231478
>>>
>>> Further discussions to make the plan more concrete is very much
>>> welcomed.
>>>
>>> Thanks.
>>>
>>
>> So I'd want to add have the subcommands without double dashes ideally.
> 
> That is not ideal at all, I am afraid.  A command that started only
> with its "primary operating mode", e.g. "git tag [-s|-a] tagname
> [object]", may have to gain "I do not want to create, I just want to
> list" and the way to signal that has to be an option that cannot be
> mistaken as its valid first argument (to avoid "git tag list" that
> cannot create a tag called "list", we use "git tag --list").  You
> could add an entirely new command "git foo" that always takes the
> command-mode word, i.e. "git foo mode$n args", but you will be
> typing the operating mode name all the time only to save --mode$n
> for 2<=$n, which may not be a good economy in the end.
> 
> Please do not go there.
> 

I see your point.
However how often do you really want to create a tag called list?
As of now it's easy:
	git tag list
and for listing all tags you'd need to type:
	git tag --list
and if you want to create a tag called --list, I'd assume you'd go
	git tag -- --list
	# However:
	fatal: '--list' is not a valid tag name.

So even as of now certain tag names cannot be done easily.
Also you have to type two more dashes for an action you'd probably want
to perform more often (as opposed to creating a tag 'list')

In my (ideal) world we'd rather have this behavior:
 	git tag list
	# behaves the same as
	git tag

Now creating a tag called 'list' is not as easy, because 'list' is a
primary operating mode name, so we need to tell git we're actually
meaning the name as opposed to the operating mode:
	git tag create -- list
	# or even
	git tag create -- --list



----
Anyways despite my arguing, it seems you rather want to rather have the
leading double dashes everywhere for the operating modes?
So the plan is to not touch the parsing, but to adjust notes and stash ?

Thanks,
Stefan