Version Control Software

Subversion

It's 2005 (or several years later). If you don't start every project by creating a repository in a version control program, then it's probably for one of the following reasons:

  • You never learned how to use version control (and you are probably ashamed of this fact)
  • You used RCS or CVS once a long time ago and decided it was too messy
  • You don't ever work with anyone else
Unfortunately, none of these are especially good excuses now that the department has Subversion installed. Sure, you could complain that you shouldn't be required to use a program unless someone teaches you how, but if you're even reading this page, then you've lost that excuse, because Subversion is so easy to use that even by reading up to this point, you're practically a Subversion user.

So don't run away, don't hide, don't fear, instead follow these simple instructions to learn Subversion. Use it often. Use it well. Become an expert. And then, come back to this Wiki page and improve these instructions.

Purpose

Version control serves two purposes. The first is that it maintains snapshots of the files you work on, so that you can roll-back to a previous state when something goes horribly wrong. The second is that it enables collaboration by managing the mechanisms by which users update the master copy of the files in a project.

Version control is not just for programmers. You can use version control for web pages, technical reports, journal articles, or any other content. The beautiful thing about version control is that it makes it easy to follow not only what changed, but also who changed it. Your days of envying Microsoft Word's track changes feature as you work on your LaTeX documents with coauthors just may be at an end!

Cautions

Our department has two versions of Subversion installed right now, and they behave differently with regard to the default format of your repository. Unfortunately, the older version defaults to a BDB (Berkley Database) format that is not safe for use over NFS (the network filesystem; the magical way that you log in to any machine and get the same files). This document assumes you are using the older version, and instructs how to override this default to use the correct backing store.

  • The new version is installed in /usr/grads/bin, but we assume you don't have it early in your PATH variable.
Also, you may have heard of "CVS servers" (CVS is an older version control system. Subversion is a descendent of it, and is better). I do not cover this topic at all. You don't need it for anything that you may do with Subversion within the department. If you reach a point where you need to run a Subversion server, you should read the full Subversion documentation (latest version)

Etiquette

There is a polite way to work with other people. I provide some recommendations at the end of this document. In brief, you should never submit changes that don't work, you should submit changes often, and you should always have meaningful comments in your submission logs.

Key Terms

Repository
A master copy of your entire project, with all versions saved.
Version
A snapshot of one consistent state of your project. Your repository will have many of these.
svn
The main program you will call. Just about every feature of Subversion is invoked from the commandline as a parameter to svn
svnadmin
The one exception to the rule about svn.
svn help
The way to get help with Subversion.
svn help command
The way to get help for a specific command (such as commit).

Our Motivational Example

I like Spongebob Squarepants, so he is going to be the basis for our example. I assume throughout this project that your username is spongebob and that you have been working on a project called pineapple (because Spongebob lives in a pineapple under the sea). I assume that your project may have subfolders, and that everything in the project initially located in the directory /u/spongebob/pineapple.

You realize one day that you should be using version control (perhaps your coauthor squidward is interested in working with the pineapple codebase), and you turned to this wiki...

If you are starting a project from scratch, then just create a folder to represent the root of your project, and then put a Makefile in that folder (you do use make, right?). Then you can continue to the next step.

Creating a New Repository

You may be trying Subversion for the first time, but it is going to become a habit. Every project you work on will have its own repository (just a fancy way of saying that there will be a master copy of your project, with all of the version history, stored somewhere). Let's start by making a folder into which you can put all of your repositories.

cd /u/spongebob/

mkdir repos

Now we can create a repository in the repos directory that contains the initial copy of our pineapple project. First we create a pineapple repository ( pay close attention to command line parameters here)

svnadmin create --fs-type fsfs /u/spongebob/repos/pineapple

And now we import all of our files:

svn import /u/spongebob/pineapple file:///u/spongebob/repos/pineapple -m "I just imported this project to Subversion because my advisor told me to"

