Version Control

Problem #1: Synchronizing Files

• Want to work on one set of files on three different machines
  • Home, office, a friend's
• Option 1: use a shared file system
  • Difficult to set up
    • And even more difficult to make secure
  • Inflexible: what if you're on the road?
• Option 2: Carry around a floppy or USB dongle
  • Have to remember to copy files onto it and then off again
  • What if your project is too big?
• Option 3: mail, FTP, SCP, etc.
  • Still have to remember to push and pull exactly the right files at exactly the right time
• Option 4: get the computer to do the work
  • Keep a master copy in one place
  • Use a program to synchronize working copies when and as needed
• Comment on this slide

Problem #2: Undoing Changes

• Often want to undo changes to a file
  • Start work, realize it's the wrong approach, want to get back to starting point
  • Like “undo” in an editor…
  • …but longer-lived—keep the whole history of every file, forever
• Similarly, often want to see who changed what, and when
  • When working in teams, want to see what your partners did
  • Bugs are more likely to be in fresh code than in code that's been running for a long time
• Comment on this slide

Solution: Version Control

• Solve both problems at once by using a version control system (VCS)
• Mechanics:
  • Keep the master copy of every file in a central repository
    • Actually, keep all old versions of every file
  • Everyone on the development team does their work in a working copy
  • When you're ready to share your changes, you commit them to the repository
  • The VCS saves the old version of the file, then writes your changes on top
    • Also records the time of the change, who made it, and a comment
  • Take a look in a moment at what happens if two or more people try to make changes at the same time
• Comment on this slide

CVS and Subversion

• Two open source version control systems in widespread use
  • Many others available commercially
  • If you can afford it, use Perforce
• CVS (Concurrent Version System)
  • Invented in the 1980s
  • Very popular, but showing its age
  • Flaw #1: it keeps track of each file separately
    • But authors often change several files in tandem
    • Since CVS has no notion of a “batch submit”, there's no reliable way to say, “What other changes were made in conjunction with this one?”
  • Flaw #2: you can create new directories, but can't ever delete old ones
• Subversion
  • Designed as a backward-compatible replacement for CVS starting in 2000
  • Fixes both of the major flaws in CVS
  • Many open source projects have switched, or are switching…
  • …so we'll use it in this course
  • See the Subversion site for details
• Comment on this slide

Basic Use

• Assume for a moment that a repository has been created, and that Ron and Hermione already have working copies
  • See below how to do this
• Ron wants to make changes to the rotor spin simulation
  • Runs svn update to bring his copy up to date with the repository
  • Edits spin.c and spin.h
  • Runs svn commit to save those changes in the repository
    • Note: the whole repository gets a new version number
