Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

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