Version Control

For Subversion (svn for short):

For Git:

Unfortunately, a lot of Git documentation is hosted at Kernel.org and is currently offline because of their security breach a bit ago.

For Mercurial (hg for short — get it?):

(At the end I talk a little bit about the tradeoffs between centralized and distributed VCSs.)

In the simple case: there is a repository and a working copy. The repository is a database of previous versions; you work out of the working copy.

You can commit the changes you’ve made in the working copy to the repository. This saves the edits you’ve made to the working copy as a new revision:

What about multiple people? In some sense, the easiest case is what’s called centralized version control, like Subversion. You just add another working copy.

Now, what happens to Bob when Alice commits? Immediately nothing. But because there is more than one person, Bob no longer has the most recent version in his working copy. At some point, he will ask Subversion to get the most recent version: this is called an update:

Verson control software will attempt to be smart regarding combining changes; we’ll look at that later.

Relatively recently, distributed VCS have become popular. With a DVCS system, there is no single repository. Instead, each working copy comes with its own repository:

Committing, by itself, only affects the repository associated with a given working copy.

You can transfer information between reposities either by pushing or pulling. If Alice pushes to Bob’s repository, Bob will then have Alice’s changes. If Alice pulls from Bob, then Alice will have Bob’s changes.

Pushing in this sense is relatively rare (and has complications) and I recommend not doing it, but instead using an alternative arrangement which is a little more centralized. There is one master repository which does not have an associated working copy (this kind of repository is called bare by both Git and Mercurial). Everyone pushes to and pulls from this master repository. (In our environment, the master repository would likely reside somewhere on your CS AFS space. The local repositories could be anywhere — another directory on AFS, your laptop, your home desktop, etc.)

Note that if you look at just the interactions between the local repositories and the master repository (and ignore the working copies), this picture looks just like the centralized VCS diagram except that “commit” is replaced by “push” and “update” is replaced by “pull”.

This section gives an overview of what several tasks look like under each VCS.

Here is the once-per-project setup:

Here is what each person does when starting a project to get a working copy or a local repository:

The <url> will be something like ssh://username@best-mumble.cs.wisc.edu/path/to/master if you are hosting the master repository on your AFS space. Subversion uses svn+ssh:// instead of ssh://. For Subversion and Git, the path you give is absolute; for Mercurial, it is relative to your home directory.

Here is what you do after you have made local edits that you want to commit to the repository (you can think of following the lines in sequence):

None of the VCSs will allow you to propagate your changes if your local copy is out-of-date with respect to the master, so you can try to skip the “update” step and see if it works.

You should also use git/hg/svn mv git/hg/svn rm instead of “normal” mv and rm commands. If you are using Subversion, you should also use svn cp instead of cp. (Git and Mercurial don’t have a cp subcommand, but don’t forget to add the new copy after you create it normally.)

One of the big benefits of using version control is it makes collaboration a ton easier. For this section, I’m going to use the term “update”; this refers to what Subversion calls an update or what distributed systems call a “pull.” (It also occurs when merging but talking about that on its own is a much more advanced topic. It might be worthwhile to say that a “pull” has an implicit “merge” built in — in fact, this is what the -u in hg pull -u that I recommended does.)

“All” version control systems make an attempt to merge concurrent changes from different people. What I mean by “concurrent changes” is Alice and Bob both make a change at the same time. Whoever commits (and pushes, in a DVCS) first will have their changes take hold, that much is probably obvious. What isn’t obvious is what happens to the second person. Suppose Alice commits (/pushes) first.

When Bob tries to commit/push his changes, the VCS will complain. Subversion will say that the local copy is “out of date”. Git will allow the local commit of course, but if Bob tries to push his changes to the master repository, Git will reject the push because it is a “non-fast forward” merge. Mercurial will reject the push saying “push creates new remote heads on branch default.” (Do not use the -f option to “fix” this problem unless you know what you’re doing! Pull and merge instead.) The thing that Bob should do now is incorporate the changes that Alice made. Bob does this by updating: svn update, git pull, or hg pull -u. (If you forget the -u, follow Mercurial’s suggestions: merge with hg merge and then commit with hg commit if there are no conflicts.)

