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