Git's inconsistent command line options

Git's inconsistent command line options

[Graeme Geldenhuys]

Hi,

I've used Git for years and this has always bothered me. Has anybody
else noticed the inconsistent command line parameteres for seemingly
similar tasks. There are many examples, but I'll list only two (I can
supply a more extensive list if needed).

eg: Renaming things.

 * When working with branches it uses "-m" or "-M" to rename a branch.

 * When working with remote repos it use "rename"  (not even the more
common -- prefix either).

eg: Deleting things

  * When working with branches it uses "-d" or "-D" to delete a branch

  * When working with remote branch it uses only a push command.

  * When deleting a remote repo it uses "remove" (again not even with
the commonly used -- prefix)


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?).

Regards,
  Graeme

Re: Git's inconsistent command line options

[Junio C Hamano]

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

Re: Git's inconsistent command line options

[Jacob Keller]

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. 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.

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

Re: Git's inconsistent command line options

[Stefan Beller]

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

Re: Git's inconsistent command line options

[Jacob Keller]

On Tue, Aug 25, 2015 at 3:06 PM, Stefan Beller <sbeller@google.com> wrote:
> 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!
>


This seems like a possible strategy for converging on command words.
So basically, we force all uses of the command words to just fail and
then once that's picked up we can migrate to the command words.

Regards,
Jake

Re: Git's inconsistent command line options

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>  $ 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 ?

This is way too aggressive behaviour and is unacceptable as the
first step.  The first step of a transition that breaks backward
compatibility should warn loudly about a command line that would
behave differently in the endgame version (either the command line
that will not do anything or do a totally different thing), but
still perform the operation asked for the current version.

    e.g. "git tag delete master" would create a tag named 'delete'
    out of 'master', but tell the user that this will instead delete
    'master' in future versions of Git.  "git tag create master"
    would create a tag named 'create' out of 'master', but tell the
    user that this will instead create 'master' out of HEAD in
    future versions of Git.

    e.g. "git tag -d foo" would delete a tag named 'foo', but tell
    the user that this will have to be spelled 'git tag delete foo'
    in the future versions of Git.

One thing that I am not enthused about the transition plan is that
"git tag delete master" will *never* be an invalid operation during
the transition.  When making an operation that used to mean one
thing to mean something else, a good transition plan should be to

 * First warn but do the old thing, and tell users a new way to do
   that in the new world order.  At the same time, find the new way
   that used to be an invalid operation in the old world order, and
   implement it.

 * Then stop supporting the old thing and support only the new
   thing.

Then during the transition period, while transitioning to the new
way, people can gradually start using the new way with the new
system, and when they occasionally have to interact with an old
system, the new way will _error out_, because we make sure we find
the new way that "used to be an invalid operation" when planning the
whole transition plan, without causing any harm.  And once people
retrain their finger after 2-3 years, nobody will be hurt if we
dropped the old way.

I do not see a good way to do such a safe transition with command
words approach, *unless* we are going to introduce new commands,
i.e. "git list-tag", "git create-tag", etc.

So don't hold your breath.  What you two are discussing is way too
uncooked for 2.6 timeframe.

Re: Git's inconsistent command line options

[Hilco Wijbenga]

On 25 August 2015 at 16:43, Junio C Hamano <gitster@pobox.com> wrote:
> I do not see a good way to do such a safe transition with command
> words approach, *unless* we are going to introduce new commands,
> i.e. "git list-tag", "git create-tag", etc.

Perhaps we could introduce a more explicit notion (in .git/config) of
a Git API version (or, perhaps more accurate, a Git CLI API version)?

