Reading 5: Version Control

Software in 6.005

Safe from bugs	Easy to understand	Ready for change
Correct today and correct in the unknown future.	Communicating clearly with future programmers, including future you.	Designed to accommodate change without rewriting.

Objectives

• In this reading, learn what version control is and why we use it
• In class, practice understanding, creating, and using version history

Introduction

Version control systems are essential tools of the software engineering world. More or less every project — serious or hobby, open source or proprietary — uses version control. Without version control, coordinating a team of programmers all editing the same project’s code will reach pull-out-your-hair levels of aggravation.

Version control systems you’ve already used

• Dropbox
• Undo/redo buffer
• Keeping multiple copies of files with version numbers

Project Report	Project Report v2	Project Report v3	Project Report final	Project Report final-v2	Project Report final-v2-fix-part-5

Inventing version control

Suppose Alice is working on a pset by herself.

She starts with one file A.java in her pset, which she works on for several days.

At the last minute before she needs to hand in her pset to be graded, she realizes she has made a change that breaks everything. If only she could go back in time and retrieve a past version!

A simple discipline of saving backup files would get the job done.

Alice uses her judgment to decide when she has reached some milestone that justifies saving the code. She saves the versions of A.java as A.1.java, A.2.java, and A.java. She follows the convention that the most recent version is just A.java to avoid confusing Eclipse. We will call the most recent version the head.

Now when Alice realizes that version 3 is fatally flawed, she can just copy version 2 back into the location for her current code. Disaster averted! But what if version 3 included some changes that were good and some that were bad? Alice can compare the files manually to find the changes, and sort them into good and bad changes. Then she can copy the good changes into version 2.

This is a lot of work, and it’s easy for the human eye to miss changes. Luckily, there are standard software tools for comparing text; in the UNIX world, one such tool is diff. A better version control system will make diffs easy to generate.

Alice also wants to be prepared in case her laptop gets run over by a bus, so she saves a backup of her work in the cloud, uploading the contents of her working directory whenever she’s satisfied with its contents.

If her laptop is kicked into the Charles, Alice can retrieve the backup and resume work on the pset on a fresh machine, retaining the ability to time-travel back to old versions at will.

Furthermore, she can develop her pset on multiple machines, using the cloud provider as a common interchange point. Alice makes some changes on her laptop and uploads them to the cloud. Then she downloads onto her desktop machine at home, does some more work, and uploads the improved code (complete with old file versions) back to the cloud.

If Alice isn’t careful, though, she can run into trouble with this approach. Imagine that she starts editing A.java to create “version 5” on her laptop. Then she gets distracted and forgets about her changes. Later, she starts working on a new “version 5” on her desktop machine, including different improvements. We’ll call these versions “5L” and “5D,” for “laptop” and “desktop.”

When it comes time to upload changes to the cloud, there is an opportunity for a mishap! Alice might copy all her local files into the cloud, causing it to contain version 5D only. Later Alice syncs from the cloud to her laptop, potentially overwriting version 5L, losing the worthwhile changes. What Alice really wants above is a merge, to create a new version based on the two version 5’s.

OK, considering just the scenario of one programmer working alone, we already have a list of operations that should be supported by a version control scheme:

• reverting to a past version
• comparing two different versions
• pushing full version history to another location
• pulling history back from that location
• merging versions that are offshoots of the same earlier version

Multiple developers

Now let’s add into the picture Bob, another developer. The picture isn’t too different from what we were just thinking about.

Alice and Bob here are like the two Alices working on different computers. They no longer share a brain, which makes it even more important to follow a strict discipline in pushing to and pulling from the shared cloud server. The two programmers must coordinate on a scheme for coming up with version numbers. Ideally, the scheme allows us to assign clear names to whole sets of files, not just individual files. (Files depend on other files, so thinking about them in isolation allows inconsistencies.)

Merely uploading new source files is not a very good way to communicate to others the high-level idea of a set of changes. So let’s add a log that records for each version who wrote it, when it was finalized, and what the changes were, in the form of a short human-authored message.

Pushing another version now gets a bit more complicated, as we need to merge the logs. This is easier to do than for Java files, since logs have a simpler structure – but without tool support, Alice and Bob will need to do it manually! We also want to enforce consistency between the logs and the actual sets of available files: for each log entry, it should be easy to extract the complete set of files that were current at the time the entry was made.

