Embedded Motion Control/Tutorials/Using Subversion to share and manage your project

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.

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

SVN checkout: downloading from the SVN

As you may recall, you already used SVN to check-out the directory that will be share between you and your teammates. Remember typing these lines:

cd ~/emc
svn co https://roboticssrv.wtb.tue.nl/svn/emc/2015/groups/emc01  # (or another group number, we will use 01 from now on as example)

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/2015/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 ~/emc/emc01
ls -a

Results in something like:

. 
..
.svn

Notice the .svn folder. This is where all SVN meta-data is stored. The folder itself is called the working copy in which you will contribute code to your group project. That is, you will do all your work in ~/emc/emc<YOUR_GROUP_NR>, and if you use SVN correctly, your work is always safely stored on the SVN-server and accessible by all your group members.

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.

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>
svn add beginner_tutorials_sjoerd

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_<YOUR_NAME>

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

svn add my_dummy_file_<YOUR_NAME>

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:

Example (don't do it yet):

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:

Example (don't do it yet):

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

Now, let's put it to practice. Navigate to your group folder:

cd ~/ros/emc/emc<YOUR_GROUP_NR>

and commit your files:

svn ci -m 'Added my tutorial ROS package'

You will see something like this:

Adding         emc01/beginner_tutorials_sjoerd
Adding         emc01/beginner_tutorials_sjoerd/CMakeLists.txt
Adding         emc01/beginner_tutorials_sjoerd/Makefile
Adding         emc01/beginner_tutorials_sjoerd/include
Adding         emc01/beginner_tutorials_sjoerd/include/beginner_tutorials_sjoerd
Adding         emc01/beginner_tutorials_sjoerd/mainpage.dox
Adding         emc01/beginner_tutorials_sjoerd/manifest.xml
Adding         emc01/beginner_tutorials_sjoerd/src
Adding         emc01/my_dummy_file
Transmitting file data .....
Committed revision 1104.

If you are not able to add the files due to asking for a GNOME keyring:

Password for '(null)' GNOME keyring:

First use the command below, follewed by the svn ci -m...

rm ~/.gnome2/keyrings/login.keyring

The files are now added to the SVN and stored on the server. The files will appear on a group members computer if he does an svn up.

Removing files from the SVN

It can always happen that you want files to be removed from the SVN. For example, the dummy file created above is not very useful. Remove it as follows:

svn rm my_dummy_file

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 my_dummy_file --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 dummy file; it was not very useful after all'

If you remove a file using the normal way, for example by using rm in the terminal, or by clicking it and deleting it in Nautilus, 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 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 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 an 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.