Re: Git's inconsistent command line options

[Stefan Beller <sbeller@google.com>]

On Tue, Aug 25, 2015 at 2:49 PM, Jacob Keller <jacob.keller@gmail.com> wrote:
> On Tue, Aug 25, 2015 at 8:13 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> On Tue, Aug 25, 2015 at 1:01 AM, Graeme Geldenhuys <graemeg@gmail.com> wrote:
>>>
>>> Even though I have worked with Git since 2009, I still have to
>>> reference the help to remind me of what parameter to use in certain
>>> situation simply because similar tasks differ so much.
>>>
>>> Maybe we could address this in the next major version of Git? Has
>>> anybody else thought about this or started work on this? Or was this
>>> discussed before and declined (link?).
>>
>> http://article.gmane.org/gmane.comp.version-control.git/231478 comes to mind,
>> which has been linked from this entry:
>>
>> Discuss and decide if we want to choose between the "mode word" UI
>> (e.g. "git submodule add") and the "mode option" UI (e.g. "git tag --delete")
>> and standardise on one; if it turns out to be a good idea, devise the migration
>> plan to break the backward-compatibility.
>>
>> in http://git-blame.blogspot.com/p/leftover-bits.html
>
> I would vote for command words, as this is clean and simple.

me too after rereading the arguments in that thread.

> The
> downside is in converting all the old options based commands, git-tag,
> and similar. These commands cannot easily convert because "valid"
> sequences would become invalid with no easy way to deprecate for
> example in the linked gmane above, "git tag delete master" can't be a
> call to delete master as it is currently a call to create a tag
> "delete" at the commit marked by master.

git-tag being a porcelain command (i.e. we do not give a promise to keep
it set to stone) can be changed with a deprecation announcement period.
Say starting with Git 2.6 we would put out warnings for upcoming commands:

 $ git tag --delete master
 $ echo $?
 # 0 # actually works as of today!

 $ git tag delete master
 #  Due to the planned switch to command words, this doesn't work.
 #  For details see road map at  `man git commandwords-roadmaps`
 $ echo $?
 # 128 maybe ?

$ git tag create delete

And after a while (maybe 3-5 years, once this version is picked up by
debian stable as well as red hat stable)
we can change it, so with Git 3.4(?)

 $ git tag --delete master
 # --delete is deprecated since 3.4, use `git tag delete` instead
 $ echo $?
 # 128

 $ git tag delete master
 # --delete is deprecated since 2.6, use `git tag delete` instead
 $ echo $?
 # 0 # actually works!

>
> I can't think of an easy way to deprecate the change in behavior over
> time, which means that making a conversion would require some other as
> yet unknown way?
>
> It may be possible to convert other options based commands, such as
> how git-branch and git-checkout do things which seem highly unrelated.
> A good example is how checkout is used to both change branches, as
> well as can create a branch, and can also checkout a file. The "reset"
> command is used to rewind history, as well as potentially reset *all*
> files, but it can't be used to reset a single file, and is completely
> different from revert. Some of these distinctions are ok because it's
> just no good way to make everything easy.
>
> Some of these could be fixed by the command word setup, but as many
> have mentioned an actual migration plan is difficult.
>
> Personally, I don't want to move to the command option "--status"
> format, as I think these aren't really options, and are very much
> sub-subcommands. I think we should try to push more uses of this
> style, and try to determine a possible migration path towards using
> them. Maybe some warts simply aren't worth the effort to fix though.
>
> Other issues are tricker to solve, and are result of git exposing more
> complex functionality and users eventually simply have to learn and
> understand.
>
> Regards,
> Jake
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html