@matheusbsbs / matheus-bagliano / commits / ef89f701a0
Fork 0

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>

J. Bruce Fields committed Jan 20, 2007 at 21:41 UTC ef89f701a0c214fa2967e921f8d3891e25cf3125
1 file changed +200 -2
Documentation/user-manual.txt
+200 -2
@@ -4,11 +4,14 @@ _________________
4 This manual is designed to be readable by someone with basic unix
5 commandline skills, but no previous knowledge of git.
6
7 -Chapters 1 and 2 explain how to fetch and study a project using
7 +Chapter 1 gives a brief overview of git commands, without any
8 +explanation; you can skip to chapter 2 on a first reading.
9 +
10 +Chapters 2 and 3 explain how to fetch and study a project using
11 git--the tools you'd need to build and test a particular version of a
12 software project, to search for regressions, and so on.
13
11 -Chapter 3 explains how to do development with git, and chapter 4 how
14 +Chapter 4 explains how to do development with git, and chapter 5 how
15 to share that development with others.
16
17 Further chapters cover more specialized topics.
@@ -20,6 +23,201 @@ pages. For a command such as "git clone", just use
23 $ man git-clone
24 ------------------------------------------------
25
26 +Git Quick Start
27 +===============
28 +
29 +This is a quick summary of the major commands; the following chapters
30 +will explain how these work in more detail.
31 +
32 +Creating a new repository
33 +-------------------------
34 +
35 +From a tarball:
36 +
37 +-----------------------------------------------
38 +$ tar xzf project.tar.gz
39 +$ cd project
40 +$ git init
41 +Initialized empty Git repository in .git/
42 +$ git add .
43 +$ git commit
44 +-----------------------------------------------
45 +
46 +From a remote repository:
47 +
48 +-----------------------------------------------
49 +$ git clone git://example.com/pub/project.git
50 +$ cd project
51 +-----------------------------------------------
52 +
53 +Managing branches
54 +-----------------
55 +
56 +-----------------------------------------------
57 +$ git branch # list all branches in this repo
58 +$ git checkout test # switch working directory to branch "test"
59 +$ git branch new # create branch "new" starting at current HEAD
60 +$ git branch -d new # delete branch "new"
61 +-----------------------------------------------
62 +
63 +Instead of basing new branch on current HEAD (the default), use:
64 +
65 +-----------------------------------------------
66 +$ git branch new test # branch named "test"
67 +$ git branch new v2.6.15 # tag named v2.6.15
68 +$ git branch new HEAD^ # commit before the most recent
69 +$ git branch new HEAD^^ # commit before that
70 +$ git branch new test~10 # ten commits before tip of branch "test"
71 +-----------------------------------------------
72 +
73 +Create and switch to a new branch at the same time:
74 +
75 +-----------------------------------------------
76 +$ git checkout -b new v2.6.15
77 +-----------------------------------------------
78 +
79 +Update and examine branches from the repository you cloned from:
80 +
81 +-----------------------------------------------
82 +$ git fetch # update
83 +$ git branch -r # list
84 + origin/master
85 + origin/next
86 + ...
87 +$ git branch checkout -b masterwork origin/master
88 +-----------------------------------------------
89 +
90 +Fetch a branch from a different repository, and give it a new
91 +name in your repository:
92 +
93 +-----------------------------------------------
94 +$ git fetch git://example.com/project.git theirbranch:mybranch
95 +$ git fetch git://example.com/project.git v2.6.15:mybranch
96 +-----------------------------------------------
97 +
98 +Keep a list of repositories you work with regularly:
99 +
100 +-----------------------------------------------
101 +$ git remote add example git://example.com/project.git
102 +$ git remote # list remote repositories
103 +example
104 +origin
105 +$ git remote show example # get details
106 +* remote example
107 + URL: git://example.com/project.git
108 + Tracked remote branches
109 + master next ...
110 +$ git fetch example # update branches from example
111 +$ git branch -r # list all remote branches
112 +-----------------------------------------------
113 +
114 +
115 +Exploring history
116 +-----------------
117 +
118 +-----------------------------------------------
119 +$ gitk # visualize and browse history
120 +$ git log # list all commits
121 +$ git log src/ # ...modifying src/
122 +$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
123 +$ git log master..test # ...in branch test, not in branch master
124 +$ git log test..master # ...in branch master, but not in test
125 +$ git log test...master # ...in one branch, not in both
126 +$ git log -S'foo()' # ...where difference contain "foo()"
127 +$ git log --since="2 weeks ago"
128 +$ git log -p # show patches as well
129 +$ git show # most recent commit
130 +$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
131 +$ git diff v2.6.15..HEAD # diff with current head
132 +$ git grep "foo()" # search working directory for "foo()"
133 +$ git grep v2.6.15 "foo()" # search old tree for "foo()"
134 +$ git show v2.6.15:a.txt # look at old version of a.txt
135 +-----------------------------------------------
136 +
137 +Searching for regressions:
138 +
139 +-----------------------------------------------
140 +$ git bisect start
141 +$ git bisect bad # current version is bad
142 +$ git bisect good v2.6.13-rc2 # last known good revision
143 +Bisecting: 675 revisions left to test after this
144 + # test here, then:
145 +$ git bisect good # if this revision is good, or
146 +$ git bisect bad # if this revision is bad.
147 + # repeat until done.
148 +-----------------------------------------------
149 +
150 +Making changes
151 +--------------
152 +
153 +Make sure git knows who to blame:
154 +
155 +------------------------------------------------
156 +$ cat >~/.gitconfig <<\EOF
157 +[user]
158 +name = Your Name Comes Here
159 +email = you@yourdomain.example.com
160 +EOF
161 +------------------------------------------------
162 +
163 +Select file contents to include in the next commit, then make the
164 +commit:
165 +
166 +-----------------------------------------------
167 +$ git add a.txt # updated file
168 +$ git add b.txt # new file
169 +$ git rm c.txt # old file
170 +$ git commit
171 +-----------------------------------------------
172 +
173 +Or, prepare and create the commit in one step:
174 +
175 +-----------------------------------------------
176 +$ git commit d.txt # use latest content of d.txt
177 +$ git commit -a # use latest content of all tracked files
178 +-----------------------------------------------
179 +
180 +Merging
181 +-------
182 +
183 +-----------------------------------------------
184 +$ git merge test # merge branch "test" into the current branch
185 +$ git pull git://example.com/project.git master
186 + # fetch and merge in remote branch
187 +$ git pull . test # equivalent to git merge test
188 +-----------------------------------------------
189 +
190 +Sharing development
191 +-------------------
192 +
193 +Importing or exporting patches:
194 +
195 +-----------------------------------------------
196 +$ git format-patch origin..HEAD # format a patch for each commit
197 + # in HEAD but not in origin
198 +$ git-am mbox # import patches from the mailbox "mbox"
199 +-----------------------------------------------
200 +
201 +Fetch a branch from a different git repository:
202 +
203 +-----------------------------------------------
204 +$ git fetch git://example.com/project.git theirbranch:mybranch
205 +-----------------------------------------------
206 +
207 +Fetch a branch in a different git repository, then merge into the
208 +current branch:
209 +
210 +-----------------------------------------------
211 +$ git pull git://example.com/project.git theirbranch
212 +-----------------------------------------------
213 +
214 +Store the fetched branch into a local branch before merging into the
215 +current branch:
216 +
217 +-----------------------------------------------
218 +$ git pull git://example.com/project.git theirbranch:mybranch
219 +-----------------------------------------------
220 +
221 Repositories and Branches
222 =========================
223