Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Martin <git@mfriebe.de> writes:

> On 01/07/2021 16:58, Junio C Hamano wrote:
>> If I understand you correctly, the confusion your hypothetical
>> newbie would have is caused by the word "start-point" in
>>
>> 	git branch -f <branch-name> <start-point>
>>
>> That is, if we repoint the branch that is currently at Z to point at
>> X with "git branch -f B X", it is possible to imagine that we build
>> more history on top of "X" simply because "X" is called "start-point",
>> i.e. we start at X and do something more.
> It is probably more the use of the word "branch" than it is "start point"
>
> Sergey made an excellent point:
>> On 01/07/2021 13:27, Sergey Organov wrote:
>>> For example:
>>>
>>> "branch": a chain of commits
>>>
>>> "branch tip": the most recent commit in a branch
>>>
>>> "branch name": specific type of symbolic reference pointing to a branch tip
>
> A lot of people think of the "chain of commits" when the word "branch" is used.
>
> If we take the sentence from the current doc:
>    --force-create
>     Similar to |--create| except that if |<new-branch>| already
> exists, it will be reset to |<start-point>|
> and replace "branch" with "chain of commits"
>     Similar to |--create| except that if |<new-||"chain of commits">|
> already exists, it will be reset to |<start-point>|
>
> What would you expect to happen?
> I would think the "chain of commits" is created at the new
> <start-point>

I find current "git switch" documentation utterly confusing, even for
experienced user, let alone for a novice. I'm only afraid that it's not
only documentation, but the design as well.

>
> What we want to say is
>     The "branch name" will point to a new "branch tip" at <start-point>
>
> However, this still leaves the point, that new users need to
> understand certain concepts and implications.
> Such as moving a "branch name" abandons the old "chain of commits" (they do not follow).
> "branch name" helps to remember that distinction, but it still needs to be learned first.
> "abandon" => leave them to the reflog until expiry.

Not necessarily. There could be other references left to this exact
commit. User doesn't need to be aware of reflog at this point at all.

>
> The point is, that those concepts (difference between branchname, and
> commits in branch) may all be documented.
> But the reader may still be learning all this.

There is no way around. Either they are expected to understand basics,
or documentation will lie to them trying to be helpful, that'd only
create even more confusion.

Thanks,

-- 
Sergey Organov