Comment by blharr

If you memorize the documentation I suppose there's no problem with it, but even then there's confusing things from the beginning design approach.

Like, reset vs revert vs restore, using three similar starting synonyms for different operations.

Reset is particularly confusing because it sounds incredibly destructive, but if you do a soft 'git reset', it just moves the "changes to be committed" to be not staged for the commit.

Then, if you change a single flag (--hard) it is destructive, instead erasing all those changes from your disk.

And there's a reason nobody reads the docs, because they're laid out confusingly at first glance to an unfamiliar person.

If I go to git-scm.com, click docs, the first suggestion is the reference manual. The first guide is on "gitattributes" which gives no philosophy or context as to what it is even used for. Ok, maybe, I'll just check the complete list of git commands... and it starts talking about porcelain and plumbing. Nope, thats not what I need. Maybe try the link "git" under Setup and Config. There the description finally links to a useful "gittutorial" page.

The gittutorial even has some confusing or specific terminology that makes git seem hard. From the beginning of importing a new project "Assume you have a tarball project.tar.gz with your initial work"... why do we need to refer to tar at all, and it doesn't even do the credit of explaining the tar xzf command or what that tarball is. It could easily say 'assume you have a directory', which is the more common case and be 200% more simple.