Re: PATCH: improve git switch documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 9, 2021, 17:41 UTC
Message-ID: <60e88a4b8592f_16bcb2082b@natae.notmuch>
In-Reply-To: <dbfa96f0-558e-ccaf-6e34-6d95c43848b5@mfriebe.de>

Martin wrote:

Show 20 quoted lines

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

I generally view git commands as verbs. In this case "checkout" is the verb, and "branch" is the direct object.

> Actually, "new" or "create" would make sense in "git branch". But in git 
> switch, they actually raise the question "create what?" / "new what?".

`git switch` doesn't switch anything other branches. I don't think `git switch-branch` would make the command somehow more understendale.

Show 17 quoted lines

> > I think you saw a correct issue: `git switch -C` might be used
> > incorrectly, but changing to the documentation would have limited value
> > (and only for the ones that read it).
> > 
> > I think if the branch already exists, the user has to be explicit to
> > what he wants to do and use `git switch --reset <branch> <commit>`
> 
> Well, that is the question as what the action is perceived.
> I think the example is wrong, rather than the command.
> 
> -c / -C /-n / -N always *c*reate an *n*ew branch. (create and new really 
> are the same thing here)
> 
> But if the branch name Foo, is already used?
> Well, it will still be a *new* branch being *created*.
> To do that it has to remove the name from the old branch. (effectively 
> removing the old branch).

But it's not removing the name, it's merely changing the head.

I don't particularly mind having -C or -N, I just would not use them because I like to be explicit. I don't use --new for something that already exists.

Show 14 quoted lines

> >> 3)
> >>
> >>      newbbranch  versus new-branch  versus  new_branch
> >>
> >> That is something that just needs to be decided.
> >> "new_branch" is in git checkout.
> > 
> > I'd rather have <branch>, but as I already said, the more ground you try
> > to cover the more impossible it will be to actually land the changes.
> 
> Well ok, if you shorten it to one word that solves it too.
> But for anything that for some reason needs two words, IMHO there should 
> be one style. "one word", "-" or "_".
> Currently different styles are mixed.

I don't see the need for that, <new branch> would do the trick, no need for hyphens or underscores.

Show 24 quoted lines

> >> Look at
> >>     git checkout --force
> >>> --force
> >>>      When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.
> >>
> > 
> > All these issues go away if we have:
> > 
> >    git switch --reset <branch> <commit>
> > 
> > And instead of -C, we have:
> > 
> >    git switch --new --reset <branch> <commit>
> > 
> > This creates a new branch if it doesn't exist, or if it exists resets
> > it.
> 
> Nope it does not go away.
> 
> All this has done, is that it no longer is a "force" command.
> So the last bit of warning has just gone.
> 
> And it still needs to be documented inside the "git switch" doc, rather 
> than forwarding the user do yet another doc.

Yes, but as I said: the documentation writes itself.

  -n <branch>, --new <branch>

    Creates a new branch.

  --reset <branch>

    Resets the branch to <head>.

> Also making the user read the "git reset" doc does not help, unless we 
> point out that this is a --hard reset, rather than "modifying the index".

Nobody is suggesting that. --reset refers to the English word "reset", not `get reset`.

> So, I still ask:
> - If "--force" to overwrite the work tree can clearly state that change 
> to files will be "thrown away".
> - Then why can "force" re-using an existing branch name not do the same?

Because we would be forcing two things now. I'd rather not overload concepts.

Cheers.

-- 
Felipe Contreras