Re: as promised, docs: git for the confused

[Junio C Hamano <junkio@cox.net>]

linux@horizon.com writes:

> "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?"

This primarily comes from the way git is architected.  We have
many commands that are not so interesting from the end-user
perspective.  If git were architected differently, many of them
may not exist in executable command form, but would instead be
library functions and listed in section 3git of the manual.

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

And I think I agree it but with a twist.  The full listing for
Porcelain writers is mostly fine as is in git(7); maybe what you
wrote have clarification material, in which case I'd appreciate
a patch to Documentation/git.txt.

What we need is a separate list aimed for end users, and
somebody looking only at that list should be able to do
day-to-day work with only the commands listed there, and does
not even have to know something called rev-parse or merge-base
exist.

A good start for this list would be the list of selected
commands git.sh used to show (these days, git.c wrapper shows
everything that starts with "git", but the old one limited
itself to show only the ones that may be useful by the
end-user).

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

Exactly.  The tutorial can also use a minor split.  It starts
out to give taste of internal workins of Porcelains, but ends up
being a fuzzy mix of "user manual" and "hints to porcelain
writers".  We probably should have a separate "end user
tutorial" --- the Alice-Bob scenario by Horst might be a good
place to start.