The default would be 2 (since we're already at Git 2.x). Git commands
could check for this setting and abort/introduce/prevent/change
behaviour/functionality as appropriate. During Git 2.x the API 2 would
be the default but users could explicitly request 3 in preparation of
Git 3.x. (With the knowledge that API 3 would still be [to some extent
at least] in flux.) API 2 could start warning about future changes
where appropriate. With the introduction of Git 3.x, the default would
become API 3 but users could still request API 2. Then for Git 4.x the
default would go to 4, with an option to request 3 but 2 would no
longer be supported (and all code supporting API 2 could be removed).

I think that from a user's point of view this could work quite well.
Obviously, (worst case scenario) Git commands might have to support up
to 3 APIs at the same time (previous [2], current [3], and future [4]
for Git 3.x) so from a code maintenance POV it would certainly
introduce complexity and probably some duplication of code. I'm
hopeful it would be limited to CL argument processing but I suspect
that when Git code calls other Git code (especially in the Bash based
commands) there might be some more complexity there.

Would something like that be feasible?

Re: Git's inconsistent command line options

[Jacob Keller]

On Tue, Aug 25, 2015 at 4:43 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>>  $ 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 ?
>
> This is way too aggressive behaviour and is unacceptable as the
> first step.  The first step of a transition that breaks backward
> compatibility should warn loudly about a command line that would
> behave differently in the endgame version (either the command line
> that will not do anything or do a totally different thing), but
> still perform the operation asked for the current version.
>


>     e.g. "git tag delete master" would create a tag named 'delete'
>     out of 'master', but tell the user that this will instead delete
>     'master' in future versions of Git.  "git tag create master"
>     would create a tag named 'create' out of 'master', but tell the
>     user that this will instead create 'master' out of HEAD in
>     future versions of Git.
>
>     e.g. "git tag -d foo" would delete a tag named 'foo', but tell
>     the user that this will have to be spelled 'git tag delete foo'
>     in the future versions of Git.
>
> One thing that I am not enthused about the transition plan is that
> "git tag delete master" will *never* be an invalid operation during
> the transition.  When making an operation that used to mean one
> thing to mean something else, a good transition plan should be to
>
>  * First warn but do the old thing, and tell users a new way to do
>    that in the new world order.  At the same time, find the new way
>    that used to be an invalid operation in the old world order, and
>    implement it.
>
>  * Then stop supporting the old thing and support only the new
>    thing.
>
> Then during the transition period, while transitioning to the new
> way, people can gradually start using the new way with the new
> system, and when they occasionally have to interact with an old
> system, the new way will _error out_, because we make sure we find
> the new way that "used to be an invalid operation" when planning the
> whole transition plan, without causing any harm.  And once people
> retrain their finger after 2-3 years, nobody will be hurt if we
> dropped the old way.
>
> I do not see a good way to do such a safe transition with command
> words approach, *unless* we are going to introduce new commands,
> i.e. "git list-tag", "git create-tag", etc.
>
> So don't hold your breath.  What you two are discussing is way too
> uncooked for 2.6 timeframe.
>
>
>

Ya, there isn't really a way to make it work, because we can't exactly
stop supporting "git tag create master" by turning it into a no-op,
because there is no equivalent tag option that would work for now.
Since there is no alternative syntax for "create" I think this is the
issue. One way might be to use the -- splitter to say,

"if you really mean to create a tag named create, use

git tag -- create master

So we'd do:

- step 1 -
git tag create master
# warn that this will change behavior in the future and they must
explicitely pass -- before it

- step 2 -
break create, but don't add anything new. If user really needs it,
they can pass "git tag -- create master" as per above warning, but
keep warning on "git tag create master" to say they must be explicit.

- step 3 -

implement git tag create master to actually perform tag creation

I think this might work, as long as "git tag -- create master" is acceptable?

then, eventually we can make it so that "git tag" doesn't mean create
by default if we ever wanted?

How does this sound? By the way, this wouldn't be necessarily done
over 2.6 or even over only a single release, I think the time frame
would have to be fairly long.

The downside is that there is no point where new and old syntax are
usable at the same time... but I don't think that will ever be the
case. We'd need to way the concern of whether this is actually worth
doing to streamline the overall feel at some point in the future or we
just live with the warts.

Regards,
Jake

Re: Git's inconsistent command line options

[Andreas Schwab]

Jacob Keller <jacob.keller@gmail.com> writes:

> "if you really mean to create a tag named create, use
>
> git tag -- create master

In all other uses of -- refs must be put on the *left* side.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Git's inconsistent command line options

[Jacob Keller]

On Tue, Aug 25, 2015 at 11:28 PM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> Jacob Keller <jacob.keller@gmail.com> writes:
>
>> "if you really mean to create a tag named create, use
>>
>> git tag -- create master
>
> In all other uses of -- refs must be put on the *left* side.
>
> Andreas.
>

Oops that wouldn't be consistent then. Normally "--" is used to
separate options from non-options arguments, but we usually use it to
separate refs from non-refs.

Guess that sort of ruins this particular strategy.

Regards,
Jake

Re: Git's inconsistent command line options

[Junio C Hamano]

Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:

> On 25 August 2015 at 16:43, Junio C Hamano <gitster@pobox.com> wrote:
>> I do not see a good way to do such a safe transition with command
>> words approach, *unless* we are going to introduce new commands,
>> i.e. "git list-tag", "git create-tag", etc.
>
> Perhaps we could introduce a more explicit notion (in .git/config) of
> a Git API version (or, perhaps more accurate, a Git CLI API version)?
> ...
> I think that from a user's point of view this could work quite well.
> Obviously, (worst case scenario) Git commands might have to support up
> to 3 APIs at the same time (previous [2], current [3], and future [4]
> for Git 3.x) so from a code maintenance POV it would certainly
> introduce complexity and probably some duplication of code. I'm
> hopeful it would be limited to CL argument processing but I suspect
> that when Git code calls other Git code (especially in the Bash based
> commands) there might be some more complexity there.
>
> Would something like that be feasible?

A bigger issue you need to think about is what to do to scripts
people have.  Your approach forces them to update a script to delete
a tag and do something else to say something silly like this:

	#!/bin/sh
        # My Script
	case "$(git config core.apiVersion)" in
        "" | 2)
		git tag -d "$1"
                do something else on "$1" using v2 API
                ;;

        3)
		git tag delete "$1"
                do something else on "$1" using v3 API
                ;;

	*)
        	echo >&2 "sorry, I do not know what Git you are using"
		exit 1
                ;;
	esac

