Distributed Version Control with Git and Mercurial
Total Page：16
File Type：pdf, Size：1020Kb
A.CHRISTOPHERTOREK DISTRIBUTEDVERSION CONTROLWITHGITAND MERCURIAL 2 copyright stuff Dedication NB: this front matter is still quite a hodgepodge; these are just various thoughts. [Find out if I can use a copy of xkcd #1597] Git is notoriously difficult for beginners. In xkcd comic #1597, Randall Munroe, referring to Git, draws a character (called “Cueball” on the explainxkcd site) who says: Just memorize these shell commands and type them to sync up. If you get errors, save your work elsewhere, delete the project, and download a fresh copy. [Maybe turn the above into an epigraph?] Everyone makes mistakes. The difference between being a novice and being an expert cannot be boiled down to just one sentence, but we can say that one—maybe the most important—difference is that an expert can recover from mistakes mid-process. This book should help you do so. Git makes it easy to make mistakes, and also easy to correct them. Mercurial makes it harder to make mistakes, but also harder to cor- rect them. There are already several good Git books, Chacon and Straub [2014] and Loeliger[ 2009]. The primary author of Mercurial has published a Mercurial book, O’Sullivan[ 2009]. So why write another book? Loeliger’s book is good but has become out of date—a constant hazard with actively-developed software. Chacon’s book is on line and gets updated, but focuses strictly on Git. O’Sullivan’s book fo- cuses strictly on Mercurial. I’m not currently aware of any books that approach version control in this particular manner, and show both Git and Mercurial usage. If you are reading this book, you probably have thought about using Git or Mercurial (or even both), or you may have used them in the past or be using them now and want to learn more. You may be considering which one to use. The book will try to address all of these. I also wanted to have a book that could also appear as a series of web pages that were structured very differently. That is, the book would proceed in a logical building-up fashion, but using a web hyperlink, you could start with any particular topic and zoom up or down the scale of generalization or specialization to find specific answers. Part of the project was to write a program to produce hypertext (HTML) web pages. It would read the LaTeX input, and actually use LaTeX to generate figures, but keep the small-section-at-a-time setup. 3 The text for the book and the text for the hypertext setup would live together in (at least relative) harmony. At the time I write this, the outcome of this experiment has yet to be determined. Both Git and Mercurial have many Graphical User Interfaces (GUIs) and Integrated Development Environments (IDEs) that al- low you to browse commits, and in some GUIs and all IDEs, change or create branches, make new commits, and so on. Every one of these is different and we cannot possibly address them, so we will stick with the command line interfaces. [Here’s an intro bit that goes with the xkcd comic] [scene: you’ve been given some shell commands to type] $ git clone ssh://host.name/path/to/repo $ cd repo make changes... $ git commit repeat change-and-commit as needed $ git pull --rebase You may get a merge conflict, and not know what to do. Or maybe you do know what to do, and have done it. But in any case, you want to continue and you try (as instructed): $ git rebase --continue but now you get an error: No changes - did you forget to use ’git add’? If there is nothing left to stage, chances are that something else already introduced the same changes; you might want to skip this patch. When you have resolved this problem run "git rebase --continue". If you would prefer to skip this patch, instead run "git rebase --skip". To check out the original branch and stop rebasing run "git rebase --abort". If you run git status , which is a good thing to use, you simply see: # Not currently on any branch. nothing to commit (working directory clean) You may also run into problems when you have used git merge or git rebase successfully—or so you thought; and then you dis- cover that you want or need to back out of the merge or rebase. This book should set you up so that you know what to do. Organization of this book The book begins with an overview of version control in general. We introduce terminology that you will need, and review some historical version control systems and their distinguishing characteristics. 4 Next, we cover graph theory and how it applies to both Git and Mercurial. It’s worth noting that while this theory has nothing to do with the controlled source itself, it’s a basic building block for performing source control. It not only interacts with merging and rebasing, it is also fundamental to the distributed nature of Git and Mercurial repositories. The third chapter describes more precisely what is in a commit; how we compare one commit to another; and how, at a high level, merging works, using the commit graph described in Chapter 2. It also mentions the issues with file path names that will affect you once you distribute a repository across dissimilar operating systems. The fourth chapter covers the mechanics of distributing repos- itories, and one of the key consequences: that some commits are public and some commits are private. Private commits can be deleted without affecting others, but once a commit is published, it may be impossible to retract it. It also includes some of the theory needed to understand how commits can be signed and authenticated. With these basics out of the way, Chapters 5 and 6 some of the basic setup and usage of both Git and Mercurial. We discover just how similar, and in some cases just how different, the two VCSes are. XXX this is now wrong Chapter 6 discusses diffs: comparisons between pairs of commits, or one commit and the corresponding working-tree files. Chapter 7 covers merging, which—while it has many variations— basically amounts to combining two diffs. Chapter 8 (. is not yet written). Those who want to jump right to using Git or Mercurial can start at Chapter 5, referring back to earlier theory chapters only as needed. However, careful reading of the history and theory chapters should give you a much better idea of what you are doing with the practical aspects of version control. Each page has room for graphics, side notes, and exercises. Side notes that are numbered are specific details regarding items in the main text. Unnumbered side notes are general ideas I find interesting or relevant, yet not directly related to the main text. The exercises are optional, but are meant to verify and cement your understanding of the concepts involved. ASCII Chapter 3 refers to ASCII, the American Standard Code for Infor- mation Interchange. This is a very old standard for saving and ex- changing data on computer systems, in which one single-byte code represents one letter, digit, or other printable symbol (and certain 5 “control” operations including tab, carriage return, and the like). ASCII is an old standard, and by the 1980s, all computers could work with it. It is not adequate to modern needs, but much is built upon it. Numbers This book mostly works with ordinary decimal numbers. However, hashes are typically encoded in hexadecimal, with “digits” that range from 0 through 9 but then continue on with abcdef, which may be written in either uppercase or lowercase. In some places, we will use a leading zero and letter-x to denote hexadecimal numbers: 0x10 rep- resents the same number as 16, 0x80 represents the same number as 128, 0x100 represents the same number as 256, and so on. We will write hashes as a27fc31 and the like, without any leading prefix. While these do represent numbers inside the computer, their deci- malized equivalent representations are not useful for anything. Bugs The term bug dates back to at least the 1870s and Thomas Edison. The first application to computing may have been in 1947 when Grace Hopper’s group at Harvard discovered a moth in the cir- cuitry of the Harvard Mark II computer. (The log book containing the remains of the moth is now in the possession of the Smithsonian Institution; see Smithsonian Institution[ 1994]). Bugs are, however, usually very small, difficult to observe from a distance, and can in- duce a great deal of revulsion in some people. In this book, we will instead use larger, friendlier mammals, specifically marsupials. In- stead of moths, ants, spiders, centipedes, and cockroaches, we will deliberately introduce kangaroos and wallabies into our programs and processes, so as to illustrate their removal. Target Audience, preface, introduction? Animals in this book The Marsupial Maker is not a real project, but marsupials are real This stuff is currently at front of book, creatures, and I find them quite interesting. Here are photos of some but probably should be at back of book. that I took on a trip to parts of Australia in February of 2010. Plate 1: Red kangaroo, Healesville Sanctuary. The kangaroo is probably the most widely known marsupial. There are actually four species of large kangaroo: the red, the eastern and western grey, and the antilopine. There are also smaller tree- kangaroos and rat-kangaroos. 8 Plate 2: Bennet’s wallaby, Cradle Mountain. The wallaby is smaller than any kangaroo, but in fact the term “wallaby” is defined a bit loosely.