Subversion information

From Comp519

With thanks to Dan Sandler and his comp314 Subversion tutorial from http://sys.cs.rice.edu/course/comp314/08/svn.html

Important: You should have already created a repository on the Rice subversion server by following the provided directions.

1 The Rice Subversion Server
2 Basics and Command-line Usage
3 Getting Subversion for your Computer
4 Links

The Rice Subversion Server

Web Interface

You can easily view repositories and files stored in the Rice subversion server through the web.

The Rice Subversion web interface is accessible at:

http://www.svn.rice.edu (for publicly-accessible repositories)
https://www.svn.rice.edu (for private repositories - requires NetID authentication)

From the authenticated web interface, you can browse any repositories that your NetID has been granted access to.

While the web is a convenient way to view files in a repository, it cannot be used to modify or add files.

Repository Access

The following URLs should be used for normal access to the subversion server (either from the command line or using a GUI-based tool):

http://svn.rice.edu/r/repository (for publicly-accessible respositories)
https://svn.rice.edu/r/repository (for private repositories - requires NetID authentication)

These URLs should be used with the commands described below.

Authentication & Authorization

Authentication (who can connect to the server) is handled by Rice. Anyone with a NetID can authenticate to the Subversion server or web interface, including guest accounts. Authentication can be forced by using the https protocol when accessing the server.

Authorization (who can access the repository) is controlled by the repository owner and their delegates. Each repository is created with a /rice_config directory. This directory contains a file named access_file. The access_file controls who has access to that specific repository. Changes to the access_file take up to 5 minutes to become active on the server. Please see the file access_file.readme which is also located in the /rice_config directory for a simple explanation of the format of this file.

You should set up your access file to ensure that others can not see your repository, unless you specifically grant them access. For example, here is a sample "access_file" that is appropriate for the class:

[groups]
mygroup = user1, user2, user3

[/]
me = rw

[/rice_config]
me = rw
* =

[/comp519]
@mygroup = rw
* =

This will allow everyone in your group (usernames: me and groupmate) to access the "comp519" subdirectory in the repository. Only you (username: me) will be able to access other files and directories in the toplevel directory.

As other students in the class (who are not in your group) and other students at other universities will be using the NetFPGA platform, it is mandatory that you restrict access to the files you use for the projects in this course.

Be very careful when editing the access_file. You can set the permissions such that you can no longer access your own repository!

Basics and Command-line Usage

The essential Subversion lifecycle is the following:

Import files into a new (empty) repository (optional)
Check out a project (a directory path) from a repository.
In that project directory, create or edit files and subdirectories.
Update your local copy from the repository, picking up changes your team members may have made since your last update.
Go to step 3. If you're ready to commit your changes, go to step 6.
Commit your changes to the repository. Go to step 3.

Importing Files to the Repository

If you have an existing tree of files that you wish to put into a new Subversion archive, the import command can be used. For example, the following command will copy the contents inside the directory "source_dir" to the repository "myrepository" on the Rice SVN server, and save a message in the log file describing this operation.

svn import source_dir https://svn.rice.edu/r/myrepository -m "Log message describing this import operation"

Checking out the Repository

Each repository has a URL from which it can be initially checked out; once that's done, the URL is remembered for future operations. Here's how to check out your newly created repository: ("co" is short for "checkout")

svn co https://svn.rice.edu/r/myrepository

The directory myrepository will be created in your current directory. You can rename or move myrepository anywhere you like; Subversion will remember the repository it refers to.

You can also just check out a subdirectory within your repository:

svn co https://svn.rice.edu/r/myrepository/project

The directory project will be created in your current directory. Again, you can rename or move project anywhere you like.

Editing a File

You don't need to do anything special to tell Subversion you'd like to change an existing file; it can figure it out from the fact that the file's contents will change when you edit it.

Adding a new file

Subversion can tell automatically when you change an existing file from the repository, but it doesn't know when you want to add a new file or directory to source control. For this you need to use svn add:

 svn add my_new_file.txt

At this point, you can commit this change like any other.

Note the implications of this. This means that if you do not add a file to your project using svn add, it will not get placed under version control and subversion will ignore it. This is extremely useful for things like binary files, which are typically very large and are easily reproducible from the source code that is under version control. Similarly, you must remember to add files, using svn add that you create that should be under version control.

Copying Files

To copy a file within the SVN repository, you can either use (1) the normal filesystem commands to copy the file and then "svn add" to add the copy to the repository, or (2) a SVN-specific command to copy the file and add it to the repository automatically.

svn copy <src> <dest>

Note that the source and destination can be a file or a directory, and the source and destination must be within the same repository.

Important note: It is strongly recommended that you use the "svn copy" command to recursively copy directories within your svn project. Subversion stores its meta-data in hidden ".svn" folders in each directory. If you accidentally copy this meta-data along with your folder(s) in a copy operation, then you will be unable to add the new files to your repository without corrupting its state. The bottom line: you should never copy a directory that is part of a subversion project using the Unix cp command. If you do this, at best, you will have extraneous .svn directories hanging around (if you copy to a location outside of the project). At worst, you entire subversion project will be corrupted (if you copy to a location inside of the project).

