Difference between revisions of "Legacy:Setting Up Subversion"

Revision as of 20:10, 29 December 2008

bocnoe This document is intended to walk you through a basic Subversion setup for use in developing Unreal-related projects. If you follow these instructions, in no time you will have a Subversion repository set up to track changes you make to all of your project-related files. If you will be working with other developers on the same project, you may also want to proceed to Setting up a Subversion Server after reading this page, to see how to make your new repository accessible to other people as well.

This document assumes you will be developing for an Unreal Tournament style of game such as UT2004 and that you will be setting up your repository under Windows XP/2000/2003/etc. Many of the directions here will also apply to other cases, but you may need to do some tweaking.

Download the Software

The first step is to download the tools you'll need:

Subversion

This can be obtained from the Subversion web site (http://subversion.tigris.org/). A Windows installer is available under http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91 (look for the latest EXE file).

TortoiseSVN

While not strictly necessary (Subversion can be used as-is from the command line) you may also want to download the TortoiseSVN graphical client for Subversion, which allows Subversion to integrate nicely with the Windows file manager. This program can be obtained from the TortoiseSVN web site (http://tortoisesvn.tigris.org).

The instructions here assume you will be using TortoiseSVN in addition to the basic Subversion package.

Install the Software

If you downloaded one of the Windows installer files for Subversion, installing it should be a simple matter of double-clicking the installer and following the prompts. Likewise, the TortoiseSVN installer is pretty much the same deal.

Note: You will need to reboot your computer after installing TortoiseSVN.

Create a Repository Directory

First, you will need to create a folder to be used to hold all of your Subversion repositories. For the purposes of this example, we'll place our repositories under C:\Subversion (you may want to place this on a drive with a fair amount of spare disk space).

Create a First Repository

Now you will want at least one repository to store things in (that is the point of Subversion, after all). You can create as many repositories as you want under the main repository directory, but for now we'll start with one:

1. Open the directory you created for repositories (C:\Subversion) in a Windows file browser window.
2. Create a new folder in this directory with the name you would like to give to your new repository (UT_work).
3. Once the new folder is created, right-click on it. The pop-up window which appears should contain a "TortoiseSVN" option. Under this menu item should be several choices, including "Create Repository here..."
4. Choose "TortoiseSVN->Create Repository here..." from the menu. This will bring up a dialog box asking what type of repository to create.
5. Choose "Native Filesystem (FSFS)" (you can really choose either one, but the Native Filesystem form is potentially faster, and in some cases easier to work with. Note: Do not use a Berkeley DB repository if it will be located on a network drive. Bad Things(tm) will happen.).

The new folder we just created is now a Subversion repository folder.

Next, we will create a "trunk" directory in our new repository (this isn't strictly required, but it is conventional to do things this way, and makes things a lot easier later when you get into sophisticated aspects of Subversion like branching). Subversion repositories aren't like normal directories, however, so we can't just create a directory using the file manager. Instead, we will need to use TortoiseSVN's "Repository Browser":

1. Right click on a file or folder anywhere in your system (doesn't matter where).
2. From the pop-up menu, select "TortoiseSVN->Repo-Browser".

A dialog box will pop up asking you for the URL of the repository to use. Type the following:

 file:///C:/Subversion/UT_work

(This is the URL of our new repository, which is how we'll need to refer to it with most Subversion commands. Note that it uses forward-slashes (/), not backslashes (\))

1. You should now see a "Repository Browser" window, with an expanded tree of folders (file:///C:, Subversion, and UT_work). Right click on the UT_work entry.
2. From the pop-up menu, select "Create Folder...", and when it asks for the name, type trunk
3. It will then ask you for a log message. This is where you describe why you're doing this for future reference. Since we're just doing initial setup here, put in something like "Intitial Setup" and click "OK".

If you now expand the UT_work entry, you should see a trunk folder underneath it. That's enough for a basic setup of our repository, time to move on to actually using it.

Alternately, you can use the Subversion command-line tools to create a new repository using the following commands: svnadmin create C:\Subversion\UT_work –fs-type fsfs svn mkdir file:///C:/Subversion/UT_work/trunk

(Don't create the UT_work directory first, the svnadmin create command will do it for you)

Set up Your Working Directory

At this stage in the process, most Subversion documentation tells you that you should use the Subversion "import" command to import a current snapshot of your project tree into the repository. For most projects, this makes sense, because each project has its own separate set of directories with only its files. For Unreal development, however, the situation is a bit different because the files being worked on are usually scattered around several directories which contain a bunch of other files. If we're working on a map, for example, we don't want to import our whole Maps directory into the repository, because that would include tons of stock files that really aren't part of the project we're working on (and don't need to be tracked), making the repository huge and difficult to work with.

For this reason, we're going to diverge a bit here from the normal procedure for setting up Subversion repositories. The first thing we will do instead is just associate our working directories with the (empty) repository we just created, by doing a "checkout".

1. Go into a file browser window and locate the main Unreal folder you'll be developing things under, which we want to be at the top level of our project (for example, C:\UT2004).
2. Right-click on this folder and from the pop-up menu, select "Checkout..."

The "Checkout" dialog box will ask for the URL of the repository to use. Type the following and press "OK":

 file:///C:/Subversion/UT_work/trunk

(this is the URL which refers to the "trunk" portion of the "UT_work" repository we set up in the previous step)

Once the checkout has completed, press F5 (refresh) in your file browser and you should see that the folder now shows up with a little green check-mark next to it. This indicates that the folder is associated with a Subversion repository, and that it is up to date (Note: sometimes the check mark doesn't show up in the tree view of the explorer).

The next step is to actually populate our repository with the files that are part of our project:

1. Again, right-click on the working directory folder (C:\UT2004)
2. You will see a new option in the pop-up menu named "Commit...". Choose this option.
3. An "Enter Log Message" dialog box will appear. This is where you write a brief description of what the change is that you're applying to the repository. Enter something like "Initial Import" in the text box at the top (If you've already been doing a lot of work on this project before setting up the repository, it would probably also be a good idea to write a few notes about what the current state of things is at the moment so if you go back some time later and want to know what the state of development was at this point, you can look at the Subversion comments for this revision and get some idea.)
4. In the bottom part of the "Enter Log Message" window, you will see a listing of all of the files under this directory (and all of its subdirectories), with checkboxes next to them (this display can take a while to display while TortoiseSVN goes through all the directories to see what's there, so be patient). This is where you specify what files you want to check in to Subversion. Find the files that are part of your project and check their checkboxes.
5. When you've selected all of the right files, press the "OK" button. TortoiseSVN will show a "SVN Commit" dialog box with the status of the operation. Once it's completed, press "OK".

Congratulations! Your project files are now in a Subversion repository!

Basics of Using Subversion

There are many documents available out there which are quite good at explaining how to use Subversion and TortoiseSVN (including the help files that come with both programs, which are available under your Start Programs menu), so we won't go into a lot of detail here, but here's the basic procedure of how things should work most of the time:

• Work on your files the same way you always do.
• Periodically, commit things back to the Subversion repository by right-clicking on your work directory and using the "Commit..." option.
• If other people are working on files in the same repository, you will periodically need to update your versions to match what other people have committed to the repository. To do this, right-click on the work directory and choose "Update".
• Note that if you rename files, Subversion won't automatically know what you've done, and will just see that the files aren't there under the name it expects, and will assume they've been deleted (and mark them as such in the repository). If you want to rename a file, make sure you do the following instead:
  1. Right-click on the file, and select the "TortoiseSVN" submenu.
  2. Choose the "Rename" option.

Setting up a Subversion Server

If all you want to do is keep backups and a change history for your own work, and you're the only one who's going to need to access your repository, then you can just stop here and use things as we've set them up so far.

If, however, you are going to want other people to be able to access the repository you've just created (and thus take advantage of some of the most powerful features of Subversion), you will want to proceed to Setting up a Subversion Server.