1A short git tutorial 2==================== 3May 2005 4 5 6Introduction 7------------ 8 9This is trying to be a short tutorial on setting up and using a git 10archive, mainly because being hands-on and using explicit examples is 11often the best way of explaining what is going on. 12 13In normal life, most people wouldn't use the "core" git programs 14directly, but rather script around them to make them more palatable. 15Understanding the core git stuff may help some people get those scripts 16done, though, and it may also be instructive in helping people 17understand what it is that the higher-level helper scripts are actually 18doing. 19 20The core git is often called "plumbing", with the prettier user 21interfaces on top of it called "porcelain". You may not want to use the 22plumbing directly very often, but it can be good to know what the 23plumbing does for when the porcelain isn't flushing... 24 25 26Creating a git archive 27---------------------- 28 29Creating a new git archive couldn't be easier: all git archives start 30out empty, and the only thing you need to do is find yourself a 31subdirectory that you want to use as a working tree - either an empty 32one for a totally new project, or an existing working tree that you want 33to import into git. 34 35For our first example, we're going to start a totally new archive from 36scratch, with no pre-existing files, and we'll call it "git-tutorial". 37To start up, create a subdirectory for it, change into that 38subdirectory, and initialize the git infrastructure with "git-init-db": 39 40 mkdir git-tutorial 41 cd git-tutorial 42 git-init-db 43 44to which git will reply 45 46 defaulting to local storage area 47 48which is just git's way of saying that you haven't been doing anything 49strange, and that it will have created a local .git directory setup for 50your new project. You will now have a ".git" directory, and you can 51inspect that with "ls". For your new empty project, ls should show you 52three entries: 53 54 - a symlink called HEAD, pointing to "refs/heads/master" 55 56 Don't worry about the fact that the file that the HEAD link points to 57 doesn't even exist yet - you haven't created the commit that will 58 start your HEAD development branch yet. 59 60 - a subdirectory called "objects", which will contain all the git SHA1 61 objects of your project. You should never have any real reason to 62 look at the objects directly, but you might want to know that these 63 objects are what contains all the real _data_ in your repository. 64 65 - a subdirectory called "refs", which contains references to objects. 66 67 In particular, the "refs" subdirectory will contain two other 68 subdirectories, named "heads" and "tags" respectively. They do 69 exactly what their names imply: they contain references to any number 70 of different "heads" of development (aka "branches"), and to any 71 "tags" that you have created to name specific versions of your 72 repository. 73 74 One note: the special "master" head is the default branch, which is 75 why the .git/HEAD file was created as a symlink to it even if it 76 doesn't yet exist. Basically, the HEAD link is supposed to always 77 point to the branch you are working on right now, and you always 78 start out expecting to work on the "master" branch. 79 80 However, this is only a convention, and you can name your branches 81 anything you want, and don't have to ever even _have_ a "master" 82 branch. A number of the git tools will assume that .git/HEAD is 83 valid, though. 84 85 [ Implementation note: an "object" is identified by its 160-bit SHA1 86 hash, aka "name", and a reference to an object is always the 40-byte 87 hex representation of that SHA1 name. The files in the "refs" 88 subdirectory are expected to contain these hex references (usually 89 with a final '\n' at the end), and you should thus expect to see a 90 number of 41-byte files containing these references in this refs 91 subdirectories when you actually start populating your tree ] 92 93You have now created your first git archive. Of course, since it's 94empty, that's not very useful, so let's start populating it with data. 95 96 97 Populating a git archive 98 ------------------------ 99 100We'll keep this simple and stupid, so we'll start off with populating a 101few trivial files just to get a feel for it. 102 103Start off with just creating any random files that you want to maintain 104in your git archive. We'll start off with a few bad examples, just to 105get a feel for how this works: 106 107 echo "Hello World" > a 108 echo "Silly example" > b 109 110you have now created two files in your working directory, but to 111actually check in your hard work, you will have to go through two steps: 112 113 - fill in the "cache" aka "index" file with the information about your 114 working directory state 115 116 - commit that index file as an object. 117 118The first step is trivial: when you want to tell git about any changes 119to your working directory, you use the "git-update-cache" program. That 120program normally just takes a list of filenames you want to update, but 121to avoid trivial mistakes, it refuses to add new entries to the cache 122(or remove existing ones) unless you explicitly tell it that you're 123adding a new entry with the "--add" flag (or removing an entry with the 124"--remove") flag. 125 126So to populate the index with the two files you just created, you can do 127 128 git-update-cache --add a b 129 130and you have now told git to track those two files. 131 132In fact, as you did that, if you now look into your object directory, 133you'll notice that git will have added two new objects to the object 134store. If you did exactly the steps above, you should now be able to do 135 136 ls .git/objects/??/* 137 138and see two files: 139 140 .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 141 .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 142 143which correspond with the object with SHA1 names of 557db... and f24c7.. 144respectively. 145 146If you want to, you can use "git-cat-file" to look at those objects, but 147you'll have to use the object name, not the filename of the object: 148 149 git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 150 151where the "-t" tells git-cat-file to tell you what the "type" of the 152object is. Git will tell you that you have a "blob" object (ie just a 153regular file), and you can see the contents with 154 155 git-cat-file "blob" 557db03de997c86a4a028e1ebd3a1ceb225be238 156 157which will print out "Hello World". The object 557db... is nothing 158more than the contents of your file "a". 159 160[ Digression: don't confuse that object with the file "a" itself. The 161 object is literally just those specific _contents_ of the file, and 162 however much you later change the contents in file "a", the object we 163 just looked at will never change. Objects are immutable. ] 164 165Anyway, as we mentioned previously, you normally never actually take a 166look at the objects themselves, and typing long 40-character hex SHA1 167names is not something you'd normally want to do. The above digression 168was just to show that "git-update-cache" did something magical, and 169actually saved away the contents of your files into the git content 170store. 171 172Updating the cache did something else too: it created a ".git/index" 173file. This is the index that describes your current working tree, and 174something you should be very aware of. Again, you normally never worry 175about the index file itself, but you should be aware of the fact that 176you have not actually really "checked in" your files into git so far, 177you've only _told_ git about them. 178 179However, since git knows about them, you can now start using some of the 180most basic git commands to manipulate the files or look at their status. 181 182In particular, let's not even check in the two files into git yet, we'll 183start off by adding another line to "a" first: 184 185 echo "It's a new day for git" >> a 186 187and you can now, since you told git about the previous state of "a", ask 188git what has changed in the tree compared to your old index, using the 189"git-diff-files" command: 190 191 git-diff-files 192 193oops. That wasn't very readable. It just spit out its own internal 194version of a "diff", but that internal version really just tells you 195that it has noticed that "a" has been modified, and that the old object 196contents it had have been replaced with something else. 197 198To make it readable, we can tell git-diff-files to output the 199differences as a patch, using the "-p" flag: 200 201 git-diff-files -p 202 203which will spit out 204 205 diff --git a/a b/a 206 --- a/a 207 +++ b/a 208 @@ -1 +1,2 @@ 209 Hello World 210 +It's a new day for git 211 212ie the diff of the change we caused by adding another line to "a". 213 214In other words, git-diff-files always shows us the difference between 215what is recorded in the index, and what is currently in the working 216tree. That's very useful. 217 218A common shorthand for "git-diff-files -p" is to just write 219 220 git diff 221 222which will do the same thing. 223 224 225 Committing git state 226 -------------------- 227 228Now, we want to go to the next stage in git, which is to take the files 229that git knows about in the index, and commit them as a real tree. We do 230that in two phases: creating a "tree" object, and committing that "tree" 231object as a "commit" object together with an explanation of what the 232tree was all about, along with information of how we came to that state. 233 234Creating a tree object is trivial, and is done with "git-write-tree". 235There are no options or other input: git-write-tree will take the 236current index state, and write an object that describes that whole 237index. In other words, we're now tying together all the different 238filenames with their contents (and their permissions), and we're 239creating the equivalent of a git "directory" object: 240 241 git-write-tree 242 243and this will just output the name of the resulting tree, in this case 244(if you have does exactly as I've described) it should be 245 246 3ede4ed7e895432c0a247f09d71a76db53bd0fa4 247 248which is another incomprehensible object name. Again, if you want to, 249you can use "git-cat-file -t 3ede4.." to see that this time the object 250is not a "blob" object, but a "tree" object (you can also use 251git-cat-file to actually output the raw object contents, but you'll see 252mainly a binary mess, so that's less interesting). 253 254However - normally you'd never use "git-write-tree" on its own, because 255normally you always commit a tree into a commit object using the 256"git-commit-tree" command. In fact, it's easier to not actually use 257git-write-tree on its own at all, but to just pass its result in as an 258argument to "git-commit-tree". 259 260"git-commit-tree" normally takes several arguments - it wants to know 261what the _parent_ of a commit was, but since this is the first commit 262ever in this new archive, and it has no parents, we only need to pass in 263the tree ID. However, git-commit-tree also wants to get a commit message 264on its standard input, and it will write out the resulting ID for the 265commit to its standard output. 266 267And this is where we start using the .git/HEAD file. The HEAD file is 268supposed to contain the reference to the top-of-tree, and since that's 269exactly what git-commit-tree spits out, we can do this all with a simple 270shell pipeline: 271 272 echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD 273 274which will say: 275 276 Committing initial tree 3ede4ed7e895432c0a247f09d71a76db53bd0fa4 277 278just to warn you about the fact that it created a totally new commit 279that is not related to anything else. Normally you do this only _once_ 280for a project ever, and all later commits will be parented on top of an 281earlier commit, and you'll never see this "Committing initial tree" 282message ever again. 283 284Again, normally you'd never actually do this by hand. There is a 285helpful script called "git commit" that will do all of this for you. So 286you could have just writtten 287 288 git commit 289 290instead, and it would have done the above magic scripting for you. 291 292 293 Making a change 294 --------------- 295 296Remember how we did the "git-update-cache" on file "a" and then we 297changed "a" afterward, and could compare the new state of "a" with the 298state we saved in the index file? 299 300Further, remember how I said that "git-write-tree" writes the contents 301of the _index_ file to the tree, and thus what we just committed was in 302fact the _original_ contents of the file "a", not the new ones. We did 303that on purpose, to show the difference between the index state, and the 304state in the working directory, and how they don't have to match, even 305when we commit things. 306 307As before, if we do "git-diff-files -p" in our git-tutorial project, 308we'll still see the same difference we saw last time: the index file 309hasn't changed by the act of committing anything. However, now that we 310have committed something, we can also learn to use a new command: 311"git-diff-cache". 312 313Unlike "git-diff-files", which showed the difference between the index 314file and the working directory, "git-diff-cache" shows the differences 315between a committed _tree_ and either the the index file or the working 316directory. In other words, git-diff-cache wants a tree to be diffed 317against, and before we did the commit, we couldn't do that, because we 318didn't have anything to diff against. 319 320But now we can do 321 322 git-diff-cache -p HEAD 323 324(where "-p" has the same meaning as it did in git-diff-files), and it 325will show us the same difference, but for a totally different reason. 326Now we're comparing the working directory not against the index file, 327but against the tree we just wrote. It just so happens that those two 328are obviously the same, so we get the same result. 329 330Again, because this is a common operation, you can also just shorthand 331it with 332 333 git diff HEAD 334 335which ends up doing the above for you. 336 337In other words, "git-diff-cache" normally compares a tree against the 338working directory, but when given the "--cached" flag, it is told to 339instead compare against just the index cache contents, and ignore the 340current working directory state entirely. Since we just wrote the index 341file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return 342an empty set of differences, and that's exactly what it does. 343 344[ Digression: "git-diff-cache" really always uses the index for its 345 comparisons, and saying that it compares a tree against the working 346 directory is thus not strictly accurate. In particular, the list of 347 files to compare (the "meta-data") _always_ comes from the index file, 348 regardless of whether the --cached flag is used or not. The --cached 349 flag really only determines whether the file _contents_ to be compared 350 come from the working directory or not. 351 352 This is not hard to understand, as soon as you realize that git simply 353 never knows (or cares) about files that it is not told about 354 explicitly. Git will never go _looking_ for files to compare, it 355 expects you to tell it what the files are, and that's what the index 356 is there for. ] 357 358However, our next step is to commit the _change_ we did, and again, to 359understand what's going on, keep in mind the difference between "working 360directory contents", "index file" and "committed tree". We have changes 361in the working directory that we want to commit, and we always have to 362work through the index file, so the first thing we need to do is to 363update the index cache: 364 365 git-update-cache a 366 367(note how we didn't need the "--add" flag this time, since git knew 368about the file already). 369 370Note what happens to the different git-diff-xxx versions here. After 371we've updated "a" in the index, "git-diff-files -p" now shows no 372differences, but "git-diff-cache -p HEAD" still _does_ show that the 373current state is different from the state we committed. In fact, now 374"git-diff-cache" shows the same difference whether we use the "--cached" 375flag or not, since now the index is coherent with the working directory. 376 377Now, since we've updated "a" in the index, we can commit the new 378version. We could do it by writing the tree by hand again, and 379committing the tree (this time we'd have to use the "-p HEAD" flag to 380tell commit that the HEAD was the _parent_ of the new commit, and that 381this wasn't an initial commit any more), but you've done that once 382already, so let's just use the helpful script this time: 383 384 git commit 385 386which starts an editor for you to write the commit message and tells you 387a bit about what you're doing. 388 389Write whatever message you want, and all the lines that start with '#' 390will be pruned out, and the rest will be used as the commit message for 391the change. If you decide you don't want to commit anything after all at 392this point (you can continue to edit things and update the cache), you 393can just leave an empty message. Otherwise git-commit-script will commit 394the change for you. 395 396You've now made your first real git commit. And if you're interested in 397looking at what git-commit-script really does, feel free to investigate: 398it's a few very simple shell scripts to generate the helpful (?) commit 399message headers, and a few one-liners that actually do the commit itself. 400 401 402 Checking it out 403 --------------- 404 405While creating changes is useful, it's even more useful if you can tell 406later what changed. The most useful command for this is another of the 407"diff" family, namely "git-diff-tree". 408 409git-diff-tree can be given two arbitrary trees, and it will tell you the 410differences between them. Perhaps even more commonly, though, you can 411give it just a single commit object, and it will figure out the parent 412of that commit itself, and show the difference directly. Thus, to get 413the same diff that we've already seen several times, we can now do 414 415 git-diff-tree -p HEAD 416 417(again, "-p" means to show the difference as a human-readable patch), 418and it will show what the last commit (in HEAD) actually changed. 419 420More interestingly, you can also give git-diff-tree the "-v" flag, which 421tells it to also show the commit message and author and date of the 422commit, and you can tell it to show a whole series of diffs. 423Alternatively, you can tell it to be "silent", and not show the diffs at 424all, but just show the actual commit message. 425 426In fact, together with the "git-rev-list" program (which generates a 427list of revisions), git-diff-tree ends up being a veritable fount of 428changes. A trivial (but very useful) script called "git-whatchanged" is 429included with git which does exactly this, and shows a log of recent 430activity. 431 432To see the whole history of our pitiful little git-tutorial project, you 433can do 434 435 git log 436 437which shows just the log messages, or if we want to see the log together 438with the associated patches use the more complex (and much more 439powerful) 440 441 git-whatchanged -p --root 442 443and you will see exactly what has changed in the repository over its 444short history. 445 446[ Side note: the "--root" flag is a flag to git-diff-tree to tell it to 447 show the initial aka "root" commit too. Normally you'd probably not 448 want to see the initial import diff, but since the tutorial project 449 was started from scratch and is so small, we use it to make the result 450 a bit more interesting ] 451 452With that, you should now be having some inkling of what git does, and 453can explore on your own. 454 455 456 Copying archives 457 ----------------- 458 459Git archives are normally totally self-sufficient, and it's worth noting 460that unlike CVS, for example, there is no separate notion of 461"repository" and "working tree". A git repository normally _is_ the 462working tree, with the local git information hidden in the ".git" 463subdirectory. There is nothing else. What you see is what you got. 464 465[ Side note: you can tell git to split the git internal information from 466 the directory that it tracks, but we'll ignore that for now: it's not 467 how normal projects work, and it's really only meant for special uses. 468 So the mental model of "the git information is always tied directly to 469 the working directory that it describes" may not be technically 100% 470 accurate, but it's a good model for all normal use ] 471 472This has two implications: 473 474 - if you grow bored with the tutorial archive you created (or you've 475 made a mistake and want to start all over), you can just do simple 476 477 rm -rf git-tutorial 478 479 and it will be gone. There's no external repository, and there's no 480 history outside of the project you created. 481 482 - if you want to move or duplicate a git archive, you can do so. There 483 is "git clone" command, but if all you want to do is just to 484 create a copy of your archive (with all the full history that 485 went along with it), you can do so with a regular 486 "cp -a git-tutorial new-git-tutorial". 487 488 Note that when you've moved or copied a git archive, your git index 489 file (which caches various information, notably some of the "stat" 490 information for the files involved) will likely need to be refreshed. 491 So after you do a "cp -a" to create a new copy, you'll want to do 492 493 git-update-cache --refresh 494 495 to make sure that the index file is up-to-date in the new one. 496 497Note that the second point is true even across machines. You can 498duplicate a remote git archive with _any_ regular copy mechanism, be it 499"scp", "rsync" or "wget". 500 501When copying a remote repository, you'll want to at a minimum update the 502index cache when you do this, and especially with other peoples 503repositories you often want to make sure that the index cache is in some 504known state (you don't know _what_ they've done and not yet checked in), 505so usually you'll precede the "git-update-cache" with a 506 507 git-read-tree --reset HEAD 508 git-update-cache --refresh 509 510which will force a total index re-build from the tree pointed to by HEAD 511(it resets the index contents to HEAD, and then the git-update-cache 512makes sure to match up all index entries with the checked-out files). 513 514The above can also be written as simply 515 516 git reset 517 518and in fact a lot of the common git command combinations can be scripted 519with the "git xyz" interfaces, and you can learn things by just looking 520at what the git-*-script scripts do ("git reset" is the above two lines 521implemented in "git-reset-script", but some things like "git status" and 522"git commit" are slightly more complex scripts around the basic git 523commands). 524 525NOTE! Many (most?) public remote repositories will not contain any of 526the checked out files or even an index file, and will _only_ contain the 527actual core git files. Such a repository usually doesn't even have the 528".git" subdirectory, but has all the git files directly in the 529repository. 530 531To create your own local live copy of such a "raw" git repository, you'd 532first create your own subdirectory for the project, and then copy the 533raw repository contents into the ".git" directory. For example, to 534create your own copy of the git repository, you'd do the following 535 536 mkdir my-git 537 cd my-git 538 rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git .git 539 540followed by 541 542 git-read-tree HEAD 543 544to populate the index. However, now you have populated the index, and 545you have all the git internal files, but you will notice that you don't 546actually have any of the _working_directory_ files to work on. To get 547those, you'd check them out with 548 549 git-checkout-cache -u -a 550 551where the "-u" flag means that you want the checkout to keep the index 552up-to-date (so that you don't have to refresh it afterward), and the 553"-a" flag means "check out all files" (if you have a stale copy or an 554older version of a checked out tree you may also need to add the "-f" 555flag first, to tell git-checkout-cache to _force_ overwriting of any old 556files). 557 558Again, this can all be simplified with 559 560 git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git 561 cd my-git 562 git checkout 563 564which will end up doing all of the above for you. 565 566You have now successfully copied somebody else's (mine) remote 567repository, and checked it out. 568 569 570 Creating a new branch 571 --------------------- 572 573Branches in git are really nothing more than pointers into the git 574object space from within the ",git/refs/" subdirectory, and as we 575already discussed, the HEAD branch is nothing but a symlink to one of 576these object pointers. 577 578You can at any time create a new branch by just picking an arbitrary 579point in the project history, and just writing the SHA1 name of that 580object into a file under .git/refs/heads/. You can use any filename you 581want (and indeed, subdirectories), but the convention is that the 582"normal" branch is called "master". That's just a convention, though, 583and nothing enforces it. 584 585To show that as an example, let's go back to the git-tutorial archive we 586used earlier, and create a branch in it. You literally do that by just 587creating a new SHA1 reference file, and switch to it by just making the 588HEAD pointer point to it: 589 590 cat .git/HEAD > .git/refs/heads/mybranch 591 ln -sf refs/heads/mybranch .git/HEAD 592 593and you're done. 594 595Now, if you make the decision to start your new branch at some other 596point in the history than the current HEAD, you usually also want to 597actually switch the contents of your working directory to that point 598when you switch the head, and "git checkout" will do that for you: 599instead of switching the branch by hand with "ln -sf", you can just do 600 601 git checkout mybranch 602 603which will basically "jump" to the branch specified, update your working 604directory to that state, and also make it become the new default HEAD. 605 606You can always just jump back to your original "master" branch by doing 607 608 git checkout master 609 610and if you forget which branch you happen to be on, a simple 611 612 ls -l .git/HEAD 613 614will tell you where it's pointing. 615 616 617 Merging two branches 618 -------------------- 619 620One of the ideas of having a branch is that you do some (possibly 621experimental) work in it, and eventually merge it back to the main 622branch. So assuming you created the above "mybranch" that started out 623being the same as the original "master" branch, let's make sure we're in 624that branch, and do some work there. 625 626 git checkout mybranch 627 echo "Work, work, work" >> a 628 git commit a 629 630Here, we just added another line to "a", and we used a shorthand for 631both going a "git-update-cache a" and "git commit" by just giving the 632filename directly to "git commit". 633 634Now, to make it a bit more interesting, let's assume that somebody else 635does some work in the original branch, and simulate that by going back 636to the master branch, and editing the same file differently there: 637 638 git checkout master 639 640Here, take a moment to look at the contents of "a", and notice how they 641don't contain the work we just did in "mybranch" - because that work 642hasn't happened in the "master" branch at all. Then do 643 644 echo "Play, play, play" >> a 645 echo "Lots of fun" >> b 646 git commit a b 647 648since the master branch is obviously in a much better mood. 649 650Now, you've got two branches, and you decide that you want to merge the 651work done. Before we do that, let's introduce a cool graphical tool that 652helps you view what's going on: 653 654 gitk --all 655 656will show you graphically both of your branches (that's what the "--all" 657means: normally it will just show you your current HEAD) and their 658histories. You can also see exactly how they came to be from a common 659source. 660 661Anyway, let's exit gitk (^Q or the File menu), and decide that we want 662to merge the work we did on the "mybranch" branch into the "master" 663branch (which is currently our HEAD too). To do that, there's a nice 664script called "git resolve", which wants to know which branches you want 665to resolve and what the merge is all about: 666 667 git resolve HEAD mybranch "Merge work in mybranch" 668 669where the third argument is going to be used as the commit message if 670the merge can be resolved automatically. 671 672Now, in this case we've intentionally created a situation where the 673merge will need to be fixed up by hand, though, so git will do as much 674of it as it can automatically (which in this case is just merge the "b" 675file, which had no differences in the "mybranch" branch), and say: 676 677 Simple merge failed, trying Automatic merge 678 Auto-merging a. 679 merge: warning: conflicts during merge 680 ERROR: Merge conflict in a. 681 fatal: merge program failed 682 Automatic merge failed, fix up by hand 683 684which is way too verbose, but it basically tells you that it failed the 685really trivial merge ("Simple merge") and did an "Automatic merge" 686instead, but that too failed due to conflicts in "a". 687 688Not to worry. It left the (trivial) conflict in "a" in the same form you 689should already be well used to if you've ever used CVS, so let's just 690open "a" in our editor (whatever that may be), and fix it up somehow. 691I'd suggest just making it so that "a" contains all four lines: 692 693 Hello World 694 It's a new day for git 695 Play, play, play 696 Work, work, work 697 698and once you're happy with your manual merge, just do a 699 700 git commit a 701 702which will very loudly warn you that you're now committing a merge 703(which is correct, so never mind), and you can write a small merge 704message about your adventures in git-merge-land. 705 706After you're done, start up "gitk --all" to see graphically what the 707history looks like. Notive that "mybranch" still exists, and you can 708switch to it, and continue to work with it if you want to. The 709"mybranch" branch will not contain the merge, but next time you merge it 710from the "master" branch, git will know how you merged it, so you'll not 711have to do _that_ merge again. 712 713 714 Merging external work 715 --------------------- 716 717It's usually much more common that you merge with somebody else than 718merging with your own branches, so it's worth pointing out that git 719makes that very easy too, and in fact, it's not that different from 720doing a "git resolve". In fact, a remote merge ends up being nothing 721more than "fetch the work from a remote repository into a temporary tag" 722followed by a "git resolve". 723 724It's such a common thing to do that it's called "git pull", and you can 725simply do 726 727 git pull <remote-repository> 728 729and optionally give a branch-name for the remote end as a second 730argument. 731 732[ Todo: fill in real examples ] 733 734 735 Tagging a version 736 ----------------- 737 738In git, there's two kinds of tags, a "light" one, and a "signed tag". 739 740A "light" tag is technically nothing more than a branch, except we put 741it in the ".git/refs/tags/" subdirectory instead of calling it a "head". 742So the simplest form of tag involves nothing more than 743 744 cat .git/HEAD > .git/refs/tags/my-first-tag 745 746after which point you can use this symbolic name for that particular 747state. You can, for example, do 748 749 git diff my-first-tag 750 751to diff your current state against that tag (which at this point will 752obviously be an empty diff, but if you continue to develop and commit 753stuff, you can use your tag as a "anchor-point" to see what has changed 754since you tagged it. 755 756A "signed tag" is actually a real git object, and contains not only a 757pointer to the state you want to tag, but also a small tag name and 758message, along with a PGP signature that says that yes, you really did 759that tag. You create these signed tags with 760 761 git tag <tagname> 762 763which will sign the current HEAD (but you can also give it another 764argument that specifies the thing to tag, ie you could have tagged the 765current "mybranch" point by using "git tag <tagname> mybranch"). 766 767You normally only do signed tags for major releases or things 768like that, while the light-weight tags are useful for any marking you 769want to do - any time you decide that you want to remember a certain 770point, just create a private tag for it, and you have a nice symbolic 771name for the state at that point. 772 773 774 Publishing your work 775 -------------------- 776 777We already talked about using somebody else's work from a remote 778repository, in the "merging external work" section. It involved 779fetching the work from a remote repository; but how would _you_ 780prepare a repository so that other people can fetch from it? 781 782Your real work happens in your working directory with your 783primary repository hanging under it as its ".git" subdirectory. 784You _could_ make it accessible remotely and ask people to pull 785from it, but in practice that is not the way things are usually 786done. A recommended way is to have a public repository, make it 787reachable by other people, and when the changes you made in your 788primary working directory are in good shape, update the public 789repository with it. 790 791[ Side note: this public repository could further be mirrored, 792 and that is how kernel.org git repositories are done. ] 793 794Publishing the changes from your private repository to your 795public repository requires you to have write privilege on the 796machine that hosts your public repository, and it is internally 797done via an SSH connection. 798 799First, you need to create an empty repository to push to on the 800machine that houses your public repository. This needs to be 801done only once. 802 803Your private repository's GIT directory is usually .git, but 804often your public repository is named "<projectname>.git". 805Let's create such a public repository for project "my-git". 806After logging into the remote machine, create an empty 807directory: 808 809 mkdir my-git.git 810 811Then, initialize that directory with git-init-db, but this time, 812since it's name is not usual ".git", we do things a bit 813differently: 814 815 GIT_DIR=my-git.git git-init-db 816 817Make sure this directory is available for others you want your 818changes to be pulled by. Also make sure that you have the 819'git-receive-pack' program on the $PATH. 820 821[ Side note: many installations of sshd does not invoke your 822 shell as the login shell when you directly run programs; what 823 this means is that if your login shell is bash, only .bashrc 824 is read bypassing .bash_profile. As a workaround, make sure 825 .bashrc sets up $PATH so that 'git-receive-pack' program can 826 be run. ] 827 828Your 'public repository' is ready to accept your changes. Now, 829come back to the machine you have your private repository. From 830there, run this command: 831 832 git push <public-host>:/path/to/my-git.git master 833 834This synchronizes your public repository to match the named 835branch head (i.e. refs/heads/master in this case) and objects 836reachable from them in your current repository. 837 838As a real example, this is how I update my public git 839repository. Kernel.org mirror network takes care of the 840propagation to other publically visible machines: 841 842 git push master.kernel.org:/pub/scm/git/git.git/ 843 844 845[ to be continued.. cvsimports, pushing and pulling ]