• Ron realizes that he forgot to make one change
  • Runs svn update again, just in case Hermione has also been making changes (she hasn't)
  • Edits spin.c again
  • Runs svn commit a second time
• Several hours later, Hermione runs svn update on her working copy
  • Subversion copies Ron's changes into her directory

Figure 3.1: Basic Use

• Comment on this slide

How To Do It

• One way to use Subversion is to type commands in a shell
  • Guaranteed to work everywhere without anything else being installed
  • But there are several good graphical interfaces for Subversion too
• RapidSVN runs on Windows, Linux, and Mac
  • Well, maybe “walks” is a better description—as of Version 0.9, it's not the fastest thing in the world

  • Figure 3.2: RapidSVN

• TortoiseSVN is a Windows shell extension
  • Which means that it integrates with the Windows file browser, rather than running separately
  • But that also means that it doesn't work on Linux or Mac

  • Figure 3.3: TortoiseSVN

• And if you're on a Macintosh, there's SmartSVN
• Comment on this slide

Working Together

• What if two (or more) people want to edit the same file at the same time?
  • Option 1: prevent it
    • Only allow one person to have a writeable copy of the file at once
    • Pessimistic concurrency
    • Microsoft Visual SourceSafe
  • Option 2: patch up afterwards
    • Optimistic concurrency
    • “It's easier to get forgiveness than permission”
    • CVS, Perforce, Subversion

Figure 3.4: Merging Conflicts

• Ron and Hermione both have copies of spin.c version 15

  • int maxRotateSetting(int * available, int length)
    {
        int i, maxFound;
        if (length == 0) {
            return 0;
        }
        for (i=0; i<length; i+=1) {
            if (available[i] > maxFound) {
                maxFound = available[i];
            }
        }
        return maxFound;
    }
    

• Ron commits his changes
  • Creates spin.c version 16

  • // Find maximum rotation setting from those available,
    // or 0 if none are available.
    int maxRotateSetting(int * available, int length)
    {
        int i, maxFound;
        if (length == 0) {
            return 0;
        }
        for (i=0; i<length; i+=1) {
            if (available[i] > maxFound) {
                maxFound = available[i];
            }
        }
        return maxFound;
    }
    

• Meanwhile, Hermione is editing her copy, and produces this:

  • // Find maximum rotation setting, or 0.
    int maxRotateSetting(int * available, int length)
    {
        int i, maxFound = 0;
        for (i=0; i<length; i+=1) {
            if (available[i] > maxFound) {
                maxFound = available[i];
            }
        }
        return maxFound;
    }
    

• Tries to submit her changes: conflict!
  • Subversion puts both Ron's and Hermione's changes in Hermione's working copy, with markers

    • <<<<<<< .mine
      // Find maximum rotation setting, or 0.
      =======
      // Find maximum rotation setting from those available,
      // or 0 if none are available.
      >>>>>>> .r471
      int maxRotateSetting(int * available, int length)
      {
          int i, maxFound = 0;
          for (i=0; i<length; i+=1) {
              if (available[i] > maxFound) {
                  maxFound = available[i];
              }
          }
          return maxFound;
      }
      

  • Also creates spin.c.mine, spin.c.15, and spin.c.16 for reference
  • Hermione must decide what to keep, and what to throw away
    • Subversion won't let her commit his changes until all the conflict markers are eliminated
  • Once Hermione is done editing, she:
    • Runs svn resolved spin.c to tell Subversion the conflict has been fixed
    • Runs svn commit spin.c to create spin.c version 17
• Comment on this slide

What Versions Actually Mean

• The discussion above referred to “version 16 of spin.c”, but in fact there is no such thing
• Instead, there's version 16 (or 17, or 18…) of the repository
  • Users are supposed to try to keep the files in the repository in a consistent state
    • I.e., don't submit things that are half-done
    • Since the next person to do an update would then be in the same half-done state you are
  • Subversion therefore updates the version number on the whole repository every time a set of changes is submitted
    • Each change set can affect any number of files (including adding or deleting files)
  • The phrase “version 229” therefore uniquely identifies an entire set of files
    • Unlike CVS and other systems, where version 319 of one file might correspond to version 107 of another, and version 794 of a third
• Comment on this slide

Warning: Binary Files

• Subversion can only mark conflicts this way in text files
  • I.e., files that store lines of human-readable characters
  • Source code, HTML—basically, anything you can edit with Notepad, Vi, or Emacs
• Images, video clips, Microsoft Word, and many other formats aren't
  • When there's a conflict, Subversion saves your copy and the master copy side by side in your working directory
  • Up to you to resolve the differences
• Comment on this slide

Rolling Back Changes

• Suppose Ron decides that he doesn't like his recent changes
  • svn diff will show him which files he has changed, and what those changes are
  • He hasn't committed anything yet, so he can use svn revert to re-synchronize with the master copy
  • If you find yourself doing this repeatedly, you should probably go and do something else for a while…
• Now suppose that Ron decides he doesn't like the changes Hermione just made to spin.c
  • Wants to do the equivalent of “undo” on several files
  • svn log shows recent history
  • He decides he wants to revert to version 16 of the repository
  • svn merge -r 17:16 spin.c means “merge changes, going from version 17 to version 16” (i.e., backwards)
    • Can obviously go back to even earlier versions to undo more changes

Figure 3.5: Undoing Changes

• Comment on this slide

And Finally, Getting Started

• To create a repository:
  • Decide where to put it (e.g., /rotor/repo)
  • Go into the containing directory: cd /rotor
  • svnadmin create repo
• Can then interact with repository in two ways
  • Directly through the file system: file:///rotor/repo
    • Use this if you're working on the same machine the repository is on
  • Through a web server: https://your.host.name/rotor/repo
    • Use this if the repository is on a remote machine
    • Note: requires your system administrator to configure the web server properly
    • https (instead of http) means “use a secure connection”
• To get a working copy (assuming you're using a web server):
  • svn checkout https://your.host.name/rotor/repo
  • Creates a new directory repo
    • Common to give it a more informative name using svn checkout https://your.host.name/rotor/repo rotorproject
  • Important: only use svn checkout once, to initialize your working copy
• Comment on this slide

Subversion Command Reference

Name	Purpose	Example
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 https://your.host.name/rotor/repo 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

Table 3.1: Common Subversion Commands

• Comment on this slide

How to Read Subversion Output

• svn status compares your working copy with the repository, printing one line for each file that's worth talking about

  • $ svn status
    

    M      spin.c
    MC     readme.txt
    

  • spin.c has been modified
  • readme.txt has been modified, and has conflicts
• svn update prints one line for each file or directory it does something to

  • $ svn update
    

    A  newspin.c
    U  spin.c
    C  spin.h
    

  • newspin.c has been added
  • spin.c has been updated (i.e., someone else modified it)
  • There's a conflict in spin.h
    • Which you'll have to resolve before you can commit your changes
• Comment on this slide

Branching and Merging

• Sometimes want to work on several different versions of software at once
  • Example: need to do bug fixes on Version 3 while making incompatible changes toward Version 4
  • Or want two sets of developers to be able to write and test large changes independently, then put things back together
• All modern version control systems allow you to branch a repository
  • Create a “parallel universe” which is initially the same as the original, but which evolves independently

  • Figure 3.6: Branching and Merging

  • Much better than just copying all the source files: the version control system remembers where the branch came from, and can trace its history back
• Can later merge changes from one branch to another
  • Example: fix a bug on one branch, merge the changes into other branches that have the same bug
  • Again, much better than copying by hand, since the version control system can keep track of where things came from, and where they went
• Warning: many people become over-excited about branching when they first start to use it
  • Keeping track of what's going on where can be a considerable management overhead
  • On a small project, very rare to need more than two active branches
• Comment on this slide

Exercises

Exercise 3.1:

Follow the instructions given to you by your instructor to check out a copy of the Subversion repository you'll be using in this course. Unless otherwise noted, the exercises below assume that you have done this, and that your working copy is in a directory called course. You will submit all of your exercises in this course by checking files into your repository.

Exercise 3.2:

Create a file course/ex01/bio.txt (where course is the root of your working copy of your Subversion repository), and write a short biography of yourself (100 words or so) of the kind used in academic journals, conference proceedings, etc. Commit this file to your repository. Remember to provide a meaningful comment when committing the file!

Exercise 3.3:

What's the difference between mv and svn mv? Put the answer in a file called course/ex01/mv.txt and commit your changes.

Once you have committed your changes, type svn log in your course directory. If you didn't know what you'd just done, would you be able to figure it out from the log messages? If not, why not?

Exercise 3.4:

In this exercise, you'll simulate the actions of two people editing a single file. To do that, you'll need to check out a second copy of your repository. One way to do this is to use a separate computer (e.g., your laptop, your home computer, or a machine in the lab). Another is to make a temporary directory, and check out a second copy of your repository there. Please make sure that the second copy isn't inside the first, or vice versa—Subversion will become very confused.

Let's call the two working copies Blue and Green. Do the following:

a) Create Blue/ex01/planets.txt, and add the following lines:

Mercury
Venus
Earth
Mars
Jupiter
Saturn

Commit the file.

b) Update the Green repository. (You should get a copy of planets.txt.)

