Subject: Re: PATCH: improve git switch documentation

From: Felipe Contreras <[email-masked]>
Date: Sat, 10 Jul 2021 14:51:45 -0500

Sergey Organov wrote:
> Martin <[email-masked]> 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.

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