The best example I can think of right now as to where git's documentation is unusable: suppose you accidentally git add'd a file, and you want to remove it without deleting it on disk (since, you know, that's your only copy of it). This doesn't come up very often, so there's no way you're going to remember the command off the top of your head. The most reasonable guess is "it sounds like a special rm, so let's look at the documentation for rm."
Here's hg help rm:
remove the specified files on the next commit
Schedule the indicated files for removal from the current branch.
This command schedules the files to be removed at the next commit. To undo
a remove before that, see 'hg revert'. To undo added files, see 'hg
forget'.
Oh, I don't want hg rm, I want hg forget. hg help forget confirms this:
This only removes files from the current branch, not from the entire
project history, and it does not delete them from the working directory.
Okay, let's ask git help rm:
Remove files from the index, or from the working tree and the index.
git rm will not remove a file from just your working directory. (There
is no option to remove a file only from the working tree and yet keep
it in the index; use /bin/rm if you want to do that.) The files being
removed have to be identical to the tip of the branch, and no updates
to their contents can be staged in the index, though that default
behavior can be overridden with the -f option. When --cached is given,
the staged content has to match either the tip of the branch or the
file on disk, allowing the file to be removed from just the index.
For this to be any use, you have to remember that "index" refers to the staging area and not anything else that might reasonably be presumed to be an index (such as the commit history). Of course, if you knew there was a glossary, you could double-check the definition in the glossary, only to find that the definition (a collection of files with stat information, whose contents are stored as objects) is about as useful as the infamous "a monad is a monoid in the category of endofunctors," but the latter was supposed to be a joke.
Sure, some problems with git may be that people have trouble understanding the concepts. But many of them are due to git's impenetrable documentation and a few of the commands that do too many things. The sheer resistance of many adherents of git to recognize that it has a UX problem is just mind-boggling.
In such cases, I look for my problem on stackoverflow. When I find a solution which seems right to me, I look up https://git-scm.com/docs to get a better understanding of what I am doing and why.
The problem with many documentations is that they are not use-case driven. Much of it is a functionality description. Such as:
- To fasten, you have to turn the nut clockwise.
instead of:
- To fit these two parts together you need to fasten the nuts onto the screws.
Here's hg help rm:
Oh, I don't want hg rm, I want hg forget. hg help forget confirms this: Okay, let's ask git help rm: For this to be any use, you have to remember that "index" refers to the staging area and not anything else that might reasonably be presumed to be an index (such as the commit history). Of course, if you knew there was a glossary, you could double-check the definition in the glossary, only to find that the definition (a collection of files with stat information, whose contents are stored as objects) is about as useful as the infamous "a monad is a monoid in the category of endofunctors," but the latter was supposed to be a joke.Sure, some problems with git may be that people have trouble understanding the concepts. But many of them are due to git's impenetrable documentation and a few of the commands that do too many things. The sheer resistance of many adherents of git to recognize that it has a UX problem is just mind-boggling.