Re: PATCH: improve git switch documentation

Sergey Organov wrote:

Martin [off-list ref] writes:

quoted

On 10/07/2021 12:24, Sergey Organov wrote:

quoted

Martin [off-list ref] writes:

quoted

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