Re: as promised, docs: git for the confused

From: Junio C Hamano <junkio@cox.net>
Date: Dec 9, 2005, 19:12 UTC
Message-ID: <7vzmna2ig2.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20051209140123.3234.qmail@science.horizon.com>

linux@horizon.com writes:

Show 5 quoted lines

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