Subject: Re: [RFC/PATCH] Make "git notes add" more user-friendly when there are existing notes

From: Michael J Gruber <[email-masked]>
Date: Mon, 04 Apr 2011 14:54:57 +0200

Lasse Makholm venit, vidit, dixit 04.04.2011 13:35:
> On 30 March 2011 11:59, Johan Herland <[email-masked]> wrote:
>>> * options vs. arguments:
>>>
>>> "tag", "branch" etc. use options for subcommands, e.g. "tag -d", "branch
>>> -d" etc. "remote", "stash" use arguments, e.g. "remote add", "stash
>>> list". I don't see us unifying that, but we should decide about a
>>> direction to go for "new" commands and stick to that. I feel that
>>> options are the way to go. What I really feel strongly about is that we
>>> should decide once and then stick to that for future commands (and may
>>> be gradually revamping).
>>
>> This is a big discussion, and I don't really have a strong opinion either
>> way (or on whether unification of options vs. arguments is really necessary
>> at all). In general, I like separating the "verb" of the command (_what_ to
>> do) from the "adverbs" (_how_ to do it). For some git commands, the verb is
>> right there in the name (e.g. "checkout", "add", "rm", etc.), so the options
>> are usually all "adverbs". Other commands, however, refer to one of git's
>> "subsystems" (for some very vague definition of "subsystem") as a "noun"
>> (e.g. "stash", "remote", "notes"), and the verb needs to be specified
>> (either as a subcommand, or as an option). In those cases, I personally
>> prefer the subcommand approach ("git noun verb --adverb") better than the
>> option approach ("git noun --verb --adverb"), so as to separate the verb
>> from the adverbs.
>>
>> However, some commands (e.g. "branch", "tag") are _both_ "verbs" ("I want to
>> tag something") and "nouns" ("I want to add a tag"). By now, I'm thoroughly
>> used to "branch -d" and "tag -d", so e.g. "branch rm" and "tag rm" look a
>> bit foreign to me, although they probably follow the above principle more
>> closely...
> 
> Think of it less as the (only) verb and more of it as a domain. In the
> domain of a git remote, (add|rm|rename|...) is the action (verb) and
> that's why it is and should be a sub-command.
> 
> git remote and git stash do it right in my opinion. The default action
> differs (list vs. create) but that's OK because so does the most
> common use case.
> 
> The canonical way to create a stash is to say "git stash create" but
> we allow you to simply say "git stash" because that's probably what
> you want. It seems then, that the canonical way to create a commit
> would be by saying "git commit create" (again, allowing the "git
> commit" shortcut).
> 
> We could even expand on the heresy and argue that git log should be an
> alias for "git commit list"... :-)
> 
> My fingers type git branch -d foo by habit as well, but were it to
> change, I'd get over it and form new habits. We shouldn't let the
> force of mere habits prevent us from doing The Right Thing.
> 
> You could argue that git branch -d is broken because -d is, in fact,
> not an option at all. If it was, you would be able to say git branch
> -d junk feature master to delete junk and branch out feature from
> master. But you can't because -d really is a sub-command in disguise.
> 
>> Then you have weird cases that further complicate things: "rebase" is
>> usually a verb, but in "rebase --continue" or "rebase --abort" another verb
>> takes the focus, and I would probably prefer them as subcommands ("rebase
>> continue" and "rebase abort").
> 
> Absolutely, yes. I don't see this as a weird case at all. In my view,
> this is clearly broken just as git branch -d is. Again, in the domain
> of a rebase, abort and continue are clearly commands and should loose
> the dashes.
> 
>> What can I say? Habits are hard to break, and this might be a case where
>> breaking them is more harmful than a somewhat messy command-line interface.
> 
> As someone, standing on the edge of a 1000+ developer deployment of
> git, the option-vs-sub-command issue is one of the many things
> currently keeping me up at night. I would take a break in habits any
> day to avoid a lifetime of pain teaching people to remember and accept
> these inconsistencies...
> 

Well, I would like say that we should take this up as a long running
task then. The problem is, though, disambiguating things like "git
branch list" if we were to go for subcommands as arguments (not
options). I have no idea how to solve this (without having a complete
switch-over day).

Michael