threads / discuss / 20989

Usability question

Subject: Usability question

## tl;dr

8 messages between Sep 17, 2009 and Sep 20, 2009.

replies: 7people: 6as markdown or json

Rob Barrett· Sep 17, 2009, 10:01 UTC · lore

When starting with git people almost always ask some variant of "how do I know whether this option should be prefixed with dashes or not?" i.e. git reset --hard vs. git stash save --patch, which coupled with other path, sha and treeish args make things a bit more confusing.

Not sure if this has been discussed before? If it has point me at the discussion and I'll go look at it -- no need to read further.

And people stop asking the question after they get used to git - but that's not the same as being usable.

Out of 60+ commands, most take the form git <subcommand> [--option] and a few take the form git <subcommand> subsubcommand [--option]

(a quick scan gives: bisect,bundle,reflog,remote,stash)

My questions:
1. What is the distinction that makes the 10% special enough to get
non-prefixed options?
2. Is it worthwhile? Wouldn't it be better if to shoot for more
consistency / less complexity?

Rob

Matthieu Moy· Sep 17, 2009, 10:41 UTC · re: Rob Barrett · lore

Re: Usability question

Rob Barrett <barrettboy@gmail.com> writes:

> My questions:
> 1. What is the distinction that makes the 10% special enough to get
> non-prefixed options?

Prefixed and non-prefixed is what people usually call respectively "options" and "subcommands". To me, the distinction is needed:

Options are flags that modify the behavior of a git command. For example, "git reset" and "git reset --hard" do something similar, but "git svn rebase" and "git svn dcommit" do something really, totally different. It's not about doing the same thing in a different way, it's really about different actions.

Subcommands are closer to commands than they are to options. The reason to group several subcommands into one command is mostly to reduce the number of commands, but for example, it could have been decided to replace "git svn dcommit" by "git svn-dcommit" (but then "git help" would have been really really scarry).

> 2. Is it worthwhile? Wouldn't it be better if to shoot for more
> consistency / less complexity?

Well, if you want to get rid of subcommands, why not get rid of commands, too?

git --commit git --status git --svn --rebase

I find the distinction between commands, subcommands and options really helpfull.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

SZEDER Gábor· Sep 17, 2009, 12:13 UTC · re: Matthieu Moy · lore

Re: Usability question

Hi,

On Thu, Sep 17, 2009 at 12:41:06PM +0200, Matthieu Moy wrote:

Show 12 quoted lines

> Rob Barrett <barrettboy@gmail.com> writes:
> > 1. What is the distinction that makes the 10% special enough to get
> > non-prefixed options?
> 
> Prefixed and non-prefixed is what people usually call respectively
> "options" and "subcommands". To me, the distinction is needed:
> 
> Options are flags that modify the behavior of a git command. For
> example, "git reset" and "git reset --hard" do something similar, but
> "git svn rebase" and "git svn dcommit" do something really, totally
> different. It's not about doing the same thing in a different way,
> it's really about different actions.

I tend to aggree, but what about 'git rebase --abort' vs. 'git rebase --continue'? IMHO they are also doing something totally different.

Best, Gábor

Matthieu Moy· Sep 17, 2009, 13:09 UTC · re: SZEDER Gábor · lore

Re: Usability question

SZEDER Gábor <szeder@ira.uka.de> writes:

> I tend to aggree, but what about 'git rebase --abort' vs. 'git rebase
> --continue'?  IMHO they are also doing something totally different.

If I were to rewrite it, I'd call them "git rebase abort" without dashes. Not sure renaming them to subcommands is worth it though.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Daniele Segato· Sep 17, 2009, 13:25 UTC · re: Matthieu Moy · lore

Re: Usability question

On Thu, Sep 17, 2009 at 12:01 PM, Rob Barrett <barrettboy@gmail.com> wrote:

> When starting with git people almost always ask some variant of "how
> do I know whether this option should be prefixed with dashes or not?"
> i.e. git reset --hard vs. git stash save --patch, which coupled with
> other path, sha and treeish args make things a bit more confusing.