So, it may be feasible to implement, but I do not think it would be
useful to do so.

Instead, if you really want to invent the multi-version world, you
would rather want to have something more like this:

	#!/bin/sh
        # My Script
	GIT_API_VERSION=2
	export GIT_API_VERSION

	git tag -d "$1"
        do something else on "$1" using v2 API

But notice that I said "if you really want to".  I personally think
it is a road to madness.

Re: Git's inconsistent command line options

[Jacob Keller]

On Wed, Aug 26, 2015 at 10:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
> But notice that I said "if you really want to".  I personally think
> it is a road to madness.

Agreed. I don't believe in command line API here. I think we'd need a
better solution.

My gut says: Live with the warts on old commands and try to make
people use command words for new commands.

Re: Git's inconsistent command line options

[Junio C Hamano]

Jacob Keller <jacob.keller@gmail.com> writes:

> On Wed, Aug 26, 2015 at 10:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> But notice that I said "if you really want to".  I personally think
>> it is a road to madness.
>
> Agreed. I don't believe in command line API here. I think we'd need a
> better solution.
>
> My gut says: Live with the warts on old commands and try to make
> people use command words for new commands.

A transition to make everybody to use subsubcommands (thereby
changing what "git tag delete master" means) is impossible in
practice.  On the other hand, a transition to make everybody use
command mode options (thereby allowing "git worktree list" to be
also spelled as "git worktree --list") _is_ possible.

