Re: PATCH: improve git switch documentation

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

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
  git switch topic # here 'switch' is the verb

Now, if you want to do both at the same time the logical options are:

  git branch --switch topic # here '--switch' is an adverb
  git switch --new topic # here '--new' is an adverb

The former reads like gibberish to me: "git, branch off in a 'switch'
way".

The latter makes perfect sense: "git, switch to a branch in a 'new' way".

> Logically, there could be something like "git new" that does create a
> branch and then switches there by default, or something like that, say:
> 
>    git new feature3 --at origin/rc-2 --track

Here the the verb is clear, but not the direct object, a "new" what?
Couldn't it be a tag? Or a commit? Or a remote? Or a worktree? Or a
bisect? Or a submodule?

It's too ambigous.

> And while we are at it, do you guys notice how 2 concepts are mixed in
> Git commands? I mean, the interface seems to mix object-oriented and
> action-oriented commands, most of commands being action-oriented with
> only a few unfortunate exceptions.
> 
> Let me try a short survey:
> 
> 1. In
> 
>   git branch ...
> 
> is "branch" a noun or a verb?

Both.

> 2. In
> 
>   git merge ...
> 
> is "merge" a noun or a verb?

Verb.

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

-- 
Felipe Contreras