Subversion

Version control concepts

Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the repository' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the time and date, the changes, the author as well as a log message. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.

All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion client. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your working copy which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:

• which files have I modified since I last synchronised with the server?
• when was that file last modified?
• who wrote the stupid bug at line 18 in file foo.c?
• what has changed in that file?

The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk. This is not a very intuitive interface and we also provide a nicer interface called websvn and select the "subversion" project.

If you don't have a subversion login, use this link instead, but then you will not be able to send anything to the server.

Keep a websvn browser window open to check the state of the repository throughout the practical.

svn: the subversion command line client

The subversion command line client is called "svn". To execute a subversion command, simply type:

$ svn command arguments

Somme command can also use options which are given withdashes:

svn command arguments --option optionvalue

Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:

$ svn help command

Getting the content for this practical

You have used the subversion client for all the practicals in the Pragmatic Programming course. To create a working copy of the repository type (first make sure you don't have a local folder called "subversion"):

$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion
A    subversion/file1
A    subversion/file2
A    subversion/folder1
A    subversion/folder1/somefile
A    subversion/folder2
A    subversion/folder2/somefile

What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.

The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is very important that you do not touch these directories.

Modifying the working copy

The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:

$ svn status
M      file2

The status shows the letter "M" for file2, indicating it has been modified.

Note that this status only shows the things that have changed in your working copy. Not the changes made by others of on the server.

You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:

$ touch newfile
$ svn status
?      newfile

The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:

$ svn add newfile
A         newfile
$ svn status
M      file2
A      newfile

Note that the letter "A" is used showing an addition.

The same things happen for deletions. Let's try to delete file1 for instance:

$ rm -f file1
$ svn status
!      file1
M      file2
A      newfile
$ svn delete file1
D         file1
$ svn status
D      file1
M      file2

The letter "D" is used for deletions.

Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:

$ svn revert file1
Reverted 'file1'
$ svn status
M      file2
A      newfile

The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.

Sending changes to the repository

Sending changes to the repository is called a commit. The syntax to commit your changes is:

$ svn commit [--message "Log message."] [--username subversionlogin]
Sending        file2
Adding         newfile
Transmitting file data ..
Committed revision 2.

You might notice the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.

Now you and other have sent changes to the server. To bring these changes back, you need to update your working copy.

Updating your working copy

To update your working copy, simply run:

$ svn commit [--message "Log message."] [--username subversionlogin]
... <- list of files that have been added/modified
At revision 8.

Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem. Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?

status, commit and update will probably be your most widely used commands:

• update regularly to bring other people's work
• status to make sure all is well
• commit

However the subversion client can also be used to looks at changes in the repository and this can boost productivity.

Investigating changes

This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.

log

To get a log of what happened, use the log command. The output is quite verbose but you can get more detail with the -v option:

$ svn log --verbose
------------------------------------------------------------------------
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line
Changed paths:
   M /trunk/file2
   A /trunk/newfile

First commit
------------------------------------------------------------------------
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines
Changed paths:
   A /trunk
   A /trunk/file1
   A /trunk/file2
   A /trunk/folder1
   A /trunk/folder1/somefile
   A /trunk/folder2
   A /trunk/folder2/somefile

Initial import into the repository.

You can also invoke the log command on a particular file/path and provide a range of revisions. For instance to see which commits affected file1 between revisions 4 and 6, one could use:

$ svn log --verbose --revision 4:6 file1
... <- log output

diff

After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.

$ echo "Added this line." >> file1
$ svn diff file1
Index: file1
===================================================================
--- file1       (revision 2)
+++ file1       (working copy)
@@ -0,0 +1 @@
+Added this line.

It is standard diff style output with "+" for additions and "-" for deletions. diff can also be used on a path and make use of revision numbers too.

blame

$ svn blame file2
     2   jprenaud Added some stuff

Other useful commands

move

Rename

$ svn mv file2 new_file2
A         new_file2
D         file2

To go further

Subversion red Book

Pragmatic Programming

That's all folks. We hope you have the right basis to be