Re: PATCH: improve git switch documentation

Sergey Organov wrote:

Felipe Contreras [off-list ref] writes:

quoted

Sergey Organov wrote:

quoted

Felipe Contreras [off-list ref] writes:

quoted

quoted

quoted

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.

quoted

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

quoted

quoted

quoted

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

quoted

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