How to use Subversion
This is a guide detailing the use of Subversion (SVN) in COMP 520. It contains critical course-specific information as well as instructions that are more generally useful.
1. What is SVN?Subversion is a version control system. It allows users to keep track of changes made to any type of electronic data, which are typically source code, web pages or design documents. It does this with the help of a repository, an SVN server, and an SVN client.
Reasons to use SVN:
2. Getting StartedIn order for us to provide you with access to the class repository, you must send us a DSA ssh public key. This is one half of a public/private key pair that you create and it allows for secure remote repository access without password authentication. If you already have an ssh key pair you can skip this next step.
$ ssh-keygen -t dsa Generating public/private dsa key pair. Enter file in which to save the key (/home/users/chris/.ssh/id_dsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/users/chris/.ssh/id_dsa. Your public key has been saved in /home/users/chris/.ssh/id_dsa.pub. The key fingerprint is: ab:3c:ce:d3:61:1e:37:75:02:f9:9e:9f:ba:d9:b6:58 chris@localhostHit enter at all of the prompts. If you already have an ssh key pair and want to use a different one for this course then you should choose a different location to save the file. In that case, you can set the environment variable
In the instructions that follow, we will use
After you have your key pair, create a copy of your public key with your CS username in place of id_dsa:
$ cp .ssh/id_dsa.pub `whoami`.puband send this file as an attachment to your TA. They will add it to the
3. Basic OperationsThis section surveys the fundamental operations that you will need for day-to-day use of SVN.
3.1 Check OutThe first thing you should do is to check out the files from the remote class repository to your local working copy:
$ mkdir cs520 $ cd cs520 $ svn co svn+ssh://email@example.com/2012/students/`whoami` `whoami`This creates a directory `whoami` which is identical to your CS username as a subdirectory of
$ svn co svn+ssh://firstname.lastname@example.org/2012/public_html public_htmlThis directory contains all of the course information and all of the source code and binaries that you need. Again, you can rename it to whatever you like. Finally, after we assign group numbers then you will have access to a folder shared between all members of your group. With your group number in place of X:
$ svn co svn+ssh://email@example.com/2012/groups/group-X group-Xwill create that group directory for you. You will use this to check in all group assignments and your course project.
After checking out, you can add, modify or delete files in the local working copy, and nothing will be changed in the repository or visible to anybody else until you commit or check in.
3.2 UpdateEvery time you start working, it is a good idea to make sure your local working copies contain the latest version. This requires the
$ cd cs520 $ cd `whoami` $ svn up $ cd ../public_html $ svn up $ cd ../group-X $ svn upOf course, you can also just do:
$ cd cs520 $ svn up `whoami` public_html group-XThis command recursively updates all files and sub-directories in all working copies. If you encounter a conflict as indicated by
3.3 DiffAfter you update and begin modifying files, you will often want to check the difference between your version and the repository version:
$ svn diffThis provides a unified diff between your version and the latest repository version on stdout, using exactly the same format as
$ svn diff -r2:3will show you what changed in the repository between revisions 2 and 3. Finally, although
It is a very good idea to run
3.4 CommitOnce finished your local work, your changes will not appear in the repository until you commit them or check them in:
$ svn ciHere,
export EDITOR='emacs -nw'means that
* Expand on SVN instructions. --This line, and those below, will be ignored-- M howtosvn.htmlFor each individual thing that changed in your commit, create a new bullet point preceded by "
$ svn ci -m "* Expand on SVN instructions."However, given that opening an editor is both fast and much safer in that it provides you with a list of modifications to review, it is best to leave this option for non-interactive scripted use.
If you want to check in individual files or directories rather
than the current working copy and all files and directories it
contains, simply pass them to
3.5 AddThe following command:
$ svn add <file>adds new files or directories to your working copy. They will not appear in the repository until you run
3.6. Copy/Move/DeleteThese three commands work similarly to the Unix commands
3.6.1 svn cp
$ svn cp <src> <dest>
$ mkdir group-X/joos # make sure parent dir exists $ svn add group-X/joos # add empty parent directory $ svn ci group-X/ # commit empty parent directory $ svn cp public_html/joos/a- group-X/joos/scanparse # create copy of source code $ svn ci # check in copy of source codeIn fact,
If we want to see what you have changed, we need simply ask
3.6.2 svn mv
$ svn mv <src> <dest>
3.6.3 svn rm
$ svn rm <file>
3.7 Retrieve LogIf you want to look at the repository history, Subversion provides a detailed log upon request:
$ svn log | lessIf you want to see full paths that are changed, pass the
$ svn log -v | lessYou can also specify individual files if you are not interested in the entire log for the current directory.
4. Less frequently used commandsOf course, there are actually many other commands, several of which are quite useful, including
$ svn help usage: svn <subcommand> [options] [args] Subversion command-line client, version 1.4.3. Type 'svn help <subcommand>' for help on a specific subcommand. Type 'svn --version' to see the program version and RA modules or 'svn --version --quiet' to see just the version number. Most subcommands take file and/or directory arguments, recursing on the directories. If no arguments are supplied to such a command, it recurses on the current directory (inclusive) by default. Available subcommands: add blame (praise, annotate, ann) cat checkout (co) cleanup commit (ci) copy (cp) delete (del, remove, rm) diff (di) export help (?, h) import info list (ls) lock log merge mkdir move (mv, rename, ren) propdel (pdel, pd) propedit (pedit, pe) propget (pget, pg) proplist (plist, pl) propset (pset, ps) resolved revert status (stat, st) switch (sw) unlock update (up) Subversion is a tool for version control. For additional information, see http://subversion.tigris.org/If anything is confusing, then again, the Subversion documention is excellent. We are also happy to help you if you send us a precise and accurate description of your problem or if you come and see us during our office hours.
5. Recommend Editing CycleAlthough you are free to use SVN as you wish, this is an editing cycle that works very well:
svn up # update svn log | less # see details of update if there was one while (change not implemented correctly) while (program does not compile) edit files # implement change make # try compiling make check # run automatic tests svn diff # review changes svn ci # commitFor source code, the time between commits should be small. Ideally, each commit makes an incremental and self-contained improvement. If you avoid checking in things that do not work, you will save yourself and others headaches in the future.
Of course, you may run into conflicts and other problems, in which case you should refer to the excellent Subversion documentation.
6. Other Advice
7. SVN GUI ClientsIf you are not used to Unix and the command line interface, life may be easier if you have a GUI client and do not need to type commands in a console. However, at the same time, this course is an excellent opportunity to improve on your command line abilities, a skill that will serve you well for years to come.
Under Windows, you can try TortoiseSVN, an SVN client that integrates commands into your right-click context menu. It is fairly easy to install and use.
For Linux, there is eSVN, although it is apparently not as stable as TortoiseSVN.
SubClipse tip: Using "Synchronize with repository" rather than "Update" will show you more detail when you want to update your local working copy.
Finally, if you are looking to use SVN in your own projects, you may be interested in Trac, an integrated bug tracking, wiki, and version control system.
|Maintained by Chris Pickett [HOME]|