On Wed, Jun 30, 2021 at 4:50 AM Martin <git@xxxxxxxxxx> wrote: > > On 30/06/2021 00:39, Junio C Hamano wrote: > > Martin <git@xxxxxxxxxx> writes: > > > >> My text may indeed have lacked clarity. I was trying to emphasize to > >> hard, that this > >> command's "force" enables 2 actions that may both not be > >> wanted. Usually if one applies > >> "force" to a command only one such action is expected, or at least I > >> would only expect the one. > > Oh, I do agree wholeheartedly if two things are forced at the same > > time, things can become confusing. > > > > But the thing is, there are no such "two things are forced at once" > > in this case. That is why I emphasized, in my response to you, that > > "switch -C <newbranch>" does not touch working tree, so "ok, the > > switch stops because it requires some working tree files with > > changes clobbered, and I can force it to make it happen" is not > > involved. If it were, then it becomes fuzzy if --force is allowing > > an existing branch getting overwritten, or allowing a modification > > in a working tree file getting discarded, or both. > Well, yes and no. IMHO. > > From what I have seen, there are main 2 cases people use -C. > > 1) By accident, meaning to do something else. Most often meaning to do a > rebase. > I.e. some one who is new, desperately to fix "branch has diverged". > For this, those people need to be made aware that -C does not move the > commits. > > 2) Intentional, when the branch to be re-created points to a commit, > which is hold > by further branches. So no commit becomes unreachable. > In that case it is not a documentation issue. It is a, how can I enable > the re-create, > but have git warn me, if I somehow misjudged the situation and on other > branch > has the commit. That is, when I see this as 2 individually actions, out > of which I want > to allow only one. Anyway that is not documentation, and I did sent > another mail. > I just want to point out that my usual use-case for using -C (or checkout -f, but the usage is similar enough for this discussion) is when I want to create a temporary branch with a generic name (e.g. tmp) and I haven't cleaned out my unused branches in a while. If I find myself having branched off the wrong commit and wanting to move work I already committed, the user should be looking to use either rebase or merge for that. I would also consider that using a command literally called "switch --force-create" does not seem like the obvious first choice for "My history is different than that history". > And yes, for the documentation, it *should* be clear that, removing a > branch, removes the > commits on it. > But then it must be said, that the branch is first removed. That is not > currently the case. > I proposed an alternate text to that nature in my last mail. > > For the rest, it is a matter of opinion. > When I think a new user may read this, I believe such consequential > implications should > be mention rather explicit. > But, if your view (the view of the git team is) a new user should have > read up far enough > to be fully aware of those consequence, then so be it. > > As per my previous mail, then maybe > Force creating a branch, means that an existing branch of the > same name is removed. > A new branch is created at the specified <start point>. The > new branch will not > necessarily have all the commits that the existing branch used to > have. > I think the current documentations usage of "reset" in Similar to --create except that if <new-branch> already exists, it will be reset to <start-point>. Is pretty clear about what happens, although it does rely on users being familiar with the semantics of "resetting" a la git reset. I think rephrasing it in terms of branch removal/creation actually obfuscates the matter. > Well, if one creates a new feature branch, and instead of forking of > master, one forks of some > random other branch. Then one can immediately re-create it at the > original intended > branch point. No commits on the branch, none lost. > But teach that to a newbie, and they may have committed to the branch, > before they > realize they forked at the wrong point. If the then do -C those commit > will be gone. (well, yes the reflog). > I don't think that this is a great usage of switch -C. generally I teach people to look at the state of their repository via `git log --graph --oneline --all` and then decide whether they need to rebase their work or if they can just reset onto the branch they want to. -- Matthew Rogers