The first one, as other people have already brought up, is that looking through man pages is not the natural entry point for most users.
The second factor is that having some good help doesn't excuse the poor quality of most of the rest of the help. It's notable that you don't refer to the "git glossary" as a good entrypoint, especially since (given the next factor I'm about to elaborate), it really ought to be a useful companion. Instead, every time I try to look something up in the git glossary, I somehow end up even more confused than when I started--the help there is literally the opposite of helpful.
The third factor is the worst problem with the help: it's absolutely laden with confusing jargon. An example I easily recall is that the "staging area"--the name by which it's pretty universally known to users, in my experience--is almost universally referred to as the "index" in git's documentation, and almost nowhere else is it referred to as that. Index is a particularly bad term in this case because, if I were to list the things in a version control system I might wish to build indexes of, the changes that are being staged for a commit yet to come is not going to rank very high.
The final factor is that the poor structure of the git CLI system means that you have to rely on the help. It's notable that the poor CLI of git keeps coming up in discussions about it, far more than any other tool I've ever seen--I can't recall any complaints about any other VCS's CLI, even accounting for their collective (now) lesser popularity. It is pretty clearly objectively bad.
A great example that combines many of these points is 'git reset.' Looking at the help documentation, in the opening paragraph:
In the first three forms, copy entries from <tree-ish> to the index. In
the last form, set the current branch head (HEAD) to <commit>,
optionally modifying index and working tree to match. The
<tree-ish>/<commit> defaults to HEAD in all forms.
It outright starts by admitting that it does different things depending on how its invoked. The help immediately launches into jargon--what is a <tree-ish>? what is the index? If I'm trying to figure out how to do something--say get an older version of a file--this doesn't immediately jump out at me as being what I want...nor does it jump out as not being what I want.
I could try laboring through the help here... or I can give up, search the internet for "git get older version of a file" and be reasonably confident that I will get an answer to my question, since somebody has likely asked my question with almost exactly the words I used. And when I choose the latter method, like so many users do, git becomes a list of canned commands that are risky to venture beyond, for if I do, I run the risk of losing data, especially because operations that might repair the repository are not going to be on that list.
After finally reading about how git works internally, I can sort of see how someone that made it would write their man pages like that. With understanding of the internals it makes perfect sense.
But barely anybody that uses git cares about it’s internals.
The first one, as other people have already brought up, is that looking through man pages is not the natural entry point for most users.
The second factor is that having some good help doesn't excuse the poor quality of most of the rest of the help. It's notable that you don't refer to the "git glossary" as a good entrypoint, especially since (given the next factor I'm about to elaborate), it really ought to be a useful companion. Instead, every time I try to look something up in the git glossary, I somehow end up even more confused than when I started--the help there is literally the opposite of helpful.
The third factor is the worst problem with the help: it's absolutely laden with confusing jargon. An example I easily recall is that the "staging area"--the name by which it's pretty universally known to users, in my experience--is almost universally referred to as the "index" in git's documentation, and almost nowhere else is it referred to as that. Index is a particularly bad term in this case because, if I were to list the things in a version control system I might wish to build indexes of, the changes that are being staged for a commit yet to come is not going to rank very high.
The final factor is that the poor structure of the git CLI system means that you have to rely on the help. It's notable that the poor CLI of git keeps coming up in discussions about it, far more than any other tool I've ever seen--I can't recall any complaints about any other VCS's CLI, even accounting for their collective (now) lesser popularity. It is pretty clearly objectively bad.
A great example that combines many of these points is 'git reset.' Looking at the help documentation, in the opening paragraph:
It outright starts by admitting that it does different things depending on how its invoked. The help immediately launches into jargon--what is a <tree-ish>? what is the index? If I'm trying to figure out how to do something--say get an older version of a file--this doesn't immediately jump out at me as being what I want...nor does it jump out as not being what I want.I could try laboring through the help here... or I can give up, search the internet for "git get older version of a file" and be reasonably confident that I will get an answer to my question, since somebody has likely asked my question with almost exactly the words I used. And when I choose the latter method, like so many users do, git becomes a list of canned commands that are risky to venture beyond, for if I do, I run the risk of losing data, especially because operations that might repair the repository are not going to be on that list.