Subversion Guide
Disclaimer[edit]
This guide is provided as-is, with no claims regarding its accuracy. We think it's correct, but follow it at your own risk. Check with the owner of any server you use before exposing a service on a port. That's just proper etiquette.
Is This Really Worth It?[edit]
Yes, yes, a million times yes. The length of this page may dissuade you, but backing up to a repository is ideal in many ways. Basically, it is very easy to use, and it lets you code with confidence. Making sweeping changes to your game is easier to do when you know that you can easily "undo" those changes all the way back to the beginning, if you so choose. Now, on to the meat of the article.
Setting Up the Repository[edit]
Using Subversion requires first that you set up the "repository" where your game will be backed up to. You have three options, in increasing order of recommendation and detail.
Reflecting to the Local File System[edit]
This is only slightly better than zipping your project folder on occasion. The problem is, you've still got all your data on one hard drive. Of course, if you have an external drive, then this option becomes slightly more enticing. Look to the Tortoise SVN page for more details.
Use Source Forge[edit]
Source Forge allows open source developers to host their projects for free, and it provides CVS and Subversion (SVN) access without much work on your part. Check their online documentation, and skip ahead to the section on Tortoise SVN.
Host Your Own Repository[edit]
It's not really that difficult; all you need is a Linux server. For those of you in college, you can probably find your way onto a school server. First, enter type svn --version and see if you get anything. If not, create/edit the .bashrc file in your home directory to include the line:
export PATH=$PATH:/usr/local/subversion/bin
Replace /usr/local/subversion/bin with the path to subversion on your server. (If it's not installed at all, you're on your own.) Then, cd to wherever you want your repository to actually be stored, and create a directory for it:
mkdir PROJECT
Replace "PROJECT" with whatever name you like. Next, actually create the repository via:
svnadmin create /PROJECT/ --fs-type fsfs
This creates a subversion repository in the directory PROJECT. The --fs-type fsfs option uses a custom database (the default is BerkeleyDB, which might give you problems.) You only have to do this once. After executing this command, you should edit /PROJECT/conf/svnserve.conf (the config file.) Set up users, set read/write access, etc. here. One thing is, if you edit the conf file, you need to uncomment the line:
# [General]
Make sure you delete the '#' AND the space after it; the '[' should be right on the beginning of the line. The settings I used are:
anon-access = none auth-access = write password-db = passwd
This means that anonymous users cannot see your source, but authenticated ones can see and update it. The last line says to use the file "passwd" for authentication. A sample "passwd" file might look like: [users] seth = XXXX frank = XXXX john = XXXX
where XXXX is a cleartext password.
Now, you need to START the server. You have two options.
Run It On Port[edit]
This option is the easiest, and relatively secure. In this case, you can use a command like:
svnserve -r /cs/somepath/PROJECT/ -d --listen-port XXXX
This will start a server. You must provide the full path to the repository (/cs/somepath/PROJECT/, in my case), because a relative path like ./PROJECT might no longer work if you logout, due to virtual directories and whatnot. If you don't know your current directory, use the command "pwd". The command above starts a daemon thread, so that you don't need to leave the console open. Just pick a port number for XXXX. The default subversion port is 3690, but it doesn't really matter.
ps -A -U USERNAME
This lets you see all threads that USERNAME is running. It's useful because it also lists process IDs, which you need to kill the process. Sometimes, -A messes up the listing. For instance, sometimes I've had to use:
ps -f -U USERNAME
To kill a process with ID YYYY, use:
kill -1 YYYY If you need to re-start your subversion server, you'll need to kill it first. The -1 means to kill it safely (flushes buffers, etc.) If THAT won't respond, use kill -9.If your terminal freezes, open another one, connect to the server, and try killing it again.
Finally, you should probably use TortoiseSVN from Windows. You'll need to pass it a URL to import files, checkout a directory, etc. Use: svn://server.domain.ext:XXXX/ where XXXX is the port number you entered earlier, and server.domain.ext is your server's, er, name. URI. Something like that.
Tortoise will prompt you for your password, which you can save. After that, you're all set!
Tunnel SSH Commands to It[edit]
This is useful if your server administrator complains to you, personally, that exposing a port is unsafe, etc. Setup required: none! To use it, you might want to download Tortoise SVN in Windows (or Rapid SVN if you're in Linux and aren't comfortable with the Console yet.) Tortoise will ask for a URL; use:
svn+ssh://USERNAME@server.domain.ext/fullpath/PROJECT
...where USERNAME is the user name you use to log in (normally) to server.domain.ext, and /fullpath/PROJECT is the full path to your repository. You cannot save your password (at least, not easily), and you may be prompted for it multiple times. You have also entered "setfacl hell" in the event that you need to collaborate. However, this method is succinct. Note that the "passwd" file created in the step above will have no effect on logging in.
Using Tortoise SVN[edit]
Tortoise SVN is a nifty Windows application that integrates into Explorer, giving you nice green check-marks if a file is up-to-date and red x's if it's not. Once it's installed, navigate to an empty directory where you want to store the local files in your project. If you've already got project files, I recommend creating an empty directory anyways, just in case something goes wrong. Now, right-click and choose "Checkout...". Enter a URL as described above (or in the Source Forge or SVN documentation) and click "checkout". Enter your password (you may be prompted multiple times) and watch as any files in the repository are added to your new folder. This only needs to ever be done once.
Getting started with SVN[edit]
Basically, life with Subversion is the same as life without. Just don't rename or delete anything the normal way. Rather, right-click on the file, choose "Subversion-->(rename/delete)" instead. So, work on your game as normal, keeping all game files in the folder you created (in Windows) or in a sub-folder of this one. Eventually, you will want to Add these new files to the repository. Right click on them (or on their parent folder) and choose "Subversion->Add". Un-check any files you want to keep purely local, and hit "Ok". Enter your password, and your files will be added. Now, right-click anywhere in the directory and hit "Subversion Commit". Enter your password, wait. When green check-marks appear over each file, you know for sure that they are backed up.
Commit and Revert[edit]
A full review of Tortoise or SVN is outside the scope of this article. However, there are two very important commands that are in scope: Commit and Revert. Whenever you change a file that's been "Add"ed, and you are satisfied with these changes, you will want to right-click on it and "Subversion Commit" it. Enter your password, if required, and wait for the red "X" over that file to turn to a green check-mark. (You may need to hit "Refresh".) If you do not commit a file, it will not be backed up.
Reverting is the antithesis of Commit. Let's say that you change a whole bunch of things in your game, and for whatever reason you want to ditch them all. Right-click on the file and choose "Revert". Enter your password and wait for the green check-mark to appear. It is not back to the last "Commit". If you want to go back more than one "Commit", check the SVN documentation for the best way to do this.