Merge branch 'lt/tree-2'
[git/git.git] / Documentation / tutorial.txt
1 A tutorial introduction to git
2 ==============================
3
4 This tutorial explains how to import a new project into git, make
5 changes to it, and share changes with other developers.
6
7 First, note that you can get documentation for a command such as "git
8 diff" with:
9
10 ------------------------------------------------
11 $ man git-diff
12 ------------------------------------------------
13
14 Importing a new project
15 -----------------------
16
17 Assume you have a tarball project.tar.gz with your initial work. You
18 can place it under git revision control as follows.
19
20 ------------------------------------------------
21 $ tar xzf project.tar.gz
22 $ cd project
23 $ git init-db
24 ------------------------------------------------
25
26 Git will reply
27
28 ------------------------------------------------
29 defaulting to local storage area
30 ------------------------------------------------
31
32 You've now initialized the working directory--you may notice a new
33 directory created, named ".git". Tell git that you want it to track
34 every file under the current directory with
35
36 ------------------------------------------------
37 $ git add .
38 ------------------------------------------------
39
40 Finally,
41
42 ------------------------------------------------
43 $ git commit -a
44 ------------------------------------------------
45
46 will prompt you for a commit message, then record the current state
47 of all the files to the repository.
48
49 Try modifying some files, then run
50
51 ------------------------------------------------
52 $ git diff
53 ------------------------------------------------
54
55 to review your changes. When you're done,
56
57 ------------------------------------------------
58 $ git commit -a
59 ------------------------------------------------
60
61 will again prompt your for a message describing the change, and then
62 record the new versions of the modified files.
63
64 A note on commit messages: Though not required, it's a good idea to
65 begin the commit message with a single short (less than 50 character)
66 line summarizing the change, followed by a blank line and then a more
67 thorough description. Tools that turn commits into email, for
68 example, use the first line on the Subject line and the rest of the
69 commit in the body.
70
71 To add a new file, first create the file, then
72
73 ------------------------------------------------
74 $ git add path/to/new/file
75 ------------------------------------------------
76
77 then commit as usual. No special command is required when removing a
78 file; just remove it, then commit.
79
80 At any point you can view the history of your changes using
81
82 ------------------------------------------------
83 $ git log
84 ------------------------------------------------
85
86 If you also want to see complete diffs at each step, use
87
88 ------------------------------------------------
89 $ git log -p
90 ------------------------------------------------
91
92 Managing branches
93 -----------------
94
95 A single git repository can maintain multiple branches of
96 development. To create a new branch named "experimental", use
97
98 ------------------------------------------------
99 $ git branch experimental
100 ------------------------------------------------
101
102 If you now run
103
104 ------------------------------------------------
105 $ git branch
106 ------------------------------------------------
107
108 you'll get a list of all existing branches:
109
110 ------------------------------------------------
111 experimental
112 * master
113 ------------------------------------------------
114
115 The "experimental" branch is the one you just created, and the
116 "master" branch is a default branch that was created for you
117 automatically. The asterisk marks the branch you are currently on;
118 type
119
120 ------------------------------------------------
121 $ git checkout experimental
122 ------------------------------------------------
123
124 to switch to the experimental branch. Now edit a file, commit the
125 change, and switch back to the master branch:
126
127 ------------------------------------------------
128 (edit file)
129 $ git commit -a
130 $ git checkout master
131 ------------------------------------------------
132
133 Check that the change you made is no longer visible, since it was
134 made on the experimental branch and you're back on the master branch.
135
136 You can make a different change on the master branch:
137
138 ------------------------------------------------
139 (edit file)
140 $ git commit -a
141 ------------------------------------------------
142
143 at this point the two branches have diverged, with different changes
144 made in each. To merge the changes made in the two branches, run
145
146 ------------------------------------------------
147 $ git pull . experimental
148 ------------------------------------------------
149
150 If the changes don't conflict, you're done. If there are conflicts,
151 markers will be left in the problematic files showing the conflict;
152
153 ------------------------------------------------
154 $ git diff
155 ------------------------------------------------
156
157 will show this. Once you've edited the files to resolve the
158 conflicts,
159
160 ------------------------------------------------
161 $ git commit -a
162 ------------------------------------------------
163
164 will commit the result of the merge. Finally,
165
166 ------------------------------------------------
167 $ gitk
168 ------------------------------------------------
169
170 will show a nice graphical representation of the resulting history.
171
172 If you develop on a branch crazy-idea, then regret it, you can always
173 delete the branch with
174
175 -------------------------------------
176 $ git branch -D crazy-idea
177 -------------------------------------
178
179 Branches are cheap and easy, so this is a good way to try something
180 out.
181
182 Using git for collaboration
183 ---------------------------
184
185 Suppose that Alice has started a new project with a git repository in
186 /home/alice/project, and that Bob, who has a home directory on the
187 same machine, wants to contribute.
188
189 Bob begins with:
190
191 ------------------------------------------------
192 $ git clone /home/alice/project myrepo
193 ------------------------------------------------
194
195 This creates a new directory "myrepo" containing a clone of Alice's
196 repository. The clone is on an equal footing with the original
197 project, possessing its own copy of the original project's history.
198
199 Bob then makes some changes and commits them:
200
201 ------------------------------------------------
202 (edit files)
203 $ git commit -a
204 (repeat as necessary)
205 ------------------------------------------------
206
207 When he's ready, he tells Alice to pull changes from the repository
208 at /home/bob/myrepo. She does this with:
209
210 ------------------------------------------------
211 $ cd /home/alice/project
212 $ git pull /home/bob/myrepo
213 ------------------------------------------------
214
215 This actually pulls changes from the branch in Bob's repository named
216 "master". Alice could request a different branch by adding the name
217 of the branch to the end of the git pull command line.
218
219 This merges Bob's changes into her repository; "git log" will
220 now show the new commits. If Alice has made her own changes in the
221 meantime, then Bob's changes will be merged in, and she will need to
222 manually fix any conflicts.
223
224 A more cautious Alice might wish to examine Bob's changes before
225 pulling them. She can do this by creating a temporary branch just
226 for the purpose of studying Bob's changes:
227
228 -------------------------------------
229 $ git fetch /home/bob/myrepo master:bob-incoming
230 -------------------------------------
231
232 which fetches the changes from Bob's master branch into a new branch
233 named bob-incoming. (Unlike git pull, git fetch just fetches a copy
234 of Bob's line of development without doing any merging). Then
235
236 -------------------------------------
237 $ git log -p master..bob-incoming
238 -------------------------------------
239
240 shows a list of all the changes that Bob made since he branched from
241 Alice's master branch.
242
243 After examining those changes, and possibly fixing things, Alice can
244 pull the changes into her master branch:
245
246 -------------------------------------
247 $ git checkout master
248 $ git pull . bob-incoming
249 -------------------------------------
250
251 The last command is a pull from the "bob-incoming" branch in Alice's
252 own repository.
253
254 Later, Bob can update his repo with Alice's latest changes using
255
256 -------------------------------------
257 $ git pull
258 -------------------------------------
259
260 Note that he doesn't need to give the path to Alice's repository;
261 when Bob cloned Alice's repository, git stored the location of her
262 repository in the file .git/remotes/origin, and that location is used
263 as the default for pulls.
264
265 Bob may also notice a branch in his repository that he didn't create:
266
267 -------------------------------------
268 $ git branch
269 * master
270 origin
271 -------------------------------------
272
273 The "origin" branch, which was created automatically by "git clone",
274 is a pristine copy of Alice's master branch; Bob should never commit
275 to it.
276
277 If Bob later decides to work from a different host, he can still
278 perform clones and pulls using the ssh protocol:
279
280 -------------------------------------
281 $ git clone alice.org:/home/alice/project myrepo
282 -------------------------------------
283
284 Alternatively, git has a native protocol, or can use rsync or http;
285 see gitlink:git-pull[1] for details.
286
287 Git can also be used in a CVS-like mode, with a central repository
288 that various users push changes to; see gitlink:git-push[1] and
289 link:cvs-migration.html[git for CVS users].
290
291 Exploring history
292 -----------------
293
294 Git history is represented as a series of interrelated commits. We
295 have already seen that the git log command can list those commits.
296 Note that first line of each git log entry also gives a name for the
297 commit:
298
299 -------------------------------------
300 $ git log
301 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
302 Author: Junio C Hamano <junkio@cox.net>
303 Date: Tue May 16 17:18:22 2006 -0700
304
305 merge-base: Clarify the comments on post processing.
306 -------------------------------------
307
308 We can give this name to git show to see the details about this
309 commit.
310
311 -------------------------------------
312 $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
313 -------------------------------------
314
315 But there other ways to refer to commits. You can use any initial
316 part of the name that is long enough to uniquely identify the commit:
317
318 -------------------------------------
319 $ git show c82a22c39c # the first few characters of the name are
320 # usually enough
321 $ git show HEAD # the tip of the current branch
322 $ git show experimental # the tip of the "experimental" branch
323 -------------------------------------
324
325 Every commit has at least one "parent" commit, which points to the
326 previous state of the project:
327
328 -------------------------------------
329 $ git show HEAD^ # to see the parent of HEAD
330 $ git show HEAD^^ # to see the grandparent of HEAD
331 $ git show HEAD~4 # to see the great-great grandparent of HEAD
332 -------------------------------------
333
334 Note that merge commits may have more than one parent:
335
336 -------------------------------------
337 $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
338 $ git show HEAD^2 # show the second parent of HEAD
339 -------------------------------------
340
341 You can also give commits names of your own; after running
342
343 -------------------------------------
344 $ git-tag v2.5 1b2e1d63ff
345 -------------------------------------
346
347 you can refer to 1b2e1d63ff by the name "v2.5". If you intend to
348 share this name with other people (for example, to identify a release
349 version), you should create a "tag" object, and perhaps sign it; see
350 gitlink:git-tag[1] for details.
351
352 Any git command that needs to know a commit can take any of these
353 names. For example:
354
355 -------------------------------------
356 $ git diff v2.5 HEAD # compare the current HEAD to v2.5
357 $ git branch stable v2.5 # start a new branch named "stable" based
358 # at v2.5
359 $ git reset --hard HEAD^ # reset your current branch and working
360 # directory its state at HEAD^
361 -------------------------------------
362
363 Be careful with that last command: in addition to losing any changes
364 in the working directory, it will also remove all later commits from
365 this branch. If this branch is the only branch containing those
366 commits, they will be lost. (Also, don't use "git reset" on a
367 publicly-visible branch that other developers pull from, as git will
368 be confused by history that disappears in this way.)
369
370 The git grep command can search for strings in any version of your
371 project, so
372
373 -------------------------------------
374 $ git grep "hello" v2.5
375 -------------------------------------
376
377 searches for all occurrences of "hello" in v2.5.
378
379 If you leave out the commit name, git grep will search any of the
380 files it manages in your current directory. So
381
382 -------------------------------------
383 $ git grep "hello"
384 -------------------------------------
385
386 is a quick way to search just the files that are tracked by git.
387
388 Many git commands also take sets of commits, which can be specified
389 in a number of ways. Here are some examples with git log:
390
391 -------------------------------------
392 $ git log v2.5..v2.6 # commits between v2.5 and v2.6
393 $ git log v2.5.. # commits since v2.5
394 $ git log --since="2 weeks ago" # commits from the last 2 weeks
395 $ git log v2.5.. Makefile # commits since v2.5 which modify
396 # Makefile
397 -------------------------------------
398
399 You can also give git log a "range" of commits where the first is not
400 necessarily an ancestor of the second; for example, if the tips of
401 the branches "stable-release" and "master" diverged from a common
402 commit some time ago, then
403
404 -------------------------------------
405 $ git log stable..experimental
406 -------------------------------------
407
408 will list commits made in the experimental branch but not in the
409 stable branch, while
410
411 -------------------------------------
412 $ git log experimental..stable
413 -------------------------------------
414
415 will show the list of commits made on the stable branch but not
416 the experimental branch.
417
418 The "git log" command has a weakness: it must present commits in a
419 list. When the history has lines of development that diverged and
420 then merged back together, the order in which "git log" presents
421 those commits is meaningless.
422
423 Most projects with multiple contributors (such as the linux kernel,
424 or git itself) have frequent merges, and gitk does a better job of
425 visualizing their history. For example,
426
427 -------------------------------------
428 $ gitk --since="2 weeks ago" drivers/
429 -------------------------------------
430
431 allows you to browse any commits from the last 2 weeks of commits
432 that modified files under the "drivers" directory. (Note: you can
433 adjust gitk's fonts by holding down the control key while pressing
434 "-" or "+".)
435
436 Finally, most commands that take filenames will optionally allow you
437 to precede any filename by a commit, to specify a particular version
438 of the file:
439
440 -------------------------------------
441 $ git diff v2.5:Makefile HEAD:Makefile.in
442 -------------------------------------
443
444 You can also use "git cat-file -p" to see any such file:
445
446 -------------------------------------
447 $ git cat-file -p v2.5:Makefile
448 -------------------------------------
449
450 Next Steps
451 ----------
452
453 This tutorial should be enough to perform basic distributed revision
454 control for your projects. However, to fully understand the depth
455 and power of git you need to understand two simple ideas on which it
456 is based:
457
458 * The object database is the rather elegant system used to
459 store the history of your project--files, directories, and
460 commits.
461
462 * The index file is a cache of the state of a directory tree,
463 used to create commits, check out working directories, and
464 hold the various trees involved in a merge.
465
466 link:tutorial-2.html[Part two of this tutorial] explains the object
467 database, the index file, and a few other odds and ends that you'll
468 need to make the most of git.
469
470 If you don't want to consider with that right away, a few other
471 digressions that may be interesting at this point are:
472
473 * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
474 series of git commits into emailed patches, and vice versa,
475 useful for projects such as the linux kernel which rely heavily
476 on emailed patches.
477
478 * gitlink:git-bisect[1]: When there is a regression in your
479 project, one way to track down the bug is by searching through
480 the history to find the exact commit that's to blame. Git bisect
481 can help you perform a binary search for that commit. It is
482 smart enough to perform a close-to-optimal search even in the
483 case of complex non-linear history with lots of merged branches.
484
485 * link:everyday.html[Everyday GIT with 20 Commands Or So]
486
487 * link:cvs-migration.html[git for CVS users].