What Just Happened?

First we created a new repository called pineapple in our repository tree, and said that it should use the FSFS system for storing information (the other option is to use BDB, which is not compatible with our NFS setup).

Then we imported the entire tree rooted at /u/spongebob/pineapple/, and when we imported it, we provided a description so that for the rest of time, we'll know that this import was committed reluctantly.

Should I really say bad things about my advisor in the log?

NO you should not. The reason I did that in the above example is to remind you that the messages you put in your repository are saved forever. You should always be professional (and if your advisor is forcing you to use Subversion, then you should buy your advisor a nice present, as it is obvious that you are studying under a wise mentor who wants you to excel!)

What if I forget to put in a message?

If you forget the -m switch, then Subversion will open your favorite editor and demand that you enter some text. When you save the text and exit, then the import will continue.

Setting Permissions

Now we need to set permissions, and I don't really know the right way to do it. If you find a better way than what I propose, then you should update this wiki.

1. Set Group Ownership
If you are going to collaborate, then you should set the group ownership and group permissions for this repository. Let's assume that there is a group bikinibottom (Spongebob's hometown), and you want to give the people in bikinibottom access to your repository. First we will change the group of the repository and let group members read and write to this folder:

cd /u/spongebob/repos

chown -R :bikinibottom pineapple

chmod -R g+r pineapple

chmod -R g+w pineapple

2. Remove World Permissions
We don't want anyone else to have access to this repository, so let's lock them out:

chmod -R o-r pineapple

chmod -R o-w pineapple

chmod -R o-x pineapple

3. Set the setUID and setGID bits
I don't know if you really need to do this, but we'll recommend it here, and if it messes up someone's repository, then we'll change the wiki later. The main idea is that we want to make sure that whatever is added to the repository still belongs to spongebob.

The directories locks, db, and those in db need the s bit. Since these are all directories under and including locks and db, you can use the change-all command

find pineapple/locks pineapple/db -type d -exec chmod ug+s {} \;

Or if you prefer individual commands:

chmod u+s pineapple/locks

chmod g+s pineapple/locks

chmod u+s pineapple/db

chmod g+s pineapple/db

chmod u+s pineapple/db/revprops

chmod g+s pineapple/db/revprops

chmod u+s pineapple/db/revs

chmod g+s pineapple/db/revs

chmod u+s pineapple/db/transactions

chmod g+s pineapple/db/transactions

That was a lot of work

True, but you only have to do it once per repository.

Is everything definitely secure?

If you trust everyone in your group, then you've probably got the necessary security in place (if not, update the wiki). You can play with the permissions within /u/spongebob/repos/pineapple, but if you make a mistake your collaborators may be temporarily prevented from checking in/out, or you might end up having files in your repository that are owned by someone else.

Am I done?

No, now your repository is set up, and the files originally in /u/spongebob/pineapple have been copied over. But you still need to check out a copy of the repository to do real work.

Checking Out a Repository

In order for version control to work, you must always work from a checked out version of the repository. So we can't use the files in /u/spongebob/pineapple, because they are from before we started to use Subversion. But we did like having the pineapple project in our root directory, so let's remove the old copy and get a new, clean, shiny copy (of the exact same files) from Subversion.

rm -rf /u/spongebob/pineapple

cd /u/spongebob

svn co file:///u/spongebob/repos/pineapple

Should I share this folder?

NO. If someone else needs to work on your project, they should use the same svn command to get their own copy of the repository.

Can I start changing things now?

Yes. But when it's time to update the repository to a new version, you should come back here to see how.

Checking In Changes

You've been editing files for a while, and you've got some work you'd like to save. It's time to check in your changes:

First, see what files changed:

svn status

Next, you might want to look at what changes you made:

svn diff

Or maybe you only want to look at the changes to the file crabbypatty:

svn diff crabbypatty

Things look good, so let's commit:

svn commit

What the heck just happened?