Updating your Sources

Usually, before you make a checkin, it's a good idea to check to make sure nobody else committed changes while you weren't looking.

svn update

Committing your changes

Now you're ready to commit your changes the the repository so your teammate(s) can see and build on them. Run svn commit on the files or directories you've changed:

svn commit file.txt   (for a specific file only)
svn commit            (for all files in the current directory and below - recursively)

Your default editor (see #Changing Default Editor) will be invoked on a temporary file; into this file you should type a short message explaining the purpose of your change. For large projects, accurate check-in comments become essential when you're looking back over your changes and trying to figure out where you fixed—or created—a bug.

You'll note that Subversion responds to your checkin with a message:

Sending       file.txt
Transmitting file data ...
Committed revision 3.

Each committed change is assigned a monotonically-increasing revision number. (In this example, that number was 3.) You can go back and examine any past checkin with svn log: (the -r flag lets you pick the revision to look at; the -v flag tells you what files were touched)

svn log -v -r3

------------------------------------------------------------------------
r3 | dsandler | 2006-01-12 14:16:11 -0600 (Thu, 12 Jan 2006) | 1 line
Changed paths:
   A /test/file.txt

 This is the log message I entered when committing the file.

When should you commit? A good time to check things in is when you've made a substantial change that stands on its own. If implementing a new feature requires three files to be changed, change all three and commit them all together. (You can specify multiple files after svn commit to do this.) This way, each file's individual change (which may not stand on its own) is associated with the entire checkin.

If you happen to invoke svn commit but realize that you didn't really mean to commit all that stuff (or all those files), exit your editor without adding a commit message. You will be given a chance to back out. (Once you write and save a commit message, you've lost that opportunity.)

Taking a look around

You'll frequently want to check to see what you've edited and what you haven't, often before a svn commit command.

svn status

You'll get a list of the files in the current directory, with flags (such as M for modified) next to each file describing its status in your local copy.

For modified files, you can determine the differences between your local copy and the file in the repository.

svn diff filename

You can also find all of the differences between your local project and the repository.

svn diff

Remember the lifecycle:

svn co (usually only done once when you start a project)
edit or add (svn add) files
svn status
svn update
svn commit
...and back to step 2

At any point in the lifecycle, if you find you are unhappy with your changes, or after an update you find they conflict with changes others have made, you do not need to commit them. If you do not commit your changes, it is like they never happened. You can always rename a modified file (so that you do not lose changes that you might later find are important) and use "svn update" to get the clean version back from the repository.

Finally, if you forget how to use a Subversion subcommand, or want to find out about the other features of the svn tool, use svn help.

Time travel

One of the most powerful features of version control systems is history. The repository records all changes made, and the "clock" can be wound backward and forward to show you any past or present version of any file.

A simple thing to try is to inspect the log to see what's been done in a given directory (and its children):

   % cd mycode/comp314-08
   % ls
   projects/        test/
   % svn log -v test
   ------------------------------------------------------------------------
   r3 | dsandler | 2006-01-12 14:16:11 -0600 (Thu, 12 Jan 2006) | 1 line
   Changed paths:
      A /test/guestbook.txt

   Something for everyone to edit.
   ------------------------------------------------------------------------
   r2 | dsandler | 2006-01-12 14:12:43 -0600 (Thu, 12 Jan 2006) | 1 line
   Changed paths:
      A /test
      A /test/README

   Add test directory.
   ------------------------------------------------------------------------

You can use the -r flag to get the svn log for a particular revision number or range of revisions. -r can also be used with svn up (update) or svn co (checkout); in this way you can get a snapshot of your code at any point in the past.

Resolving conflicts

Read the Subversion book's [section on conflicts].

Changing Default Editor

When you invoke svn commit, Subversion will launch your "default editor" so it can ask you to add some comments to a text file. The default editor on comp519.cs.rice.edu is GNU Nano. If you wish SVN to use a different editor by default,

export EDITOR=emacs

You'll probably want to add a line like that to your .profile so that your default editor is properly configured every time you start working.

Getting Subversion for your Computer

Linux users: Your distribution probably has "subversion" or "svn" packages you can install; ask your system's package tool (apt-get or yum or what have you).
Perhaps the best SVN graphical interface is SmartSVN. There is a free version available for Windows, MAC, and Linux.
Other SVN tools
- Windows users: TortoiseSVN is a Windows shell extension which augments the file explorer to show SVN status badges on any files that are under version control.
- Mac users: You can download the command-line tools (packaged as standalone executables). There is also a graphical client, SvnX, if you want to play with it.
- Eclipse users: There's an excellent Eclipse plug-in for called Subclipse that adds Subversion support to Eclipse's source control features (alongside the built-in CVS support). The installation guide is well worth reading.