user-manual: add "quick start" as chapter 1

Add a "quick start" guide, modelled after Mercurial's, as the
first chapter.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 369cdad4fa11845f1da7e05880c97df365f690ea..df0f76241bfa42a98baae561106b68c82f32dd35 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4,11 +4,14 @@ _________________
 This manual is designed to be readable by someone with basic unix
 commandline skills, but no previous knowledge of git.
 
-Chapters 1 and 2 explain how to fetch and study a project using
+Chapter 1 gives a brief overview of git commands, without any
+explanation; you can skip to chapter 2 on a first reading.
+
+Chapters 2 and 3 explain how to fetch and study a project using
 git--the tools you'd need to build and test a particular version of a
 software project, to search for regressions, and so on.
 
-Chapter 3 explains how to do development with git, and chapter 4 how
+Chapter 4 explains how to do development with git, and chapter 5 how
 to share that development with others.
 
 Further chapters cover more specialized topics.
@@ -20,6 +23,201 @@ pages.  For a command such as "git clone", just use
 $ man git-clone
 ------------------------------------------------
 
+Git Quick Start
+===============
+
+This is a quick summary of the major commands; the following chapters
+will explain how these work in more detail.
+
+Creating a new repository
+-------------------------
+
+From a tarball:
+
+-----------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init
+Initialized empty Git repository in .git/
+$ git add .
+$ git commit
+-----------------------------------------------
+
+From a remote repository:
+
+-----------------------------------------------
+$ git clone git://example.com/pub/project.git
+$ cd project
+-----------------------------------------------
+
+Managing branches
+-----------------
+
+-----------------------------------------------
+$ git branch        # list all branches in this repo
+$ git checkout test  # switch working directory to branch "test"
+$ git branch new     # create branch "new" starting at current HEAD
+$ git branch -d new  # delete branch "new"
+-----------------------------------------------
+
+Instead of basing new branch on current HEAD (the default), use:
+
+-----------------------------------------------
+$ git branch new test    # branch named "test"
+$ git branch new v2.6.15 # tag named v2.6.15
+$ git branch new HEAD^   # commit before the most recent
+$ git branch new HEAD^^  # commit before that
+$ git branch new test~10 # ten commits before tip of branch "test"
+-----------------------------------------------
+
+Create and switch to a new branch at the same time:
+
+-----------------------------------------------
+$ git checkout -b new v2.6.15
+-----------------------------------------------
+
+Update and examine branches from the repository you cloned from:
+
+-----------------------------------------------
+$ git fetch            # update
+$ git branch -r                # list
+  origin/master
+  origin/next
+  ...
+$ git branch checkout -b masterwork origin/master
+-----------------------------------------------
+
+Fetch a branch from a different repository, and give it a new
+name in your repository:
+
+-----------------------------------------------
+$ git fetch git://example.com/project.git theirbranch:mybranch
+$ git fetch git://example.com/project.git v2.6.15:mybranch
+-----------------------------------------------
+
+Keep a list of repositories you work with regularly:
+
+-----------------------------------------------
+$ git remote add example git://example.com/project.git
+$ git remote           # list remote repositories
+example
+origin
+$ git remote show example # get details
+* remote example
+  URL: git://example.com/project.git
+  Tracked remote branches
+    master next ...
+$ git fetch example    # update branches from example
+$ git branch -r                # list all remote branches
+-----------------------------------------------
+
+
+Exploring history
+-----------------
+
+-----------------------------------------------
+$ gitk                     # visualize and browse history
+$ git log                  # list all commits
+$ git log src/             # ...modifying src/
+$ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
+$ git log master..test     # ...in branch test, not in branch master
+$ git log test..master     # ...in branch master, but not in test
+$ git log test...master            # ...in one branch, not in both
+$ git log -S'foo()'        # ...where difference contain "foo()"
+$ git log --since="2 weeks ago"
+$ git log -p               # show patches as well
+$ git show                 # most recent commit
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
+$ git diff v2.6.15..HEAD    # diff with current head
+$ git grep "foo()"         # search working directory for "foo()"
+$ git grep v2.6.15 "foo()"  # search old tree for "foo()"
+$ git show v2.6.15:a.txt    # look at old version of a.txt
+-----------------------------------------------
+
+Searching for regressions:
+
+-----------------------------------------------
+$ git bisect start
+$ git bisect bad               # current version is bad
+$ git bisect good v2.6.13-rc2  # last known good revision
+Bisecting: 675 revisions left to test after this
+                               # test here, then:
+$ git bisect good              # if this revision is good, or
+$ git bisect bad               # if this revision is bad.
+                               # repeat until done.
+-----------------------------------------------
+
+Making changes
+--------------
+
+Make sure git knows who to blame:
+
+------------------------------------------------
+$ cat >~/.gitconfig <<\EOF
+[user]
+name = Your Name Comes Here
+email = you@yourdomain.example.com
+EOF
+------------------------------------------------
+
+Select file contents to include in the next commit, then make the
+commit:
+
+-----------------------------------------------
+$ git add a.txt    # updated file
+$ git add b.txt    # new file
+$ git rm c.txt     # old file
+$ git commit
+-----------------------------------------------
+
+Or, prepare and create the commit in one step:
+
+-----------------------------------------------
+$ git commit d.txt # use latest content of d.txt
+$ git commit -a           # use latest content of all tracked files
+-----------------------------------------------
+
+Merging
+-------
+
+-----------------------------------------------
+$ git merge test   # merge branch "test" into the current branch
+$ git pull git://example.com/project.git master
+                  # fetch and merge in remote branch
+$ git pull . test  # equivalent to git merge test
+-----------------------------------------------
+
+Sharing development
+-------------------
+
+Importing or exporting patches:
+
+-----------------------------------------------
+$ git format-patch origin..HEAD # format a patch for each commit
+                               # in HEAD but not in origin
+$ git-am mbox # import patches from the mailbox "mbox"
+-----------------------------------------------
+
+Fetch a branch from a different git repository:
+
+-----------------------------------------------
+$ git fetch git://example.com/project.git theirbranch:mybranch
+-----------------------------------------------
+
+Fetch a branch in a different git repository, then merge into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch
+-----------------------------------------------
+
+Store the fetched branch into a local branch before merging into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch:mybranch
+-----------------------------------------------
+
 Repositories and Branches
 =========================