Re: as promised, docs: git for the confused

From: linux@horizon.com <linux@horizon.com>
Date: Dec 9, 2005, 14:01 UTC
Message-ID: <20051209140123.3234.qmail@science.horizon.com>
In-Reply-To: <20051209094328.GT22159@pasky.or.cz>

>   BTW, such a "wide" reply is a bit hard to handle - it might be perhaps
> more practical to make separate replies at least to the mails whose
> contents does not overlap. Also, people would not get Cc's of subthreads
> they are not involved with.

Sorry... it was one edit session while I made all the corrections, and it was just more natural...

>> Unfortunately, given the number of commands, you can't just document
>> them well individually.  Some overview of how they fit together into
>> a system is required.

Show 7 quoted lines

> Hmm. Well, actually... what's the point? If I want to get a really quick
> overview, I do
>
>	whatis git
>
> and it will DTRT. But when do I need something more detailed but not yet
> the manual page of the given command?

"I want to do X and Y but not Z.  What commands are worth knowing?"

I have 106 git-* commands available to me (my document covers 105; I'll have to find the extra), and the biggest question I have is "how many of those man pages can I get away with NOT reading?"

Heck, that categorized list is what I started out writing, and I happen to think it's the most important part of the whole document.

The man page tells me HOW to execute a command. But before I'm ready for that level of detail, I need to figure out WHICH command to execute. To be specific, I need to know the terrain just well enough so I can plan a route from where I am to where I want to be. Then I can look into the details of each step.

But without that overview, my trip is going to take me into a lot of dead ends, because I'm executing commands that I think are getting me closer, but I have the wrong mental model of what "close" is.

Or perhaps I found one command that sort-of does what I want an missed the one that works better.

(BTW, don't you mean "whatis -w git\*"?)