Has anybody created a handy catalog of Git commands with subcommands
and command mode options?  If we see such a list and replace the
column of subcommands with command mode options, we might find that
such a "command mode option only" world a pleasant future for us to
live in, or an unpleasant one that we have to keep typing two extra
dashes all the time.  I cannot tell offhand.

Re: Git's inconsistent command line options

[Philip Oakley]

From: "Jacob Keller" <jacob.keller@gmail.com>
> On Wed, Aug 26, 2015 at 10:56 AM, Junio C Hamano <gitster@pobox.com> 
> wrote:
>> But notice that I said "if you really want to".  I personally think
>> it is a road to madness.
>
> Agreed. I don't believe in command line API here. I think we'd need a
> better solution.
>
> My gut says: Live with the warts on old commands and try to make
> people use command words for new commands.
> --
Agreed. However Graeme's original question also said "I can supply a 
more extensive list if needed", and "I still have to reference the help 
to remind me of what parameter to use in certain situation", which 
suggests that one option is to capture that list within some part of the 
documentation, especially if Graeme already has an easy to read layout.

If it could be part of the documenation, where should it go - gitcli or 
perhaps it's own guide (`git help -g` and friends)?

--

Philip

Re: Git's inconsistent command line options

[Jacob Keller]

On Wed, Aug 26, 2015 at 3:52 PM, Philip Oakley <philipoakley@iee.org> wrote:
> From: "Jacob Keller" <jacob.keller@gmail.com>
>>
>> On Wed, Aug 26, 2015 at 10:56 AM, Junio C Hamano <gitster@pobox.com>
>> wrote:
>>>
>>> But notice that I said "if you really want to".  I personally think
>>> it is a road to madness.
>>
>>
>> Agreed. I don't believe in command line API here. I think we'd need a
>> better solution.
>>
>> My gut says: Live with the warts on old commands and try to make
>> people use command words for new commands.
>> --
>
> Agreed. However Graeme's original question also said "I can supply a more
> extensive list if needed", and "I still have to reference the help to remind
> me of what parameter to use in certain situation", which suggests that one
> option is to capture that list within some part of the documentation,
> especially if Graeme already has an easy to read layout.
>
> If it could be part of the documenation, where should it go - gitcli or
> perhaps it's own guide (`git help -g` and friends)?
>

I hope to spend some time investigating this in the near future.
Personally I feel that command names make more sense than options
since they are essentially non-options, and it helps separate
logically related but non-equivalent operations more easily.

The confusion that results from git-checkout, and git-branch has
caught more than a few new people at $dayjob.

Regards,
Jake

Re: Git's inconsistent command line options

[Jacob Keller]

On Wed, Aug 26, 2015 at 4:02 PM, Jacob Keller <jacob.keller@gmail.com> wrote:
> On Wed, Aug 26, 2015 at 3:52 PM, Philip Oakley <philipoakley@iee.org> wrote:
>> From: "Jacob Keller" <jacob.keller@gmail.com>
>>>
>>> On Wed, Aug 26, 2015 at 10:56 AM, Junio C Hamano <gitster@pobox.com>
>>> wrote:
>>>>
>>>> But notice that I said "if you really want to".  I personally think
>>>> it is a road to madness.
>>>
>>>
>>> Agreed. I don't believe in command line API here. I think we'd need a
>>> better solution.
>>>
>>> My gut says: Live with the warts on old commands and try to make
>>> people use command words for new commands.
>>> --
>>
>> Agreed. However Graeme's original question also said "I can supply a more
>> extensive list if needed", and "I still have to reference the help to remind
>> me of what parameter to use in certain situation", which suggests that one
>> option is to capture that list within some part of the documentation,
>> especially if Graeme already has an easy to read layout.
>>
>> If it could be part of the documenation, where should it go - gitcli or
>> perhaps it's own guide (`git help -g` and friends)?
>>
>
> I hope to spend some time investigating this in the near future.
> Personally I feel that command names make more sense than options
> since they are essentially non-options, and it helps separate
> logically related but non-equivalent operations more easily.
>
> The confusion that results from git-checkout, and git-branch has
> caught more than a few new people at $dayjob.
>
> Regards,
> Jake

