From ef89f701a0c214fa2967e921f8d3891e25cf3125 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 20 Jan 2007 21:41:48 -0500 Subject: [PATCH] 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" --- Documentation/user-manual.txt | 202 +++++++++++++++++++++++++++++++++- 1 file changed, 200 insertions(+), 2 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 369cdad4fa..df0f76241b 100644 --- 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 =========================