Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 30/06/2021 00:39, Junio C Hamano wrote:
> 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.

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