Your favorite editor popped up so that you can type in comments to describe this new version of your program. Once you save the changes and close your editor, the process will continue. Remember that the comments should not include disparaging remarks about your advisor!

Adding Files

Let's suppose that the pineapple project needs a new file to represent Spongebob's pet snail (named Gary). We first create the file garythesnail somewhere in the pineapple tree, and then we add the file:

svn add garythesnail

Now when we do our next commit, this file will be posted to the repository.

Reading the Log

You've been diligently adding files, making changes, and posting updates for months. Suddenly your advisor calls a meeting and asks you to describe your progress. Of course, you've been diligently filling in your log entries, and these are documentation enough to explain why you deserve free food and the respect of your peers. Let's get the log from Subversion:

svn log

That was too much information. How can I just look at the 5th version of the repository?

svn log -r 5

I can't remember the last time I made changes to the file sandythesquirrel. How can I check?

svn log sandythesquirrel

Reverting a File

Let's suppose that you checked in everything yesterday, and then began a massive update to the algorithm in the file recumbent (squidward rides a recumbent bicycle). This morning, you realize that the new algorithm will never work. To revert your copy of recumbent to the previous version, you can simply type:

svn revert recumbent

Deleting, Moving, and Copying Files

These commands are quite simple:

svn delete file1

svn move file2 file3

svn copy file4 file5

Can I undelete files?

Yes, but it is not easy. Your best bet is to create a new folder outside of this repository tree, and then check out an old version of the repository. This is pretty tricky, and you should probably read the manual.

Why the heck would I ever move or copy like that?

When you move or copy using svn, svn will remember all of the revision history for the file.

Collaborating

You've been so productive using Subversion that your advisor assigns a few more students to work with you. The immediately check out their own copies of the repository, and then they start making changes to the code. Let's suppose that mrkrabs (the proprietor of the Krusty Krab, where Spongebob works) submits some changes. You can get the latest version of the repository by typing:

svn update

