Svn instructions

setenv CS552_REPOS file:///p/course/cs552-karu/handin/user/CS552_REPOS/
set path = ($path /u/k/a/karu/courses/cs552/spring2009/handouts/bins)

1.  Overview

For this course we use a version control system called svn. Details on svn are here. With svn you can track changes to the files as you modify them and arbitrarily revert back to older versions, without having to maintain messy manual backups. The other big advantage of an automatic version control system are that it allows you easily shared project files between project partners.

2.  Concepts

2.1  svn repository

The repository is the place where the master copy of your files are maintained. To modify files you should "checkout" from the repository. When you are satisfied about a small set of changes you have made you should "commit" the changes at which point, the files will be modified in the repository.

2.2  svn work directory

The work directory is a checkout of the repository and contains any modifications you made

2.3  svn commands

• checkout: checkout copy of the repository into the current work directory
• add: adds a file or directory to the svn repository.
• remove: removes a file or directory from the svn repository.
• commit: commit your changes in the working copy to the repository. The add command has no effect until you commit the change
• diff: difference between two versions, or the difference between your modifications and the golden copy in the repository
• log: show you a log of all changes you have made
• cat: display an older version of a file without checking it out.
• status: shows status of current files

3.  Cookbook

An svn repository has been created for each one of you in this location: (replace user with your cs login)

The repository has been populated with just the directory structure and you are expected to stick to this structure. This is for information only. You will NEVER need to go to that directory and do anything in that directory.

3.1  Initial checkout

First you must go to your home directory, or to some other directory where you want your cs552 related stuff to be in. It is also useful to set the prompt to show your current directory all the time. Which is what the set prompt command does.

prompt> cd ~
prompt> set prompt="%n@%m%~>"

Now, to checkout the repository issue the following command.

prompt> svn co $CS552_REPOS/trunk cs552_work

This will create a directory called cs552_work in whichever directory you issue this from. You should see the following directory hierarchy, if you execute ls:

README.TXT
hw2/
hw3/
hw4/
hw5/
hw6/
project/

4.  Homework problems and project

As the name suggests you will work on individual homeworks and the project in different directory. For each problem that must be electronically turned in you must create a directory of its own. For example hw2, requires problem 1 and problem 2 to be turned. You must perform the following steps:

4.1  Create the directory

prompt> cd hw2
prompt> mkdir problem1

4.2  Add the directory to svn repository

prompt> svn add problem1
prompt> svn commit -m "created directory"

What is specified with -m is a comment. You should put something descriptive here.

4.3  Do the homework!

You will end up creating a few verilog files, lets say adder.v, mux.v.

4.4  Add the files to svn

prompt> svn add adder.v mux.v
prompt> svn commit -m "added files"

4.5  Spend some time debugging

At this point you may make a bunch of changes. As and when you discover a small bug and fix it, commit that change. If you did not add any new files, you can just issue commit. Which will copy over the latest files to the repository.

prompt> svn commit -m "fixed bug in carry out"

You should provide a descriptive piece of text following -m

4.6  Final submit of homework

To finally submit the homework, when you are all done, you create a tag. Each homework will have its own tag. To create a tag called "hw2-submit", issue the following command:

prompt> svn copy $CS552_REPOS/trunk $CS552_REPOS/tags/hw2-submit -m "submitting homework"

You can provide any message following the -m.

Important notes:

1. You must first commit your changes before issuing svn copy.

4.7  If you want to submit a homework multiple times, do the following:

prompt> svn commit -m "commited modifications after submitting homework"
prompt> svn delete $CS552_REPOS/tags/hw2-submit -m "deleting submission"
prompt> svn copy $CS552_REPOS/trunk $CS552_REPOS/tags/hw2-submit -m "submitting again"

You may re-submit as many times as you please.

4.8  Checking that what you submitted actually got turned in

You should simply checkout the tag you just created in a temporary directory and see if all the files you intended to submit are there. At the unix prompt issue the following commands:

Wherever you see [user] replace with your cs login.

prompt> cd /tmp
prompt> rm -rf submit-test-dir-[user]
prompt> svn checkout $CS552_REPOS/tags/hw2-submit submit-test-dir-[user]
prompt> cd submit-test-dir-[user]
prompt> ls

You should see the files listed. If any files that you intended to submit are missing, go back to your original work directory mywork, issue svn add, svn commit, and the svn delete, svn copy sequence to re-submit. The checkout in a temporary copy to see if everything has been submitted.

4.9  Show what submissions I have made

prompt>svn list $CS552_REPOS/tags

5.  Fun things with svn

5.1  svn log

This will show you a log of all the changes you have made

5.2  svn diff

• svn diff file.v will show a difference of changes you have made compared to what is in the repository.
• svn diff add.v | kompare -o - will show you the difference through a nice gui
• svnprettydiff foo.v same as above.

5.3  svn cat: Reverting to an older version.

Lets saying you have been making several modifications to a file and are at revision 45 for a file. After doing a bunch of debugging, you realized revision 41 is actually the cleanest file and you want to go back to that as the latest copy. i.e create revision 46 which is the same as revision 41.

 

prompt> svn cat -r41 add.v > add.v
# It is important to specify the filename twice with the greater than sign in-between. What the svn cat command does is dumps the file to the screen. What we are doing with the "> add.v" construct is redirecting the output to the file add.v

prompt> svn commit -m "reverting to version 41"

5.4  svn remove: removing a file or directory

To remove an entire directory and all the files in it from the repository; you can do:

prompt> svn remove foobar
prompt> svn commit -m "removed the directory foobar and all files in it"

If you want to remove a single file:

prompt> svn remove foobar.v
prompt> svn commit -m "removed the file foobar.v"

If you want to remove multiple files:

prompt> svn remove foobar.v file1.v file2.v
prompt> svn commit -m "removed the file foobar.v file1.v file2.v" 

5.5  svn list: show the submissions or tags I have made:

prompt>svn list $CS552_REPOS/tags

5.6  Undoing a remove!

I just removed a directory or file, and issued svn commit. I want it back!

First find what revision number you are at, lets says you are at revision 20. You can determine this by doing the following:

prompt>svn update; svn info

You will see something like tihs:

Path: .
URL: file:///p/course/cs552-karu/handin/foo/CS552_REPOS/trunk
Repository Root: file:///p/course/cs552-karu/handin/foo/CS552_REPOS
Repository UUID: dff6809d-9a60-4b0f-90cb-be1f33e79980
Revision: 20
Node Kind: directory
Schedule: normal
Last Changed Author: karu
Last Changed Rev: 20
Last Changed Date: 2009-02-10 18:26:39 -0600 (Tue, 10 Feb 2009)

Look at the line "Last Changed Rev: " to get the current revision. The file you deleted is then in the previous revision, "19". Then issue the following command:

prompt> svn merge -r20:19 $CS552_REPOS/trunk

Check if the files you want have been restored; then commit this:

prompt> svn commit -m "got back the files"

6.  Summary of commands

• svn add file.v -m "adding a file"
• svn commit -m "committing changes"
• svn delete $CS552_REPOS/tags/hw1 -m "deleting submission"
• svn copy $CS552_REPOS/trunk $CS552_REPOS/tags/hw2-submit -m "submitting homework"
• svn diff
• svn cat -r41 add.v > add.v
  • ; revert to version 41
• svn log
• svnprettydiff foo.v