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 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. $ echo "Added this line." >> file1 $ svn diff file1 Index: file1

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

blame
$ svn blame file2 2  jprenaud Added some stuff

=Resolving conflicts=

=Other useful commands=

move
Rename $ svn mv file2 new_file2 A        new_file2 D        file2

merge
=To go further= Subversion red Book =Pragmatic Programming= That's all folks. We hope you have the right basis to be