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:
> >> Martin <git@mfriebe.de> writes:
> >> 
> >> > On 10/07/2021 12:24, Sergey Organov wrote:
> >> >> Martin <git@mfriebe.de> writes:
> >> >>> Actually, "new" or "create" would make sense in "git branch". But in
> >> >>> git switch, they actually raise the question "create what?" / "new
> >> >>> what?".
> >> >> I believe that's because "git switch" tries to do too much. "git switch"
> >> >> should rather switch between existing branches, and do nothing else. As
> >> >> I said once in this discussion already: trouble writing good
> >> >> documentation is often indication of some flaws in the design.
> >> >> Creating (a branch) is fundamentally different operation than switching
> >> >> to (a branch), and that's why the former doesn't fit into "git switch".
> >> >> 
> >> >
> >> > Right, yes. But creating a branch is often followed by switching to it.
> >> 
> >> Yep, but here the creation is the primary operation, not switching, so
> >> putting this into "git switch" looks like design flaw. These 2 actions
> >> are fine to co-exist in "git branch" = "whatever you want to do to
> >> branches", but not in "git switch" == "wherever you want to switch".
> >
> > 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?

"branch" can be a verb, that's a fact.

> >> To me, while the latter is obvious, it's verb and specifies the action
> >> to be performed, the former looks more like "whatever you want to do
> >> with branches", and thus the "branch" is a noun there and the command
> >> thus is object-oriented.
> >
> > 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.

Either way this is way too far from the original point. I don't think
you can convince me that `git new branch` makese sense, but there's no
need for that.

To move forward we need to find consensus, and if you and me agree that
`git branch new` makes sense, that's where we should focus on.

Even standardizing `git branch` would be an almost-impossible task, even
if we manage to convince others. `git new branch` even more impossible.

-- 
Felipe Contreras