But with logs, all sorts of useful operations are enabled. We can look at the log for just a particular file: a view of the log restricted to those changes that involved modifying some file. We can also use the log to figure out which change contributed each line of code, or, even better, which person contributed each line, so we know who to complain to when the code doesn’t work. This sort of operation would be tedious to do manually; the automated operation in version control systems is called annotate or blame.

Multiple branches

It sometimes makes sense for a subset of the developers to go off and work on a branch, a parallel code universe for, say, experimenting with a new feature. The other developers don’t want to pull in the new feature until it is done, even if several coordinated versions are created in the meantime. Even a single developer can find it useful to create a branch, for the same reasons that Alice was originally using the cloud server despite working alone.

In general, it will be useful to have many shared places for exchanging project state. There may be multiple branch locations at once, each shared by several programmers. With the right set-up, any programmer can pull from or push to any location, creating serious flexibility in cooperation patterns.

The shocking conclusion

Of course, it turns out we haven’t invented anything here: Git does all these things for you, and so do many other version control systems.

Distributed vs. centralized

Traditional centralized version control systems like CVS and Subversion do a subset of the things we’ve imagined above. They support a collaboration graph – who’s sharing what changes with who – with one master server and copies that only communicate with the master.

In a centralized system, everyone must share their work to and from the master repository, and a change is only in version control if it’s in the master repository.

In contrast, distributed version control systems like Git and Mercurial allow all sorts of different collaboration graphs, where teams and subsets of teams can experiment easily with alternate versions of code & history, merging versions together as they are determined to be good ideas.

In a distributed system, all repositories are created equal, and it’s up to users to assign them different roles. Different users might share their work to and from different repos, and the team must decide what it means for a change to be in version control. If it’s in… any repo? Or a certain special repo?

Version control terminology

• Repository: a local or remote store of the versions in our project

• Working copy: a local, editable copy of our project that we can work on

• File: a single file in our project

• Version or revision: a record of the contents of our project at a point in time

• Change or diff: the difference between two versions

• Head: the current version

Features of a version control system

• Reliable: keep versions around for as long as we need them; allow backups

• Multiple files: track versions of a project, not single files

• Meaningful versions: what were the changes, why where they made?

• Revert: restore old versions, in whole or in part

• Compare versions

• Review history: for the whole project or individual files

• Not just for code: prose, images, …

It should allow multiple people to work together:

• Merge: combine versions that diverged from a common previous version

• Track responsibility: who made that change, who touched that line of code?

• Work in parallel: allow one programmer to work on their own for a while (without giving up version control)

• Work-in-progress: allow multiple programmers to share unfinished work (without disrupting others, without giving up version control)

Version control in 6.005

The version control system we’ll use in 6.005 is Git. It’s powerful and worth learning. But Git’s user interface can be terribly frustrating. What is Git’s user interface?

• In 6.005, we will use Git on the command line. The command line is a fact of life, ubiquitous because it is so powerful.

• The command line can make it very difficult to see what is going on in your repositories. You may find SourceTree (shown on the right) for Mac & Windows useful. On any platform, gitk can give you a basic Git GUI. Ask Google for other suggestions.

An important note about tools for Git:

• Eclipse has built-in support for Git. If you follow the problem set instructions, Eclipse will know your project is in Git and will show you helpful icons. But because Eclipse Git support is buggy, if you use the Eclipse Git UI to make changes, commit, etc., course staff may not be able to help you.

• GitHub makes desktop apps for Mac and Windows. Because the GitHub app tries to change how some Git operations work, if you use the GitHub app, course staff may not be able to help you.

Git

On the Git website, you can find two particularly useful resources:

• Pro Git documents everything you might need to know about Git.
• The Git command reference can help with the syntax of Git commands.

Version control and the big three

Safe from bugs

find when and where something broke
look for other, similar mistakes
gain confidence that code hasn’t changed accidentally

Easy to understand

why was a change made?
what else was changed at the same time?
who can I ask about this code?

Ready for change

all about managing and organizing changes
accept and integrate changes from other developers
isolate speculative work on branches