mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation: revise top of git man page

Browse Source 
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>
This commit is contained in:
J. Bruce Fields
2006-04-02 17:54:34 -04:00
committed by Junio C Hamano
parent ec26b4d6b0
commit 23091e954c
1 changed files with 41 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
Documentation/git.txt
View File

@ -12,10 +12,14 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
----------- -----------
'git' is both a program and a directory content tracker system. Git is a fast, scalable, distributed revision control system with an
The program 'git' is just a wrapper to reach the core git programs unusually rich command set that provides both high-level operations
(or a potty if you like, as it's not exactly porcelain but still and full access to internals.
brings your stuff to the plumbing).
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 OPTIONS
------- -------
@ -35,55 +39,38 @@ OPTIONS
the current setting and then exit. the current setting and then exit.
NOT LEARNING CORE GIT COMMANDS FURTHER DOCUMENTATION
------------------------------ ---------------------
This manual is intended to give complete background information See the references above to get started using git. The following is
and internal workings of git, which may be too much for most probably more detail than necessary for a first-time user.
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) The <<Discussion,Discussion>> section below and the
projects, use link:tutorial.html[The Tutorial] to get you started, link:core-tutorial.html[Core tutorial] both provide introductions to the
and then link:everyday.html[Everyday GIT] as a guide to the underlying git architecture.
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 See also the link:howto-index.html[howto] documents for some useful
internally work. examples.
If you are migrating from CVS, link:cvs-migration.html[cvs GIT COMMANDS
migration] document may be helpful after you finish the ------------
tutorial.
After you get the general feel from the tutorial and this We divide git into high level ("porcelain") commands and low level
overview page, you may want to take a look at the ("plumbing") commands.
link:howto-index.html[howto] documents.
Low-level commands (plumbing)
-----------------------------
CORE GIT COMMANDS 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].
If you are writing your own Porcelain, you need to be familiar We divide the low-level commands into commands that manipulate objects (in
with most of the low level commands --- I suggest starting from the repository, index, and working tree), commands that interrogate and
gitlink:git-update-index[1] and gitlink:git-read-tree[1]. compare objects, and commands that move objects and references between
repositories.
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.
In addition, git itself comes with a spartan set of porcelain
commands. They are usable but are not meant to compete with real
Porcelains.
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.
Manipulation commands Manipulation commands
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -248,8 +235,14 @@ gitlink:git-upload-pack[1]::
what are asked for. 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]:: gitlink:git-add[1]::
Add paths to the index. Add paths to the index.
@ -346,7 +339,7 @@ gitlink:git-whatchanged[1]::
Ancillary Commands Ancillary Commands
------------------ ~~~~~~~~~~~~~~~~~~
Manipulators: Manipulators:
gitlink:git-applypatch[1]:: gitlink:git-applypatch[1]::