Tutorial on SVN

Another thing that is very important, is revision control. YOU SHOULD USE 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 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.

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>

To get an SVN client for any machine (Linux, OSX, Windows), you can look at http://subversion.tigris.org/project_packages.html

Now, when you are in the checked out directory, you can execute a number of commands.

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

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
G    file2.C
C    file3.C

A means it was added, 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

or for a specific file:

svn ci file.C

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.

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.