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". 674There will be asterisk in front of the branch you are currently on. 675 676Sometimes you may wish to create a new branch _without_ actually 677checking it out and switching to it. If so, just use the command 678 679 git branch <branchname> [startingpoint] 680 681which will simply _create_ the branch, but will not do anything further. 682You can then later - once you decide that you want to actually develop 683on that branch - switch to that branch with a regular "git checkout" 684with the branchname as the argument. 685 686 687Merging two branches 688-------------------- 689 690One of the ideas of having a branch is that you do some (possibly 691experimental) work in it, and eventually merge it back to the main 692branch. So assuming you created the above "mybranch" that started out 693being the same as the original "master" branch, let's make sure we're in 694that branch, and do some work there. 695 696 git checkout mybranch 697 echo "Work, work, work" >>hello 698 git commit -m 'Some work.' hello 699 700Here, we just added another line to "hello", and we used a shorthand for 701both going a "git-update-cache hello" and "git commit" by just giving the 702filename directly to "git commit". The '-m' flag is to give the 703commit log message from the command line. 704 705Now, to make it a bit more interesting, let's assume that somebody else 706does some work in the original branch, and simulate that by going back 707to the master branch, and editing the same file differently there: 708 709 git checkout master 710 711Here, take a moment to look at the contents of "hello", and notice how they 712don't contain the work we just did in "mybranch" - because that work 713hasn't happened in the "master" branch at all. Then do 714 715 echo "Play, play, play" >>hello 716 echo "Lots of fun" >>example 717 git commit -m 'Some fun.' hello example 718 719since the master branch is obviously in a much better mood. 720 721Now, you've got two branches, and you decide that you want to merge the 722work done. Before we do that, let's introduce a cool graphical tool that 723helps you view what's going on: 724 725 gitk --all 726 727will show you graphically both of your branches (that's what the "--all" 728means: normally it will just show you your current HEAD) and their 729histories. You can also see exactly how they came to be from a common 730source. 731 732Anyway, let's exit gitk (^Q or the File menu), and decide that we want 733to merge the work we did on the "mybranch" branch into the "master" 734branch (which is currently our HEAD too). To do that, there's a nice 735script called "git resolve", which wants to know which branches you want 736to resolve and what the merge is all about: 737 738 git resolve HEAD mybranch "Merge work in mybranch" 739 740where the third argument is going to be used as the commit message if 741the merge can be resolved automatically. 742 743Now, in this case we've intentionally created a situation where the 744merge will need to be fixed up by hand, though, so git will do as much 745of it as it can automatically (which in this case is just merge the "example" 746file, which had no differences in the "mybranch" branch), and say: 747 748 Simple merge failed, trying Automatic merge 749 Auto-merging hello. 750 merge: warning: conflicts during merge 751 ERROR: Merge conflict in hello. 752 fatal: merge program failed 753 Automatic merge failed, fix up by hand 754 755which is way too verbose, but it basically tells you that it failed the 756really trivial merge ("Simple merge") and did an "Automatic merge" 757instead, but that too failed due to conflicts in "hello". 758 759Not to worry. It left the (trivial) conflict in "hello" in the same form you 760should already be well used to if you've ever used CVS, so let's just 761open "hello" in our editor (whatever that may be), and fix it up somehow. 762I'd suggest just making it so that "hello" contains all four lines: 763 764 Hello World 765 It's a new day for git 766 Play, play, play 767 Work, work, work 768 769and once you're happy with your manual merge, just do a 770 771 git commit hello 772 773which will very loudly warn you that you're now committing a merge 774(which is correct, so never mind), and you can write a small merge 775message about your adventures in git-merge-land. 776 777After you're done, start up "gitk --all" to see graphically what the 778history looks like. Notice that "mybranch" still exists, and you can 779switch to it, and continue to work with it if you want to. The 780"mybranch" branch will not contain the merge, but next time you merge it 781from the "master" branch, git will know how you merged it, so you'll not 782have to do _that_ merge again. 783 784Another useful tool, especially if you do not work in X-Window 785environment all the time, is "git show-branch". 786 787------------------------------------------------ 788$ git show-branch master mybranch 789* [master] Merged "mybranch" changes. 790 ! [mybranch] Some work. 791-- 792+ [master] Merged "mybranch" changes. 793+ [master~1] Some fun. 794++ [mybranch] Some work. 795------------------------------------------------ 796 797The first two lines indicate that it is showing the two branches 798and the first line of the commit log message from their 799top-of-the-tree commits, you are currently on "master" branch 800(notice the asterisk "*" character), and the first column for 801the later output lines is used to show commits contained in the 802"master" branch, and the second column for the "mybranch" 803branch. Three commits are shown along with their log messages. 804All of them have plus '+' characters in the first column, which 805means they are now part of the "master" branch. Only the "Some 806work" commit has the plus '+' character in the second column, 807because "mybranch" has not been merged to incorporate these 808commits from the master branch. 809 810Now, let's pretend you are the one who did all the work in 811mybranch, and the fruit of your hard work has finally been merged 812to the master branch. Let's go back to "mybranch", and run 813resolve to get the "upstream changes" back to your branch. 814 815 git checkout mybranch 816 git resolve HEAD master "Merge upstream changes." 817 818This outputs something like this (the actual commit object names 819would be different) 820 821 Updating from ae3a2da... to a80b4aa.... 822 example | 1 + 823 hello | 1 + 824 2 files changed, 2 insertions(+), 0 deletions(-) 825 826Because your branch did not contain anything more than what are 827already merged into the master branch, the resolve operation did 828not actually do a merge. Instead, it just updated the top of 829the tree of your branch to that of the "master" branch. This is 830often called "fast forward" merge. 831 832You can run "gitk --all" again to see how the commit ancestry 833looks like, or run "show-branch", which tells you this. 834 835------------------------------------------------ 836$ git show-branch master mybranch 837! [master] Merged "mybranch" changes. 838 * [mybranch] Merged "mybranch" changes. 839-- 840++ [master] Merged "mybranch" changes. 841------------------------------------------------ 842 843 844Merging external work 845--------------------- 846 847It's usually much more common that you merge with somebody else than 848merging with your own branches, so it's worth pointing out that git 849makes that very easy too, and in fact, it's not that different from 850doing a "git resolve". In fact, a remote merge ends up being nothing 851more than "fetch the work from a remote repository into a temporary tag" 852followed by a "git resolve". 853 854It's such a common thing to do that it's called "git pull", and you can 855simply do 856 857 git pull <remote-repository> 858 859and optionally give a branch-name for the remote end as a second 860argument. 861 862The "remote" repository can even be on the same machine. One of 863the following notations can be used to name the repository to 864pull from: 865 866 Rsync URL 867 rsync://remote.machine/path/to/repo.git/ 868 869 HTTP(s) URL 870 http://remote.machine/path/to/repo.git/ 871 872 GIT URL 873 git://remote.machine/path/to/repo.git/ 874 875 SSH URL 876 remote.machine:/path/to/repo.git/ 877 878 Local directory 879 /path/to/repo.git/ 880 881[ Digression: you could do without using any branches at all, by 882 keeping as many local repositories as you would like to have 883 branches, and merging between them with "git pull", just like 884 you merge between branches. The advantage of this approach is 885 that it lets you keep set of files for each "branch" checked 886 out and you may find it easier to switch back and forth if you 887 juggle multiple lines of development simultaneously. Of 888 course, you will pay the price of more disk usage to hold 889 multiple working trees, but disk space is cheap these days. ] 890 891[ Digression #2: you could even pull from your own repository by 892 giving '.' as <remote-repository> parameter to "git pull". ] 893 894It is likely that you will be pulling from the same remote 895repository from time to time. As a short hand, you can store 896the remote repository URL in a file under .git/remotes/ 897directory, like this: 898 899------------------------------------------------ 900mkdir -p .git/remotes/ 901cat >.git/remotes/linus <<\EOF 902URL: http://www.kernel.org/pub/scm/git/git.git/ 903EOF 904------------------------------------------------ 905 906and use the filename to "git pull" instead of the full URL. 907The URL specified in such file can even be a prefix 908of a full URL, like this: 909 910------------------------------------------------ 911cat >.git/remotes/jgarzik <<\EOF 912URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/ 913EOF 914------------------------------------------------ 915 916 917Examples. 918 919 (1) git pull linus 920 (2) git pull linus tag v0.99.1 921 (3) git pull jgarzik/netdev-2.6.git/ e100 922 923the above are equivalent to: 924 925 (1) git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD 926 (2) git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1 927 (3) git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100 928 929 930Publishing your work 931-------------------- 932 933So we can use somebody else's work from a remote repository; but 934how can _you_ prepare a repository to let other people pull from 935it? 936 937Your do your real work in your working tree that has your 938primary repository hanging under it as its ".git" subdirectory. 939You _could_ make that repository accessible remotely and ask 940people to pull from it, but in practice that is not the way 941things are usually done. A recommended way is to have a public 942repository, make it reachable by other people, and when the 943changes you made in your primary working tree are in good shape, 944update the public repository from it. This is often called 945"pushing". 946 947[ Side note: this public repository could further be mirrored, 948 and that is how kernel.org git repositories are done. ] 949 950Publishing the changes from your local (private) repository to 951your remote (public) repository requires a write privilege on 952the remote machine. You need to have an SSH account there to 953run a single command, "git-receive-pack". 954 955First, you need to create an empty repository on the remote 956machine that will house your public repository. This empty 957repository will be populated and be kept up-to-date by pushing 958into it later. Obviously, this repository creation needs to be 959done only once. 960 961[ Digression: "git push" uses a pair of programs, 962 "git-send-pack" on your local machine, and "git-receive-pack" 963 on the remote machine. The communication between the two over 964 the network internally uses an SSH connection. ] 965 966Your private repository's GIT directory is usually .git, but 967your public repository is often named after the project name, 968i.e. "<project>.git". Let's create such a public repository for 969project "my-git". After logging into the remote machine, create 970an empty directory: 971 972 mkdir my-git.git 973 974Then, make that directory into a GIT repository by running 975git-init-db, but this time, since its name is not the usual 976".git", we do things slightly differently: 977 978 GIT_DIR=my-git.git git-init-db 979 980Make sure this directory is available for others you want your 981changes to be pulled by via the transport of your choice. Also 982you need to make sure that you have the "git-receive-pack" 983program on the $PATH. 984 985[ Side note: many installations of sshd do not invoke your shell 986 as the login shell when you directly run programs; what this 987 means is that if your login shell is bash, only .bashrc is 988 read and not .bash_profile. As a workaround, make sure 989 .bashrc sets up $PATH so that you can run 'git-receive-pack' 990 program. ] 991 992Your "public repository" is now ready to accept your changes. 993Come back to the machine you have your private repository. From 994there, run this command: 995 996 git push <public-host>:/path/to/my-git.git master 997 998This synchronizes your public repository to match the named 999branch head (i.e. "master" in this case) and objects reachable1000from them in your current repository.10011002As a real example, this is how I update my public git1003repository. Kernel.org mirror network takes care of the1004propagation to other publicly visible machines:10051006 git push master.kernel.org:/pub/scm/git/git.git/ 100710081009Packing your repository1010-----------------------10111012Earlier, we saw that one file under .git/objects/??/ directory1013is stored for each git object you create. This representation1014is convenient and efficient to create atomically and safely, but1015not so convenient to transport over the network. Since git objects are1016immutable once they are created, there is a way to optimize the1017storage by "packing them together". The command10181019 git repack10201021will do it for you. If you followed the tutorial examples, you1022would have accumulated about 17 objects in .git/objects/??/1023directories by now. "git repack" tells you how many objects it1024packed, and stores the packed file in .git/objects/pack1025directory.10261027[ Side Note: you will see two files, pack-*.pack and pack-*.idx,1028 in .git/objects/pack directory. They are closely related to1029 each other, and if you ever copy them by hand to a different1030 repository for whatever reason, you should make sure you copy1031 them together. The former holds all the data from the objects1032 in the pack, and the latter holds the index for random1033 access. ]10341035If you are paranoid, running "git-verify-pack" command would1036detect if you have a corrupt pack, but do not worry too much.1037Our programs are always perfect ;-).10381039Once you have packed objects, you do not need to leave the1040unpacked objects that are contained in the pack file anymore.10411042 git prune-packed10431044would remove them for you.10451046You can try running "find .git/objects -type f" before and after1047you run "git prune-packed" if you are curious.10481049[ Side Note: "git pull" is slightly cumbersome for HTTP transport,1050 as a packed repository may contain relatively few objects in a1051 relatively large pack. If you expect many HTTP pulls from your1052 public repository you might want to repack & prune often, or1053 never. ]10541055If you run "git repack" again at this point, it will say1056"Nothing to pack". Once you continue your development and1057accumulate the changes, running "git repack" again will create a1058new pack, that contains objects created since you packed your1059repository the last time. We recommend that you pack your project1060soon after the initial import (unless you are starting your1061project from scratch), and then run "git repack" every once in a1062while, depending on how active your project is.10631064When a repository is synchronized via "git push" and "git pull",1065objects packed in the source repository are usually stored1066unpacked in the destination, unless rsync transport is used.106710681069Working with Others1070-------------------10711072Although git is a truly distributed system, it is often1073convenient to organize your project with an informal hierarchy1074of developers. Linux kernel development is run this way. There1075is a nice illustration (page 17, "Merges to Mainline") in Randy1076Dunlap's presentation (http://tinyurl.com/a2jdg).10771078It should be stressed that this hierarchy is purely "informal".1079There is nothing fundamental in git that enforces the "chain of1080patch flow" this hierarchy implies. You do not have to pull1081from only one remote repository.108210831084A recommended workflow for a "project lead" goes like this:10851086 (1) Prepare your primary repository on your local machine. Your1087 work is done there.10881089 (2) Prepare a public repository accessible to others.10901091 (3) Push into the public repository from your primary1092 repository.10931094 (4) "git repack" the public repository. This establishes a big1095 pack that contains the initial set of objects as the1096 baseline, and possibly "git prune-packed" if the transport1097 used for pulling from your repository supports packed1098 repositories.10991100 (5) Keep working in your primary repository. Your changes1101 include modifications of your own, patches you receive via1102 e-mails, and merges resulting from pulling the "public"1103 repositories of your "subsystem maintainers".11041105 You can repack this private repository whenever you feel1106 like.11071108 (6) Push your changes to the public repository, and announce it1109 to the public.11101111 (7) Every once in a while, "git repack" the public repository.1112 Go back to step (5) and continue working.111311141115A recommended work cycle for a "subsystem maintainer" who works1116on that project and has an own "public repository" goes like this:11171118 (1) Prepare your work repository, by "git clone" the public1119 repository of the "project lead". The URL used for the1120 initial cloning is stored in .git/branches/origin.11211122 (2) Prepare a public repository accessible to others.11231124 (3) Copy over the packed files from "project lead" public1125 repository to your public repository by hand; preferrably1126 use rsync for that task.11271128 (4) Push into the public repository from your primary1129 repository. Run "git repack", and possibly "git1130 prune-packed" if the transport used for pulling from your1131 repository supports packed repositories.11321133 (5) Keep working in your primary repository. Your changes1134 include modifications of your own, patches you receive via1135 e-mails, and merges resulting from pulling the "public"1136 repositories of your "project lead" and possibly your1137 "sub-subsystem maintainers".11381139 You can repack this private repository whenever you feel1140 like.11411142 (6) Push your changes to your public repository, and ask your1143 "project lead" and possibly your "sub-subsystem1144 maintainers" to pull from it.11451146 (7) Every once in a while, "git repack" the public repository.1147 Go back to step (5) and continue working.114811491150A recommended work cycle for an "individual developer" who does1151not have a "public" repository is somewhat different. It goes1152like this:11531154 (1) Prepare your work repository, by "git clone" the public1155 repository of the "project lead" (or a "subsystem1156 maintainer", if you work on a subsystem). The URL used for1157 the initial cloning is stored in .git/branches/origin.11581159 (2) Do your work there. Make commits.11601161 (3) Run "git fetch origin" from the public repository of your1162 upstream every once in a while. This does only the first1163 half of "git pull" but does not merge. The head of the1164 public repository is stored in .git/refs/heads/origin.11651166 (4) Use "git cherry origin" to see which ones of your patches1167 were accepted, and/or use "git rebase origin" to port your1168 unmerged changes forward to the updated upstream.11691170 (5) Use "git format-patch origin" to prepare patches for e-mail1171 submission to your upstream and send it out. Go back to1172 step (2) and continue.117311741175Working with Others, Shared Repository Style1176--------------------------------------------11771178If you are coming from CVS background, the style of cooperation1179suggested in the previous section may be new to you. You do not1180have to worry. git supports "shared public repository" style of1181cooperation you are probably more familiar with as well.11821183For this, set up a public repository on a machine that is1184reachable via SSH by people with "commit privileges". Put the1185committers in the same user group and make the repository1186writable by that group.11871188Each committer would then:11891190 - clone the shared repository to a local repository,11911192------------------------------------------------1193$ git clone repo.shared.xz:/pub/scm/project.git/ my-project1194$ cd my-project1195$ hack away1196------------------------------------------------11971198 - merge the work others might have done while you were1199 hacking away.12001201------------------------------------------------1202$ git pull origin1203$ test the merge result1204------------------------------------------------12051206 - push your work as the new head of the shared1207 repository.12081209------------------------------------------------1210$ git push origin master1211------------------------------------------------12121213If somebody else pushed into the same shared repository while1214you were working locally, the last step "git push" would1215complain, telling you that the remote "master" head does not1216fast forward. You need to pull and merge those other changes1217back before you push your work when it happens.121812191220[ to be continued.. cvsimports ]