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: every time 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 information about 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 navigating 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.

"trunk/" at the end of the URL is just a convention. Usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.

svn: the subversion command line client

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

$ svn command arguments

Some commands can also use options which are given with dashes:

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 yours to work with 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 have noticed 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.

Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:

$ export EDITOR=emacs

At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.

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 in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose 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.

$ svn diff file1
Index: file1
Index: file1
===================================================================
--- file1       (revision 3)
+++ file1       (working copy)
@@ -1 +1,4 @@
-Added this line.
+Added this (removed some text here)
+
+Add a new line here
+

Standard diff syntax is used with "+" for additions and "-" for deletions.

blame

Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:

$ svn blame file2
     2   jprenaud Added some stuff
     3   jprenaud Another line
     4   jprenaud A third line.

You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.

$ svn log file2 --revision 3
------------------------------------------------------------------------
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line

More things.
------------------------------------------------------------------------

Other useful commands

move

If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do:

$ svn move file2 new_file2
A         new_file2
D         file2

You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.

import

When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:

$ svn import PATH URL/trunk --message "Log message."

• PATH is the path to the local folder (by default it ses "./", i.e. the current folder)
• URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.

mkdir and cp

Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:

$ svn mkdir URL/branches --message "Log message."

Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:

$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."

Then you could check out URL/branches/version1 to work on version1 rather than the trunk.

export

Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the Linux1 and Linux2 practicals.

You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:

$ svn export URL PATH

merge

When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the Subversion Red Book for more information about merging.

To go further

The Subversion Red Book is the bible of subversion. Very recommended.

Pragmatic Programming

That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.