Using Subversion with TortoiseSVN
by Matt Holmes (Calefaction)
Subversion; SVN: Link
- "A version control system that is a compelling replacement for CVS in the open source community."
- It records the history and manages changes to a repository of files by multiple users.
- The programmers have been using a similar system called CVS for some time to manage our source code, and with SVN we've now rolled this out to include all game binaries/assets too.
- It takes care of ensuring that we don't overwrite each other's files when we commit files to it, and checks what you've already downloaded against what's in the repository so that it'll only download things that have changed since your last update.
- "A free/open-source client for the Subversion version control system."
- An easy-to-use tool that integrates with Windows Explorer. It is used to access the Subversion repository.
- Files are stored in a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your files and examine the history of how and when your data changed.
Section 1: Creating Your Account
For WFG team members: Request an account from Erik Johansson (Feneur) or Philip Taylor (Ykkrosh). You will be given a User Name (typically your first name) and password. This will be used as your personal login to access the SVN repositories.
Note: Non-team members don't need an account to checkout the code, we've enabled read-only anonymous access. Team members need it to be able to commit, we cannot enable anonymous committing for obvious reasons.
Section 2: Getting and Installing TortoiseSVN
You can obtain TortoiseSVN from here. Select the latest version available for your operating system. Follow the standard installation procedure and reboot when asked.
Section 3: Making your first Checkout
Now we need to point you to the correct SVN URL and checkout the current SVN source tree onto your harddrive. The current SVN trunk URL is:
Anonymous read-only access to non WFG members is at this URL: http://svn.wildfiregames.com/public/ps/trunk
Non-anonymous (i.e. requiring user account) access for WFG members with commit access is at this URL: http://svn.wildfiregames.com/svn/ps/trunk
I also suggest creating a unique directory. I use the directory
C:\0ad, but feel free to use whatever directory you see fit.
The directory you check the game out to should ideally have no spaces in its path. For example, C:\My Documents\0AD may cause problems.
Next, follow these steps to checkout the SVN tree.
1 In Windows Explorer, navigate to the directory where you want to check the SVN tree out to.
2 Right click to bring up the context menu. Select 'Checkout...' in the SVN section of the menu:
3 In the 'Url of repository' field enter the URL above. Leave all other fields at their defaults:
4 After pressing OK, a dialog refering to caching the SVN server's host key could come up. Accept that key if it does.
You should then be prompted for your account login. Enter the username and password you have requested. In some cases you may be asked for your password twice.
Once your password has been succesfully entered, you should see the repository beginning to download:
Note: This will take a while. That's perfectly normal. You're checking out over a hundred megabytes of stuff. Leave it to get on with it, and go do something else for a while.
Checkout puts a lot of strain on the server. If it times out, try checking out sub-sections of the repository at a time, or try again later when less members are downloading.
Section 4: Updating your files
A key component to any version control system is the ability to update your files to the latest versions available in the repository. Much like the rest of your everyday SVN operations, TortoiseSVN makes this extremely easy. The following steps will detail how this is done:
1 Select the file, files or directories that you want to update (NOTE: I suggest updating entire modules of the project at a time. For instance, update the entire 'source' or 'binaries' module, or both. This will keep your entire source base in sync with the Subversion tree. If you have a reason to only update a subset of the projects objects, then you may do that as well)
2 Right click to bring up the context menu. In the SVN section of the menu, select 'Update...':
3 You should immediately see a status dialog detailing what SVN is updating:
The next two sections describe how to add to or change the repository contents, and are only available to accounts with write access (artists and programmers).
Section 5: Making your first commit
Once you have made some changes and are ready to check them in, you will need to commit them. You can commit an entire directory (and all of its sub-directories), a group of files, or a single file. Use the following steps to commit files to Subversion:
1 Select the file, files or directories that you want to commit.
2 Right click to bring up the context menu. Select 'Commit...' in the SVN area of the menu:
4 Press 'OK'. The commit should begin and you should see the following status dialog:
Section 6: Adding files to the repository
Before you can commit a new file to the repository, you must first add it. Adding files to the repository is much like committing them, just use the following steps:
1 Select the file, files or directories that you want to add.
2 Right click to bring up the context menu. Under the 'TortoiseSVN' sub-menu, select the 'Add...' option:
3 Confirm which files you want to add to the repository:
4 Press 'OK'. You will see a status dialog detailing what was added to the SVN repository:
NOTE: To finalise the addition of files to the SVN repository you must Commit the files you added! Follow the section on Committing files above to see how that is done.
- You can update your SVN password from http://svn.wildfiregames.com/admin/svnadmin.php
- See BuildInstructions for how to compile the code from SVN.
- A log (showing all recent activity) and source browser is available via Trac, at http://trac.wildfiregames.com/
A useful setting
As you might have noticed (or in case you haven't checked out yet: will) the Thumbs.db files can cause some trouble when updating. They're Windows system files (hidden by default) that are different from computer to computer and thus causes trouble if people commit them. There is a way to make Tortoise SVN ignore these files, but everyone has to edit the settings (more on that below) or just avoid committing these files of course, but as it's easy to do it by mistake here's some info on how to edit the settings.
http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-settings.html#tsvn-dug-settings-main <-- there you can read about the general settings dialog. You can get to the General settings by right-clicking on a file/folder that's downloaded from SVN and there, in the Tortoise SVN submenu, left-click on Settings) The one we're interested in now is "Global ignore pattern", in that box please enter "Thumbs.db" (without the quotation marks, but with the capital T) and click confirm.