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