Re: PATCH: improve git switch documentation

Martin [off-list ref] writes:

On 09/07/2021 18:10, Felipe Contreras wrote:

quoted

Martin wrote:

quoted

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