Re: git blame [was: git and bzr]

From: Linus Torvalds <torvalds@osdl.org>
Date: Nov 30, 2006, 18:44 UTC
Message-ID: <Pine.LNX.4.64.0611301034420.3513@woody.osdl.org>
In-Reply-To: <456F21D6.1060200@webdrake.net>

On Thu, 30 Nov 2006, Joseph Wakeling wrote:

Show 5 quoted lines

> 
> What would be nice would be to have in the documentation a whole bunch
> of stupid examples for the main commands, something where someone can
> create a repo from scratch, create and modify some simple files
> according to instructions, and see the particular command in action.

100% agreed. A lot of the man-pages etc have been written to be about the technology, not about the _use_ of it.

I encouraged people at some point to add an "Examples" section to some of the functions to show what it all _means_, so for "man git-log", I think some of the most useful stuff is that examples section that shows the combination of revision naming and path-name limiting, for example. I personally think that that is a much better way of teaching people what the commands actually do than by mentioning the arguments one by one.

But that only exists for a couple of man-pages, and mostly for the simple ones at that. And a lot of the real examples would need "real data" to work on, so it can't easily be done as a trivial example in a man-page, it really needs a tutorial to "build up" to the situation where you can then explain with an example what to do.

> The tutorials do this, of course, but only for a few cases, when to be
> honest it's the more complex commands that most need such explanation.

Yeah. The git "tutorial.txt" should be extended, and preferably be a while nice set of "follow along with the bouncing ball" kind of web-page sequence.

So I absolutely agree. It's just that at least me personally, I just can't write documentation. I wrote some of the original tutorial, I've written some of the original tech docs, but I just can't get into the whole "document it" mindset, especially not from a user perspective. It doesn't float my boat, and judging by a lot of the discussions, I obviously also don't even see why something could _possibly_ cause confusion.

To make things worse, a lot of the docs (and by that I also mean some of the error messages and helpful hints) tend to be old.

The whole fact that "git commit" mentions "git update-index" is exactly that kind of thing: it's largely a legacy message. You'd almost never actually _use_ git-update-index itself these days, and it's much more convenient to just list the files you want to commit to "git commit" directly (or just use the -a flag, if that is what you want to do).

But that message exists, because it was written in an earlier age.