TortoiseSVN mini-guide for MechEng students

The Basics

Subversion is a revision control tool that is used to manage simultaneous modification of a set of project files. The basic idea is that changes are managed in a central repository that all people can access, from which each person can get a copy of the most recent files (SVN Checkout), update their local copy of the files to the latest (SVN Update), and send their changes back to the repository (SVN Commit).

TortoiseSVN is a graphical interface to the Subversion tool.

Starting Out

The first thing we need to do is to create a repository. To do this:

• Create a folder in a shared location (eg. in a shared folder on a network drive) for your subversion repository. In CATS you may have a folder in "w:\Projects", and in the MechEng labs you may have a folder in "m:\finalyear" (for the latter, if you want one for your project, please contact us). Call it "repos".
• Right click on it, select "TortoiseSVN" / "Create repository here".
• Ensure "Native Filesystem (FSFS)" is selected. EXTREMELY IMPORTANT: Do NOT select "Berkeley database (BDB)", it doesn't work properly on network drives. It will fail later.
• Click "Ok", then "Ok".

You have now created your repository. You should leave this folder completely alone at this point, as changing the files within can break the repository. Now:

• Create a new folder somewhere else (on your desktop is fine). Call it "import".
• Inside this folder, create another folder with a suitable project name. I'll assume that you call this "project" for now.
• Inside the "project" folder, put all of the files you would like controlled by subversion. You should discuss this with your group and decide which files should and shouldn't go in there.
• When you are done, return to the "import" folder. Right click on it, select "TortoiseSVN" / "Import".
• Click the "..." on the right of "URL of repository".
• Browse to the "repos" folder you made earlier and select "Ok". The URL should now look something like: "file:///your/path/here/repos".
• Click "Ok".
• Wait, then click on "Ok".
• You should now check to see if the import worked correctly. To do this:
  • Locate the "repos" folder, right click on it
  • Select "TortoiseSVN" / "Repo-browser".
  • Browse through the repository by either clicking the "+" button or double-clicking folders.
  • Open a file to view it by right clicking on it and choosing "Open" or "Open with...". This will grab a copy of the file from the repository and open it for you.
    
• If the repository looks right, then continue. If it doesn't, remove the repository and retry these instructions.
  
• Close the repository browser.

Now that you are done, move the "import" directory somewhere safe. You won't be using it any more, but it's worth keeping a backup of it, just in case.

Check out a copy

Eventually, each group member will need to check out a copy from the repository. To do this:

• Create a working folder that you will be working in. You can actually choose any name you like, but I'll assume that you use "work" for now. It is recommended that you create it on your desktop to start with. In the future you might like to store it on a USB stick instead, to allow you to work at home.
  
• Right click on it ("work"), and select "SVN Checkout".
• Ensure the repository name is correct. If it is blank or you are not sure, browse to the repository ("repos") using the "..." button on the right. The repository should be of the form: "file:///your/path/here/repos". If "project" appears after the repository name, either remove it or browse to "repos" instead.
  
• Ensure the checkout directory is correct. The default is generally set to the "work" folder you clicked, and is usually fine.
  
• Click on "Ok".
• The files will now be checked out. Wait, then click on "Ok".

You can now work on the files. Simply go into your "work" folder, then into "project" (or whatever you called it when setting it up). All of the files you originally imported should be there. Notice that as you make changes, the icon on each file should change from a little green tick to a red exclamation mark. If you have created your "work" folder on a network drive or on your desktop in CATS, you will not see these icons.

Commit your changes

To send your changes back to the repository where they can be used by other group members, you need to commit your changes. To do this:

• Right click on your "work" folder, and select  "SVN Commit...".
• Enter a comment describing your changes, so you and your other group members know why you changed the files. You can look below to see the changes you are about to commit.
  
• When you're ready, hit "Ok".
• Assuming there are no problems, you'll be told the process is complete, after which you should hit "Ok".

If there are any problems, you may need to do an update first - refer to the next section.

You can also commit individual files instead if you wish- simply right click the file and select "SVN Commit..." to do so.

Update your copy

If another group member has changed any files, you will have to perform an update to get those changes from the repository. To do this:

• Right click on your "work" folder, and select "SVN Update".

Subversion will then attempt to merge in the latest changes from the repository into your "work" folder. Sometimes it can do this automatically, and sometimes there are problems.

If there are problems, for example, if more than one of you have made changes to the same file, you may have to manually resolve the conflict. Refer to the TortoiseSVN and Subversion documentation for more information.

Adding new files

To add a new file:

• Inside your "work" folder, place the new file in the appropriate place.
  
• Right click the file, and select "TortoiseSVN" / "Add...".
• Click "Ok", wait, then click "Ok".
• You may notice a blue "+" on the file if icons are working (not on a network drive or in CATS). This indicates that TortoiseSVN (and Subversion) now knows that the file needs to be added to your project.

To send the new file to the repository so that other group members can check it out, you need to commit your changes. This is detailed previously.

Further resources

This is a fairly basic document designed to get you started quickly. Subversion is a powerful tool and there is much to learn about it. For further information, you should refer to these resources:

• The TortoiseSVN help pages. You can view the help pages from the Start Menu at: "Programs" / "TortoiseSVN" / "Help".
• The TortoiseSVN web pages here.
• The Subversion web pages here.
  

If you get stuck, you can always give us a try here: