How to use SubversionThis 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 dsaHit 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 SVN_SSH to ssh -i
/path/to/your/private/key/id_dsa . If you enter a password, you
will get annoyed at having to authenticate for each repository access
and will end up wanting to use the ssh-agent tool.
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 with the subject "COMP520 ssh key `whoami`". The TA will add the key to the .ssh/authorized_keys
file for the course account and you will then have repository access.In the email include information about your project partners. Who would you like to pair up with for the group projects? Please build groups of two or three students. Having trouble finding partners? Use our discussion group. Also make sure to include your CS username! 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:
This creates a directory `whoami` which is identical to your CS username as a subdirectory of cs520 . It is your personal
student repository, and you will use it to check in all of your
individual assignments. You can rename it to whatever you like,
Subversion does not care. Next, you should check out the course
website:
$ svn co svn+ssh://cs520@svn.cs.mcgill.ca/2008/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://cs520@svn.cs.mcgill.ca/2008/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 thesvn
update or svn up command:
$ cd cs520Of course, you can also just do:
$ cd cs520This command recursively updates all files and sub-directories in all working copies. If you encounter a conflict as indicated by C ,
you should refer to the Subversion documentation for details on how to
resolve it.
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 diff
-u . You can also use svn diff to look at the
changes between two specific revisions. For instance:
$ svn diff -r2:3will show you what changed in the repository between revisions 2 and 3. Finally, although svn diff operates on the current
directory . by default, you can also specify a particular
file, directory, or some local or remote URI.
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:
Here, svn ci is an alias for svn commit .
The svn binary will attempt to open an editor for you to
leave a log message, and you can control which editor is opened through
use of the EDITOR environment variable. For example, on my system:
export EDITOR='emacs -nw'means that svn will open the command line interface to
Emacs in the current terminal. You should always leave a meaningful
log message. For example, if we were to check in changes to the
current document at this very moment we might write:
* Expand on SVN instructions.For each individual thing that changed in your commit, create a new bullet point preceded by " * ". This makes it much easier
for you, your collaborators, and your instructor and TA to follow
along. If you do not save the file, svn will prompt you
to a)bort, c)ontinue, e)dit . This lets you back out of a
commit if you realize you are missing something. As an alternative to
editing a file, you can also specify a log message on the command line:
$ 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:
adds new files or directories to your working copy. They will not appear in the repository until you run svn ci . Note that
you can disable the recursion when adding directories with the -N
flag.Ignoring filesSometimes, you may want to add files to Subversion but ignore others. When you do an update on a folder or check its status and this folder contains files that are neither added nor ignored then Subversion won't know what to do with them and show a question mark. Therefore usually you want to ignore files that are automatically generated from others or are just temporary and do not need to be stored. For instance, you should check in your yacc or SableCC grammar file but you should not check in the files generated from these grammars, as they can easily be reproduced by just calling your makefile or Ant script. Subversion maintaines a list of files or file patterns to be ignored for each folder; in fact this list is a "property" of this folder. You can change the property of the current folder by typing:$ svn propedit svn:ignore .This will open a text editor that shows the currently ignored files, folders or patterns for this folder. Let's say that you want to exclude the folder generated (because it only contains generated classes) and all files ending in .class. In this case you add the following lines to the file: generated *.classThen save the file. Subversion will automatically update the property. To cancel, simply do not save the file. For this class we expect you not to check in any generated files or binary files, such as .class files, object code etc. On the other hand you should of course check in every file that is human-readable and to be altered by a programmer, i.e. you. 3.6. Tagging and Branching with Copy/Move/DeleteThese three commands work similarly to the Unix commandscp ,
mv , and rm but they affect both the
working copy and the repository in sync. You can use them to "tag" a
certain revision of your repository or to "branch" off a version of it.
Tagging means that you simply copy a repository url to another, e.g.:$ svn mkdir svn+ssh://cs520@svn.cs.mcgill.ca/2008/groups/group-X/tags/ # create "tags" directory Branching works essentially the same as tagging. You simply
use svn cp to copy a url to a
different folder and then you check out the newly created copy using svn co. Then you modify this copy
(the branch) as usual. All changes that you commit will be commited to
the the branch and not to the SVN folder which the copy originated
from. Note that copying one SVN URL to another is cheap: SVN simply
creates a database entry for the new folder. No files are actually
being copied. However, there are other uses of svn cp... 3.6.1 svn cp$ svn cp <src> <dest> svn cp will also add the destination file or
directory to the working copy. The advantage of this command is that it
maintains version history from before the copy, and that it requires
almost no extra storage space in the repository. For example, assume
there is a directory called joos/a- that is a
subdirectory of the public_html directory for this course
that contains some source code you wish to modify for an assignment,
and that the instructor has asked you to place your modified source
code in group-X/joos/scanparse . In that case, you need
simply enter:
$ mkdir group-X/joos # make sure parent dir existsIn fact, svn cp is really the mechanism for creating branches
with SVN.
If we want to see what you have changed, we need simply ask 3.6.2 svn mv$ svn mv <src> <dest> svn mv can either be used to rename files and
directories, or to move files or directories to different directories
while keeping the same name. In doing so, it maintains version history.
3.6.3 svn rm$ svn rm <file> svn rm deletes the file or directory from the
working copy, as you might expect.
Important: Like 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 -v
option:
$ 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, includingsvn status , svn revert ,
svn cleanup , svn merge , and svn
resolved . When things go wrong, and they will go wrong, these
commands are there to help you out. In fact, there is actually a
built-in command to teach you about them:
$ svn helpIf 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 # updateFor 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. A cross-platform solutions is SubClipse, an Eclipse plugin that does the same job. You can find very clear instructions on how to install this plugin here: http://subclipse.tigris.org/install.html. 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. 8. References
|
Maintained by Eric Bodden. [HOME] |