Merge branch 'maint'
[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 Initialized empty Git repository in .git/
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
91 Git tracks content not files
92 ----------------------------
93
94 With git you have to explicitly "add" all the changed _content_ you
95 want to commit together. This can be done in a few different ways:
96
97 1) By using 'git add <file_spec>...'
98
99 This can be performed multiple times before a commit. Note that this
100 is not only for adding new files. Even modified files must be
101 added to the set of changes about to be committed. The "git status"
102 command gives you a summary of what is included so far for the
103 next commit. When done you should use the 'git commit' command to
104 make it real.
105
106 Note: don't forget to 'add' a file again if you modified it after the
107 first 'add' and before 'commit'. Otherwise only the previous added
108 state of that file will be committed. This is because git tracks
109 content, so what you're really 'add'ing to the commit is the *content*
110 of the file in the state it is in when you 'add' it.
111
112 2) By using 'git commit -a' directly
113
114 This is a quick way to automatically 'add' the content from all files
115 that were modified since the previous commit, and perform the actual
116 commit without having to separately 'add' them beforehand. This will
117 not add content from new files i.e. files that were never added before.
118 Those files still have to be added explicitly before performing a
119 commit.
120
121 But here's a twist. If you do 'git commit <file1> <file2> ...' then only
122 the changes belonging to those explicitly specified files will be
123 committed, entirely bypassing the current "added" changes. Those "added"
124 changes will still remain available for a subsequent commit though.
125
126 However, for normal usage you only have to remember 'git add' + 'git commit'
127 and/or 'git commit -a'.
128
129
130 Viewing the changelog
131 ---------------------
132
133 At any point you can view the history of your changes using
134
135 ------------------------------------------------
136 $ git log
137 ------------------------------------------------
138
139 If you also want to see complete diffs at each step, use
140
141 ------------------------------------------------
142 $ git log -p
143 ------------------------------------------------
144
145 Managing branches
146 -----------------
147
148 A single git repository can maintain multiple branches of
149 development. To create a new branch named "experimental", use
150
151 ------------------------------------------------
152 $ git branch experimental
153 ------------------------------------------------
154
155 If you now run
156
157 ------------------------------------------------
158 $ git branch
159 ------------------------------------------------
160
161 you'll get a list of all existing branches:
162
163 ------------------------------------------------
164 experimental
165 * master
166 ------------------------------------------------
167
168 The "experimental" branch is the one you just created, and the
169 "master" branch is a default branch that was created for you
170 automatically. The asterisk marks the branch you are currently on;
171 type
172
173 ------------------------------------------------
174 $ git checkout experimental
175 ------------------------------------------------
176
177 to switch to the experimental branch. Now edit a file, commit the
178 change, and switch back to the master branch:
179
180 ------------------------------------------------
181 (edit file)
182 $ git commit -a
183 $ git checkout master
184 ------------------------------------------------
185
186 Check that the change you made is no longer visible, since it was
187 made on the experimental branch and you're back on the master branch.
188
189 You can make a different change on the master branch:
190
191 ------------------------------------------------
192 (edit file)
193 $ git commit -a
194 ------------------------------------------------
195
196 at this point the two branches have diverged, with different changes
197 made in each. To merge the changes made in experimental into master, run
198
199 ------------------------------------------------
200 $ git pull . experimental
201 ------------------------------------------------
202
203 If the changes don't conflict, you're done. If there are conflicts,
204 markers will be left in the problematic files showing the conflict;
205
206 ------------------------------------------------
207 $ git diff
208 ------------------------------------------------
209
210 will show this. Once you've edited the files to resolve the
211 conflicts,
212
213 ------------------------------------------------
214 $ git commit -a
215 ------------------------------------------------
216
217 will commit the result of the merge. Finally,
218
219 ------------------------------------------------
220 $ gitk
221 ------------------------------------------------
222
223 will show a nice graphical representation of the resulting history.
224
225 If you develop on a branch crazy-idea, then regret it, you can always
226 delete the branch with
227
228 -------------------------------------
229 $ git branch -D crazy-idea
230 -------------------------------------
231
232 Branches are cheap and easy, so this is a good way to try something
233 out.
234
235 Using git for collaboration
236 ---------------------------
237
238 Suppose that Alice has started a new project with a git repository in
239 /home/alice/project, and that Bob, who has a home directory on the
240 same machine, wants to contribute.
241
242 Bob begins with:
243
244 ------------------------------------------------
245 $ git clone /home/alice/project myrepo
246 ------------------------------------------------
247
248 This creates a new directory "myrepo" containing a clone of Alice's
249 repository. The clone is on an equal footing with the original
250 project, possessing its own copy of the original project's history.
251
252 Bob then makes some changes and commits them:
253
254 ------------------------------------------------
255 (edit files)
256 $ git commit -a
257 (repeat as necessary)
258 ------------------------------------------------
259
260 When he's ready, he tells Alice to pull changes from the repository
261 at /home/bob/myrepo. She does this with:
262
263 ------------------------------------------------
264 $ cd /home/alice/project
265 $ git pull /home/bob/myrepo master
266 ------------------------------------------------
267
268 This merges the changes from Bob's "master" branch into Alice's
269 current branch. If Alice has made her own changes in the meantime,
270 then she may need to manually fix any conflicts. (Note that the
271 "master" argument in the above command is actually unnecessary, as it
272 is the default.)
273
274 The "pull" command thus performs two operations: it fetches changes
275 from a remote branch, then merges them into the current branch.
276
277 You can perform the first operation alone using the "git fetch"
278 command. For example, Alice could create a temporary branch just to
279 track Bob's changes, without merging them with her own, using:
280
281 -------------------------------------
282 $ git fetch /home/bob/myrepo master:bob-incoming
283 -------------------------------------
284
285 which fetches the changes from Bob's master branch into a new branch
286 named bob-incoming. Then
287
288 -------------------------------------
289 $ git log -p master..bob-incoming
290 -------------------------------------
291
292 shows a list of all the changes that Bob made since he branched from
293 Alice's master branch.
294
295 After examining those changes, and possibly fixing things, Alice
296 could pull the changes into her master branch:
297
298 -------------------------------------
299 $ git checkout master
300 $ git pull . bob-incoming
301 -------------------------------------
302
303 The last command is a pull from the "bob-incoming" branch in Alice's
304 own repository.
305
306 Alice could also perform both steps at once with:
307
308 -------------------------------------
309 $ git pull /home/bob/myrepo master:bob-incoming
310 -------------------------------------
311
312 This is just like the "git pull /home/bob/myrepo master" that we saw
313 before, except that it also stores the unmerged changes from bob's
314 master branch in bob-incoming before merging them into Alice's
315 current branch. Note that git pull always merges into the current
316 branch, regardless of what else is given on the commandline.
317
318 Later, Bob can update his repo with Alice's latest changes using
319
320 -------------------------------------
321 $ git pull
322 -------------------------------------
323
324 Note that he doesn't need to give the path to Alice's repository;
325 when Bob cloned Alice's repository, git stored the location of her
326 repository in the file .git/remotes/origin, and that location is used
327 as the default for pulls.
328
329 Bob may also notice a branch in his repository that he didn't create:
330
331 -------------------------------------
332 $ git branch
333 * master
334 origin
335 -------------------------------------
336
337 The "origin" branch, which was created automatically by "git clone",
338 is a pristine copy of Alice's master branch; Bob should never commit
339 to it.
340
341 If Bob later decides to work from a different host, he can still
342 perform clones and pulls using the ssh protocol:
343
344 -------------------------------------
345 $ git clone alice.org:/home/alice/project myrepo
346 -------------------------------------
347
348 Alternatively, git has a native protocol, or can use rsync or http;
349 see gitlink:git-pull[1] for details.
350
351 Git can also be used in a CVS-like mode, with a central repository
352 that various users push changes to; see gitlink:git-push[1] and
353 link:cvs-migration.html[git for CVS users].
354
355 Exploring history
356 -----------------
357
358 Git history is represented as a series of interrelated commits. We
359 have already seen that the git log command can list those commits.
360 Note that first line of each git log entry also gives a name for the
361 commit:
362
363 -------------------------------------
364 $ git log
365 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
366 Author: Junio C Hamano <junkio@cox.net>
367 Date: Tue May 16 17:18:22 2006 -0700
368
369 merge-base: Clarify the comments on post processing.
370 -------------------------------------
371
372 We can give this name to git show to see the details about this
373 commit.
374
375 -------------------------------------
376 $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
377 -------------------------------------
378
379 But there other ways to refer to commits. You can use any initial
380 part of the name that is long enough to uniquely identify the commit:
381
382 -------------------------------------
383 $ git show c82a22c39c # the first few characters of the name are
384 # usually enough
385 $ git show HEAD # the tip of the current branch
386 $ git show experimental # the tip of the "experimental" branch
387 -------------------------------------
388
389 Every commit has at least one "parent" commit, which points to the
390 previous state of the project:
391
392 -------------------------------------
393 $ git show HEAD^ # to see the parent of HEAD
394 $ git show HEAD^^ # to see the grandparent of HEAD
395 $ git show HEAD~4 # to see the great-great grandparent of HEAD
396 -------------------------------------
397
398 Note that merge commits may have more than one parent:
399
400 -------------------------------------
401 $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
402 $ git show HEAD^2 # show the second parent of HEAD
403 -------------------------------------
404
405 You can also give commits names of your own; after running
406
407 -------------------------------------
408 $ git-tag v2.5 1b2e1d63ff
409 -------------------------------------
410
411 you can refer to 1b2e1d63ff by the name "v2.5". If you intend to
412 share this name with other people (for example, to identify a release
413 version), you should create a "tag" object, and perhaps sign it; see
414 gitlink:git-tag[1] for details.
415
416 Any git command that needs to know a commit can take any of these
417 names. For example:
418
419 -------------------------------------
420 $ git diff v2.5 HEAD # compare the current HEAD to v2.5
421 $ git branch stable v2.5 # start a new branch named "stable" based
422 # at v2.5
423 $ git reset --hard HEAD^ # reset your current branch and working
424 # directory to its state at HEAD^
425 -------------------------------------
426
427 Be careful with that last command: in addition to losing any changes
428 in the working directory, it will also remove all later commits from
429 this branch. If this branch is the only branch containing those
430 commits, they will be lost. (Also, don't use "git reset" on a
431 publicly-visible branch that other developers pull from, as git will
432 be confused by history that disappears in this way.)
433
434 The git grep command can search for strings in any version of your
435 project, so
436
437 -------------------------------------
438 $ git grep "hello" v2.5
439 -------------------------------------
440
441 searches for all occurrences of "hello" in v2.5.
442
443 If you leave out the commit name, git grep will search any of the
444 files it manages in your current directory. So
445
446 -------------------------------------
447 $ git grep "hello"
448 -------------------------------------
449
450 is a quick way to search just the files that are tracked by git.
451
452 Many git commands also take sets of commits, which can be specified
453 in a number of ways. Here are some examples with git log:
454
455 -------------------------------------
456 $ git log v2.5..v2.6 # commits between v2.5 and v2.6
457 $ git log v2.5.. # commits since v2.5
458 $ git log --since="2 weeks ago" # commits from the last 2 weeks
459 $ git log v2.5.. Makefile # commits since v2.5 which modify
460 # Makefile
461 -------------------------------------
462
463 You can also give git log a "range" of commits where the first is not
464 necessarily an ancestor of the second; for example, if the tips of
465 the branches "stable-release" and "master" diverged from a common
466 commit some time ago, then
467
468 -------------------------------------
469 $ git log stable..experimental
470 -------------------------------------
471
472 will list commits made in the experimental branch but not in the
473 stable branch, while
474
475 -------------------------------------
476 $ git log experimental..stable
477 -------------------------------------
478
479 will show the list of commits made on the stable branch but not
480 the experimental branch.
481
482 The "git log" command has a weakness: it must present commits in a
483 list. When the history has lines of development that diverged and
484 then merged back together, the order in which "git log" presents
485 those commits is meaningless.
486
487 Most projects with multiple contributors (such as the linux kernel,
488 or git itself) have frequent merges, and gitk does a better job of
489 visualizing their history. For example,
490
491 -------------------------------------
492 $ gitk --since="2 weeks ago" drivers/
493 -------------------------------------
494
495 allows you to browse any commits from the last 2 weeks of commits
496 that modified files under the "drivers" directory. (Note: you can
497 adjust gitk's fonts by holding down the control key while pressing
498 "-" or "+".)
499
500 Finally, most commands that take filenames will optionally allow you
501 to precede any filename by a commit, to specify a particular version
502 of the file:
503
504 -------------------------------------
505 $ git diff v2.5:Makefile HEAD:Makefile.in
506 -------------------------------------
507
508 You can also use "git cat-file -p" to see any such file:
509
510 -------------------------------------
511 $ git cat-file -p v2.5:Makefile
512 -------------------------------------
513
514 Next Steps
515 ----------
516
517 This tutorial should be enough to perform basic distributed revision
518 control for your projects. However, to fully understand the depth
519 and power of git you need to understand two simple ideas on which it
520 is based:
521
522 * The object database is the rather elegant system used to
523 store the history of your project--files, directories, and
524 commits.
525
526 * The index file is a cache of the state of a directory tree,
527 used to create commits, check out working directories, and
528 hold the various trees involved in a merge.
529
530 link:tutorial-2.html[Part two of this tutorial] explains the object
531 database, the index file, and a few other odds and ends that you'll
532 need to make the most of git.
533
534 If you don't want to consider with that right away, a few other
535 digressions that may be interesting at this point are:
536
537 * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
538 series of git commits into emailed patches, and vice versa,
539 useful for projects such as the linux kernel which rely heavily
540 on emailed patches.
541
542 * gitlink:git-bisect[1]: When there is a regression in your
543 project, one way to track down the bug is by searching through
544 the history to find the exact commit that's to blame. Git bisect
545 can help you perform a binary search for that commit. It is
546 smart enough to perform a close-to-optimal search even in the
547 case of complex non-linear history with lots of merged branches.
548
549 * link:everyday.html[Everyday GIT with 20 Commands Or So]
550
551 * link:cvs-migration.html[git for CVS users].