Tutorial:Using SVN

From NCSU EDA Wiki
Jump to: navigation, search

Subversion (SVN), like it's predecessor CVS, is an open-source system for facilitating versioning of data when multiple users are working on the same project. Although it is intended primarily for software development, we recommend using it with Cadence design projects as well. This page details the practices that should be adopted in order to use Subversion with Cadence most effectively.

Major Differences between Subversion and CVS

For those coming to Subversion from CVS, there are a few kew differences that are helpful to know before jumping in (feel free to skip this if you are not familiar with CVS):

  1. Subversion handles binary files just as easily as text files. There is no need to specify the "-kb" tag, as with CVS.
  2. Unlike CVS, there is no environment variable that sets the repository. Instead, the repository URL is given when a repository is created, when files are initially imported, and when a tree is checked out. At all other times, Subversion gets the URL for the repository from the local ".svn" directory.
  3. Subvsersion tracks directory structure as well as the files. This means that you typically check out an entire tree, rather than individual parts of a repository. It also means that new directories must be checked-in after they are added, just like regular files.
  4. Subversion gives a revision number to the entire repository, rather than individual files. This means that you can check out the entire repository for any point in time with a single revision number.

Usage Policies and Maintenance

In order to allow the most freedom in viewing and using design-data created by other group member, we suggest the following policies:

  • Anyone is free to create directories in the repository. Consult other group members for tips on the most logical location in the repository.
  • Users are free to check-out other users' code. It's not advisable to commit any changes, however, without consulting the author.

Getting Started with Subversion

First, find the URL of your repository. If you do not have a repository, see Creating a Repository below. You will need to provide this URL when you import and checkout directory trees from the repository.

Also, check the version of the subversion tool installed on your system with the following command:

svn --version

The version installed on most machines at NCSU is 1.6.11. Make sure that you are not using a version older than 1.4.1, since older versions have been known to corrupt the repository when committing.

Creating a Repository

It is recommended that you not create the repository yourself, because it's very complicated to do it properly. Simple methods do exist for creating repositories, but these can lead to data corruption in certain cases. Still, if you want to get started, you can create a repository by executing the following command once and only once:

svnadmin create /path/to/repository

This will create a directory called repository that contains the necessary files for all group members to check files in and out. The URL for the example above would be file:///path/to/repository.

Security Risks

The recommended way to use subversion is to have a repository created by ece_help@ncsu.edu, served from https://svn.ece.ncsu.edu, and accessed using the Linux SVN client. One issue that comes up is that the LINUX SVN client can store your password in your home directory so that you don't need to type it in every time you access the repository. Although this is very handy, it's quite a security risk. Anyone who has access to your home directory could potentially read your Unity password from this file. This includes anyone who happens to be logged in to the same machine as you and possesses the super-user password. To warn you about it, SVN prints the following message:

----------------------------------------------------------------------
ATTENTION! Your password for authentication realm: 

<https://svn.ece.ncsu.edu:443> VisualSVN Server

can only be stored to disk unencrypted! You are advised to configure
your system so that Subversion can store passwords encrypted, if
possible. See the documentation for details.

You can avoid future appearances of this warning by setting the value
of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
'/afs/unity.ncsu.edu/users/w/wdavis/.subversion/servers'.
----------------------------------------------------------------------
Store password unencrypted (yes/no)?

If you answer no to this question, your password is not stored, but you must answer the annoying question every time to access the repository. We recommend that you add the following text to your ~/.subversion/servers file:

[global]
store-plaintext-passwords = no

If you ever answer yes to this question, then your password is at risk of discovery! The simplest way to solve this problem is to delete all files in the directory ~/.subversion/auth/svn.simple, thereby resetting your preferences for this server and removing the record of your password.


Documentation

For more information, see the "Subversion Book" at http://svnbook.red-bean.com.

Using Private Source Directories

Private source directories are where all users should do their work for the project. These directories are created by Subversion using the directions below. They can usually be identified by the fact that they always contain a subdirectory called ".svn".

Creating a Private Source Directory

To create a private source directory, use the "checkout" command (abbreviated "co"):

svn co [URL] [path]

Where [URL] gives the repository URL, and [path] gives the path for your private source directory. Note that [path] argument is optional. If omitted, your private source directory will take the same name as the repository directory. Unlike CVS, Subversion assumes that you will check out the entire directory tree of the repository, rather than give you the option of chosing which parts of the repository that you want to check out.

You cannot checkout files that have not yet been added to the repository. See Adding and Importing New Files and Directories below to add new files.

Updating a Private Source Directory

