Re: PATCH: improve git switch documentation

Sergey Organov wrote:

Martin [off-list ref] writes:

quoted

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.

I don't know if it's trying to do too much. I know `git checkout` is
trying to do too much, and I've been trying to use `git switch` instead
for a while. I often create branches and switch to them using
`git switch -c` (which I think should be `git switch -n`).

In my mind it's "switch to a new branch".

So, how would I do this operation (create a new branch and switch to
it), without using `git checkout` or `git switch -c`?

As I said once in this discussion already: trouble writing good
documentation is often indication of some flaws in the design.

Completely agree. But I believe the difficulty is in the semantics of
what a branch means in git, not anything to do with `git switch` per se.

Creating (a branch) is fundamentally different operation than switching
to (a branch), and that's why the former doesn't fit into "git switch".

Not in my mind. Instead of switching to an existing branch, I'm switching
to a new branch, which is easily understood by
`git switch --new branch`.

-- 
Felipe Contreras