# General SVN information

During this course, you will work with a team on one software project. It is therefore essential to be able to share your work (i.e., programming code) with your team members in an efficient way. This page introduces the concepts underlying an SVN system with which you can do exactly that. Even though it might seem more attractive to use a USB stick or Dropbox instead, we highly recommend you to use the SVN. Once you get used to the SVN, you will for sure see the advantages.

## Background

Apache subversion, abbreviated SVN, is a tool for software versioning. With an SVN each unique state of your software can be associated with a unique revision number. At any point in time you can go back to any previous revision using the unique number. This is particularly useful after making some changes that did decrease the performance of the code. In addition, an SVN is very useful when working on a software project with a group of people.

During the Embedded Motion Control course all team members get access to the team’s SVN. In order to make your SVN experience a pleasant one it is important to keep some simple rules in mind.

## How does it work?

At any time you can add any file to the subversion control. Once you have added a file a copy of this file is stored on the SVN server which is location on the faculty server and other team members can download this file. Downloading files or folders from the SVN server is referred to as checking out. After checking out files, a copy of the files on the SVN server is available on your local hard disk.

# Getting started with SVN

In order to keep your SVN properly working it is very important to know how to work with it. This section explains how to use an SVN. Keep these rules in mind and use the commands given below since doing things wrong might lead to strange behaviors and typically costs a lot of time!

## An important lesson

In order to do the SVN related administration, SVN uses hidden files and folders on your local disk. If you would like to make any changes to file locations or names you need to inform the SVN! This means you should NEVER copy, move, rename or delete files the way you usually do this. If you want to do this, use the commands given below! As a rule of thumb, do not perform any of these operations without using a command that starts with ‘svn’.

As you may recall, you already used SVN to check-out the files needed the run the PICO simulator in this tutorial. Remember typing these lines:

cd ~/ros/emc
svn co https://roboticssrv.wtb.tue.nl/svn/emc/2014/general


Let’s zoom in on the command. Every svn command starts with ‘svn’. The second part ‘co’ is an abbreviation for checkout, in fact, the command also works if you type ‘checkout’ instead of ‘co’! The third part of the command is the location of the SVN. This command therefore means:

download the files which are located on the SVN with location https://roboticssrv.wtb.tue.nl/svn/emc/2014/groups/emc01 and store them in the current folder.

But svn co does more: it creates a hidden folder that is used by SVN to know the current status of the files on your computer: their revision number, their latest changes, etc. You can show hidden files and directories in a terminal with ls by using the -a option:

cd ~/ros/emc/general
ls -a


Results in something like:

.            gazebo_map_spawner  pico_gazebo         tue_gazebo_plugins
..           pico_description    pico_visualization
demo_opencv  pico_example        .svn


Notice the .svn folder. This is where all SVN metadata is stored. Your local copy of the software that was checked out from the SVN is called the working copy.

Remember you also checked out your group folder. This is the working copy in which you will contribute code to your group project. That is, you will do all your work in ~/ros/emc/emc<YOUR_GROUP_NR>, and if you use SVN correctly, your work is always safe and accessible by all your group members.

Before you start working on files which are also on the SVN you must make sure you have the latest changes available. You get the latest versions of the software by updating the files to the latest version:

svn up


The up is short for update. If you’d like, you could also type update instead.

It is very important that before you make changes to your files, you update to the latest version. Otherwise you make changes to an old version of a file which may introduce a conflict. In that case the SVN does not know which of the conflicting changes to take.

## Adding files to the SVN

Remember the ROS package we created in the previous tutorial? It was created in your group folder, which is under version control as explained above. You may think that because the ROS package was created in this working copy, the package is automatically added to the SVN (e.g. this would happen with Dropbox), but this is not the case! You have to tell SVN to start keeping track' of your files. This can be done using the svn add command:

cd ~/ros/emc/emc<YOUR_GROUP_NR>


You will see something like this:

A         beginner_tutorials_sjoerd
A         beginner_tutorials_sjoerd/manifest.xml
A         beginner_tutorials_sjoerd/CMakeLists.txt
A         beginner_tutorials_sjoerd/Makefile
A         beginner_tutorials_sjoerd/src
A         beginner_tutorials_sjoerd/include
A         beginner_tutorials_sjoerd/include/beginner_tutorials_sjoerd
A         beginner_tutorials_sjoerd/mainpage.dox


The A stands for Added'. Notice that the whole directory, including all files and subdirectories, is added. It is nice that SVN recursively adds files, but you also have to be careful: not all files belong on the SVN! For example, you don't want to share files that are specific to your system, e.g. directories such as the build and bin folders that are auto-generated when compiling your package. So in general: do not add files that do not belong on the svn server!

The svn add command can be used on directories, but also on separate files. For example, let's create a dummy file:

gedit my_dummy_file

Put some text in it and save the file. Now, from the terminal, add the file to the svn:

svn add my_dummy_file

## Sending your changes to the SVN server

