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 config --global user.name "Your Name Comes Here"
  20 $ git 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 config --get remote.origin.url
 357 /home/bob/myrepo
 358 -------------------------------------
 359
 360 (The complete configuration created by git-clone is visible using
 361 "git config -l", and the gitlink:git-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].