user-manual: add "quick start" as chapter 1
authorJ. Bruce Fields <bfields@citi.umich.edu>
Sun, 21 Jan 2007 02:41:48 +0000 (21:41 -0500)
committerJ. Bruce Fields <bfields@citi.umich.edu>
Sun, 21 Jan 2007 02:41:48 +0000 (21:41 -0500)
Add a "quick start" guide, modelled after Mercurial's, as the
first chapter.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Documentation/user-manual.txt
index 369cdad4fa11845f1da7e05880c97df365f690ea..df0f76241bfa42a98baae561106b68c82f32dd35 100644 (file)
@@ -4,11 +4,14 @@ _________________
 This manual is designed to be readable by someone with basic unix
 commandline skills, but no previous knowledge of git.
 
 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.
 
 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.
 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
 ------------------------------------------------
 
 $ 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
 =========================
 
 Repositories and Branches
 =========================