c) Change Blue/ex01/planets.txt so that it reads:

1. Mercury
2. Venus
3. Earth
4. Mars
5. Jupiter
6. Saturn

Commit the changes.

d) Edit Green/ex01/planets.txt so that its contents are as shown below. Do not do svn update before editing this file, as that will spoil the exercise.

Mercury 0
Venus 0
Earth 1
Mars 2
Jupiter 16 (and counting)
Saturn 14 (and counting)

e) Now, in Green, do svn update. Subversion should tell you that there are conflicts in planets.txt. Resolve the conflicts so that the file contains:

1. Mercury 0
2. Venus 0
3. Earth 1
4. Mars 2
5. Jupiter 16
6. Saturn 14

Commit the changes.

f) Update the Blue repository, and check that planets.txt now has the same content as it has in the Green repository.

Exercise 3.5:

Add another line or two to course/ex01/bio.txt and commit those changes. Then, use svn merge to restore the original contents of your biography (course/ex01/bio.txt), and commit the result. When you are done, bio.txt should look the way it did at the end of the first part of the previous exercise.) Note: the purpose of this exercise is to teach you how to go back in time to get old versions of files—while it would be simpler in this case just to edit bio.txt, you can't (reliably) do that when you've made larger changes, to multiple files, over a longer period of time.