Ideally, Alice’s changes and Bob’s changes do not conflict. (We’d say that “Alice’s changes applied cleanly.”) This definitely happens if Alice and Bob changed different files. It can also happen if Alice and Bob change different places in the same file. (For purposes of VCS, “place” means “around the same line.”)

However, if Alice and Bob both change the same place in the same file, there will be a conflict (or sometimes a merge conflict). You will have to manually resolve these. Basically every VCS does the same thing: it displays both versions of the changes to you with conflict markers. This is probably easiest shown in an example.

Suppose both Alice and Bob start with the same file:

Now Alice decides that the message should have a comma in it:

Meanwhile, Bob decides that the message is a little too overstated and wants to tone it down a little bit:

Now Alice commits (and pushes), so the current version in the repository agrees with her. Bob tries to commit (or push) and gets a message about not having the current version. So he updates/pulls, and the VCS informs him that there is a conflict. (Subversion will ask what to do; sometimes you can resolve this right away, but assume Bob answers p to postpone. Git by default just tells you. On the CSL machines, by default Mercurial opens an editior (gvimdiff) to resolve the conflict immediately, but it is possible to change this behavior by editing ~/.hgrc; add merge=internal:merge to the [ui] section. You may want to leave the settings as-is though.)

Bob’s working copy of the copy has been edited with conflict markers:

The <<<<<<< and >>>>>>> denote a conflict, and ======= separates the versions. The top version is Bob’s local copy, and the bottom version is the version that Bob pulled from Alice. (The big hash is the ID of Alice’s commit.)

Bob then looks at what Alice changed, and decides how he wants to integrate the changes. Perhaps like this:

He manually makes this change in an editor, saves the file, and then commits (and pushes).

Here are some other things that you may want to do:

If you’re a Windows user, each has an excellent shell addon: TortoiseSVN, TortoiseGit (on Windows, prefer MSysGit to Cygwin), and TortoiseHg. (Well, I have firsthand experience with the first two. Hopefully TortoiseHg lives up to the TortoiseCVS/TortoiseSVN predecessors.)

If you want to learn more, there’s a lot to do:

Seeing as how similar the diagrams are, what benefits do DVCSs have over centralized version control?

The main drawback to DVCSs are that they are a bit more complicated, both conceptually and practically. The conceptual complication is evident in the complexity of the DVCS diagram relative to the centralized one. Practically speaking, DVCS tools are a lot newer than centralized tools, and are a little less refined in their user interface in some respects. There’s no way I would go from Git back to Subversion under my own free will, but there have been some times when I’ve gotten my Git repositories into a weird state. (Nothing irrecoverable though.) And there are enough refinements in the interface (like the aforementioned git add --interactive) to make up for the loss.

If you choose to use a distributed VCS, I recommend either Git or Mercurial (Hg), though there are a number of other choices. (Some other open source ones are Bazaar (bzr), Darcs, and Monotone.) I use Git, but Mercurial seems to be slightly more popular amongst your classmates who are familiar with a DVCS. If you choose to use a centralized VCS, I think there is really only one reasonable open source choice: Subversion. CVS falls into this category, but Subversion is so much better that there’s basically no reason that CVS should ever be used for a new project.

Git vs Mercurial is pretty much a tossup I think. I choose Git for my stuff, and I have a couple reasons why I think I’d prefer it, but I haven’t exactly given Mercurial a totally fair shake. My general impression is that in the areas where they differ, Git makes harder stuff easier and Mercurial makes easy stuff easier.

(There are also a lot of proprietary choices, especially in the centralized case. Perforce, ClearCase, Visual SourceSafe, and the Team Foundation Server are some of the ones you may have heard of. BitKeeper is the big commercial name in the distributed world. There are lots of others, though.)