|
I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes. GNU packages often have documentation that's bad in the typical "Linux docs are bad" way. Try `man less`. First, it commits a grave sin in having a totally useless one-line summary, which reads "less - opposite of more". Funny, but totally useless and doesn't even remotely suggest what the command does (if you know what more is on UNIX, you surely know what less does). Or `man grep`. It's a reference page, very good for knowing what all the options do, but with no useful everyday examples, and with gems like these: > Finally, certain named classes of characters are predefined within bracket expressions, as follows. Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. Self explanatory? Yes, if you used grep in the 90s. Is alnum alphanumeric or all numbers? Is alpha short for alphabet, as in what most people would intuitively call letters? What's xdigit? Extra digits? Except digits? Oh, it's hex digits. Pretty obvious that periods and commas are in punct... but also + * - {} are punct, among other stuff. `man tar` is extremely comprehensive, an impressive reference, but very hard to figure out if you've never used tar. I've been recently looking at FreeBSD documentation for common commands, and the source code as well. Both are so much better than the usual GNU versions you find on Linux. |
Having used both Mercurial and git, it is my general experience that Mercurial has a much better documentation system. Git's documentation has improved, but mostly only in the more-well-used commands; when you want to reach for more exotic stuff, you start to find that the documentation is too full of jargon.
As a recent example, I wanted to get a list of files managed by git. Since I know mercurial best, I wanted the equivalent of hg manifest. Its documentation is thus:
> hg manifest [-r REV]
> output the current or given revision of the project manifest
> Print a list of version controlled files for the given revision. If no revision is given, the first parent of the working directory is used, or the null revision if no revision is checked out.
This is unusually bad documentation for mercurial--the short description and command name are reliant on jargon, and it's not aliased to "hg ls" or something like that. Okay, how about the equivalent git command? git ls-files looks promising. Here's its short description:
> git-ls-files - Show information about files in the index and the working tree
But its description is, um:
> This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two.
Mercurial suffers from a bit of jargon, but reading its description would enlighten you as to what it does without understanding the jargon. Git's documentation here starts with jargon, and then doubles down on it so that the more I read, the less sure I am about what it actually does. [In the end, by actually running it, I did verify that it's basically the equivalent of hg manifest].
Now both mercurial and git have a glossary (help glossary), but I've never seen anyone actually point a newbie to either one. Of course, here you can also see the world of difference in the documentation quality. Mercurial's glossary entry for the jargon term "manifest" says:
> Each changeset has a manifest, which is the list of files that are tracked by the changeset.
Now compare git's glossary entry for "index":
> A collection of files with stat information, whose contents are stored as objects. The index is a stored version of your working tree. Truth be told, it can also contain a second, and even a third version of a working tree, which are used when merging.
... and that is why people like me say that git suffers from poor documentation.