Sourceforge and TortoiseSVN Tutorial
If you’ve ever come across an OpenSource or OpenHardware project then you have probably heard of Sourcforge. I have to admit that I have know about Sorceforge and (Sub)version Control for years but I could never figure out why someone would want to use something so complex. I finally figured it out…it’s because Sourceforge and Version control is not at all complex. In fact it is actually very cool. In order to use Sourceforge you’ll need a subversion (SVN) client. TortoiseSVN is the self proclaimed “coolest interface to (sub)version control”. This tutorial will get you up and running quickly with an existing Sourceforge project. You will be able to Checkout entire projects and have an exact copy on your local PC for editing and you will also learn how to Add files and Commit changed files
Overview of TortoiseSVN
TortoiseSVN is a shell application. That means it’s an application that it interacts with the operating system. In this case it interacts with the file system. This will become visible in just a few moments. The other thing to know about TortoiseSVN is that you won’t find an icon in your start menu to run some elaborate GUI (Graphical User Interface). Instead, you will notice a new menu whenever you Right-Click on your Desktop, a File Folder, or a File. The Windows file system esentially becomes your GUI for working with Files.
The subversion process works by creating a local copy of the existing files. You will be able to distinguish these files from others because they will have additonal icons overlayed on top of your files and folders to show you the status. Once you are finished editing existing files and adding new files you then commit the changes to the remote file server (i.e. Sourceforge.)
About Those Icons:
A fresh checked out working copy has a green checkmark as overlay. That means the Subversion status is Normal.
As soon as you start editing a file, the status changes to Modified and the icon overlay then changes to a red exclamation mark. That way you can easily see which files were changed since you last updated your working copy and need to be committed.
If during an update a conflict occurs then the icon changes to a yellow exclamation mark.
If you have set the
property on a file, Subversion makes that file ReadOnly until you get a lock on that file. Read-only files have this overlay to indicate that you have to get a lock first before you can edit that file.
If you hold a lock on a file, and the Subversion status is normal, this icon overlay reminds you that you should release the lock if you are not using it to allow others to commit their changes to the file.
This icon shows you that some files or folders inside the current folder have been scheduled to be deleted from version control or a file under version control is missing in a folder.
The plus sign tells you that a file or folder has been scheduled to be added to version control.
Download the latest TortoiseSVN installer from http://tortoisesvn.net/downloads. It will have the .msi (Microsoft Installer) file extention. The TortoiseSVN installer is very straight forward. Just follow the instructions.
Working with Sourceforge
Setting up a Sourceforge account is beyond the scope of this tutorial. We will be looking at this from a supporters or end users perspective. In order to make changes to a projects repository you will need permission from the projects administrator. Sign up for an account and notify the administrator providing them your username.
You will need the URL to the projects repository. This can be found by browsing to the projects homepage and clicking the Develop link on the top menu. Under the subversion access section you will find a URL that looks similar to this: https://hhscnc.svn.sourceforge.net/svnroot/hhscnc.
Putting it all Together
Now that you have installed TortoiseSVN and you found the URL to the repository you want to work with you’ll need to create a local copy of that repository on your machine.
1. First, right click on your desktop or in a windows file explorer window where you want the folder to be created. Then click the SVN Checkout button.
2. Enter the URL obtained earlier from the projects sourceforge page. Then enter the file path where you would like the folder to be created. We used “New Folder” as our example folder. Then click OK.
3. If you have not already created the folder you will be asked if you would like TortoiseSVN to automatically create it.
4. Watch as TortoiseSVN downloads the files from the remote server and saves them as a local copy in the folder you named above. Then press OK.
5. You should now have a new folder on your desktop. You may or may not see the icon overlays on the root folder. If you don’t see an icon like ours don’t worry it’s still working properly and should show up after you work with the local copies and make a few changes to the files and folders.
Now that you have a local copy of the repository you can start making changes to those files. Don’t worry about messing anything up because the changes do not show up in the remote repository unless you commit them and even if you do mess something up the administrator of the project can revert back to a previous copy of the file. You should try to be careful when commiting changes because reverting (rolling back) to a previous version of a file is not always easy.
Here is an example of what your folder structures may look like locally. Note the icons as mentioned earlier. In our case all of our folders and files are unchanged. Under settings you can have TortoiseSVN check for updates automatically. This is setup by default as to check weekly but you may change it.
Working with Folders and Files
Adding, Deleting, Renaming and Commiting changes to the files and folders is very simple. Just work with the folder as if it were any other folder on your file system. After all it actually is just like every other folder. When you create a new file or folder you need to right click on that file or folder and select Add from the TortoiseSVN menu. This does not actually commit the file to the repository. You will need to right click on the folder and select SVN Commit… from the menu to commit added, renamed, deleted or changed files.
One last thing to note is that there is a Delete option under the TortoiseSVN menu. Insteady of simply pressing Delete when working with your files and folders you may want to use this menu item as it will also delete the remote copy of the file the next time you commit the changes.
This tutorial is meant to get you up and running quickly. TortoiseSVN is well documented and you should read about any features not discussed here before using those features. Especially if you don’t own the project you are working on.