Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

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

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

2. In

  git merge ...

is "merge" a noun or a 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.

From this POV, to me specifically these 3 commands:

  git branch
  git tag
  git sparse-checkout

look like exceptions which should be eventually obsoleted after their
features are moved elsewhere, provided Git community is interested in
regularizing Git interfaces.

Thanks,
-- 
Sergey Organov