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.
- 1 Major Differences between Subversion and CVS
- 2 Usage Policies and Maintenance
- 3 Checking Out the Repository
- 4 Documentation
- 5 Using Private Source Directories
- 6 Examining Changes and Fixing Conflicts
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):
- Subversion handles binary files just as easily as text files. There is no need to specify the "-kb" tag, as with CVS.
- 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.
- 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.
- 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.
- CVS users generally use the command "cvs update" to check for modified files in a private source directory. This is not advisable with Subversion, because it will always merge changes. Instead, use "svn status" for this purpose. The Subversion status command gives a summary of all changes, rather than the detailed information with CVS.
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 check out the entire repository.
- In order to commit changes to the repository, you must have a login ID on the NCSU Unity system, and that ID must be in the list of developers. If you would like to get an NCSU Unity ID and/or be added to the list of developers, please contact Rhett Davis .
- Developers are free to create directories in the repository. Consult other developers for tips on the most logical location in the repository.
- Developers are free to modify other developers' code. It's not advisable to commit any changes, however, without consulting the author.
Checking Out the Repository
First, make sure that you have the executable "svn" on your system. I have been using SVN version 1.1.4 on Linux machines and version 1.4.5 with MS-Windows and Cygwin. So far, I haven't noticed any problems mixing the versions.
I suggest checking out the repository with the steps below.
svn co https://svn.unity.ncsu.edu/osi/freepdk45/trunk freepdk45/trunk
This will check out the entire kit and put it in the subdirectory "freepdk45/trunk". This is your Private Source Directory. If you want to check out a subtree (such as "ncsu_basekit" or "osu_soc"), I would suggest appending the directory name to the last argument above, so that the directory structure of your checked-out copy matches the repository directory structure.
For more information, see the freely downloadable PDF "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".
Updating a Private Source Directory
The "status" and "update" commands allows us to see what changes we have made and/or if other people have modified the repository. To see a summary of your changes, use the command
This will examine your directories and search for files that you have modified. 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 four characters printed before each filename:
- M - Modified - You have locally modified this file from the version that was checked out.
- A - Add - You scheduled this file to be added to the repository, but it has not yet been committed.
- D - Delete - You scheduled this file to be deleted from the repository, but it has not yet been committed.
- C - Conflicts - You updated this file (see below), and there were conflicts on the update.
Note that the "svn status" command does not need to access the network, so it will not check for changes from other users. If you want to see what files other users have modified, then use the "-u" option. This will print an asterisk "*" by the names of files that other users have modified. Alternatively, the "svn update" command does more than "svn status -u", because it will actually load the changes from other users and attempt to merge your changes with other users' changes.
If changes have been made to a file, then you will see one of the following six characters printed before each filename:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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.
Note also that may need to enter your NCSU-Unity ID and password, depending on where you are running the command.
Examining Past Revisions
Use the following command to see a list of all repository revisions for a specific file or directory, along with the log message for each one.
svn log [path]
If you want to see the list of all revisions for the entire repository, then change to the root directory, and issue the command with no path argument.
Sometimes you may want to see a list of files that were changed for a specific revision. To do this, I generally do a diff between two revisions, and suppress the printing of the actual changes, so that only the filenames are listed. The command for this is
svn diff -rN:M --summarize
where N and M are the two revisions you want to check.
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 -m "[description of file]" [file/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 a large number of files, it can be quite tedious to add them one by one. You can import a tree of files with the command
svn import [local path] https://svn.unity.ncsu.edu/osi/freepdk45/trunk/[repository path] -m "[message]"
All of the files and directories within the directory [local path] will be added to the repository directory [repository path]. Note that the directory given by [local path] will not be added unless you explicitly include it in the [repository path] argument. If you find that you have mistakenly imported something to the wrong place in the repository, then see "moving directories" below.
Note also that this does not turn [local path] into a private source directory. You will still need to check out the files you imported to create a private source directory, or simply use "svn update" to load the new files into an existing private source directory.
By convention, the first message is usually something simple, like "initial import".
Moving Files and Directories
Because SVN manages directories as well as files, moving a directory in the repository must be done with the command
svn mv [oldpath] [newpath]
This command will copy the directory from oldpath to newpath without deleting the old directory. Once you commit the changes, the old directory will be deleted. The entire revision history will follow the files to the new location. You can also use this method to change the name of a file, if you want the revision history to be saved with the new file.
Examining Changes and 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 similar 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. The command will print out lines from your private file with a preceeding "+" character and lines from the repository version with a "-" character. Lines with no preceeding character are there to help see the surrounding lines, but do not actually differ between the two 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. You would need to merge these differences yourself into a file that resolved the conflicts.
For your conveneince, Subversion also creates the following three files, whenever an update encounters conflicts:
- filename.mine - Your original file, before you issued the "svn update" command
- filename.rOLDREV - The old repository revision that you were editing
- filename.rNEWREV - The new revision that caused the conflicts
After resolving the conflicts, use the following command to remove these three files and let Subversion know that the file is no longer in a state of conflict.
svn resolved [filename]
You will still need to check in your changes, after using the "svn resolved" command.
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]"