> And people stop asking the question after they get used to git - but
> that's not the same as being usable.

without speaking of usability I'll tell them to use autocompletion to see which command / options they have until they get used to them

regards, Daniele

Rob Barrett· Sep 20, 2009, 02:21 UTC · re: Matthieu Moy · lore

Re: Usability question

On Thu, Sep 17, 2009 at 8:41 PM, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

Show 7 quoted lines

> Well, if you want to get rid of subcommands, why not get rid of
> commands, too?
>
> git --commit
> git --status
> git --svn --rebase
>

Well, granted, that's a sort of heavyweight consistency, but all we should need to do is to help reduce a _new_ user's confusion about when the word after a subcommand gets a '--' prefix and when it doesn't.

And do it in a way that's backwards compatible so it doesn't affect the usage patterns of seasoned users, existing scripts, crons etc.

Will patch and see how it looks..

Rob

Dmitry Potapov· Sep 20, 2009, 18:54 UTC · re: Rob Barrett · lore

Re: Usability question

On Sun, Sep 20, 2009 at 12:21:38PM +1000, Rob Barrett wrote:

Show 19 quoted lines

> On Thu, Sep 17, 2009 at 8:41 PM, Matthieu Moy
> <Matthieu.Moy@grenoble-inp.fr> wrote:
> > Well, if you want to get rid of subcommands, why not get rid of
> > commands, too?
> >
> > git --commit
> > git --status
> > git --svn --rebase
> >
> 
> Well, granted, that's a sort of heavyweight consistency, but all we
> should need to do is to help reduce a _new_ user's confusion about
> when the word after a subcommand gets a '--' prefix and when it
> doesn't.
> 
> And do it in a way that's backwards compatible so it doesn't affect
> the usage patterns of seasoned users, existing scripts, crons etc.
> 
> Will patch and see how it looks..

It will be horrible broken... Do you realize that there is a bigger difference between commands and options than just that commands are written without a '--' prefix? Take a look at the following commands:

$ git -p log $ git log -p

There are completely difference because in the former case the -p option modifies 'git' behavior while in the later case 'git log'.

If you change commands to options, you are going to break everything.

Dmitry

Owen Taylor· Sep 17, 2009, 11:20 UTC · re: Rob Barrett · lore

Re: Usability question

On Thu, 2009-09-17 at 20:01 +1000, Rob Barrett wrote:

Show 23 quoted lines

> When starting with git people almost always ask some variant of "how
> do I know whether this option should be prefixed with dashes or not?"
> i.e. git reset --hard vs. git stash save --patch, which coupled with
> other path, sha and treeish args make things a bit more confusing.
> 
> Not sure if this has been discussed before? If it has point me at the
> discussion and I'll go look at it -- no need to read further.
> 
> And people stop asking the question after they get used to git - but
> that's not the same as being usable.
> 
> Out of 60+ commands, most take the form
> git <subcommand> [--option]
> and a few take the form
> git <subcommand> subsubcommand [--option]
> 
> (a quick scan gives: bisect,bundle,reflog,remote,stash)
> 
> My questions:
> 1. What is the distinction that makes the 10% special enough to get
> non-prefixed options?
> 2. Is it worthwhile? Wouldn't it be better if to shoot for more
> consistency / less complexity?

I don't think anybody is going to say that it all makes perfect sense. One pattern is:

 git <verb>

vs.

 git <subsystem> <verb>  (gui, svn, ...)
 git <noun> <verb>       (bundle, remote, stash, submodule, ...)

Another pattern is that options don't change the verb, they just modify it.

But it's easy to find exceptions:

 git tag -l
 git branch --contains <commit>
 git am --abort

I personally think it would help consistency to use the subsubcommand pattern more and treat 'git tag <tag>' as an shorthand. If you really want to to create a tag called 'list', you'd need to use 'git tag tag list', or maybe 'git tag -- list'.

Even with compat support for options and a general agreement that I doubt exists, that's at best a 95% compatible change, so it's unlikely to happen soon.

- Owen