Subversion

Note: This reference is still being updated. If you would like to see something explained here, let us know

What is SVN?

Subversion (SVN) is a versioning system that we use to manage Colony project code. It works by storing the code repositories on a central server and allowing users to download local working copies of the repository, wherever SVN is used. Handy features include: modification tracking, branch/merge, update/commit, revert to revision, and lots more.

Getting SVN

Repository Access

Use your roboticsclub.org account to access the repository. To gain write access you must be added to the Colony group.

roboticsclub.org Accounts

Ask an officer to get an account

Being Added to the Colony Group

You need to log in as rc99 (only officers can do this) and use chgrp and add colony as one of your groups or launch users-admin and add the user to the Colony group.

Checking Out

Windows (TortoiseSVN)

  • Create the directory where you want you the repository to be downloaded to (usually your Andrew ID)
  • Right-click that directory and use SVN Checkout
  • Type svn+ssh://<user_name>@roboticsclub.org in the top field replacing user_name with your Andrew ID and repository_url with the repository you want to check out (see URLs above)

Linux / Mac

  • Create the directory where you want you the repository to be downloaded to (usually your Andrew ID)
  • cd into that directory
  • Run 'svn co svn+ssh://<user_name>@roboticsclub.org/home/svn/colony' to download the entire repository, including all branches. Run 'svn co svn+ssh://<user_name>@roboticsclub.org/home/svn/colony/trunk' to just download the trunk.

Getting Permissions to Access the Old Repository

Step by step procedure for gaining Read and Write rights to a Roboclub SVN.

  1. SSH into unix.andrew.cmu.edu
  2. %mkdir .ssh (This folder should already be there, but do this just in case it isn't)
  3. %nano .ssh/rc
  4. type: aklog club.cc.cmu.edu
  5. hit: ctrl-x, y, enter
  6. %pts createuser <your_andrew_id>@andrew.cmu.edu -cell club.cc.cmu.edu #
    1. If you get "user already exists" or "user added" or no output, you have succeeded. Go to step 9.
    2. If you get "cell does not exist" or "unable to contact cell" or some error like that, go to step 8.
  7. Tell a roboclub officer that pts is broken and that cclub needs to be fixed. Then wait patiently until it is.
  8. Tell your project leader (or whoever is managing the SVN for your project) that you are ready to be added to the group.

Using the Repository

Once you have checked out the repository, you will want to update it to get the changes of others and commit your own changes.
Here are some useful commands for Linux / Mac. There are equivalent ways to perform these operations in TortoiseSVN.

  • svn update : Update the repository to reflect the changes others have made. Use -r to update to a specific revision.
  • svn commit --message "What I changed." : Commit your changes to the repository so others can see them. Make sure that you leave a message. This will be viewable in the log and on track so that everyone can known what you changed. The message should only be a sentence or two. Note that this will only commit the current directory and its contents, not the entire repository.
  • svn add filename : Add a file to the repository. This only needs to be done for new files or directories. The changes will not take affect until you run 'svn commit'.
  • svn delete filename : Delete a file from the repository.
  • svn revert filename : Revert a file to the version that was checked out.
  • svn mv oldname newname : Move a file within the repository. This should be used instead of moving the file manually and adding / deleting since it will preserve the history of the file.
  • svn status : Useful before committing. This shows the files which will be modified, added and deleted in a commit.
  • svn diff filename : See how a file differs from its version in the repository. Use -r revision_number to compare to a specific revision, or -r R1:R2 to compare two revisions.
  • svn log : View the log of messages people wrote when committing. This is useful if you want to see what's been changed.
  • svn help : The most useful svn command.

Branching

Note: If you are new, don't use branching until it has been fully explained to you.

Creating Branches

Windows
  1. Go to the top level folder you wish to branch from (ex. /trunk)
  2. Right-click -> SVN -> Branch
  3. In the To: field, enter the afs path for where you want your branch to be stored (ex. /branches/<branch_name>
  4. Choose which version you want to branch from (ex. TOP Revision of the trunk)
  5. Branch!
Linux / Mac

Merging Branches

Note: This assumes you want to merge from a branch to the trunk. However, you can merge from any branch to any other branch. It gets complicated though, so don't branch like crazy.

Windows
  1. Go to the top level folder you wish to merge back into (ex. /trunk/projects)
  2. Right-click -> SVN -> Merge
  3. Use "Merge a range of revisions"
  4. In the From: field, enter the svn+ssh path for that same folder (ex. /trunk/projects)
  5. Choose the range of revisions from which you originally branched from to the range you wish to merge to (ex. revision 66-HEAD)
    • Use the SVN -> Show Logs on the branch if you can't remember
  6. Make sure the working copy path matches (ex. /trunk/projects)
  7. Do a dry run to verify that the correct files will be modified/added/deleted
  8. Merge!
  9. Go to the top level folder that you merged into (ex. /trunk/projects)
  10. Commit your changes
    • Begin your change log with "MERGED"
Linux / Mac

Modifying and Recompiling the Library

Follow these instructions if you need to modify and recompile libdragonfly or libwireless.
Note that the makefile should recompile the library for you automatically, or you can run "make library" to force it to.

Linux / Mac

  1. Navigate to code/projects/libdragonfly or code/projects/libwireless/lib (NOT in the lib directory).
  2. Make your changes. Be sure to add javadoc style comments if you add or change any methods.
  3. Run make to build the library.
  4. Test the modified library. Make sure your changes do what you think they should, and that they won't screw up existing code.
  5. Commit the files you edited.
  6. Run "make dist" to copy the library into the lib directory, where other people can use it.
  7. If you added any new files to the library, use "svn add" in the lib directory to add them. You will need to do this for both the source and header files.
  8. Commit the lib directory.
  9. If you modified the documentation, run "make docs" in the directory with the source code you modified. svn add any new files in the docs folders, and commit the docs folder.

More Information

SVN Presentation

setup.pl Magnifier - Download Colony Script (266 Bytes) Joseph Lee, 03/12/2011 10:00 pm