1gitcore-tutorial(7) 2=================== 3 4NAME 5---- 6gitcore-tutorial - A git core tutorial for developers 7 8SYNOPSIS 9-------- 10git * 11 12DESCRIPTION 13----------- 14 15This tutorial explains how to use the "core" git commands to set up and 16work with a git repository. 17 18If you just need to use git as a revision control system you may prefer 19to start with "A Tutorial Introduction to Git" (linkgit:gittutorial[7]) or 20link:user-manual.html[the Git User Manual]. 21 22However, an understanding of these low-level tools can be helpful if 23you want to understand git's internals. 24 25The core git is often called "plumbing", with the prettier user 26interfaces on top of it called "porcelain". You may not want to use the 27plumbing directly very often, but it can be good to know what the 28plumbing does for when the porcelain isn't flushing. 29 30Back when this document was originally written, many porcelain 31commands were shell scripts. For simplicity, it still uses them as 32examples to illustrate how plumbing is fit together to form the 33porcelain commands. The source tree includes some of these scripts in 34contrib/examples/ for reference. Although these are not implemented as 35shell scripts anymore, the description of what the plumbing layer 36commands do is still valid. 37 38[NOTE] 39Deeper technical details are often marked as Notes, which you can 40skip on your first reading. 41 42 43Creating a git repository 44------------------------- 45 46Creating a new git repository couldn't be easier: all git repositories start 47out empty, and the only thing you need to do is find yourself a 48subdirectory that you want to use as a working tree - either an empty 49one for a totally new project, or an existing working tree that you want 50to import into git. 51 52For our first example, we're going to start a totally new repository from 53scratch, with no pre-existing files, and we'll call it 'git-tutorial'. 54To start up, create a subdirectory for it, change into that 55subdirectory, and initialize the git infrastructure with 'git init': 56 57------------------------------------------------ 58$ mkdir git-tutorial 59$ cd git-tutorial 60$ git init 61------------------------------------------------ 62 63to which git will reply 64 65---------------- 66Initialized empty Git repository in .git/ 67---------------- 68 69which is just git's way of saying that you haven't been doing anything 70strange, and that it will have created a local `.git` directory setup for 71your new project. You will now have a `.git` directory, and you can 72inspect that with 'ls'. For your new empty project, it should show you 73three entries, among other things: 74 75 - a file called `HEAD`, that has `ref: refs/heads/master` in it. 76 This is similar to a symbolic link and points at 77 `refs/heads/master` relative to the `HEAD` file. 78+ 79Don't worry about the fact that the file that the `HEAD` link points to 80doesn't even exist yet -- you haven't created the commit that will 81start your `HEAD` development branch yet. 82 83 - a subdirectory called `objects`, which will contain all the 84 objects of your project. You should never have any real reason to 85 look at the objects directly, but you might want to know that these 86 objects are what contains all the real 'data' in your repository. 87 88 - a subdirectory called `refs`, which contains references to objects. 89 90In particular, the `refs` subdirectory will contain two other 91subdirectories, named `heads` and `tags` respectively. They do 92exactly what their names imply: they contain references to any number 93of different 'heads' of development (aka 'branches'), and to any 94'tags' that you have created to name specific versions in your 95repository. 96 97One note: the special `master` head is the default branch, which is 98why the `.git/HEAD` file was created points to it even if it 99doesn't yet exist. Basically, the `HEAD` link is supposed to always 100point to the branch you are working on right now, and you always 101start out expecting to work on the `master` branch. 102 103However, this is only a convention, and you can name your branches 104anything you want, and don't have to ever even 'have' a `master` 105branch. A number of the git tools will assume that `.git/HEAD` is 106valid, though. 107 108[NOTE] 109An 'object' is identified by its 160-bit SHA1 hash, aka 'object name', 110and a reference to an object is always the 40-byte hex 111representation of that SHA1 name. The files in the `refs` 112subdirectory are expected to contain these hex references 113(usually with a final `\n` at the end), and you should thus 114expect to see a number of 41-byte files containing these 115references in these `refs` subdirectories when you actually start 116populating your tree. 117 118[NOTE] 119An advanced user may want to take a look at linkgit:gitrepository-layout[5] 120after finishing this tutorial. 121 122You have now created your first git repository. Of course, since it's 123empty, that's not very useful, so let's start populating it with data. 124 125 126Populating a git repository 127--------------------------- 128 129We'll keep this simple and stupid, so we'll start off with populating a 130few trivial files just to get a feel for it. 131 132Start off with just creating any random files that you want to maintain 133in your git repository. We'll start off with a few bad examples, just to 134get a feel for how this works: 135 136------------------------------------------------ 137$ echo "Hello World" >hello 138$ echo "Silly example" >example 139------------------------------------------------ 140 141you have now created two files in your working tree (aka 'working directory'), 142but to actually check in your hard work, you will have to go through two steps: 143 144 - fill in the 'index' file (aka 'cache') with the information about your 145 working tree state. 146 147 - commit that index file as an object. 148 149The first step is trivial: when you want to tell git about any changes 150to your working tree, you use the 'git update-index' program. That 151program normally just takes a list of filenames you want to update, but 152to avoid trivial mistakes, it refuses to add new entries to the index 153(or remove existing ones) unless you explicitly tell it that you're 154adding a new entry with the `--add` flag (or removing an entry with the 155`--remove`) flag. 156 157So to populate the index with the two files you just created, you can do 158 159------------------------------------------------ 160$ git update-index --add hello example 161------------------------------------------------ 162 163and you have now told git to track those two files. 164 165In fact, as you did that, if you now look into your object directory, 166you'll notice that git will have added two new objects to the object 167database. If you did exactly the steps above, you should now be able to do 168 169 170---------------- 171$ ls .git/objects/??/* 172---------------- 173 174and see two files: 175 176---------------- 177.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 178.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 179---------------- 180 181which correspond with the objects with names of `557db...` and 182`f24c7...` respectively. 183 184If you want to, you can use 'git cat-file' to look at those objects, but 185you'll have to use the object name, not the filename of the object: 186 187---------------- 188$ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 189---------------- 190 191where the `-t` tells 'git cat-file' to tell you what the "type" of the 192object is. git will tell you that you have a "blob" object (i.e., just a 193regular file), and you can see the contents with 194 195---------------- 196$ git cat-file blob 557db03 197---------------- 198 199which will print out "Hello World". The object `557db03` is nothing 200more than the contents of your file `hello`. 201 202[NOTE] 203Don't confuse that object with the file `hello` itself. The 204object is literally just those specific *contents* of the file, and 205however much you later change the contents in file `hello`, the object 206we just looked at will never change. Objects are immutable. 207 208[NOTE] 209The second example demonstrates that you can 210abbreviate the object name to only the first several 211hexadecimal digits in most places. 212 213Anyway, as we mentioned previously, you normally never actually take a 214look at the objects themselves, and typing long 40-character hex 215names is not something you'd normally want to do. The above digression 216was just to show that 'git update-index' did something magical, and 217actually saved away the contents of your files into the git object 218database. 219 220Updating the index did something else too: it created a `.git/index` 221file. This is the index that describes your current working tree, and 222something you should be very aware of. Again, you normally never worry 223about the index file itself, but you should be aware of the fact that 224you have not actually really "checked in" your files into git so far, 225you've only *told* git about them. 226 227However, since git knows about them, you can now start using some of the 228most basic git commands to manipulate the files or look at their status. 229 230In particular, let's not even check in the two files into git yet, we'll 231start off by adding another line to `hello` first: 232 233------------------------------------------------ 234$ echo "It's a new day for git" >>hello 235------------------------------------------------ 236 237and you can now, since you told git about the previous state of `hello`, ask 238git what has changed in the tree compared to your old index, using the 239'git diff-files' command: 240 241------------ 242$ git diff-files 243------------ 244 245Oops. That wasn't very readable. It just spit out its own internal 246version of a 'diff', but that internal version really just tells you 247that it has noticed that "hello" has been modified, and that the old object 248contents it had have been replaced with something else. 249 250To make it readable, we can tell 'git diff-files' to output the 251differences as a patch, using the `-p` flag: 252 253------------ 254$ git diff-files -p 255diff --git a/hello b/hello 256index 557db03..263414f 100644 257--- a/hello 258+++ b/hello 259@@ -1 +1,2 @@ 260 Hello World 261+It's a new day for git 262---- 263 264i.e. the diff of the change we caused by adding another line to `hello`. 265 266In other words, 'git diff-files' always shows us the difference between 267what is recorded in the index, and what is currently in the working 268tree. That's very useful. 269 270A common shorthand for `git diff-files -p` is to just write `git 271diff`, which will do the same thing. 272 273------------ 274$ git diff 275diff --git a/hello b/hello 276index 557db03..263414f 100644 277--- a/hello 278+++ b/hello 279@@ -1 +1,2 @@ 280 Hello World 281+It's a new day for git 282------------ 283 284 285Committing git state 286-------------------- 287 288Now, we want to go to the next stage in git, which is to take the files 289that git knows about in the index, and commit them as a real tree. We do 290that in two phases: creating a 'tree' object, and committing that 'tree' 291object as a 'commit' object together with an explanation of what the 292tree was all about, along with information of how we came to that state. 293 294Creating a tree object is trivial, and is done with 'git write-tree'. 295There are no options or other input: `git write-tree` will take the 296current index state, and write an object that describes that whole 297index. In other words, we're now tying together all the different 298filenames with their contents (and their permissions), and we're 299creating the equivalent of a git "directory" object: 300 301------------------------------------------------ 302$ git write-tree 303------------------------------------------------ 304 305and this will just output the name of the resulting tree, in this case 306(if you have done exactly as I've described) it should be 307 308---------------- 3098988da15d077d4829fc51d8544c097def6644dbb 310---------------- 311 312which is another incomprehensible object name. Again, if you want to, 313you can use `git cat-file -t 8988d...` to see that this time the object 314is not a "blob" object, but a "tree" object (you can also use 315`git cat-file` to actually output the raw object contents, but you'll see 316mainly a binary mess, so that's less interesting). 317 318However -- normally you'd never use 'git write-tree' on its own, because 319normally you always commit a tree into a commit object using the 320'git commit-tree' command. In fact, it's easier to not actually use 321'git write-tree' on its own at all, but to just pass its result in as an 322argument to 'git commit-tree'. 323 324'git commit-tree' normally takes several arguments -- it wants to know 325what the 'parent' of a commit was, but since this is the first commit 326ever in this new repository, and it has no parents, we only need to pass in 327the object name of the tree. However, 'git commit-tree' also wants to get a 328commit message on its standard input, and it will write out the resulting 329object name for the commit to its standard output. 330 331And this is where we create the `.git/refs/heads/master` file 332which is pointed at by `HEAD`. This file is supposed to contain 333the reference to the top-of-tree of the master branch, and since 334that's exactly what 'git commit-tree' spits out, we can do this 335all with a sequence of simple shell commands: 336 337------------------------------------------------ 338$ tree=$(git write-tree) 339$ commit=$(echo 'Initial commit' | git commit-tree $tree) 340$ git update-ref HEAD $commit 341------------------------------------------------ 342 343In this case this creates a totally new commit that is not related to 344anything else. Normally you do this only *once* for a project ever, and 345all later commits will be parented on top of an earlier commit. 346 347Again, normally you'd never actually do this by hand. There is a 348helpful script called `git commit` that will do all of this for you. So 349you could have just written `git commit` 350instead, and it would have done the above magic scripting for you. 351 352 353Making a change 354--------------- 355 356Remember how we did the 'git update-index' on file `hello` and then we 357changed `hello` afterward, and could compare the new state of `hello` with the 358state we saved in the index file? 359 360Further, remember how I said that 'git write-tree' writes the contents 361of the *index* file to the tree, and thus what we just committed was in 362fact the *original* contents of the file `hello`, not the new ones. We did 363that on purpose, to show the difference between the index state, and the 364state in the working tree, and how they don't have to match, even 365when we commit things. 366 367As before, if we do `git diff-files -p` in our git-tutorial project, 368we'll still see the same difference we saw last time: the index file 369hasn't changed by the act of committing anything. However, now that we 370have committed something, we can also learn to use a new command: 371'git diff-index'. 372 373Unlike 'git diff-files', which showed the difference between the index 374file and the working tree, 'git diff-index' shows the differences 375between a committed *tree* and either the index file or the working 376tree. In other words, 'git diff-index' wants a tree to be diffed 377against, and before we did the commit, we couldn't do that, because we 378didn't have anything to diff against. 379 380But now we can do 381 382---------------- 383$ git diff-index -p HEAD 384---------------- 385 386(where `-p` has the same meaning as it did in 'git diff-files'), and it 387will show us the same difference, but for a totally different reason. 388Now we're comparing the working tree not against the index file, 389but against the tree we just wrote. It just so happens that those two 390are obviously the same, so we get the same result. 391 392Again, because this is a common operation, you can also just shorthand 393it with 394 395---------------- 396$ git diff HEAD 397---------------- 398 399which ends up doing the above for you. 400 401In other words, 'git diff-index' normally compares a tree against the 402working tree, but when given the `--cached` flag, it is told to 403instead compare against just the index cache contents, and ignore the 404current working tree state entirely. Since we just wrote the index 405file to HEAD, doing `git diff-index --cached -p HEAD` should thus return 406an empty set of differences, and that's exactly what it does. 407 408[NOTE] 409================ 410'git diff-index' really always uses the index for its 411comparisons, and saying that it compares a tree against the working 412tree is thus not strictly accurate. In particular, the list of 413files to compare (the "meta-data") *always* comes from the index file, 414regardless of whether the `--cached` flag is used or not. The `--cached` 415flag really only determines whether the file *contents* to be compared 416come from the working tree or not. 417 418This is not hard to understand, as soon as you realize that git simply 419never knows (or cares) about files that it is not told about 420explicitly. git will never go *looking* for files to compare, it 421expects you to tell it what the files are, and that's what the index 422is there for. 423================ 424 425However, our next step is to commit the *change* we did, and again, to 426understand what's going on, keep in mind the difference between "working 427tree contents", "index file" and "committed tree". We have changes 428in the working tree that we want to commit, and we always have to 429work through the index file, so the first thing we need to do is to 430update the index cache: 431 432------------------------------------------------ 433$ git update-index hello 434------------------------------------------------ 435 436(note how we didn't need the `--add` flag this time, since git knew 437about the file already). 438 439Note what happens to the different 'git diff-{asterisk}' versions here. 440After we've updated `hello` in the index, `git diff-files -p` now shows no 441differences, but `git diff-index -p HEAD` still *does* show that the 442current state is different from the state we committed. In fact, now 443'git diff-index' shows the same difference whether we use the `--cached` 444flag or not, since now the index is coherent with the working tree. 445 446Now, since we've updated `hello` in the index, we can commit the new 447version. We could do it by writing the tree by hand again, and 448committing the tree (this time we'd have to use the `-p HEAD` flag to 449tell commit that the HEAD was the *parent* of the new commit, and that 450this wasn't an initial commit any more), but you've done that once 451already, so let's just use the helpful script this time: 452 453------------------------------------------------ 454$ git commit 455------------------------------------------------ 456 457which starts an editor for you to write the commit message and tells you 458a bit about what you have done. 459 460Write whatever message you want, and all the lines that start with '#' 461will be pruned out, and the rest will be used as the commit message for 462the change. If you decide you don't want to commit anything after all at 463this point (you can continue to edit things and update the index), you 464can just leave an empty message. Otherwise `git commit` will commit 465the change for you. 466 467You've now made your first real git commit. And if you're interested in 468looking at what `git commit` really does, feel free to investigate: 469it's a few very simple shell scripts to generate the helpful (?) commit 470message headers, and a few one-liners that actually do the 471commit itself ('git commit'). 472 473 474Inspecting Changes 475------------------ 476 477While creating changes is useful, it's even more useful if you can tell 478later what changed. The most useful command for this is another of the 479'diff' family, namely 'git diff-tree'. 480 481'git diff-tree' can be given two arbitrary trees, and it will tell you the 482differences between them. Perhaps even more commonly, though, you can 483give it just a single commit object, and it will figure out the parent 484of that commit itself, and show the difference directly. Thus, to get 485the same diff that we've already seen several times, we can now do 486 487---------------- 488$ git diff-tree -p HEAD 489---------------- 490 491(again, `-p` means to show the difference as a human-readable patch), 492and it will show what the last commit (in `HEAD`) actually changed. 493 494[NOTE] 495============ 496Here is an ASCII art by Jon Loeliger that illustrates how 497various 'diff-{asterisk}' commands compare things. 498 499 diff-tree 500 +----+ 501 | | 502 | | 503 V V 504 +-----------+ 505 | Object DB | 506 | Backing | 507 | Store | 508 +-----------+ 509 ^ ^ 510 | | 511 | | diff-index --cached 512 | | 513 diff-index | V 514 | +-----------+ 515 | | Index | 516 | | "cache" | 517 | +-----------+ 518 | ^ 519 | | 520 | | diff-files 521 | | 522 V V 523 +-----------+ 524 | Working | 525 | Directory | 526 +-----------+ 527============ 528 529More interestingly, you can also give 'git diff-tree' the `--pretty` flag, 530which tells it to also show the commit message and author and date of the 531commit, and you can tell it to show a whole series of diffs. 532Alternatively, you can tell it to be "silent", and not show the diffs at 533all, but just show the actual commit message. 534 535In fact, together with the 'git rev-list' program (which generates a 536list of revisions), 'git diff-tree' ends up being a veritable fount of 537changes. A trivial (but very useful) script called 'git whatchanged' is 538included with git which does exactly this, and shows a log of recent 539activities. 540 541To see the whole history of our pitiful little git-tutorial project, you 542can do 543 544---------------- 545$ git log 546---------------- 547 548which shows just the log messages, or if we want to see the log together 549with the associated patches use the more complex (and much more 550powerful) 551 552---------------- 553$ git whatchanged -p 554---------------- 555 556and you will see exactly what has changed in the repository over its 557short history. 558 559[NOTE] 560When using the above two commands, the initial commit will be shown. 561If this is a problem because it is huge, you can hide it by setting 562the log.showroot configuration variable to false. Having this, you 563can still show it for each command just adding the `--root` option, 564which is a flag for 'git diff-tree' accepted by both commands. 565 566With that, you should now be having some inkling of what git does, and 567can explore on your own. 568 569[NOTE] 570Most likely, you are not directly using the core 571git Plumbing commands, but using Porcelain such as 'git add', `git-rm' 572and `git-commit'. 573 574 575Tagging a version 576----------------- 577 578In git, there are two kinds of tags, a "light" one, and an "annotated tag". 579 580A "light" tag is technically nothing more than a branch, except we put 581it in the `.git/refs/tags/` subdirectory instead of calling it a `head`. 582So the simplest form of tag involves nothing more than 583 584------------------------------------------------ 585$ git tag my-first-tag 586------------------------------------------------ 587 588which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag` 589file, after which point you can then use this symbolic name for that 590particular state. You can, for example, do 591 592---------------- 593$ git diff my-first-tag 594---------------- 595 596to diff your current state against that tag which at this point will 597obviously be an empty diff, but if you continue to develop and commit 598stuff, you can use your tag as an "anchor-point" to see what has changed 599since you tagged it. 600 601An "annotated tag" is actually a real git object, and contains not only a 602pointer to the state you want to tag, but also a small tag name and 603message, along with optionally a PGP signature that says that yes, 604you really did 605that tag. You create these annotated tags with either the `-a` or 606`-s` flag to 'git tag': 607 608---------------- 609$ git tag -s <tagname> 610---------------- 611 612which will sign the current `HEAD` (but you can also give it another 613argument that specifies the thing to tag, e.g., you could have tagged the 614current `mybranch` point by using `git tag <tagname> mybranch`). 615 616You normally only do signed tags for major releases or things 617like that, while the light-weight tags are useful for any marking you 618want to do -- any time you decide that you want to remember a certain 619point, just create a private tag for it, and you have a nice symbolic 620name for the state at that point. 621 622 623Copying repositories 624-------------------- 625 626git repositories are normally totally self-sufficient and relocatable. 627Unlike CVS, for example, there is no separate notion of 628"repository" and "working tree". A git repository normally *is* the 629working tree, with the local git information hidden in the `.git` 630subdirectory. There is nothing else. What you see is what you got. 631 632[NOTE] 633You can tell git to split the git internal information from 634the directory that it tracks, but we'll ignore that for now: it's not 635how normal projects work, and it's really only meant for special uses. 636So the mental model of "the git information is always tied directly to 637the working tree that it describes" may not be technically 100% 638accurate, but it's a good model for all normal use. 639 640This has two implications: 641 642 - if you grow bored with the tutorial repository you created (or you've 643 made a mistake and want to start all over), you can just do simple 644+ 645---------------- 646$ rm -rf git-tutorial 647---------------- 648+ 649and it will be gone. There's no external repository, and there's no 650history outside the project you created. 651 652 - if you want to move or duplicate a git repository, you can do so. There 653 is 'git clone' command, but if all you want to do is just to 654 create a copy of your repository (with all the full history that 655 went along with it), you can do so with a regular 656 `cp -a git-tutorial new-git-tutorial`. 657+ 658Note that when you've moved or copied a git repository, your git index 659file (which caches various information, notably some of the "stat" 660information for the files involved) will likely need to be refreshed. 661So after you do a `cp -a` to create a new copy, you'll want to do 662+ 663---------------- 664$ git update-index --refresh 665---------------- 666+ 667in the new repository to make sure that the index file is up-to-date. 668 669Note that the second point is true even across machines. You can 670duplicate a remote git repository with *any* regular copy mechanism, be it 671'scp', 'rsync' or 'wget'. 672 673When copying a remote repository, you'll want to at a minimum update the 674index cache when you do this, and especially with other peoples' 675repositories you often want to make sure that the index cache is in some 676known state (you don't know *what* they've done and not yet checked in), 677so usually you'll precede the 'git update-index' with a 678 679---------------- 680$ git read-tree --reset HEAD 681$ git update-index --refresh 682---------------- 683 684which will force a total index re-build from the tree pointed to by `HEAD`. 685It resets the index contents to `HEAD`, and then the 'git update-index' 686makes sure to match up all index entries with the checked-out files. 687If the original repository had uncommitted changes in its 688working tree, `git update-index --refresh` notices them and 689tells you they need to be updated. 690 691The above can also be written as simply 692 693---------------- 694$ git reset 695---------------- 696 697and in fact a lot of the common git command combinations can be scripted 698with the `git xyz` interfaces. You can learn things by just looking 699at what the various git scripts do. For example, `git reset` used to be 700the above two lines implemented in 'git reset', but some things like 701'git status' and 'git commit' are slightly more complex scripts around 702the basic git commands. 703 704Many (most?) public remote repositories will not contain any of 705the checked out files or even an index file, and will *only* contain the 706actual core git files. Such a repository usually doesn't even have the 707`.git` subdirectory, but has all the git files directly in the 708repository. 709 710To create your own local live copy of such a "raw" git repository, you'd 711first create your own subdirectory for the project, and then copy the 712raw repository contents into the `.git` directory. For example, to 713create your own copy of the git repository, you'd do the following 714 715---------------- 716$ mkdir my-git 717$ cd my-git 718$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git 719---------------- 720 721followed by 722 723---------------- 724$ git read-tree HEAD 725---------------- 726 727to populate the index. However, now you have populated the index, and 728you have all the git internal files, but you will notice that you don't 729actually have any of the working tree files to work on. To get 730those, you'd check them out with 731 732---------------- 733$ git checkout-index -u -a 734---------------- 735 736where the `-u` flag means that you want the checkout to keep the index 737up-to-date (so that you don't have to refresh it afterward), and the 738`-a` flag means "check out all files" (if you have a stale copy or an 739older version of a checked out tree you may also need to add the `-f` 740flag first, to tell 'git checkout-index' to *force* overwriting of any old 741files). 742 743Again, this can all be simplified with 744 745---------------- 746$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git 747$ cd my-git 748$ git checkout 749---------------- 750 751which will end up doing all of the above for you. 752 753You have now successfully copied somebody else's (mine) remote 754repository, and checked it out. 755 756 757Creating a new branch 758--------------------- 759 760Branches in git are really nothing more than pointers into the git 761object database from within the `.git/refs/` subdirectory, and as we 762already discussed, the `HEAD` branch is nothing but a symlink to one of 763these object pointers. 764 765You can at any time create a new branch by just picking an arbitrary 766point in the project history, and just writing the SHA1 name of that 767object into a file under `.git/refs/heads/`. You can use any filename you 768want (and indeed, subdirectories), but the convention is that the 769"normal" branch is called `master`. That's just a convention, though, 770and nothing enforces it. 771 772To show that as an example, let's go back to the git-tutorial repository we 773used earlier, and create a branch in it. You do that by simply just 774saying that you want to check out a new branch: 775 776------------ 777$ git checkout -b mybranch 778------------ 779 780will create a new branch based at the current `HEAD` position, and switch 781to it. 782 783[NOTE] 784================================================ 785If you make the decision to start your new branch at some 786other point in the history than the current `HEAD`, you can do so by 787just telling 'git checkout' what the base of the checkout would be. 788In other words, if you have an earlier tag or branch, you'd just do 789 790------------ 791$ git checkout -b mybranch earlier-commit 792------------ 793 794and it would create the new branch `mybranch` at the earlier commit, 795and check out the state at that time. 796================================================ 797 798You can always just jump back to your original `master` branch by doing 799 800------------ 801$ git checkout master 802------------ 803 804(or any other branch-name, for that matter) and if you forget which 805branch you happen to be on, a simple 806 807------------ 808$ cat .git/HEAD 809------------ 810 811will tell you where it's pointing. To get the list of branches 812you have, you can say 813 814------------ 815$ git branch 816------------ 817 818which used to be nothing more than a simple script around `ls .git/refs/heads`. 819There will be an asterisk in front of the branch you are currently on. 820 821Sometimes you may wish to create a new branch _without_ actually 822checking it out and switching to it. If so, just use the command 823 824------------ 825$ git branch <branchname> [startingpoint] 826------------ 827 828which will simply _create_ the branch, but will not do anything further. 829You can then later -- once you decide that you want to actually develop 830on that branch -- switch to that branch with a regular 'git checkout' 831with the branchname as the argument. 832 833 834Merging two branches 835-------------------- 836 837One of the ideas of having a branch is that you do some (possibly 838experimental) work in it, and eventually merge it back to the main 839branch. So assuming you created the above `mybranch` that started out 840being the same as the original `master` branch, let's make sure we're in 841that branch, and do some work there. 842 843------------------------------------------------ 844$ git checkout mybranch 845$ echo "Work, work, work" >>hello 846$ git commit -m "Some work." -i hello 847------------------------------------------------ 848 849Here, we just added another line to `hello`, and we used a shorthand for 850doing both `git update-index hello` and `git commit` by just giving the 851filename directly to `git commit`, with an `-i` flag (it tells 852git to 'include' that file in addition to what you have done to 853the index file so far when making the commit). The `-m` flag is to give the 854commit log message from the command line. 855 856Now, to make it a bit more interesting, let's assume that somebody else 857does some work in the original branch, and simulate that by going back 858to the master branch, and editing the same file differently there: 859 860------------ 861$ git checkout master 862------------ 863 864Here, take a moment to look at the contents of `hello`, and notice how they 865don't contain the work we just did in `mybranch` -- because that work 866hasn't happened in the `master` branch at all. Then do 867 868------------ 869$ echo "Play, play, play" >>hello 870$ echo "Lots of fun" >>example 871$ git commit -m "Some fun." -i hello example 872------------ 873 874since the master branch is obviously in a much better mood. 875 876Now, you've got two branches, and you decide that you want to merge the 877work done. Before we do that, let's introduce a cool graphical tool that 878helps you view what's going on: 879 880---------------- 881$ gitk --all 882---------------- 883 884will show you graphically both of your branches (that's what the `--all` 885means: normally it will just show you your current `HEAD`) and their 886histories. You can also see exactly how they came to be from a common 887source. 888 889Anyway, let's exit 'gitk' (`^Q` or the File menu), and decide that we want 890to merge the work we did on the `mybranch` branch into the `master` 891branch (which is currently our `HEAD` too). To do that, there's a nice 892script called 'git merge', which wants to know which branches you want 893to resolve and what the merge is all about: 894 895------------ 896$ git merge -m "Merge work in mybranch" mybranch 897------------ 898 899where the first argument is going to be used as the commit message if 900the merge can be resolved automatically. 901 902Now, in this case we've intentionally created a situation where the 903merge will need to be fixed up by hand, though, so git will do as much 904of it as it can automatically (which in this case is just merge the `example` 905file, which had no differences in the `mybranch` branch), and say: 906 907---------------- 908 Auto-merging hello 909 CONFLICT (content): Merge conflict in hello 910 Automatic merge failed; fix conflicts and then commit the result. 911---------------- 912 913It tells you that it did an "Automatic merge", which 914failed due to conflicts in `hello`. 915 916Not to worry. It left the (trivial) conflict in `hello` in the same form you 917should already be well used to if you've ever used CVS, so let's just 918open `hello` in our editor (whatever that may be), and fix it up somehow. 919I'd suggest just making it so that `hello` contains all four lines: 920 921------------ 922Hello World 923It's a new day for git 924Play, play, play 925Work, work, work 926------------ 927 928and once you're happy with your manual merge, just do a 929 930------------ 931$ git commit -i hello 932------------ 933 934which will very loudly warn you that you're now committing a merge 935(which is correct, so never mind), and you can write a small merge 936message about your adventures in 'git merge'-land. 937 938After you're done, start up `gitk --all` to see graphically what the 939history looks like. Notice that `mybranch` still exists, and you can 940switch to it, and continue to work with it if you want to. The 941`mybranch` branch will not contain the merge, but next time you merge it 942from the `master` branch, git will know how you merged it, so you'll not 943have to do _that_ merge again. 944 945Another useful tool, especially if you do not always work in X-Window 946environment, is `git show-branch`. 947 948------------------------------------------------ 949$ git show-branch --topo-order --more=1 master mybranch 950* [master] Merge work in mybranch 951 ! [mybranch] Some work. 952-- 953- [master] Merge work in mybranch 954*+ [mybranch] Some work. 955* [master^] Some fun. 956------------------------------------------------ 957 958The first two lines indicate that it is showing the two branches 959with the titles of their top-of-the-tree commits, you are currently on 960`master` branch (notice the asterisk `*` character), and the first 961column for the later output lines is used to show commits contained in the 962`master` branch, and the second column for the `mybranch` 963branch. Three commits are shown along with their titles. 964All of them have non blank characters in the first column (`*` 965shows an ordinary commit on the current branch, `-` is a merge commit), which 966means they are now part of the `master` branch. Only the "Some 967work" commit has the plus `+` character in the second column, 968because `mybranch` has not been merged to incorporate these 969commits from the master branch. The string inside brackets 970before the commit log message is a short name you can use to 971name the commit. In the above example, 'master' and 'mybranch' 972are branch heads. 'master^' is the first parent of 'master' 973branch head. Please see linkgit:gitrevisions[7] if you want to 974see more complex cases. 975 976[NOTE] 977Without the '--more=1' option, 'git show-branch' would not output the 978'[master^]' commit, as '[mybranch]' commit is a common ancestor of 979both 'master' and 'mybranch' tips. Please see linkgit:git-show-branch[1] 980for details. 981 982[NOTE] 983If there were more commits on the 'master' branch after the merge, the 984merge commit itself would not be shown by 'git show-branch' by 985default. You would need to provide '--sparse' option to make the 986merge commit visible in this case. 987 988Now, let's pretend you are the one who did all the work in 989`mybranch`, and the fruit of your hard work has finally been merged 990to the `master` branch. Let's go back to `mybranch`, and run 991'git merge' to get the "upstream changes" back to your branch. 992 993------------ 994$ git checkout mybranch 995$ git merge -m "Merge upstream changes." master 996------------ 997 998This outputs something like this (the actual commit object names 999would be different)10001001----------------1002Updating from ae3a2da... to a80b4aa....1003Fast-forward (no commit created; -m option ignored)1004 example | 1 +1005 hello | 1 +1006 2 files changed, 2 insertions(+)1007----------------10081009Because your branch did not contain anything more than what had1010already been merged into the `master` branch, the merge operation did1011not actually do a merge. Instead, it just updated the top of1012the tree of your branch to that of the `master` branch. This is1013often called 'fast-forward' merge.10141015You can run `gitk --all` again to see how the commit ancestry1016looks like, or run 'show-branch', which tells you this.10171018------------------------------------------------1019$ git show-branch master mybranch1020! [master] Merge work in mybranch1021 * [mybranch] Merge work in mybranch1022--1023-- [master] Merge work in mybranch1024------------------------------------------------102510261027Merging external work1028---------------------10291030It's usually much more common that you merge with somebody else than1031merging with your own branches, so it's worth pointing out that git1032makes that very easy too, and in fact, it's not that different from1033doing a 'git merge'. In fact, a remote merge ends up being nothing1034more than "fetch the work from a remote repository into a temporary tag"1035followed by a 'git merge'.10361037Fetching from a remote repository is done by, unsurprisingly,1038'git fetch':10391040----------------1041$ git fetch <remote-repository>1042----------------10431044One of the following transports can be used to name the1045repository to download from:10461047Rsync::1048 `rsync://remote.machine/path/to/repo.git/`1049+1050Rsync transport is usable for both uploading and downloading,1051but is completely unaware of what git does, and can produce1052unexpected results when you download from the public repository1053while the repository owner is uploading into it via `rsync`1054transport. Most notably, it could update the files under1055`refs/` which holds the object name of the topmost commits1056before uploading the files in `objects/` -- the downloader would1057obtain head commit object name while that object itself is still1058not available in the repository. For this reason, it is1059considered deprecated.10601061SSH::1062 `remote.machine:/path/to/repo.git/` or1063+1064`ssh://remote.machine/path/to/repo.git/`1065+1066This transport can be used for both uploading and downloading,1067and requires you to have a log-in privilege over `ssh` to the1068remote machine. It finds out the set of objects the other side1069lacks by exchanging the head commits both ends have and1070transfers (close to) minimum set of objects. It is by far the1071most efficient way to exchange git objects between repositories.10721073Local directory::1074 `/path/to/repo.git/`1075+1076This transport is the same as SSH transport but uses 'sh' to run1077both ends on the local machine instead of running other end on1078the remote machine via 'ssh'.10791080git Native::1081 `git://remote.machine/path/to/repo.git/`1082+1083This transport was designed for anonymous downloading. Like SSH1084transport, it finds out the set of objects the downstream side1085lacks and transfers (close to) minimum set of objects.10861087HTTP(S)::1088 `http://remote.machine/path/to/repo.git/`1089+1090Downloader from http and https URL1091first obtains the topmost commit object name from the remote site1092by looking at the specified refname under `repo.git/refs/` directory,1093and then tries to obtain the1094commit object by downloading from `repo.git/objects/xx/xxx...`1095using the object name of that commit object. Then it reads the1096commit object to find out its parent commits and the associate1097tree object; it repeats this process until it gets all the1098necessary objects. Because of this behavior, they are1099sometimes also called 'commit walkers'.1100+1101The 'commit walkers' are sometimes also called 'dumb1102transports', because they do not require any git aware smart1103server like git Native transport does. Any stock HTTP server1104that does not even support directory index would suffice. But1105you must prepare your repository with 'git update-server-info'1106to help dumb transport downloaders.11071108Once you fetch from the remote repository, you `merge` that1109with your current branch.11101111However -- it's such a common thing to `fetch` and then1112immediately `merge`, that it's called `git pull`, and you can1113simply do11141115----------------1116$ git pull <remote-repository>1117----------------11181119and optionally give a branch-name for the remote end as a second1120argument.11211122[NOTE]1123You could do without using any branches at all, by1124keeping as many local repositories as you would like to have1125branches, and merging between them with 'git pull', just like1126you merge between branches. The advantage of this approach is1127that it lets you keep a set of files for each `branch` checked1128out and you may find it easier to switch back and forth if you1129juggle multiple lines of development simultaneously. Of1130course, you will pay the price of more disk usage to hold1131multiple working trees, but disk space is cheap these days.11321133It is likely that you will be pulling from the same remote1134repository from time to time. As a short hand, you can store1135the remote repository URL in the local repository's config file1136like this:11371138------------------------------------------------1139$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/1140------------------------------------------------11411142and use the "linus" keyword with 'git pull' instead of the full URL.11431144Examples.11451146. `git pull linus`1147. `git pull linus tag v0.99.1`11481149the above are equivalent to:11501151. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`1152. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`115311541155How does the merge work?1156------------------------11571158We said this tutorial shows what plumbing does to help you cope1159with the porcelain that isn't flushing, but we so far did not1160talk about how the merge really works. If you are following1161this tutorial the first time, I'd suggest to skip to "Publishing1162your work" section and come back here later.11631164OK, still with me? To give us an example to look at, let's go1165back to the earlier repository with "hello" and "example" file,1166and bring ourselves back to the pre-merge state:11671168------------1169$ git show-branch --more=2 master mybranch1170! [master] Merge work in mybranch1171 * [mybranch] Merge work in mybranch1172--1173-- [master] Merge work in mybranch1174+* [master^2] Some work.1175+* [master^] Some fun.1176------------11771178Remember, before running 'git merge', our `master` head was at1179"Some fun." commit, while our `mybranch` head was at "Some1180work." commit.11811182------------1183$ git checkout mybranch1184$ git reset --hard master^21185$ git checkout master1186$ git reset --hard master^1187------------11881189After rewinding, the commit structure should look like this:11901191------------1192$ git show-branch1193* [master] Some fun.1194 ! [mybranch] Some work.1195--1196* [master] Some fun.1197 + [mybranch] Some work.1198*+ [master^] Initial commit1199------------12001201Now we are ready to experiment with the merge by hand.12021203`git merge` command, when merging two branches, uses 3-way merge1204algorithm. First, it finds the common ancestor between them.1205The command it uses is 'git merge-base':12061207------------1208$ mb=$(git merge-base HEAD mybranch)1209------------12101211The command writes the commit object name of the common ancestor1212to the standard output, so we captured its output to a variable,1213because we will be using it in the next step. By the way, the common1214ancestor commit is the "Initial commit" commit in this case. You can1215tell it by:12161217------------1218$ git name-rev --name-only --tags $mb1219my-first-tag1220------------12211222After finding out a common ancestor commit, the second step is1223this:12241225------------1226$ git read-tree -m -u $mb HEAD mybranch1227------------12281229This is the same 'git read-tree' command we have already seen,1230but it takes three trees, unlike previous examples. This reads1231the contents of each tree into different 'stage' in the index1232file (the first tree goes to stage 1, the second to stage 2,1233etc.). After reading three trees into three stages, the paths1234that are the same in all three stages are 'collapsed' into stage12350. Also paths that are the same in two of three stages are1236collapsed into stage 0, taking the SHA1 from either stage 2 or1237stage 3, whichever is different from stage 1 (i.e. only one side1238changed from the common ancestor).12391240After 'collapsing' operation, paths that are different in three1241trees are left in non-zero stages. At this point, you can1242inspect the index file with this command:12431244------------1245$ git ls-files --stage1246100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example1247100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello1248100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello1249100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello1250------------12511252In our example of only two files, we did not have unchanged1253files so only 'example' resulted in collapsing. But in real-life1254large projects, when only a small number of files change in one commit,1255this 'collapsing' tends to trivially merge most of the paths1256fairly quickly, leaving only a handful of real changes in non-zero1257stages.12581259To look at only non-zero stages, use `--unmerged` flag:12601261------------1262$ git ls-files --unmerged1263100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello1264100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello1265100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello1266------------12671268The next step of merging is to merge these three versions of the1269file, using 3-way merge. This is done by giving1270'git merge-one-file' command as one of the arguments to1271'git merge-index' command:12721273------------1274$ git merge-index git-merge-one-file hello1275Auto-merging hello1276ERROR: Merge conflict in hello1277fatal: merge program failed1278------------12791280'git merge-one-file' script is called with parameters to1281describe those three versions, and is responsible to leave the1282merge results in the working tree.1283It is a fairly straightforward shell script, and1284eventually calls 'merge' program from RCS suite to perform a1285file-level 3-way merge. In this case, 'merge' detects1286conflicts, and the merge result with conflict marks is left in1287the working tree.. This can be seen if you run `ls-files1288--stage` again at this point:12891290------------1291$ git ls-files --stage1292100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example1293100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1 hello1294100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2 hello1295100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello1296------------12971298This is the state of the index file and the working file after1299'git merge' returns control back to you, leaving the conflicting1300merge for you to resolve. Notice that the path `hello` is still1301unmerged, and what you see with 'git diff' at this point is1302differences since stage 2 (i.e. your version).130313041305Publishing your work1306--------------------13071308So, we can use somebody else's work from a remote repository, but1309how can *you* prepare a repository to let other people pull from1310it?13111312You do your real work in your working tree that has your1313primary repository hanging under it as its `.git` subdirectory.1314You *could* make that repository accessible remotely and ask1315people to pull from it, but in practice that is not the way1316things are usually done. A recommended way is to have a public1317repository, make it reachable by other people, and when the1318changes you made in your primary working tree are in good shape,1319update the public repository from it. This is often called1320'pushing'.13211322[NOTE]1323This public repository could further be mirrored, and that is1324how git repositories at `kernel.org` are managed.13251326Publishing the changes from your local (private) repository to1327your remote (public) repository requires a write privilege on1328the remote machine. You need to have an SSH account there to1329run a single command, 'git-receive-pack'.13301331First, you need to create an empty repository on the remote1332machine that will house your public repository. This empty1333repository will be populated and be kept up-to-date by pushing1334into it later. Obviously, this repository creation needs to be1335done only once.13361337[NOTE]1338'git push' uses a pair of commands,1339'git send-pack' on your local machine, and 'git-receive-pack'1340on the remote machine. The communication between the two over1341the network internally uses an SSH connection.13421343Your private repository's git directory is usually `.git`, but1344your public repository is often named after the project name,1345i.e. `<project>.git`. Let's create such a public repository for1346project `my-git`. After logging into the remote machine, create1347an empty directory:13481349------------1350$ mkdir my-git.git1351------------13521353Then, make that directory into a git repository by running1354'git init', but this time, since its name is not the usual1355`.git`, we do things slightly differently:13561357------------1358$ GIT_DIR=my-git.git git init1359------------13601361Make sure this directory is available for others you want your1362changes to be pulled via the transport of your choice. Also1363you need to make sure that you have the 'git-receive-pack'1364program on the `$PATH`.13651366[NOTE]1367Many installations of sshd do not invoke your shell as the login1368shell when you directly run programs; what this means is that if1369your login shell is 'bash', only `.bashrc` is read and not1370`.bash_profile`. As a workaround, make sure `.bashrc` sets up1371`$PATH` so that you can run 'git-receive-pack' program.13721373[NOTE]1374If you plan to publish this repository to be accessed over http,1375you should do `mv my-git.git/hooks/post-update.sample1376my-git.git/hooks/post-update` at this point.1377This makes sure that every time you push into this1378repository, `git update-server-info` is run.13791380Your "public repository" is now ready to accept your changes.1381Come back to the machine you have your private repository. From1382there, run this command:13831384------------1385$ git push <public-host>:/path/to/my-git.git master1386------------13871388This synchronizes your public repository to match the named1389branch head (i.e. `master` in this case) and objects reachable1390from them in your current repository.13911392As a real example, this is how I update my public git1393repository. Kernel.org mirror network takes care of the1394propagation to other publicly visible machines:13951396------------1397$ git push master.kernel.org:/pub/scm/git/git.git/1398------------139914001401Packing your repository1402-----------------------14031404Earlier, we saw that one file under `.git/objects/??/` directory1405is stored for each git object you create. This representation1406is efficient to create atomically and safely, but1407not so convenient to transport over the network. Since git objects are1408immutable once they are created, there is a way to optimize the1409storage by "packing them together". The command14101411------------1412$ git repack1413------------14141415will do it for you. If you followed the tutorial examples, you1416would have accumulated about 17 objects in `.git/objects/??/`1417directories by now. 'git repack' tells you how many objects it1418packed, and stores the packed file in `.git/objects/pack`1419directory.14201421[NOTE]1422You will see two files, `pack-*.pack` and `pack-*.idx`,1423in `.git/objects/pack` directory. They are closely related to1424each other, and if you ever copy them by hand to a different1425repository for whatever reason, you should make sure you copy1426them together. The former holds all the data from the objects1427in the pack, and the latter holds the index for random1428access.14291430If you are paranoid, running 'git verify-pack' command would1431detect if you have a corrupt pack, but do not worry too much.1432Our programs are always perfect ;-).14331434Once you have packed objects, you do not need to leave the1435unpacked objects that are contained in the pack file anymore.14361437------------1438$ git prune-packed1439------------14401441would remove them for you.14421443You can try running `find .git/objects -type f` before and after1444you run `git prune-packed` if you are curious. Also `git1445count-objects` would tell you how many unpacked objects are in1446your repository and how much space they are consuming.14471448[NOTE]1449`git pull` is slightly cumbersome for HTTP transport, as a1450packed repository may contain relatively few objects in a1451relatively large pack. If you expect many HTTP pulls from your1452public repository you might want to repack & prune often, or1453never.14541455If you run `git repack` again at this point, it will say1456"Nothing new to pack.". Once you continue your development and1457accumulate the changes, running `git repack` again will create a1458new pack, that contains objects created since you packed your1459repository the last time. We recommend that you pack your project1460soon after the initial import (unless you are starting your1461project from scratch), and then run `git repack` every once in a1462while, depending on how active your project is.14631464When a repository is synchronized via `git push` and `git pull`1465objects packed in the source repository are usually stored1466unpacked in the destination, unless rsync transport is used.1467While this allows you to use different packing strategies on1468both ends, it also means you may need to repack both1469repositories every once in a while.147014711472Working with Others1473-------------------14741475Although git is a truly distributed system, it is often1476convenient to organize your project with an informal hierarchy1477of developers. Linux kernel development is run this way. There1478is a nice illustration (page 17, "Merges to Mainline") in1479link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].14801481It should be stressed that this hierarchy is purely *informal*.1482There is nothing fundamental in git that enforces the "chain of1483patch flow" this hierarchy implies. You do not have to pull1484from only one remote repository.14851486A recommended workflow for a "project lead" goes like this:148714881. Prepare your primary repository on your local machine. Your1489 work is done there.149014912. Prepare a public repository accessible to others.1492+1493If other people are pulling from your repository over dumb1494transport protocols (HTTP), you need to keep this repository1495'dumb transport friendly'. After `git init`,1496`$GIT_DIR/hooks/post-update.sample` copied from the standard templates1497would contain a call to 'git update-server-info'1498but you need to manually enable the hook with1499`mv post-update.sample post-update`. This makes sure1500'git update-server-info' keeps the necessary files up-to-date.150115023. Push into the public repository from your primary1503 repository.150415054. 'git repack' the public repository. This establishes a big1506 pack that contains the initial set of objects as the1507 baseline, and possibly 'git prune' if the transport1508 used for pulling from your repository supports packed1509 repositories.151015115. Keep working in your primary repository. Your changes1512 include modifications of your own, patches you receive via1513 e-mails, and merges resulting from pulling the "public"1514 repositories of your "subsystem maintainers".1515+1516You can repack this private repository whenever you feel like.151715186. Push your changes to the public repository, and announce it1519 to the public.152015217. Every once in a while, 'git repack' the public repository.1522 Go back to step 5. and continue working.152315241525A recommended work cycle for a "subsystem maintainer" who works1526on that project and has an own "public repository" goes like this:152715281. Prepare your work repository, by 'git clone' the public1529 repository of the "project lead". The URL used for the1530 initial cloning is stored in the remote.origin.url1531 configuration variable.153215332. Prepare a public repository accessible to others, just like1534 the "project lead" person does.153515363. Copy over the packed files from "project lead" public1537 repository to your public repository, unless the "project1538 lead" repository lives on the same machine as yours. In the1539 latter case, you can use `objects/info/alternates` file to1540 point at the repository you are borrowing from.154115424. Push into the public repository from your primary1543 repository. Run 'git repack', and possibly 'git prune' if the1544 transport used for pulling from your repository supports1545 packed repositories.154615475. Keep working in your primary repository. Your changes1548 include modifications of your own, patches you receive via1549 e-mails, and merges resulting from pulling the "public"1550 repositories of your "project lead" and possibly your1551 "sub-subsystem maintainers".1552+1553You can repack this private repository whenever you feel1554like.155515566. Push your changes to your public repository, and ask your1557 "project lead" and possibly your "sub-subsystem1558 maintainers" to pull from it.155915607. Every once in a while, 'git repack' the public repository.1561 Go back to step 5. and continue working.156215631564A recommended work cycle for an "individual developer" who does1565not have a "public" repository is somewhat different. It goes1566like this:156715681. Prepare your work repository, by 'git clone' the public1569 repository of the "project lead" (or a "subsystem1570 maintainer", if you work on a subsystem). The URL used for1571 the initial cloning is stored in the remote.origin.url1572 configuration variable.157315742. Do your work in your repository on 'master' branch.157515763. Run `git fetch origin` from the public repository of your1577 upstream every once in a while. This does only the first1578 half of `git pull` but does not merge. The head of the1579 public repository is stored in `.git/refs/remotes/origin/master`.158015814. Use `git cherry origin` to see which ones of your patches1582 were accepted, and/or use `git rebase origin` to port your1583 unmerged changes forward to the updated upstream.158415855. Use `git format-patch origin` to prepare patches for e-mail1586 submission to your upstream and send it out. Go back to1587 step 2. and continue.158815891590Working with Others, Shared Repository Style1591--------------------------------------------15921593If you are coming from CVS background, the style of cooperation1594suggested in the previous section may be new to you. You do not1595have to worry. git supports "shared public repository" style of1596cooperation you are probably more familiar with as well.15971598See linkgit:gitcvs-migration[7] for the details.15991600Bundling your work together1601---------------------------16021603It is likely that you will be working on more than one thing at1604a time. It is easy to manage those more-or-less independent tasks1605using branches with git.16061607We have already seen how branches work previously,1608with "fun and work" example using two branches. The idea is the1609same if there are more than two branches. Let's say you started1610out from "master" head, and have some new code in the "master"1611branch, and two independent fixes in the "commit-fix" and1612"diff-fix" branches:16131614------------1615$ git show-branch1616! [commit-fix] Fix commit message normalization.1617 ! [diff-fix] Fix rename detection.1618 * [master] Release candidate #11619---1620 + [diff-fix] Fix rename detection.1621 + [diff-fix~1] Better common substring algorithm.1622+ [commit-fix] Fix commit message normalization.1623 * [master] Release candidate #11624++* [diff-fix~2] Pretty-print messages.1625------------16261627Both fixes are tested well, and at this point, you want to merge1628in both of them. You could merge in 'diff-fix' first and then1629'commit-fix' next, like this:16301631------------1632$ git merge -m "Merge fix in diff-fix" diff-fix1633$ git merge -m "Merge fix in commit-fix" commit-fix1634------------16351636Which would result in:16371638------------1639$ git show-branch1640! [commit-fix] Fix commit message normalization.1641 ! [diff-fix] Fix rename detection.1642 * [master] Merge fix in commit-fix1643---1644 - [master] Merge fix in commit-fix1645+ * [commit-fix] Fix commit message normalization.1646 - [master~1] Merge fix in diff-fix1647 +* [diff-fix] Fix rename detection.1648 +* [diff-fix~1] Better common substring algorithm.1649 * [master~2] Release candidate #11650++* [master~3] Pretty-print messages.1651------------16521653However, there is no particular reason to merge in one branch1654first and the other next, when what you have are a set of truly1655independent changes (if the order mattered, then they are not1656independent by definition). You could instead merge those two1657branches into the current branch at once. First let's undo what1658we just did and start over. We would want to get the master1659branch before these two merges by resetting it to 'master~2':16601661------------1662$ git reset --hard master~21663------------16641665You can make sure `git show-branch` matches the state before1666those two 'git merge' you just did. Then, instead of running1667two 'git merge' commands in a row, you would merge these two1668branch heads (this is known as 'making an Octopus'):16691670------------1671$ git merge commit-fix diff-fix1672$ git show-branch1673! [commit-fix] Fix commit message normalization.1674 ! [diff-fix] Fix rename detection.1675 * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'1676---1677 - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'1678+ * [commit-fix] Fix commit message normalization.1679 +* [diff-fix] Fix rename detection.1680 +* [diff-fix~1] Better common substring algorithm.1681 * [master~1] Release candidate #11682++* [master~2] Pretty-print messages.1683------------16841685Note that you should not do Octopus because you can. An octopus1686is a valid thing to do and often makes it easier to view the1687commit history if you are merging more than two independent1688changes at the same time. However, if you have merge conflicts1689with any of the branches you are merging in and need to hand1690resolve, that is an indication that the development happened in1691those branches were not independent after all, and you should1692merge two at a time, documenting how you resolved the conflicts,1693and the reason why you preferred changes made in one side over1694the other. Otherwise it would make the project history harder1695to follow, not easier.16961697SEE ALSO1698--------1699linkgit:gittutorial[7],1700linkgit:gittutorial-2[7],1701linkgit:gitcvs-migration[7],1702linkgit:git-help[1],1703link:everyday.html[Everyday git],1704link:user-manual.html[The Git User's Manual]17051706GIT1707---1708Part of the linkgit:git[1] suite.