That being said, use of "--create" or so forth really isn't that
bothersome so maybe the gains outway the cons here.

Regards,
Jake

Re: Git's inconsistent command line options

[Duy Nguyen]

On Wed, Aug 26, 2015 at 6:43 AM, Junio C Hamano <gitster@pobox.com> wrote:
> ...
>
> I do not see a good way to do such a safe transition with command
> words approach, *unless* we are going to introduce new commands,
> i.e. "git list-tag", "git create-tag", etc.

I'm probably shot down for this. But could we go with a clean plate
and create a new command prefix (something like git-next, git2, or
gt...)? We could then redesign the entire UI without worrying about
backward compatibility. At some point we can start to deprecate "git"
and encourage to use the new command prefix only. Of course somebody
has to go over all the commands and options to propose some consistent
UI, then more discussions and coding so it could likely follow the
path of pack v4..
-- 
Duy

Re: Git's inconsistent command line options

[Barry Warsaw]

[-- Attachment #1: Type: text/plain, Size: 800 bytes --]

On Aug 31, 2015, at 05:10 PM, Duy Nguyen wrote:

>I'm probably shot down for this. But could we go with a clean plate
>and create a new command prefix (something like git-next, git2, or
>gt...)? We could then redesign the entire UI without worrying about
>backward compatibility. At some point we can start to deprecate "git"
>and encourage to use the new command prefix only. Of course somebody
>has to go over all the commands and options to propose some consistent
>UI, then more discussions and coding so it could likely follow the
>path of pack v4..

`git` itself could also be a thin wrapper which consulted a configuration
variable to see which version of the ui to expose.

"All problems in computer science can be solved by another level of
indirection"

Cheers,
-Barry


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Git's inconsistent command line options

[David Aguilar]

On Mon, Aug 31, 2015 at 10:25:58AM -0400, Barry Warsaw wrote:
> On Aug 31, 2015, at 05:10 PM, Duy Nguyen wrote:
> 
> >I'm probably shot down for this. But could we go with a clean plate
> >and create a new command prefix (something like git-next, git2, or
> >gt...)? We could then redesign the entire UI without worrying about
> >backward compatibility. At some point we can start to deprecate "git"
> >and encourage to use the new command prefix only. Of course somebody
> >has to go over all the commands and options to propose some consistent
> >UI, then more discussions and coding so it could likely follow the
> >path of pack v4..
> 
> `git` itself could also be a thin wrapper which consulted a configuration
> variable to see which version of the ui to expose.
> 
> "All problems in computer science can be solved by another level of
> indirection"

Except for poor performance, simplicity, and bad ideas.

The Git project does not break backwards compatibility.
Let's let Python3 serve as a good lesson on why not to do that! ;-p

While a script writer could write, "git -c core.cliversion=1 ...",
no one does that, no one wants to do that, and it just seems
like a bad idea that's best left unexplored.

The only idea in this thread that's user-friendly would be a new
Git that still supported the entirety of the existing,
perfectly-good CLI interface and *also* accepted some new
"consistent" user interface.

Otherwise, this entire thread seems like a big non-issue.
The existing CLI hasn't hurt adoption, and tossing a config
option at it only makes it worse.  The best config is no config.

There really are ony a few corner cases that would need to be
tweaked to support --named-subcommands style, and after that is
done, is Git really that much easier to use?

Maybe a little bit, but not enough that warrants breaking
existing scripts IMO.
---
David

Re: Git's inconsistent command line options

[Barry Warsaw]

[-- Attachment #1: Type: text/plain, Size: 1284 bytes --]

On Sep 01, 2015, at 02:28 AM, David Aguilar wrote:

>While a script writer could write, "git -c core.cliversion=1 ...",
>no one does that, no one wants to do that, and it just seems
>like a bad idea that's best left unexplored.

Sure, no one will do that from the command line, but I don't think people
generally change their preferences that often.  Much more likely is that
they'll `git config` a more permanent choice for their shell usage and then
just use straight up "git" with the new ui.  -c would be reserved for scripts
which hard code a particular ui.

>Otherwise, this entire thread seems like a big non-issue.  The existing CLI
>hasn't hurt adoption...

A significant factor driving git adoption is network effects.  That's highly
motivating to overcome discomfort or confusion with the cli.  Once you've lost
your beginner's mind, you are much less aware of the cli inconsistencies and
disconnects from other vcses.  The latter might not affect new users whose
only experience with vcses is git, but it presents a steeper learning curve
for folks migrating from other tools.

>...and tossing a config option at it only makes it worse.  The best config is
>no config.

git already has no shortage of configuration options. ;)

Cheers,
-Barry

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Git's inconsistent command line options

[Junio C Hamano]

(Administrivia) please do not cull CC list when replying.

Barry Warsaw <barry@python.org> writes:

> On Sep 01, 2015, at 02:28 AM, David Aguilar wrote:
>
>>While a script writer could write, "git -c core.cliversion=1 ...",
>>no one does that, no one wants to do that, and it just seems
>>like a bad idea that's best left unexplored.
>
> Sure, no one will do that from the command line, but I don't think people
> generally change their preferences that often.  Much more likely is that
> they'll `git config` a more permanent choice for their shell usage and then
> just use straight up "git" with the new ui.  -c would be reserved for scripts
> which hard code a particular ui.

That way, you are forcing all the existing scripts to be updated to
say "git -c ..." for _all_ invocations of Git they have, aren't you?

That is simply unworkable.

By the way, you can review what has already been said in this
discussion here:

  http://thread.gmane.org/gmane.comp.version-control.git/276509/focus=276589

Re: Git's inconsistent command line options

[Barry Warsaw]

[-- Attachment #1: Type: text/plain, Size: 473 bytes --]

On Sep 01, 2015, at 09:42 AM, Junio C Hamano wrote:

>That way, you are forcing all the existing scripts to be updated to
>say "git -c ..." for _all_ invocations of Git they have, aren't you?

No, why?  If the default value enables the current ui, then no scripts need
changing.  Users can enable the new ui for their own benefit at their own
pace.  If you eventually want to make the new ui the default, provide a
sufficient transition period.

Cheers,
-Barry

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Git's inconsistent command line options

[Stefan Beller]

On Tue, Sep 1, 2015 at 10:50 AM, Barry Warsaw <barry@python.org> wrote:
> On Sep 01, 2015, at 09:42 AM, Junio C Hamano wrote:
>
>>That way, you are forcing all the existing scripts to be updated to
>>say "git -c ..." for _all_ invocations of Git they have, aren't you?
>
> No, why?  If the default value enables the current ui, then no scripts need
> changing.  Users can enable the new ui for their own benefit at their own
> pace.  If you eventually want to make the new ui the default, provide a
> sufficient transition period.
>
> Cheers,
> -Barry

So say I am a user who wants to take the new command set. And as I am lazy to
type it all the time I just do:

  $ git config --global command-version 2

Now I have all the new fancy stuff when I type it directly into the terminal.
But when I run one of the old scripts my coworker gave me (which is used to
the old notion), it must adhere to the old command world. How do you now figure
out if this is interactive or script?

Re: Git's inconsistent command line options

[Michael J Gruber]

David Aguilar venit, vidit, dixit 01.09.2015 11:28:
> On Mon, Aug 31, 2015 at 10:25:58AM -0400, Barry Warsaw wrote:
>> On Aug 31, 2015, at 05:10 PM, Duy Nguyen wrote:
>>
>>> I'm probably shot down for this. But could we go with a clean plate
>>> and create a new command prefix (something like git-next, git2, or
>>> gt...)? We could then redesign the entire UI without worrying about
>>> backward compatibility. At some point we can start to deprecate "git"
>>> and encourage to use the new command prefix only. Of course somebody
>>> has to go over all the commands and options to propose some consistent
>>> UI, then more discussions and coding so it could likely follow the
>>> path of pack v4..
>>
>> `git` itself could also be a thin wrapper which consulted a configuration
>> variable to see which version of the ui to expose.
>>
>> "All problems in computer science can be solved by another level of
>> indirection"
> 
> Except for poor performance, simplicity, and bad ideas.
> 
> The Git project does not break backwards compatibility.
> Let's let Python3 serve as a good lesson on why not to do that! ;-p
> 
> While a script writer could write, "git -c core.cliversion=1 ...",
> no one does that, no one wants to do that, and it just seems
> like a bad idea that's best left unexplored.
> 
> The only idea in this thread that's user-friendly would be a new
> Git that still supported the entirety of the existing,
> perfectly-good CLI interface and *also* accepted some new
> "consistent" user interface.

Give it a break. If Git had a perfectly-good CLI interface we didn't
have any complaints. But we have many well-founded complaints about
inconsistencies, such as short-options (-n), subsubcommands etc.

> Otherwise, this entire thread seems like a big non-issue.
> The existing CLI hasn't hurt adoption, and tossing a config
> option at it only makes it worse.  The best config is no config.

I certainly agree with you on that. Unfortunately, we've seen quite an
increase of config options whose sole purpose is changing default
options for some commands.

> There really are ony a few corner cases that would need to be
> tweaked to support --named-subcommands style, and after that is
> done, is Git really that much easier to use?
> 
> Maybe a little bit, but not enough that warrants breaking
> existing scripts IMO.
> ---
> David

Well, it may actually hurt to reach some substantial improvements. It
may actually be worth it if it ends constant suffering from how it is
now. Those are the points that we have to weigh carefully. Simply
resisting change won't take us anywhere.

Michael

Re: Git's inconsistent command line options

[Michael J Gruber]

Stefan Beller venit, vidit, dixit 01.09.2015 19:56:
> On Tue, Sep 1, 2015 at 10:50 AM, Barry Warsaw <barry@python.org> wrote:
>> On Sep 01, 2015, at 09:42 AM, Junio C Hamano wrote:
>>
>>> That way, you are forcing all the existing scripts to be updated to
>>> say "git -c ..." for _all_ invocations of Git they have, aren't you?
>>
>> No, why?  If the default value enables the current ui, then no scripts need
>> changing.  Users can enable the new ui for their own benefit at their own
>> pace.  If you eventually want to make the new ui the default, provide a
>> sufficient transition period.
>>
>> Cheers,
>> -Barry
> 
> So say I am a user who wants to take the new command set. And as I am lazy to
> type it all the time I just do:
> 
>   $ git config --global command-version 2
> 
> Now I have all the new fancy stuff when I type it directly into the terminal.
> But when I run one of the old scripts my coworker gave me (which is used to
> the old notion), it must adhere to the old command world. How do you now figure
> out if this is interactive or script?

You can't. We have that exact same problem already with the recent
option-overriding config bloat. It needs to be solved sooner or later
anyways, by introducing some sort of "mode" (interactive vs. scripting),
since while in principle we have a separation between porcelain and
plumbing commands, we don't have, say, a plumbing version of "git tag"
and take that as an excuse^Wreason for any change to the porcelain
command "git tag". (You can freely interchange the roles here.)

Really, that porcelain-plumbing separation that's often mentioned is
more wishful thinking than actual reality, at least no complete reality,
or else we wouldn't even have any backward compatibility problem to
solve here.

So, UI rework or not, we should think about making that promise real: a
clear separation between a stable scripting interface and an evolving
user interface. Two possible ways are:

- separate commands, such as git-log vs. git-rev-list
- separate modes for the same commands

We use both of them ("interactive" detection for some default settings),
but partially only.

Michael