Unfortunately, it is possible that mrkrabs changed a file (let's say the file was krabbypatty) that you were editing. If this happens, Subversion should let you know. In the process of "letting you know", Subversion will change the file to indicate all the changes that mrkrabs made. Now it is your responsibility to resolve the conflicts (if they exist). Once you have done this, type:

svn resolved krabbypatty

And now svn will trust that you've resolved everything that conflicted in that file.

Now when you are ready to submit, you can use the standard commit command

svn ci

I thought the commit command was svn commit

It is. You can also use svn ci.

What if I don't update first?

Subversion will complain, give you an error message, and not commit your changes. You are responsible for making sure that you keep your copy of the repository up to date.

Tunneling

Lets suppose that you work at home and you want to use Subversion over ssh. It turns out that this is quite easy. The first time you check out the repository, you need to give an ssh tunnel command, and then all future transactions with svn will work beautifully:

svn co svn+ssh://spongebob@somemachine.cs.rochester.edu/u/spongebob/repos/pineapple

This will prompt you for your password, and then get a copy of the repository. From here on out, every time you interact with the repository, you don't need to say the whole svn+ssh part (Subversion will remember that for you), but you'll be prompted for a password.

Aggregating repositories using svn externals

You may have multiple svn repositories, for example, one for each paper you have written. They may share some common module, for example, the bibliography files. You can create a svn module named bib and include it in your modules by setting the svn external property.

svn propedit svn:externals _paper_dir

When the editor opens the property file, type the following line

bib _bib_repository_path_

Use svn+ssh (see Tunneling) for remote directories. You can link in basically any svn repository you have access to, including those on the Internet. If you want to use the bib files shared by the compiler group, the path is /p/compiler/writing/repos/bib/trunk.

Is it really that simple?

Yes

It didn't work for me, I think you are a liar.

A common mistake is that spongebob does not have his path set correctly on somemachine, and consequently the svn command doesn't run on the remote host. If this isn't your problem, and you find a fix for your problem, add it to this wiki.

Etiquette

Now that you are collaborating, you should obey the following rules:

Submit early, submit often
There is going to be one file that everyone always changes (let's suppose it's the one with the main() function). When you've been working for 36 hours straight, and finally type svn ci, the last thing you want to see is an error that ten minutes ago, someone else changed a file and now you have to go through the whole update=/=resolved process. A better strategy would be to develop with revision control in mind. In other words, do a small checkin that changes the main() function to call an empty subroutine in a new file. Check this in, and then do all of your work in that new file. When you're done, you don't have to re-check in the main() file, and you are less likely to have a conflict.

Don't submit broken code
You and your collaborators should agree upon a series of tests that must be passed before a checkin is allowed. It is incredibly frustrating to track a bug for a week, only to discover that it isn't yours.

Write good comments
This applies to your code, and to your notes in the revision history. These notes may be the only way that someone who picks up your project in 2 years will ever figure out what you did.

Send email when you commit changes
Have you ever had ten minutes of downtime, where you didn't want to start something big but you didn't want to stop working yet? Well, when you collaborate, these times are ripe for code review and resolving conflicts. If you know that a peer just updated a file that you use, then the next 10 minutes could be productively spent merging his work with yours, instead of reading slashdot.

Note: The ideal commit email contains a list of all files changed, the description that was entered into Subversion, and whatever other information you deem necessary.

Test on a clean repository
Sometimes you will create files and forget to add them to your repository. If you have two independent checkouts of the repository, then immediately after checking in, go to your clean checkout and synchronize. If you can't compile and pass the tests, then you probably forgot to add a file, but at least you found the bug before one of your peers.

Be careful what you add to the repository
It probably isn't wise to save binaries and object files in the repository, unless you have special tools that all users need to have in their repository tree and that aren't available any other way.

Closing Pleas

Please feel free to make corrections and additions to this document.

Please don't just change the examples because you dislike Spongebob.

Please use version control every time you write code.

Please obey my suggested eqiquette rules. They will really make your life easier.

-- MichaelSpear - 06 Oct 2005

Ignoring Some Files

If you would like to have Subversion ignore some of the files in the current directory (e.g. core dumps or intermediate data) do the following:
svn propedit svn:ignore <directory>
where <directory> is assumed to be $PWD if omitted. This will open an editor, with which you should place file globs such as *.o on separate lines.

For those who are familiar with cvs, the .cvsignore file can be simulated:
svn propset -F .cvsignore .
will load all of the ignore rules.

-- KirkKelsey - 06 Oct 2005

Merging Differences

If you're a big fan of using GUIs, take a look at xxdiff-subversion, which is installed in /usr/grads/bin/. It will display changes and allow you to resolve them directly. Try xxdiff-subversion --help for usage.

-- KirkKelsey - 26 Oct 2005

Emacs mode

There are a couple of ways to interface with svn in emacs, one of which uses the existing VC-mode, the other can be grabbed from /u/vandurme/local/lib/emacs/site-lisp/psvn/psvn.el. See the top of that file for instructions on use.

-- BenjaminVanDurme - 20 Dec 2005

A Short Summary of Basic Commands

Basic svn Commands:

svn up - update your working copy - you should do this before committing anything

svn up -r revision_number filename - revert to a previous version of a file

svn commit - commit your changes

svn add - add new files that you've created

svn rm - remove files no longer needed

svn stat - lists all files and whether they are M - modified / A - added/ C - in conflict/ ? - status unknown

svn revert - changes your local file back to whatever is in the repository

svn log - lists changes log file

svn resolved - after you fix a conflict you need to use this on the file before you can commit

-- copied from McGill Soot wiki page by ChenDing - 7 Mar 2008


This topic: Main > WebLeftBar > TechTalk > VersionStuff
Topic revision: r13 - 2011-02-02 - JonathanGordon
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding URCS? Send feedback