Re: as promised, docs: git for the confused

[linux@horizon.com]

>   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.

> 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\*"?)