1A short git tutorial 2==================== 3v0.99.5, Aug 2005 4 5Introduction 6------------ 7 8This is trying to be a short tutorial on setting up and using a git 9repository, mainly because being hands-on and using explicit examples is 10often the best way of explaining what is going on. 11 12In normal life, most people wouldn't use the "core" git programs 13directly, but rather script around them to make them more palatable. 14Understanding the core git stuff may help some people get those scripts 15done, though, and it may also be instructive in helping people 16understand what it is that the higher-level helper scripts are actually 17doing. 18 19The core git is often called "plumbing", with the prettier user 20interfaces on top of it called "porcelain". You may not want to use the 21plumbing directly very often, but it can be good to know what the 22plumbing does for when the porcelain isn't flushing... 23 24 25Creating a git repository 26------------------------- 27 28Creating a new git repository couldn't be easier: all git repositories start 29out empty, and the only thing you need to do is find yourself a 30subdirectory that you want to use as a working tree - either an empty 31one for a totally new project, or an existing working tree that you want 32to import into git. 33 34For our first example, we're going to start a totally new repository from 35scratch, with no pre-existing files, and we'll call it "git-tutorial". 36To start up, create a subdirectory for it, change into that 37subdirectory, and initialize the git infrastructure with "git-init-db": 38 39 mkdir git-tutorial 40 cd git-tutorial 41 git-init-db 42 43to which git will reply 44 45 defaulting to local storage area 46 47which is just git's way of saying that you haven't been doing anything 48strange, and that it will have created a local .git directory setup for 49your new project. You will now have a ".git" directory, and you can 50inspect that with "ls". For your new empty project, ls should show you 51three entries, among other things: 52 53 - a symlink called HEAD, pointing to "refs/heads/master" 54 55 Don't worry about the fact that the file that the HEAD link points to 56 doesn't even exist yet - you haven't created the commit that will 57 start your HEAD development branch yet. 58 59 - a subdirectory called "objects", which will contain all the 60 objects of your project. You should never have any real reason to 61 look at the objects directly, but you might want to know that these 62 objects are what contains all the real _data_ in your repository. 63 64 - a subdirectory called "refs", which contains references to objects. 65 66 In particular, the "refs" subdirectory will contain two other 67 subdirectories, named "heads" and "tags" respectively. They do 68 exactly what their names imply: they contain references to any number 69 of different "heads" of development (aka "branches"), and to any 70 "tags" that you have created to name specific versions in your 71 repository. 72 73 One note: the special "master" head is the default branch, which is 74 why the .git/HEAD file was created as a symlink to it even if it 75 doesn't yet exist. Basically, the HEAD link is supposed to always 76 point to the branch you are working on right now, and you always 77 start out expecting to work on the "master" branch. 78 79 However, this is only a convention, and you can name your branches 80 anything you want, and don't have to ever even _have_ a "master" 81 branch. A number of the git tools will assume that .git/HEAD is 82 valid, though. 83 84 [ Implementation note: an "object" is identified by its 160-bit SHA1 85 hash, aka "name", and a reference to an object is always the 40-byte 86 hex representation of that SHA1 name. The files in the "refs" 87 subdirectory are expected to contain these hex references (usually 88 with a final '\n' at the end), and you should thus expect to see a 89 number of 41-byte files containing these references in this refs 90 subdirectories when you actually start populating your tree ] 91 92You have now created your first git repository. Of course, since it's 93empty, that's not very useful, so let's start populating it with data. 94 95 96Populating a git repository 97--------------------------- 98 99We'll keep this simple and stupid, so we'll start off with populating a 100few trivial files just to get a feel for it. 101 102Start off with just creating any random files that you want to maintain 103in your git repository. We'll start off with a few bad examples, just to 104get a feel for how this works: 105 106 echo "Hello World" >hello 107 echo "Silly example" >example 108 109you have now created two files in your working tree (aka "working directory"), but to 110actually check in your hard work, you will have to go through two steps: 111 112 - fill in the "index" file (aka "cache") with the information about your 113 working tree state. 114 115 - commit that index file as an object. 116 117The first step is trivial: when you want to tell git about any changes 118to your working tree, you use the "git-update-cache" program. That 119program normally just takes a list of filenames you want to update, but 120to avoid trivial mistakes, it refuses to add new entries to the cache 121(or remove existing ones) unless you explicitly tell it that you're 122adding a new entry with the "--add" flag (or removing an entry with the 123"--remove") flag. 124 125So to populate the index with the two files you just created, you can do 126 127 git-update-cache --add hello example 128 129and you have now told git to track those two files. 130 131In fact, as you did that, if you now look into your object directory, 132you'll notice that git will have added two new objects to the object 133database. If you did exactly the steps above, you should now be able to do 134 135 ls .git/objects/??/* 136 137and see two files: 138 139 .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 140 .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 141 142which correspond with the objects with names of 557db... and f24c7.. 143respectively. 144 145If you want to, you can use "git-cat-file" to look at those objects, but 146you'll have to use the object name, not the filename of the object: 147 148 git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 149 150where the "-t" tells git-cat-file to tell you what the "type" of the 151object is. Git will tell you that you have a "blob" object (ie just a 152regular file), and you can see the contents with 153 154 git-cat-file "blob" 557db03 155 156which will print out "Hello World". The object 557db03 is nothing 157more than the contents of your file "hello". 158 159[ Digression: don't confuse that object with the file "hello" itself. The 160 object is literally just those specific _contents_ of the file, and 161 however much you later change the contents in file "hello", the object we 162 just looked at will never change. Objects are immutable. ] 163 164[ Digression #2: the second example demonstrates that you can 165 abbreviate the object name to only the first several 166 hexadecimal digits in most places. ] 167 168Anyway, as we mentioned previously, you normally never actually take a 169look at the objects themselves, and typing long 40-character hex 170names is not something you'd normally want to do. The above digression 171was just to show that "git-update-cache" did something magical, and 172actually saved away the contents of your files into the git object 173database. 174 175Updating the cache did something else too: it created a ".git/index" 176file. This is the index that describes your current working tree, and 177something you should be very aware of. Again, you normally never worry 178about the index file itself, but you should be aware of the fact that 179you have not actually really "checked in" your files into git so far, 180you've only _told_ git about them. 181 182However, since git knows about them, you can now start using some of the 183most basic git commands to manipulate the files or look at their status. 184 185In particular, let's not even check in the two files into git yet, we'll 186start off by adding another line to "hello" first: 187 188 echo "It's a new day for git" >>hello 189 190and you can now, since you told git about the previous state of "hello", ask 191git what has changed in the tree compared to your old index, using the 192"git-diff-files" command: 193 194 git-diff-files 195 196Oops. That wasn't very readable. It just spit out its own internal 197version of a "diff", but that internal version really just tells you 198that it has noticed that "hello" has been modified, and that the old object 199contents it had have been replaced with something else. 200 201To make it readable, we can tell git-diff-files to output the 202differences as a patch, using the "-p" flag: 203 204 git-diff-files -p 205 206which will spit out 207 208 diff --git a/hello b/hello 209 --- a/hello 210 +++ b/hello 211 @@ -1 +1,2 @@ 212 Hello World 213 +It's a new day for git 214 215ie the diff of the change we caused by adding another line to "hello". 216 217In other words, git-diff-files always shows us the difference between 218what is recorded in the index, and what is currently in the working 219tree. That's very useful. 220 221A common shorthand for "git-diff-files -p" is to just write 222 223 git diff 224 225which will do the same thing. 226 227 228Committing git state 229-------------------- 230 231Now, we want to go to the next stage in git, which is to take the files 232that git knows about in the index, and commit them as a real tree. We do 233that in two phases: creating a "tree" object, and committing that "tree" 234object as a "commit" object together with an explanation of what the 235tree was all about, along with information of how we came to that state. 236 237Creating a tree object is trivial, and is done with "git-write-tree". 238There are no options or other input: git-write-tree will take the 239current index state, and write an object that describes that whole 240index. In other words, we're now tying together all the different 241filenames with their contents (and their permissions), and we're 242creating the equivalent of a git "directory" object: 243 244 git-write-tree 245 246and this will just output the name of the resulting tree, in this case 247(if you have done exactly as I've described) it should be 248 249 8988da15d077d4829fc51d8544c097def6644dbb 250 251which is another incomprehensible object name. Again, if you want to, 252you can use "git-cat-file -t 8988d.." to see that this time the object 253is not a "blob" object, but a "tree" object (you can also use 254git-cat-file to actually output the raw object contents, but you'll see 255mainly a binary mess, so that's less interesting). 256 257However - normally you'd never use "git-write-tree" on its own, because 258normally you always commit a tree into a commit object using the 259"git-commit-tree" command. In fact, it's easier to not actually use 260git-write-tree on its own at all, but to just pass its result in as an 261argument to "git-commit-tree". 262 263"git-commit-tree" normally takes several arguments - it wants to know 264what the _parent_ of a commit was, but since this is the first commit 265ever in this new repository, and it has no parents, we only need to pass in 266the object name of the tree. However, git-commit-tree also wants to get a commit message 267on its standard input, and it will write out the resulting object name for the 268commit to its standard output. 269 270And this is where we start using the .git/HEAD file. The HEAD file is 271supposed to contain the reference to the top-of-tree, and since that's 272exactly what git-commit-tree spits out, we can do this all with a simple 273shell pipeline: 274 275 echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD 276 277which will say: 278 279 Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb 280 281just to warn you about the fact that it created a totally new commit 282that is not related to anything else. Normally you do this only _once_ 283for a project ever, and all later commits will be parented on top of an 284earlier commit, and you'll never see this "Committing initial tree" 285message ever again. 286 287Again, normally you'd never actually do this by hand. There is a 288helpful script called "git commit" that will do all of this for you. So 289you could have just written 290 291 git commit 292 293instead, and it would have done the above magic scripting for you. 294 295 296Making a change 297--------------- 298 299Remember how we did the "git-update-cache" on file "hello" and then we 300changed "hello" afterward, and could compare the new state of "hello" with the 301state we saved in the index file? 302 303Further, remember how I said that "git-write-tree" writes the contents 304of the _index_ file to the tree, and thus what we just committed was in 305fact the _original_ contents of the file "hello", not the new ones. We did 306that on purpose, to show the difference between the index state, and the 307state in the working tree, and how they don't have to match, even 308when we commit things. 309 310As before, if we do "git-diff-files -p" in our git-tutorial project, 311we'll still see the same difference we saw last time: the index file 312hasn't changed by the act of committing anything. However, now that we 313have committed something, we can also learn to use a new command: 314"git-diff-cache". 315 316Unlike "git-diff-files", which showed the difference between the index 317file and the working tree, "git-diff-cache" shows the differences 318between a committed _tree_ and either the index file or the working 319tree. In other words, git-diff-cache wants a tree to be diffed 320against, and before we did the commit, we couldn't do that, because we 321didn't have anything to diff against. 322 323But now we can do 324 325 git-diff-cache -p HEAD 326 327(where "-p" has the same meaning as it did in git-diff-files), and it 328will show us the same difference, but for a totally different reason. 329Now we're comparing the working tree not against the index file, 330but against the tree we just wrote. It just so happens that those two 331are obviously the same, so we get the same result. 332 333Again, because this is a common operation, you can also just shorthand 334it with 335 336 git diff HEAD 337 338which ends up doing the above for you. 339 340In other words, "git-diff-cache" normally compares a tree against the 341working tree, but when given the "--cached" flag, it is told to 342instead compare against just the index cache contents, and ignore the 343current working tree state entirely. Since we just wrote the index 344file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return 345an empty set of differences, and that's exactly what it does. 346 347[ Digression: "git-diff-cache" really always uses the index for its 348 comparisons, and saying that it compares a tree against the working 349 tree is thus not strictly accurate. In particular, the list of 350 files to compare (the "meta-data") _always_ comes from the index file, 351 regardless of whether the --cached flag is used or not. The --cached 352 flag really only determines whether the file _contents_ to be compared 353 come from the working tree or not. 354 355 This is not hard to understand, as soon as you realize that git simply 356 never knows (or cares) about files that it is not told about 357 explicitly. Git will never go _looking_ for files to compare, it 358 expects you to tell it what the files are, and that's what the index 359 is there for. ] 360 361However, our next step is to commit the _change_ we did, and again, to 362understand what's going on, keep in mind the difference between "working 363tree contents", "index file" and "committed tree". We have changes 364in the working tree that we want to commit, and we always have to 365work through the index file, so the first thing we need to do is to 366update the index cache: 367 368 git-update-cache hello 369 370(note how we didn't need the "--add" flag this time, since git knew 371about the file already). 372 373Note what happens to the different git-diff-xxx versions here. After 374we've updated "hello" in the index, "git-diff-files -p" now shows no 375differences, but "git-diff-cache -p HEAD" still _does_ show that the 376current state is different from the state we committed. In fact, now 377"git-diff-cache" shows the same difference whether we use the "--cached" 378flag or not, since now the index is coherent with the working tree. 379 380Now, since we've updated "hello" in the index, we can commit the new 381version. We could do it by writing the tree by hand again, and 382committing the tree (this time we'd have to use the "-p HEAD" flag to 383tell commit that the HEAD was the _parent_ of the new commit, and that 384this wasn't an initial commit any more), but you've done that once 385already, so let's just use the helpful script this time: 386 387 git commit 388 389which starts an editor for you to write the commit message and tells you 390a bit about what you have done. 391 392Write whatever message you want, and all the lines that start with '#' 393will be pruned out, and the rest will be used as the commit message for 394the change. If you decide you don't want to commit anything after all at 395this point (you can continue to edit things and update the cache), you 396can just leave an empty message. Otherwise git-commit-script will commit 397the change for you. 398 399You've now made your first real git commit. And if you're interested in 400looking at what git-commit-script really does, feel free to investigate: 401it's a few very simple shell scripts to generate the helpful (?) commit 402message headers, and a few one-liners that actually do the commit itself. 403 404 405Checking it out 406--------------- 407 408While creating changes is useful, it's even more useful if you can tell 409later what changed. The most useful command for this is another of the 410"diff" family, namely "git-diff-tree". 411 412git-diff-tree can be given two arbitrary trees, and it will tell you the 413differences between them. Perhaps even more commonly, though, you can 414give it just a single commit object, and it will figure out the parent 415of that commit itself, and show the difference directly. Thus, to get 416the same diff that we've already seen several times, we can now do 417 418 git-diff-tree -p HEAD 419 420(again, "-p" means to show the difference as a human-readable patch), 421and it will show what the last commit (in HEAD) actually changed. 422 423More interestingly, you can also give git-diff-tree the "-v" flag, which 424tells it to also show the commit message and author and date of the 425commit, and you can tell it to show a whole series of diffs. 426Alternatively, you can tell it to be "silent", and not show the diffs at 427all, but just show the actual commit message. 428 429In fact, together with the "git-rev-list" program (which generates a 430list of revisions), git-diff-tree ends up being a veritable fount of 431changes. A trivial (but very useful) script called "git-whatchanged" is 432included with git which does exactly this, and shows a log of recent 433activities. 434 435To see the whole history of our pitiful little git-tutorial project, you 436can do 437 438 git log 439 440which shows just the log messages, or if we want to see the log together 441with the associated patches use the more complex (and much more 442powerful) 443 444 git-whatchanged -p --root 445 446and you will see exactly what has changed in the repository over its 447short history. 448 449[ Side note: the "--root" flag is a flag to git-diff-tree to tell it to 450 show the initial aka "root" commit too. Normally you'd probably not 451 want to see the initial import diff, but since the tutorial project 452 was started from scratch and is so small, we use it to make the result 453 a bit more interesting. ] 454 455With that, you should now be having some inkling of what git does, and 456can explore on your own. 457 458[ Side note: most likely, you are not directly using the core 459 git Plumbing commands, but using Porcelain like Cogito on top 460 of it. Cogito works a bit differently and you usually do not 461 have to run "git-update-cache" yourself for changed files (you 462 do tell underlying git about additions and removals via 463 "cg-add" and "cg-rm" commands). Just before you make a commit 464 with "cg-commit", Cogito figures out which files you modified, 465 and runs "git-update-cache" on them for you. ] 466 467 468Tagging a version 469----------------- 470 471In git, there are two kinds of tags, a "light" one, and an "annotated tag". 472 473A "light" tag is technically nothing more than a branch, except we put 474it in the ".git/refs/tags/" subdirectory instead of calling it a "head". 475So the simplest form of tag involves nothing more than 476 477 git tag my-first-tag 478 479which just writes the current HEAD into the .git/refs/tags/my-first-tag 480file, after which point you can then use this symbolic name for that 481particular state. You can, for example, do 482 483 git diff my-first-tag 484 485to diff your current state against that tag (which at this point will 486obviously be an empty diff, but if you continue to develop and commit 487stuff, you can use your tag as an "anchor-point" to see what has changed 488since you tagged it. 489 490An "annotated tag" is actually a real git object, and contains not only a 491pointer to the state you want to tag, but also a small tag name and 492message, along with optionally a PGP signature that says that yes, you really did 493that tag. You create these signed tags with either the "-a" or "-s" flag to "git tag": 494 495 git tag -s <tagname> 496 497which will sign the current HEAD (but you can also give it another 498argument that specifies the thing to tag, ie you could have tagged the 499current "mybranch" point by using "git tag <tagname> mybranch"). 500 501You normally only do signed tags for major releases or things 502like that, while the light-weight tags are useful for any marking you 503want to do - any time you decide that you want to remember a certain 504point, just create a private tag for it, and you have a nice symbolic 505name for the state at that point. 506 507 508Copying repositories 509-------------------- 510 511Git repositories are normally totally self-sufficient, and it's worth noting 512that unlike CVS, for example, there is no separate notion of 513"repository" and "working tree". A git repository normally _is_ the 514working tree, with the local git information hidden in the ".git" 515subdirectory. There is nothing else. What you see is what you got. 516 517[ Side note: you can tell git to split the git internal information from 518 the directory that it tracks, but we'll ignore that for now: it's not 519 how normal projects work, and it's really only meant for special uses. 520 So the mental model of "the git information is always tied directly to 521 the working tree that it describes" may not be technically 100% 522 accurate, but it's a good model for all normal use ] 523 524This has two implications: 525 526 - if you grow bored with the tutorial repository you created (or you've 527 made a mistake and want to start all over), you can just do simple 528 529 rm -rf git-tutorial 530 531 and it will be gone. There's no external repository, and there's no 532 history outside the project you created. 533 534 - if you want to move or duplicate a git repository, you can do so. There 535 is "git clone" command, but if all you want to do is just to 536 create a copy of your repository (with all the full history that 537 went along with it), you can do so with a regular 538 "cp -a git-tutorial new-git-tutorial". 539 540 Note that when you've moved or copied a git repository, your git index 541 file (which caches various information, notably some of the "stat" 542 information for the files involved) will likely need to be refreshed. 543 So after you do a "cp -a" to create a new copy, you'll want to do 544 545 git-update-cache --refresh 546 547 in the new repository to make sure that the index file is up-to-date. 548 549Note that the second point is true even across machines. You can 550duplicate a remote git repository with _any_ regular copy mechanism, be it 551"scp", "rsync" or "wget". 552 553When copying a remote repository, you'll want to at a minimum update the 554index cache when you do this, and especially with other peoples' 555repositories you often want to make sure that the index cache is in some 556known state (you don't know _what_ they've done and not yet checked in), 557so usually you'll precede the "git-update-cache" with a 558 559 git-read-tree --reset HEAD 560 git-update-cache --refresh 561 562which will force a total index re-build from the tree pointed to by HEAD. 563It resets the index contents to HEAD, and then the git-update-cache 564makes sure to match up all index entries with the checked-out files. 565If the original repository had uncommitted changes in its 566working tree, "git-update-cache --refresh" notices them and 567tells you they need to be updated. 568 569The above can also be written as simply 570 571 git reset 572 573and in fact a lot of the common git command combinations can be scripted 574with the "git xyz" interfaces, and you can learn things by just looking 575at what the git-*-script scripts do ("git reset" is the above two lines 576implemented in "git-reset-script", but some things like "git status" and 577"git commit" are slightly more complex scripts around the basic git 578commands). 579 580Many (most?) public remote repositories will not contain any of 581the checked out files or even an index file, and will _only_ contain the 582actual core git files. Such a repository usually doesn't even have the 583".git" subdirectory, but has all the git files directly in the 584repository. 585 586To create your own local live copy of such a "raw" git repository, you'd 587first create your own subdirectory for the project, and then copy the 588raw repository contents into the ".git" directory. For example, to 589create your own copy of the git repository, you'd do the following 590 591 mkdir my-git 592 cd my-git 593 rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git 594 595followed by 596 597 git-read-tree HEAD 598 599to populate the index. However, now you have populated the index, and 600you have all the git internal files, but you will notice that you don't 601actually have any of the working tree files to work on. To get 602those, you'd check them out with 603 604 git-checkout-cache -u -a 605 606where the "-u" flag means that you want the checkout to keep the index 607up-to-date (so that you don't have to refresh it afterward), and the 608"-a" flag means "check out all files" (if you have a stale copy or an 609older version of a checked out tree you may also need to add the "-f" 610flag first, to tell git-checkout-cache to _force_ overwriting of any old 611files). 612 613Again, this can all be simplified with 614 615 git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git 616 cd my-git 617 git checkout 618 619which will end up doing all of the above for you. 620 621You have now successfully copied somebody else's (mine) remote 622repository, and checked it out. 623 624 625Creating a new branch 626--------------------- 627 628Branches in git are really nothing more than pointers into the git 629object database from within the ".git/refs/" subdirectory, and as we 630already discussed, the HEAD branch is nothing but a symlink to one of 631these object pointers. 632 633You can at any time create a new branch by just picking an arbitrary 634point in the project history, and just writing the SHA1 name of that 635object into a file under .git/refs/heads/. You can use any filename you 636want (and indeed, subdirectories), but the convention is that the 637"normal" branch is called "master". That's just a convention, though, 638and nothing enforces it. 639 640To show that as an example, let's go back to the git-tutorial repository we 641used earlier, and create a branch in it. You do that by simply just 642saying that you want to check out a new branch: 643 644 git checkout -b mybranch 645 646will create a new branch based at the current HEAD position, and switch 647to it. 648 649[ Side note: if you make the decision to start your new branch at some 650 other point in the history than the current HEAD, you can do so by 651 just telling "git checkout" what the base of the checkout would be. 652 In other words, if you have an earlier tag or branch, you'd just do 653 654 git checkout -b mybranch earlier-commit 655 656 and it would create the new branch "mybranch" at the earlier commit, 657 and check out the state at that time. ] 658 659You can always just jump back to your original "master" branch by doing 660 661 git checkout master 662 663(or any other branch-name, for that matter) and if you forget which 664branch you happen to be on, a simple 665 666 ls -l .git/HEAD 667 668will tell you where it's pointing. To get the list of branches 669you have, you can say 670 671 git branch 672 673which is nothing more than a simple script around "ls .git/refs/heads". 674 675Sometimes you may wish to create a new branch _without_ actually 676checking it out and switching to it. If so, just use the command 677 678 git branch <branchname> [startingpoint] 679 680which will simply _create_ the branch, but will not do anything further. 681You can then later - once you decide that you want to actually develop 682on that branch - switch to that branch with a regular "git checkout" 683with the branchname as the argument. 684 685 686Merging two branches 687-------------------- 688 689One of the ideas of having a branch is that you do some (possibly 690experimental) work in it, and eventually merge it back to the main 691branch. So assuming you created the above "mybranch" that started out 692being the same as the original "master" branch, let's make sure we're in 693that branch, and do some work there. 694 695 git checkout mybranch 696 echo "Work, work, work" >>hello 697 git commit -m 'Some work.' hello 698 699Here, we just added another line to "hello", and we used a shorthand for 700both going a "git-update-cache hello" and "git commit" by just giving the 701filename directly to "git commit". The '-m' flag is to give the 702commit log message from the command line. 703 704Now, to make it a bit more interesting, let's assume that somebody else 705does some work in the original branch, and simulate that by going back 706to the master branch, and editing the same file differently there: 707 708 git checkout master 709 710Here, take a moment to look at the contents of "hello", and notice how they 711don't contain the work we just did in "mybranch" - because that work 712hasn't happened in the "master" branch at all. Then do 713 714 echo "Play, play, play" >>hello 715 echo "Lots of fun" >>example 716 git commit -m 'Some fun.' hello example 717 718since the master branch is obviously in a much better mood. 719 720Now, you've got two branches, and you decide that you want to merge the 721work done. Before we do that, let's introduce a cool graphical tool that 722helps you view what's going on: 723 724 gitk --all 725 726will show you graphically both of your branches (that's what the "--all" 727means: normally it will just show you your current HEAD) and their 728histories. You can also see exactly how they came to be from a common 729source. 730 731Anyway, let's exit gitk (^Q or the File menu), and decide that we want 732to merge the work we did on the "mybranch" branch into the "master" 733branch (which is currently our HEAD too). To do that, there's a nice 734script called "git resolve", which wants to know which branches you want 735to resolve and what the merge is all about: 736 737 git resolve HEAD mybranch "Merge work in mybranch" 738 739where the third argument is going to be used as the commit message if 740the merge can be resolved automatically. 741 742Now, in this case we've intentionally created a situation where the 743merge will need to be fixed up by hand, though, so git will do as much 744of it as it can automatically (which in this case is just merge the "example" 745file, which had no differences in the "mybranch" branch), and say: 746 747 Simple merge failed, trying Automatic merge 748 Auto-merging hello. 749 merge: warning: conflicts during merge 750 ERROR: Merge conflict in hello. 751 fatal: merge program failed 752 Automatic merge failed, fix up by hand 753 754which is way too verbose, but it basically tells you that it failed the 755really trivial merge ("Simple merge") and did an "Automatic merge" 756instead, but that too failed due to conflicts in "hello". 757 758Not to worry. It left the (trivial) conflict in "hello" in the same form you 759should already be well used to if you've ever used CVS, so let's just 760open "hello" in our editor (whatever that may be), and fix it up somehow. 761I'd suggest just making it so that "hello" contains all four lines: 762 763 Hello World 764 It's a new day for git 765 Play, play, play 766 Work, work, work 767 768and once you're happy with your manual merge, just do a 769 770 git commit hello 771 772which will very loudly warn you that you're now committing a merge 773(which is correct, so never mind), and you can write a small merge 774message about your adventures in git-merge-land. 775 776After you're done, start up "gitk --all" to see graphically what the 777history looks like. Notice that "mybranch" still exists, and you can 778switch to it, and continue to work with it if you want to. The 779"mybranch" branch will not contain the merge, but next time you merge it 780from the "master" branch, git will know how you merged it, so you'll not 781have to do _that_ merge again. 782 783Another useful tool, especially if you do not work in X-Window 784environment all the time, is "git show-branch". 785 786------------------------------------------------ 787$ git show-branch master mybranch 788* [master] Merged "mybranch" changes. 789 ! [mybranch] Some work. 790-- 791+ [master] Merged "mybranch" changes. 792+ [master~1] Some fun. 793++ [mybranch] Some work. 794------------------------------------------------ 795 796The first two lines indicate that it is showing the two branches 797and the first line of the commit log message from their 798top-of-the-tree commits, you are currently on "master" branch 799(notice the asterisk "*" character), and the first column for 800the later output lines is used to show commits contained in the 801"master" branch, and the second column for the "mybranch" 802branch. Three commits are shown along with their log messages. 803All of them have plus '+' characters in the first column, which 804means they are now part of the "master" branch. Only the "Some 805work" commit has the plus '+' character in the second column, 806because "mybranch" has not been merged to incorporate these 807commits from the master branch. 808 809Now, let's pretend you are the one who did all the work in 810mybranch, and the fruit of your hard work has finally been merged 811to the master branch. Let's go back to "mybranch", and run 812resolve to get the "upstream changes" back to your branch. 813 814 git checkout mybranch 815 git resolve HEAD master "Merge upstream changes." 816 817This outputs something like this (the actual commit object names 818would be different) 819 820 Updating from ae3a2da... to a80b4aa.... 821 example | 1 + 822 hello | 1 + 823 2 files changed, 2 insertions(+), 0 deletions(-) 824 825Because your branch did not contain anything more than what are 826already merged into the master branch, the resolve operation did 827not actually do a merge. Instead, it just updated the top of 828the tree of your branch to that of the "master" branch. This is 829often called "fast forward" merge. 830 831You can run "gitk --all" again to see how the commit ancestry 832looks like, or run "show-branch", which tells you this. 833 834------------------------------------------------ 835$ git show-branch master mybranch 836! [master] Merged "mybranch" changes. 837 * [mybranch] Merged "mybranch" changes. 838-- 839++ [master] Merged "mybranch" changes. 840------------------------------------------------ 841 842 843Merging external work 844--------------------- 845 846It's usually much more common that you merge with somebody else than 847merging with your own branches, so it's worth pointing out that git 848makes that very easy too, and in fact, it's not that different from 849doing a "git resolve". In fact, a remote merge ends up being nothing 850more than "fetch the work from a remote repository into a temporary tag" 851followed by a "git resolve". 852 853It's such a common thing to do that it's called "git pull", and you can 854simply do 855 856 git pull <remote-repository> 857 858and optionally give a branch-name for the remote end as a second 859argument. 860 861The "remote" repository can even be on the same machine. One of 862the following notations can be used to name the repository to 863pull from: 864 865 Rsync URL 866 rsync://remote.machine/path/to/repo.git/ 867 868 HTTP(s) URL 869 http://remote.machine/path/to/repo.git/ 870 871 GIT URL 872 git://remote.machine/path/to/repo.git/ 873 874 SSH URL 875 remote.machine:/path/to/repo.git/ 876 877 Local directory 878 /path/to/repo.git/ 879 880[ Digression: you could do without using any branches at all, by 881 keeping as many local repositories as you would like to have 882 branches, and merging between them with "git pull", just like 883 you merge between branches. The advantage of this approach is 884 that it lets you keep set of files for each "branch" checked 885 out and you may find it easier to switch back and forth if you 886 juggle multiple lines of development simultaneously. Of 887 course, you will pay the price of more disk usage to hold 888 multiple working trees, but disk space is cheap these days. ] 889 890[ Digression #2: you could even pull from your own repository by 891 giving '.' as <remote-repository> parameter to "git pull". ] 892 893It is likely that you will be pulling from the same remote 894repository from time to time. As a short hand, you can store 895the remote repository URL in a file under .git/remotes/ 896directory, like this: 897 898------------------------------------------------ 899mkdir -p .git/remotes/ 900cat >.git/remotes/linus <<\EOF 901URL: http://www.kernel.org/pub/scm/git/git.git/ 902EOF 903------------------------------------------------ 904 905and use the filename to "git pull" instead of the full URL. 906The URL specified in such file can even be a prefix 907of a full URL, like this: 908 909------------------------------------------------ 910cat >.git/remotes/jgarzik <<\EOF 911URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/ 912EOF 913------------------------------------------------ 914 915 916Examples. 917 918 (1) git pull linus 919 (2) git pull linus tag v0.99.1 920 (3) git pull jgarzik/netdev-2.6.git/ e100 921 922the above are equivalent to: 923 924 (1) git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD 925 (2) git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1 926 (3) git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100 927 928 929Publishing your work 930-------------------- 931 932So we can use somebody else's work from a remote repository; but 933how can _you_ prepare a repository to let other people pull from 934it? 935 936Your do your real work in your working tree that has your 937primary repository hanging under it as its ".git" subdirectory. 938You _could_ make that repository accessible remotely and ask 939people to pull from it, but in practice that is not the way 940things are usually done. A recommended way is to have a public 941repository, make it reachable by other people, and when the 942changes you made in your primary working tree are in good shape, 943update the public repository from it. This is often called 944"pushing". 945 946[ Side note: this public repository could further be mirrored, 947 and that is how kernel.org git repositories are done. ] 948 949Publishing the changes from your local (private) repository to 950your remote (public) repository requires a write privilege on 951the remote machine. You need to have an SSH account there to 952run a single command, "git-receive-pack". 953 954First, you need to create an empty repository on the remote 955machine that will house your public repository. This empty 956repository will be populated and be kept up-to-date by pushing 957into it later. Obviously, this repository creation needs to be 958done only once. 959 960[ Digression: "git push" uses a pair of programs, 961 "git-send-pack" on your local machine, and "git-receive-pack" 962 on the remote machine. The communication between the two over 963 the network internally uses an SSH connection. ] 964 965Your private repository's GIT directory is usually .git, but 966your public repository is often named after the project name, 967i.e. "<project>.git". Let's create such a public repository for 968project "my-git". After logging into the remote machine, create 969an empty directory: 970 971 mkdir my-git.git 972 973Then, make that directory into a GIT repository by running 974git-init-db, but this time, since its name is not the usual 975".git", we do things slightly differently: 976 977 GIT_DIR=my-git.git git-init-db 978 979Make sure this directory is available for others you want your 980changes to be pulled by via the transport of your choice. Also 981you need to make sure that you have the "git-receive-pack" 982program on the $PATH. 983 984[ Side note: many installations of sshd do not invoke your shell 985 as the login shell when you directly run programs; what this 986 means is that if your login shell is bash, only .bashrc is 987 read and not .bash_profile. As a workaround, make sure 988 .bashrc sets up $PATH so that you can run 'git-receive-pack' 989 program. ] 990 991Your "public repository" is now ready to accept your changes. 992Come back to the machine you have your private repository. From 993there, run this command: 994 995 git push <public-host>:/path/to/my-git.git master 996 997This synchronizes your public repository to match the named 998branch head (i.e. "master" in this case) and objects reachable 999from them in your current repository.10001001As a real example, this is how I update my public git1002repository. Kernel.org mirror network takes care of the1003propagation to other publicly visible machines:10041005 git push master.kernel.org:/pub/scm/git/git.git/ 100610071008Packing your repository1009-----------------------10101011Earlier, we saw that one file under .git/objects/??/ directory1012is stored for each git object you create. This representation1013is convenient and efficient to create atomically and safely, but1014not so convenient to transport over the network. Since git objects are1015immutable once they are created, there is a way to optimize the1016storage by "packing them together". The command10171018 git repack10191020will do it for you. If you followed the tutorial examples, you1021would have accumulated about 17 objects in .git/objects/??/1022directories by now. "git repack" tells you how many objects it1023packed, and stores the packed file in .git/objects/pack1024directory.10251026[ Side Note: you will see two files, pack-*.pack and pack-*.idx,1027 in .git/objects/pack directory. They are closely related to1028 each other, and if you ever copy them by hand to a different1029 repository for whatever reason, you should make sure you copy1030 them together. The former holds all the data from the objects1031 in the pack, and the latter holds the index for random1032 access. ]10331034If you are paranoid, running "git-verify-pack" command would1035detect if you have a corrupt pack, but do not worry too much.1036Our programs are always perfect ;-).10371038Once you have packed objects, you do not need to leave the1039unpacked objects that are contained in the pack file anymore.10401041 git prune-packed10421043would remove them for you.10441045You can try running "find .git/objects -type f" before and after1046you run "git prune-packed" if you are curious.10471048[ Side Note: "git pull" is slightly cumbersome for HTTP transport,1049 as a packed repository may contain relatively few objects in a1050 relatively large pack. If you expect many HTTP pulls from your1051 public repository you might want to repack & prune often, or1052 never. ]10531054If you run "git repack" again at this point, it will say1055"Nothing to pack". Once you continue your development and1056accumulate the changes, running "git repack" again will create a1057new pack, that contains objects created since you packed your1058repository the last time. We recommend that you pack your project1059soon after the initial import (unless you are starting your1060project from scratch), and then run "git repack" every once in a1061while, depending on how active your project is.10621063When a repository is synchronized via "git push" and "git pull",1064objects packed in the source repository are usually stored1065unpacked in the destination, unless rsync transport is used.106610671068Working with Others1069-------------------10701071Although git is a truly distributed system, it is often1072convenient to organize your project with an informal hierarchy1073of developers. Linux kernel development is run this way. There1074is a nice illustration (page 17, "Merges to Mainline") in Randy1075Dunlap's presentation (http://tinyurl.com/a2jdg).10761077It should be stressed that this hierarchy is purely "informal".1078There is nothing fundamental in git that enforces the "chain of1079patch flow" this hierarchy implies. You do not have to pull1080from only one remote repository.108110821083A recommended workflow for a "project lead" goes like this:10841085 (1) Prepare your primary repository on your local machine. Your1086 work is done there.10871088 (2) Prepare a public repository accessible to others.10891090 (3) Push into the public repository from your primary1091 repository.10921093 (4) "git repack" the public repository. This establishes a big1094 pack that contains the initial set of objects as the1095 baseline, and possibly "git prune-packed" if the transport1096 used for pulling from your repository supports packed1097 repositories.10981099 (5) Keep working in your primary repository. Your changes1100 include modifications of your own, patches you receive via1101 e-mails, and merges resulting from pulling the "public"1102 repositories of your "subsystem maintainers".11031104 You can repack this private repository whenever you feel1105 like.11061107 (6) Push your changes to the public repository, and announce it1108 to the public.11091110 (7) Every once in a while, "git repack" the public repository.1111 Go back to step (5) and continue working.111211131114A recommended work cycle for a "subsystem maintainer" who works1115on that project and has an own "public repository" goes like this:11161117 (1) Prepare your work repository, by "git clone" the public1118 repository of the "project lead". The URL used for the1119 initial cloning is stored in .git/branches/origin.11201121 (2) Prepare a public repository accessible to others.11221123 (3) Copy over the packed files from "project lead" public1124 repository to your public repository by hand; preferrably1125 use rsync for that task.11261127 (4) Push into the public repository from your primary1128 repository. Run "git repack", and possibly "git1129 prune-packed" if the transport used for pulling from your1130 repository supports packed repositories.11311132 (5) Keep working in your primary repository. Your changes1133 include modifications of your own, patches you receive via1134 e-mails, and merges resulting from pulling the "public"1135 repositories of your "project lead" and possibly your1136 "sub-subsystem maintainers".11371138 You can repack this private repository whenever you feel1139 like.11401141 (6) Push your changes to your public repository, and ask your1142 "project lead" and possibly your "sub-subsystem1143 maintainers" to pull from it.11441145 (7) Every once in a while, "git repack" the public repository.1146 Go back to step (5) and continue working.114711481149A recommended work cycle for an "individual developer" who does1150not have a "public" repository is somewhat different. It goes1151like this:11521153 (1) Prepare your work repository, by "git clone" the public1154 repository of the "project lead" (or a "subsystem1155 maintainer", if you work on a subsystem). The URL used for1156 the initial cloning is stored in .git/branches/origin.11571158 (2) Do your work there. Make commits.11591160 (3) Run "git fetch origin" from the public repository of your1161 upstream every once in a while. This does only the first1162 half of "git pull" but does not merge. The head of the1163 public repository is stored in .git/refs/heads/origin.11641165 (4) Use "git cherry origin" to see which ones of your patches1166 were accepted, and/or use "git rebase origin" to port your1167 unmerged changes forward to the updated upstream.11681169 (5) Use "git format-patch origin" to prepare patches for e-mail1170 submission to your upstream and send it out. Go back to1171 step (2) and continue.117211731174Working with Others, Shared Repository Style1175--------------------------------------------11761177If you are coming from CVS background, the style of cooperation1178suggested in the previous section may be new to you. You do not1179have to worry. git supports "shared public repository" style of1180cooperation you are probably more familiar with as well.11811182For this, set up a public repository on a machine that is1183reachable via SSH by people with "commit privileges". Put the1184committers in the same user group and make the repository1185writable by that group.11861187Each committer would then:11881189 - clone the shared repository to a local repository,11901191------------------------------------------------1192$ git clone repo.shared.xz:/pub/scm/project.git/ my-project1193$ cd my-project1194$ hack away1195------------------------------------------------11961197 - merge the work others might have done while you were1198 hacking away.11991200------------------------------------------------1201$ git pull origin1202$ test the merge result1203------------------------------------------------12041205 - push your work as the new head of the shared1206 repository.12071208------------------------------------------------1209$ git push origin master1210------------------------------------------------12111212If somebody else pushed into the same shared repository while1213you were working locally, the last step "git push" would1214complain, telling you that the remote "master" head does not1215fast forward. You need to pull and merge those other changes1216back before you push your work when it happens.121712181219[ to be continued.. cvsimports ]