Re: PATCH: improve git switch documentation

[Felipe Contreras <felipe.contreras@gmail.com>]

Sergey Organov wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> > Sergey Organov wrote:
> >> Felipe Contreras <felipe.contreras@gmail.com> writes:

> >> > I don't see the logic in here.
> >> >
> >> >   git branch topic # here 'branch' is the verb
> >> 
> >> Not to me. I assumed the "branch" is always a noun in "git branch", and
> >> the actual meaning of this command is:
> >> 
> >>    git branch [create|new] topic
> >> 
> >> I.e., creation just being the default action taken on the branch.
> >
> > The question is not what you assumed, the question is can other people
> > assume otherwise?
> 
> Sure they can, and that's part of the problem. I described how *I* see
> it, as I try to interpret things as coherently as possible, and I don't
> like to interpret "branch" in "git branch" as either noun or verb
> depending on options when universal interpretation as noun is
> sufficient.
> 
> > "branch" can be a verb, that's a fact.
> 
> Yep, who argues?
> 
> My argument is that specifically in "git branch" it could be universally
> interpreted as noun, but can't universally be interpreted as verb, so
> /for me/ it's noun there.

Yeah, but universal interpretation is not part of human language.
Context is always relevant.

Sometimes it can be a verb.

> >> > I agree, and I did have indeed noticed the inconsistency. But there's
> >> > another category of commands that receive subcommands, like:
> >> >
> >> >   git remote $subcommand
> >> >   git worktree $subcommand
> >> >   git bisect $subcommand
> >> >
> >> > In my opinion `git branch` fits more these subcommand commands, and it
> >> > was a mistake to make the subcommands options, it should be:
> >> >
> >> >   git branch list
> >> >   git branch new
> >> >   git branch set-upstream
> >> >   git branch move
> >> >   ...
> >> >
> >> > Now the verb is crystal-clear.
> >> 
> >> Yes, lacking (assumed) subcommands is yet another dimension of
> >> inconsistencies.
> >> 
> >> I mean what I'm after is inconsistency of the first argument to "git".
> >> It's being the verb more often is where we currently are, at least when
> >> considering "primary" commands that "git help" outputs. 
> >> 
> >> I mean, consider:
> >> 
> >>    git branch new nice-feature
> >> 
> >> vs
> >> 
> >>    git new branch nice-feature
> >> 
> >> It should have been the latter, when in fact it's currently the
> >> [reduced] former.
> >
> > I disagree. I prefer the former.
> 
>      git create branch "nice-feature"
> 
> Almost plain human language. Isn't it nice?

But I'm not talking to a human. If I wast talking to a human I would say
"create a branch called X", and "with git" would be implied.

But there's no "create" binary on my system. Why would there be? I've
been using Linux systems for more than 20 years, I know that if I want
to do something with vim, I have to start the command with 'vim'.

> > Even standardizing `git branch` would be an almost-impossible task, even
> > if we manage to convince others. `git new branch` even more
> > impossible.
> 
> Quite an opposite. In fact it's easier to add new ways of doing things
> that, provided they prove being useful, eventually obsolete and replace
> old ways. "git switch" and "git restore" are recent examples of that.

That's what *should* be the case, but this discussion proves that even
experimental commands (which are clearly demarcated as experimental) are
hard to change.

Moreover, keep in mind that the person who managed to introduce both
`git switch` and `git resotre` already left the project. That should
give you a pretty good idea of how much faith he has on these commands
eventually being useful.

Sure, at this point in time introducing `git branch new` might be
impossible, however, `git branch --new` isn't. And if we agree on what
should have been the case for `git branch`, then what should be the case
for `git switch` is more attainable.

Cheers.

-- 
Felipe Contreras