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