SVN instruction

General SVN information

This page introduces the concepts underlying an SVN system. Even though it might seem more attractive to use a USB stick or a dropbox instead, we highly recommand 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.

Each time you have made some useful changes to one or multiple files on your hard disk you can commit your changes to the SVN server. Committing changes means ‘I want my current local version to be the latest version on the SVN server on the faculty server’. The SVN managing system will associated a unique number with your changes and stores the changes. Since the unique revision numbers might not be very informative each commit can be associated with a text message. This so-called commit message should be used to explain the changes you have made. ‘Added a function that filters the laser range data using a moving average filter’ is a useful commit message, whereas ‘today’s work’ is a very poor one. If another team member wants to get the latest changes you made to some files, he or she can simply update the versions currently on his computer. Note the difference in terminology: the first time you ‘download’ files from the SVN this is called a check out whereas getting the latest changes on files you have checked out before is an update.

Getting started

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

Your first (and second) checkout

The first thing you need to do is to check out all there currently is at your team’s SVN. After a checkout, the files will be placed in the current folder by default. Therefore, it is important to first navigate to the desired folder. First open a new terminal. Then create a directory in which you would like to check out the SVN by typing:

mkdir -p ~/ros/emc

Now there is a folder named ros in your home folder. Within this folder, there now exists a folder named emc. The next step is to enter this folder in your terminal:

cd ~/ros/emc

The folder in which you are is shown in the beginning of the line in your terminal. Now it is time to check out everything there is on the SVN into the newly created folder. For group one this means:

svn co https://roboticssrv.wtb.tue.nl/svn/emc/2014/groups/emc01

You will be asked to provide a user name and a password. This is to avoid other groups from checking out or modifying files on your SVN. 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’. After this command a new folder appeared in your folder. Apart from the team SVN you will also need the general software accessible for all groups. This contains for example the simulator. To keep your hard disk organized, you should make sure you are in the right folder:

cd ~/ros/emc

Now, we can check out the general software by typing:

svn co https://roboticssrv.wtb.tue.nl/svn/emc/2013/general

Keeping your files up-to-date

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. If you make changes to an old version of a file on the SVN you might introduce conflicts. In that case the SVN does not know which of the conflicting changes to take.

Adding files to the SVN

If you have created a file, for example a piece of code, you can add it to the SVN version control system by typing:

svn add file_I_want_to_add.cpp

Sometimes you create many files and adding them one by one is annoying. In that case you can add a folder together with all files in this folder by typing:

svn add folder_I_want_to_add

All files in the folder are added to the version control system. When adding folders, be careful not to add files that do not belong on the svn server (e.g. bin or build files), see also `Bringing it into practice' at the bottom of this page.

With the ‘svn add’ commit you informed the SVN program on your computer that you would like to add some files and/or folders to the version control system. If you create a new file in a folder which is under SVN control, this new file will not be under version control unless you add the file using the command given above.

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

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

Undo changes you made

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 many information is available on the internet.

Bringing it into practice

Now it is time to bring all this into practice. Let’s create a ROS package. Navigate to your team’s folder using the ‘cd’ command and create a package the way you learned it during the ROS tutorials:

roscreate-pkg my_first_pkg roscpp

Now immediately add all files belonging to this package to the SVN (before typing make or rosmake) using the command:

svn add my_first_pkg

This command adds the folder and all files within this folder. You can use ‘svn st –q’ to see all files are actually added.

From now on, you must remember to only add files you create yourself. This means: launch files (.launch), sources files (.cpp or .h), ROS message files (.msg)or ROS service files (.srv). During the compilation of your code a number of files is created, for example in the bin and build folders of your package. It is important to not add these to the SVN since this causes conflicts whenever you or anyone else tries to compile your code on a different computer.