Re: PATCH: improve git switch documentation
- From
- Martin <git@mfriebe.de>
- Date
- Jun 30, 2021, 08:50 UTC
- Message-ID
- <7870a0ad-8fa1-9dbd-1978-1f44ec6970c5@mfriebe.de>
- In-Reply-To
- <xmqqpmw4uwh2.fsf@gitster.g>
On 30/06/2021 00:39, Junio C Hamano wrote:
Show 19 quoted lines
> Martin <git@mfriebe.de> 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.
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.
But without It therefore also means that commits from the old existing branch may be no longer reachable.
Show 17 quoted lines
>> The actions being, giving up the link to the commit that is the tip of >> the branch; and >> making commits unreachable. (for an expert in git tightly linked >> together, but not for everyone) > Sorry, I do not quite see how the removing the reference to a commit > (i.e. the commit C that used to be pointed at by the branch would no > longer be pointed at by that branch---that is by definition what > moving the branch to point at a different commit means) and the > commit becoming not reachable from the reference (i.e. such a commit > C may not be reachable from the branch---unless the new commit it > points at happens to be a descendant of C) are not one and the same > thing. I do not think there is distinction between expert vs > everyone else involved here at all. > > Can you give an example where one of the two holds while the other > one does not? >
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).
Personally (that may not be a common pattern), I have used two branches for one feature branch. One that holds the tip, and represents my local work. One that I move forward and backward on the branch, to run tests, and decide what I already want to push. Forward could be done by ff-merge, but backward not (it's reset, or switch -C).
--------- About your comment on changes in the worktree. In none of my examples do I have any changes in my worktree.
I know that when I just try to switch a branch, git switch will refuse to overwrite my changes. The doc for the -C section does not say if it will. That is something I actually would still need to check, and if -C in addition to forcing the branch, and consequently but only in some cases "making commits unreachable", does also overwrite working dir changes that would be yet one more "forced" action. That again not everyone may automatically be aware off.