Re: PATCH: improve git switch documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 10, 2021, 19:51 UTC
Message-ID: <60e9fa5132e14_7ef20849@natae.notmuch>
In-Reply-To: <87im1ieaba.fsf@osv.gnss.ru>

Sergey Organov wrote:

Show 30 quoted lines

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

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