Documentation: revise top of git man page

I'm afraid I'll be accused of trying to suck all the jokes and the
personality out of the git documentation.  I'm not!  Really!

That said, "man git" is one of the first things a new user is likely try,
and it seems a little cruel to start off with a somewhat obscure joke
about the architecture of git.

So instead I'm trying for a relatively straightforward description of what
git does, and what features distinguish it from other systems, together
with immediate links to introductory documentation.

I also did some minor reorganization in an attempt to clarify the
classification of commands.  And revised a bit for conciseness (as is
obvious from the diffstat--hopefully I didn't cut anything important).

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/git.txt b/Documentation/git.txt
index fe34f50..06b2e53 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -12,10 +12,14 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-'git' is both a program and a directory content tracker system.
-The program 'git' is just a wrapper to reach the core git programs
-(or a potty if you like, as it's not exactly porcelain but still
-brings your stuff to the plumbing).
+Git is a fast, scalable, distributed revision control system with an
+unusually rich command set that provides both high-level operations
+and full access to internals.
+
+See this link:tutorial.html[tutorial] to get started, then see
+link:everyday.html[Everyday Git] for a useful minimum set of commands, and
+"man git-commandname" for documentation of each command.  CVS users may
+also want to read link:cvs-migration.html[CVS migration].
 
 OPTIONS
 -------
@@ -35,55 +39,38 @@ OPTIONS
        the current setting and then exit.
 
 
-NOT LEARNING CORE GIT COMMANDS
-------------------------------
-
-This manual is intended to give complete background information
-and internal workings of git, which may be too much for most
-people.  The <<Discussion>> section below contains much useful
-definition and clarification - read that first.
-
-If you are interested in using git to manage (version control)
-projects, use link:tutorial.html[The Tutorial] to get you started,
-and then link:everyday.html[Everyday GIT] as a guide to the
-minimum set of commands you need to know for day-to-day work.
-Most likely, that will get you started, and you can go a long
-way without knowing the low level details too much.
-
-The link:core-tutorial.html[Core tutorial] document covers how things
-internally work.
-
-If you are migrating from CVS, link:cvs-migration.html[cvs
-migration] document may be helpful after you finish the
-tutorial.
+FURTHER DOCUMENTATION
+---------------------
 
-After you get the general feel from the tutorial and this
-overview page, you may want to take a look at the
-link:howto-index.html[howto] documents.
+See the references above to get started using git.  The following is
+probably more detail than necessary for a first-time user.
 
+The <<Discussion,Discussion>> section below and the
+link:core-tutorial.html[Core tutorial] both provide introductions to the
+underlying git architecture.
 
-CORE GIT COMMANDS
------------------
+See also the link:howto-index.html[howto] documents for some useful
+examples.
 
-If you are writing your own Porcelain, you need to be familiar
-with most of the low level commands --- I suggest starting from
-gitlink:git-update-index[1] and gitlink:git-read-tree[1].
+GIT COMMANDS
+------------
 
+We divide git into high level ("porcelain") commands and low level
+("plumbing") commands.
 
-Commands Overview
------------------
-The git commands can helpfully be split into those that manipulate
-the repository, the index and the files in the working tree, those that
-interrogate and compare them, and those that moves objects and
-references between repositories.
+Low-level commands (plumbing)
+-----------------------------
 
-In addition, git itself comes with a spartan set of porcelain
-commands.  They are usable but are not meant to compete with real
-Porcelains.
+Although git includes its
+own porcelain layer, its low-level commands are sufficient to support
+development of alternative porcelains.  Developers of such porcelains
+might start by reading about gitlink:git-update-index[1] and
+gitlink:git-read-tree[1].
 
-There are also some ancillary programs that can be viewed as useful
-aids for using the core commands but which are unlikely to be used by
-SCMs layered over git.
+We divide the low-level commands into commands that manipulate objects (in
+the repository, index, and working tree), commands that interrogate and
+compare objects, and commands that move objects and references between
+repositories.
 
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
@@ -248,8 +235,14 @@ gitlink:git-upload-pack[1]::
        what are asked for.
 
 
-Porcelain-ish Commands
-----------------------
+High-level commands (porcelain)
+-------------------------------
+
+We separate the porcelain commands into the main commands and some
+ancillary user utilities.
+
+Main porcelain commands
+~~~~~~~~~~~~~~~~~~~~~~~
 
 gitlink:git-add[1]::
        Add paths to the index.
@@ -346,7 +339,7 @@ gitlink:git-whatchanged[1]::
 
 
 Ancillary Commands
-------------------
+~~~~~~~~~~~~~~~~~~
 Manipulators:
 
 gitlink:git-applypatch[1]::