The "update" command allows us to see if other people have modified the repository. To update the contents of a private source directory, change to that directory and use the command

svn update

Generally, if no changes have been made to a file, nothing will happen. If changes have been made, then you will see one of the following six characters printed before each filename:

  1. U - Update - You made no changes to the file, but someone else made changes to this file and committed them to the repository. An up-to-date version of the file is copied into your private source directory.
  2. A - Add - Someone added this file to the repository since you last updated. An up-to-date version of the file is copied into your private source directory.
  3. D - Delete - You made no changes to the file, but someone deleted this file from the repository since you last updated. Your copy is deleted. An up-to-date version of the file is copied into your private source directory. If you had made changes, this would not happen. Your changes would be saved.
  4. R - Replace - You made no changes to the file, but someone deleted this file and added a new file with the same name since you last updated. An up-to-date version of the file is copied into your private source directory. This may seem redundant with U, but Subversion considers them to be different objects.
  5. G - Merge - You made changes to the file, but someone else made changes to this file and committed them to the repository. You modified different parts of the file, however, and so Subversion was able to merge your changes with the other person's changes successfully.
  6. C - Conflicts - As with the Merge case above, Subversion attempted to merge your changes with the changes in the repository. This time was unsuccessful, however. Your private version is renamed with a ".mine" extension, and a new file is created with the original name that contains hints about where the conflicts lie. See fixing conflicts below. Generally, only text files can be merged successfully, so this feature seldom is useful with Cadence designs.

Note that if you want to "force" an update of a file that you modified (to throw away any changes that you have made), you can do so with the "revert" command:

svn revert [filename]

Note, however, that this does not get the most up-to-date revision of the file... it simply throws away your changes. You'll still need to use "svn update" to get a most-recent copy.

Committing Changes

Once you've made changes to a file, you can "commit" (abbreviated "ci") them with the command

svn ci [filename] -m "[log message]" 

The message doen't have to be much, just enough to make life easy if you or someone else needs to fix conflicts later. Note that if you omit filename, all files in the current directory and subdirectory will be committed.

Adding New Files and Directories

It's easiest to add new files and directories to the repository from an existing private source directory. Simply create the new file/directory and type

svn add [file or directory name]

Unlike CVS, no special options are required to add binary files.

The new directory and all of its files and subdirectories will be recursively added to the repository. Other users won't be able to see them, however, until you use the command "svn ci" to commit them.

Importing New Files and Directories

If you want to add files but don't have an existing private source directory (as is generally the case when you first create the repository), you can do so with the command

svn import [path] [URL] -m "[message]"

where [URL] gives the repository URL, and [path] gives the path for the directory containing the files to import. By convention the message is something simple like "initial import".

Fixing Conflicts

If someone committed changes to a repository file that you were editing, the changes need to be merged. If you already know that someone made changes to your file, you can find out how many differences there are with the "diff" command:

svn diff [filename]

This command is identical to the normal UNIX "diff" command, except that it retrieves the most up-to-date revision from the repository for the second file. Note that this operation is not very useful for binary files.

Otherwise, if you have arrived at this point because you used "svn update" and had conflicts, then Subversion automatically prints the results of the "diff" into the source file, with the characters ">>>>>>>", "=======", and "<<<<<<<" to delineate the differences.

Checking a File's Status

You can check to see if your files need to be merged by using the command

svn status -u

You will see an M printed next to the files that you have modified. The "-u" argument is necessary for svn to check the repository. Otherwise, it will simply tell you if you made any changes. With the "-u" argument, however, you will see an asterisk "*" next to the files that you haven't updated since the last changes were checked in.

Rolling Back to a Previous Version

If the changes are too much to deal with, then perhaps it's best to just roll back to an earlier revision. To do this, first figure out the revision number that you want with the command

svn log [filename]

This prints out all revisions of this file and the log messages that were used when they were committed. Scan through the log entries and find the revision number that you want (something like "7", for example). Then use the following command to retrieve that revision in your private source directory:

svn cat -r [revision number] [filename] > [filename]

The cat command pipes the file to standard out, which is then redirected into the file. This approach may seem verbose, but we would otherwise not be able to commit the old revision as the most-current one. Once you've looked the file over, you can commit the changes as before, making this old revision the new, most recent revision.

svn ci [filename] -m "[message]"

Resolving Conflicts

Once you have fixed the conflicts, you must tell subversion that the conflict is gone by using the resolved command. Otherwise, you will continue to see the conflict when you check a file's status.

svn resolved [filename]

Links

Poojan Wagh has a blog posting about using Subversion with Cadence. I've been meaning to work through it and see what goodies he's got.