If you have added files or made changes to files which are under SVN control already the next step is to send the changes to the online SVN server. Sending files to the server is called a ‘commit’. Changes you have made or files you have added locally on your machine are not send to the SVN server until you do a commit. You need your user name and password for this.

Doing a commit can be done using this command:

svn ci –m ‘a short description of the changes I have made’


As all SVN commands, the command starts with svn. The second part is ‘ci’ which is short for commit. You could also replace the ‘ci’ by ‘commit’ if you like. The third part of the command is ‘-m’ this means: ‘I would like to add a message which describes the changes I have made’. The last part of the command is the message describing the changes you have made. The message is optional, but as explained before, it is highly recommended to add useful messages for reasons given before.

If you do a commit all changes in the current folder will be committed recursively. This means changes in the current folder as well as changes in all folders within the current folder are sent to the SVN. If you want to commit a single file, you can use the following command:

svn ci file_I_want_to_commit.cpp –m ‘a short description of the changes I have made’


It is useful to do commits on a regular basis, for example, every time you made some useful changes (say every hour or so, not every minute).

## Removing files from the SVN

It can always happen that you want files to be removed from the SVN. This can be done by typing:

svn rm file_I_want_to_commit.cpp


After doing this the file will also be removed from your hard disk! If you like you can also type ‘svn remove’ instead of ‘svn rm’ in the command above. If you want to keep a local copy of the file then you need an additional option. When using the option, the file is no longer under version control but it is still on your local hard disk:

svn rm file_I_want_to_commit.cpp --keep-local


Again, the changes are only made locally on your hard disk. After this, you again need a commit to inform the online SVN server about your plan to remove a file from the SVN control:

svn ci –m ‘removed the file ... because ...’


If you remove a file using the normal way, for example by clicking it and selecting delete, it will not be removed from the SVN, hence the file will reappear the next time you update using ‘svn up’.

## Inspecting the current status

You can always print the current status of the files on your disk by typing:

svn st -q


where ‘st’ stands for status. You can type ‘svn status’ instead of ‘svn st’ if you like. The optional ‘-q’ makes sure only the status of files which are under SVN control is shown.

Files might appear with a capital in front of the name:

• M this files is modified: you have made changes to the file on your local hard disk and as a result the file no longer corresponds to the file on the SVN server. After a commit, the local changes are sent to the SVN server and the M will disappear.
• A this file is added: the file is added to the version control system on your disk, but the file is not yet on the SVN server. After a commit, the file will be on the SVN server and the A disappears.
• D this file is deleted: the file is removed from the version control system locally but not yet on the SVN server. After a commit the file will be removed from the SVN server as well.
• C this file is in conflict: this means you did not update the your local file before modifying it. As a result you modified an old version of the file (the file on the SVN server is newer than the file you started editing). If you want to solve this issue you can revert your changes if they are not important (see the section on ‘going back to an older version’). If your changes are important you need to merge your file with the file on the SVN (svn merge) or overwrite the changes on the SVN server (svn resolve). Please use google for more information and basic examples.

A second useful SVN comment related to inspecting the status of a file is:

svn log


This prints the all commit messages associated with the files in the current folder together with the revision numbers (the unique number indicating the unique versions of the files). The log message can be very long, therefore it is often better to only show the last couple of entries:

svn log –l number_of_messages_you_would_like_to_see


If you have one or multiple files with local changes you can view the differences with the version on the SVN using the diff command:

svn diff the_file_which_changed.cpp


or if you want to see all changes in all files in the current folder:

svn diff


## Going back to an older version

Going to an older version on the SVN can be done with a single command if you know the revision number. The revision number can be obtained by inspected the svn log as explained above. Then type:

svn up –r number_of_the_revision_you_want_to_get


Everyone makes mistakes. If you made some changes to a file which appeared to be useless for some reason you can easily undo them (this will delete all your changes permanently):

svn rv file_in_which_the_unwanted_changes_are.cpp


Undoing changes is called reverting. For that reason, you can replace ‘rv’ by revert in the command above. After doing a svn revert, the version which is on the SVN server overwrites the local changes on your hard disk. After reverting a file you do not have to do a commit since you did not make any changes that must be saved on the SVN server.

## Copying or moving files

As stated before it is important to never copy files using ctrl+c or right click -> copy and never move files using drag & drop! If you want move a file you must use the SVN tools:

svn mv old_folder/some_file_old_name.cpp new_folder/some_file_new_name.cpp


You can use ‘svn move’ instead of ‘svn mv’ in the command above if you like. You can also use this command to rename a file. If you want to make a copy, you can use:

svn mv old_folder/some_file_old_name.cpp new_folder/some_file_new_name.cpp
`

Once again you will need a commit to send the changes to the SVN server a make them available to the other group members.

## Cheat sheets

Many cheat sheets summarizing all possible SVN commands are available online. One example can be found at [[1]]. An SVN is a very popular tool hence a lot of information is available on the internet.

Now you know how to use the SVN and we have added our ROS package to it, let's see if we can compile our package.