Tutorial on SVN

Another thing that is very important, is revision control. You should use Subversion (SVN) to manage your revisions. If you do not, you will eventually delete a file by mistake or want to undo an edit and you will be out of luck. SVN can mostly handle binary formats automatically.

All of the above source files should be checked into an SVN repository that is either in your personal space or on the group server. A repository is simply database that tracks all changes to all files. It also manages the changes among many contributors. If you look at the repository itself (e.g. /mada/users/vlsi) you will see non-human readable directory structure. You should only access the repository using the "svn" tool (or maybe "svnadmin" occasionally). SVN takes subcommands for the actions to perform on the repository and optionally a file argument:

svn <subcommand> [file]

If you omit the file, it performs the action on the subdirectory of the repository associated with the current directory you are in. If you are not in a copy of a repository it will tell you so and do nothing. The rest of this tutorial will cover the most frequently used svn subcommands.

Note that SVN should NOT be used to house files that change frequently. If you have a file that is generated as output, DO NOT put it in the repository.

Getting SVN

SVN is already installed on the mada machines. To get an SVN client for any machine (Linux, OSX, Windows), you can look at

http://subversion.tigris.org/project_packages.html

Creating your own repository

Everyone is currently using a shared repository and should not have to do this.

Checking out a project

To access our group SVN server from the mada cluster, you can do this:

svn co file:///mada/users/vlsi/<project>

To access it from outside the cluster, you can access it through ssh like this:

svn co svn+ssh://user@mada0.cse.ucsc.edu/mada/users/vlsi/<project>

Modifying a project

To add new files to a repository:

svn add file.C

and it will remember from where the repository came. Note that if you add a directory, it will add the entire subcontents to SVN. You can also create a new directory with:

svn mkdir newsubdir

or

svn mkdir svn+ssh://user@mada0.cse.ucsc.edu/mada/users/vlsi/<project>

which will immediately commit the directory to the repository.

To remove a file from the repository, use:

svn rm file.C

To move a file within the repository, use:

svn mv file.C newfile.C

To copy a file within the repository, use:

svn cp file.C newfile.C

Updating your copy

If someone else commits changes, you will need to get an updated copy. If you try to commit and it says you are out of date, you also need to do this before you can check in your changes. In the directory type:

svn up

This will give you a status for all of the changes encoded as a character next to each file:

A    file1.C
D    file2.C
G    file3.C
C    file4.C

A means it was added, D means it was deleted, G means changes were merged into your copy, C means there were conflicts. If there were conflicts, see the section on merging.

Commit changes

After you know your modifications (or file addition/removal/moves) are right, you want to add the changes back to the repository so that other people can get them. Before you commit your changes, you must do an "svn up" to get the most recent copy from the repository. If you don't, it will give you a warning that you must update.

To check in all changes, simply do:

svn ci -m "One line comment about the changes you made."

or for a specific file:

svn ci file.C -m "One line comment about the changes you made."

The comment is REQUIRED and should be a useful description of what you did. This lets others know what changes you made and can be used if you need to undo changes later. If you omit the -m on the command line, svn will open the vi text editor for you to enter a commit message.

Merging conflicts

First, how does a conflict happen?

You and I both make changes to the same file. I check mine in first. Now, you have an updated file without my changes. To get these changes, do an "svn up" with your modified file in your svn directory. When you do this, svn takes care of any lines that either of us change (but not both). If we both change it, it isn't sure which one to keep and then it has a conflict (specified by a C during check-in) and requires a manual merge.

So, what do I do?

When there is a conflict (i.e. rarely) are 3 copies placed in your directory:

• bar.c.mine
• bar.c.rOLDREV
• bar.c.rNEWREV

bar.c.mine is your copy in its original form bar.c.rOLDREV is the old revision without any of your or the latest changes bar.c.rNEWREV is the new revision without any of your changes bar.c is the "merge" with diff sections that show the conflicts.

To resolve, you can:

1) edit bar.c by hand and resolve all the conflicts.This is typically what I do. These are indicated by text like:

<<<<<
old stuff
=====
new stuff
>>>>>

You just pick one or the other and delete the special characters.

2) copy one of bar.c.mine, bar.c.rOLDREV or bar.c.rNEWREV as appropriate. This will either undo all changes, keep all of your changes and undo mine, keep all of mine and ignore yours.

After you are done, you MUST delete all the extra bar.c.r* and bar.c.mine files. This is required so that svn knows you merged to complete the check in.

Other useful things

Diff

You can find how your copy differs from the repository with:

svn diff

or

svn diff file.C

This will show a diff log that only includes the changed lines.

Revisions

Each commit to the repository is tracked with a revision number. This number can be used to retrieve the EXACT COPY of everything in the repository anytime in the future. To update to a specific version in the past, do:

svn update -r 9405

where 9405 is the revision number. You can see the comment of each revision with:

svn log

which will show all revisions like this:

------------------------------------------------------------------------
r2000 | mrg | 2009-05-07 10:42:30 -0700 (Thu, 07 May 2009) | 1 line
Updated publications and news.

Blame

You can find out who committed a line of a file to a repository with:

svn blame file.C

Each line will be prefixed with the author.

Status

You can find the status of your copy of the repository with:

svn status

It will show:

? foo1.C
C foo2.C
M foo3.C
A foo4.C
D foo5.C

where ? means it is a local copy only, C means there is a conflict, M means the file is modified from the repository, A means it is added (but not committed), and D means it is deleted (but not committed).

Binary files

Usually, SVN will recognize files as binary. It does this when it finds a non-printable character in the first part of a file. If this is not the case as with some PDFs, you can set a binary property like this:

svn propset svn:mime-type application/octet-stream path/to/thingy

This will keep full copies of a file rather than incremental changes.