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