Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Martin <git@mfriebe.de> writes:

> On 11/07/2021 09:57, Sergey Organov wrote:
>> Martin <git@mfriebe.de> writes:
>> 
>> [...]
>> 
>>> Currently only the branch is mentioned.
>>> Currently nothing does explicitly say that *commits* can be affected.
>> Commits cannot be immediately affected. One of the most essential
>> features of Git is that commits could only be affected (deleted) by
>> garbage collection. That's what makes Git so nicely safe in operation.
>> It'd be unfortunate to have statements in the manual pages that
>> contradict this.
>> 
>
> Tell that a new user, who never heard of "dangling commits" or the reflog.
>
> For ages, I wondered what git fsck meant by "dangling commits" and why
> my repro always had "that problem".
> And what I might do with that hash it gave me.
>
> For a new user, a commit that is not in any branch listed by
> "git branch --all" or "git stash"
> is effectively not existent.
>
> For a new user, it is also "no help" (and the doc should help) to
> avoid saying it, and instead refer to something else from which it
> could be
> concluded.
> "reset the branch" talks about the branch, and not the commit.
> A new user, even if he read about it before, may very well not make
> the conclusion.
> So "reset the branch" does nothing for a new user. And an expert
> already knows it. So for whom should that be there?
>
> We can use the term unreachable. But it is no better than say "drop"
>
> Technically they are not "unreachable". If I have the hash, I (as
> expert) can reach them.
> If I do not, I can get it from "fsck". (And spend a good amount of
> time, going through a few dozen hashes. (That is, if the reflog was
> disabled)
>
> "Drop" does not mean "deleted". More like "dropped from view", "given up"
> But a new user reading "dropped" will take it as a hint to be careful.
>
> We can add "dropped commit" to the glossary. Then there is no
> ambiguity. (I don't think its needed, but...)
>
> We can say "may no longer have a reference" instead of "dropped"
> But it is long, and again obscure (to a new user).

As I just stated in anther answer, which see, I see what you mean. I'm
still against "dropped" though.

I did suggest a wording in that post:

"Allows to reuse <branch-name>. Commits from the former branch may
become unreferenced."

Another one could be:

"Allows to reuse <branch-name>. Commits from the former branch could be
lost."

Thanks,
-- 
Sergey Organov