Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Martin <git@mfriebe.de> writes:

> On 09/07/2021 18:10, Felipe Contreras wrote:
>> Martin wrote:
>>> As for "git switch -C"
>>> This should IMHO change to (the 2nd arg, actually depends on the point
>>> "1" above)
>>>      git switch (-c|-C) <branch-name> [<base-commit>]
>>>
>>> I suggest to not call it "new-branch-name" because, it might be an
>>> existing name.
>> I think the name is all wrong. As Ævar pointed out --new (-n) is much
>> better. Also it doesn't make much sense to use "create" or "new" for
>> something that already exists.
>
> The n versus c issue is IMHO separate. Maybe tiny overlaps.
>
> I see it mostly in the light of -c should be for "copy".
>
> On "git checkout" it is "-b" for branch. That works, if you perceive
> "branch" as a verb. "The action of branching creates a new branch".
>
> If needs must, that would work as "git switch -b" to.
>
> 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".

Thanks,
-- 
Sergey Organov