LearnHub

Version control is at the heart of every mature, modern software development project but it is amazing how many people / teams either do not use it at all, or use it effectively. This lesson will teach you how to do both.

Aside from taking my word for it, why would you use version control?

Collaboration
Without version control, having two or more people working on the same file reqiures them to either

• Take turns, which is not that productive
• Patch differences later, which is a lot of rework and things always get lost

With version control

• A master copy of the file is kept in a central repository
• Each person edits a working copy
• When they are ready to share their changes, they commit them to the repository
• Other people then update to get the changes

Tip: This is also a great way for one person to manage files across multiple machines. No more mailing files to yourself, burning cds or carrying USB drives -- YAY!

Undoing Changes

Which Version Control System?

There are a number of commercial and open source version control solutions. If you have the budget, Perforce is an excellent choice. However, since the Software Carpentry is about free tools, the choice becomes either CVS or Subversion (SVN).

CVS is the most popular of the two, but suffers from two flaws:

1. Each file is tracked seperately so you cannot see which files were changed at the same time
2. You can create new directories, but you cannot delete it

Subversion addresses both these and will be used for the rest of the lesson.

Basic Use

The version control workflow is best illustrated with an example. Suppose Ron and Hermione each have a working copy of the solarsystem project repository...

• Ron synchronizes with the repository using the svn update command. The makes sure he has the current working copy; in our example it is 120.
• He creates the file moons.txt in the jupiters directory
• Once he finishes his updates, he addes it to the repository with svn add moons.txt
• But the change doesn't actually happen until he saves his changes by running svn commit. The repository is now at revision 121.
• Later in the afternoon, Hermione runs the svn update and subversion sends her version 121 as well.

Conflicts

When multiple users are working on the same set of files, conflicts are bound to occur. There are two ways to deal with this situation.

• Pessimistic Concurrency - only one person can edit a file at a time
• Optimistic Concurrency - anyone can edit the file and any conflicts are resolved afterward by merging files

Most modern systems, including Subversion use Optimistic Concurrency in the belief that it is easier to ask forgiveness for an edit than as permission. Especially if you work with someone who forgets to unlock their files before going to lunch.

This graphic helps explain the conflict resolution process.

• Ron and Hermoine both have version 151 of the reposity in their workspace
• Ron checks in some changes which changes the repository version to 152
• Hermoine also checks in some changes, but Subversion notifies her of a conflict
• Subversion creates 3 files in Hermoine's workspace
• 1. moons.txt.mine - which is her changes
  2. moons.txt.151 - the file before either her or Ron's change
  3. moons.txt.152 - the most recent version of the file
• At this point, Hermione can
• 1. Run svn revert moons.txt to throw away her changes
  2. Edit moons.txt to remove the conflict markers (see below)
  3. Copy one of the three temporary files on top of moons.txt
• Once she's done, she runs:
• 1. svn resolved moons.txt to let Subversion know she's done
  2. svn commit to commit her changes (creating version 153 of the repository)

Conflict Markers

Conflict Markers are put in the text of files which are in conflict. Once you have manually corrected the problem, you remove them.

• <<<<<<< shows the start of the section from the first file
• ======= divides the sections
• >>>>>>> shows the end of the section from the second file

Four More Bits On Conflicts

Starvation
What happens if Ginny commits another set of changes while Hermione is resolving? And then Harry commits yet another set? Starvation: Hermione never gets a turn because someone else always gets there first.

This is a management problem, not a technical one

• Break the file(s) up into smaller pieces
• Give people clearer responsibilities
• The version control system is trying to tell you that people on your team are working at cross purposes

Binary Files

Subversion can only merge conflicts in text files. So images, Microsoft Word documents, pdf files or similar binary formats get teated differently. When a binary conflict is encountered, Subversion saves your working copy and the the master copy side-by-side and trusts you to figure out how to resolve the differences.

This is not Subversion's fault. Creators of non-text formats rarely provide a way to find or merge differences between files.

Reverting

After doing some more work, Ron decides he's on the wrong path. Using svn diff he see which files he has changed, and what those changes are. Since he hasn't committed anything yet, so he uses svn revert to discard his work. This synchronizes his files back to his last svn update, not with any changes other people have made since then. To get those he will need to update again.

If you find yourself reverting repeatedly, you should probably go and do something else for a while…

Rolling Back

Now Ron decides that he doesn't like the changes Harry just made to moons.txt and wants to do the equivalent of "undo". Scanning the recent history produced by svn log he sees that the current revision is 157 and that he wasn to revert to revision 156.

svn merge -r 157:156 moons.txt will do the trick. The argument to the -r flag specifies the revisions involved. Merging allows him to keep some of Harry's changes if he wants to. Note, that even though Ron's changes are revision 158, revision 157 is still in the repository available.

Subversion Command Reference

This lesson concludes with a handy list of the commands you will use to interact with your respository.

• svn add - Add files and/or directories to version control. svn add newfile.c newdir
• svn checkout - Get a fresh working copy of a repository. svn checkout http://learnhub.com/redirect?u=https%3A%2F%2Fyour.host.name%2Frotor%2Frepo rotorproject
• svn commit - Send changes from working copy to repository (inverse of update). svn commit -m "Comment on the changes"
• svn delete - Delete files and/or directories from version control. svn delete oldfile.c
• svn help - Get help (in general, or for a particular command). svn help update
• svn log - Show history of recent changes. svn log --verbose *.c
• svn merge - Merge two different versions of a file into one. svn merge -r 18:16 spin.c
• svn mkdir - Create a new directory and put it under version control. svn mkdir newmodule
• svn rename - Rename a file or directory, keeping track of history. svn rename temp.txt release_notes.txt
• svn revert - Undo changes to working copy (i.e., resynchronize with repository). svn revert spin.h
• svn status - Show the status of files and directories in the working copy. svn status
• svn update - Bring changes from repository into working copy (inverse of commit). svn update

For more information on advanced Subversion topics including Server Configuration, and Branching / Merging can be found in the Subversion book.