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 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.
------------------------------------------------------------------------

Creating the conflict

Let us create a conflict:

Somebody modifies file1 by adding a line and commits (let's assume revision5)
All of you update your working copies
Person1 modifies the new line
All of you modify the same line too
Person1 commits (revision 6)
Now all of you, try to update

The update does not fail but file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:

$svn status
?      file1.r5
?      file1.r6
?      file1.mine
C      file1

file1.r5 is file1 as at revision 5 (i.e. the one at your last update)
file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)
file1.mine is file1 as it was in working copy before the update
file1 contains an attempt at merging the changes

Let's look at file1:

$ cat file1
Added this line.
<<<<<<< .mine
This will create the conflict.
=======
This LINE will create the conflict.
>>>>>>> .r6

Subversion uses "<<<<<<" and ">>>>>>" to show the problem(s). Your version of the problem lines is shown first (.mine) and then the version in the repository (.r6).

To solve the conflict, you need to edit this file and mark it as solved. For instance, let's assume that your version was the good one (that's probably not a good assumption in normal development cycles as you are just ignoring one commit here). To resolve the conflict, one could do:

$ cp file1.mine file1
$ svn resolved file1
Resolved conflicted state of 'file1'
$ svn status
M      file1

Now you could commit your changes. But don't during the practical as all of you have resolved the conflict at the same time and this should be done only once.

Other useful commands

move

Rename

$ svn mv file2 new_file2
A         new_file2
D         file2

import

mkdir

export

merge

To go further

Subversion red Book

Pragmatic Programming

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

Subversion

Contents