Using Subversion

For general information about Subversion and how to use it, please see the Subversion manual. If you are not familiar with version-control systems, the first chapter of the manual is a must-read. If you are familiar with CVS, please read at least Appendix B of the manual. From the command line, svn help gives you a complete overview of the commands and their use.

On the BCI2000 Wiki, you can find good tutorials on using the Subversion client and TortoiseSVN. They have been written for BCI2000, but can be used also for other repositories if you change the URLs. Another graphical front-end for Subversion is RapidSVN, which is cross-platform and works with Linux.

See also the Configuring Subversion page.

Quick Introduction

Please really do read the Subversion manual, and in particular the first chapter if you are new to version-control systems or the Appendix B if you are used to CVS. Here follows a short list of the tasks that you can accomplish using Subversion, so you have an idea of what you can (or should) do.

Checkout

'Checkout' refers to getting a copy of the repository on your local disk. The svn checkout command creates a mirror of the repository, with all files and directories and some metadata used by Subversion to keep things in sync. You can checkout just a part (a subdirectory) of a repository, if you like. Please notice that since version 1.5 of the Subversion client you can also exclude specific subdirectories from the checkout; for more details please refer to the Sparse directory feature on the manual.

Creating new files from scratch

Create the file as usual (e.g., File->New from your favorite editor) and add it to the repository when you have the first version ready. You can use the svn add command from the command line or the equivalent command from a graphical front-end.

Creating new files from existing files

Use the svn copy command (or the equivalent menu entry of a graphical front-end) to create a copy of the file and edit the new file. This is needed to preserve the modification history; do not make the copy with a file manager or operating system commands.

Renaming or moving files/directories

The svn move command is the correct way to rename a file/directory or to move it from a directory to another one. Do not use a file manager or other operating system commands, as this will lose the history of the file.

Creating new directories

Use the svn mkdir command. Alternatively, you can create a directory with you favorite file manager and then use the svn add command (in this case any file in the directory may be added to the repository).

Commit changes

This is important. Every change you make is local until you perform a commit; from the command line, use svn ci. This transfers the local changes to the repository on the server (it works in one direction only: It doesn't fetch modifications from the server).

Update from the server

In order to receive the modifications made by others on the repository you have to issue an svn update command. This modifies only your local copy, and doesn't modify in any way what's on the server.

It's a good practice to make an update every time you begin to work on a file, so you get notified of any change that someone else has made.

View history and changes

You can examine the history of a file or directory with the svn log command. It shows who made any modification to the repository and when, and also which files were affected.

You can examine the differences between your local version of a file or directory and any older version, or between two old versions. Please refer to the help on the svn diff command for the details.

Retrieving or restoring old versions

You can access an old version of a file with svn cat command.

Command Line Crash Course

This is a short list of commands you can use to start using a Subversion repository immediately:

$ svn co https://svn.ws.dei.polimi.it/REPOSITORY

or for a subdirectory just

$ svn co https://svn.ws.dei.polimi.it/REPOSITORY/PATH

To add a new file or directory (directories are imported recursively) to the repository just execute

$ svn add <filename/dirname>

This code does not actually update the Subversion repository. In order to do this you need to check-in the change with

$ svn ci <filename/dirname>

you can use this command to check-in any change to your local files, not just to import new ones.

If you just want to check if something has changed locally or remotely, you can use

$ svn stat

while to update your local version with the latest changes in the repository you just need to update with

$ svn update

This command might generate conflicts you need to settle... but this is another story and you should read it the manual

This may always come handy:

$ svn help