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

From Control Systems Technology Group
Jump to navigation Jump to search

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

Your first (and second) checkout

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.

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

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

Retrieved from "https://dsdwiki.wtb.tue.nl/index.php?title=Embedded_Motion_Control/Tutorials/Using_Subversion_to_share_and_manage_your_project&oldid=8436"