isnoop.net blog

This guide is a simple step-by-step guide to help you convert your currently live website to a handy-dandy revision-control system called Subversion. It also contains information on how to create a discrete development environment where you can modify your site and test your changes without affecting live traffic.

If you:
…want a place to beta test your code
…want to keep a revision history of your code
…have every modified or deleted a file on your website and wished you hadn’t done that
…realize that CVS sucks cat ass
You should try subversion!

Assumptions:
•You are hosted on a *nix machine*.
•You have SVN installed or can install it.
•You have SSH access to your site.
•Your web host allows for the creation of subdomains (if you want a dev environment).
•Your HTTP document root is not the root of your home directory. For example, when you log in to SSH, you see a list of system directories but one of them contains all of your web content.

Notes:
•The command syntaxes that I provide are those used by FreeBSD. If you’re savvy on another system and you notice a syntax difference, please speak up.
•Throughout this text, I will refer to your web documents directory’s absolute path as docroot, the repository as repos, and your home path (the full path from the drive root to your home directory) as homepath.
•The paths described above do not contain trailing slashes. Do not add a trailing slash to paths unless specifically indicated.
•Always always always back up your data, especially before attempting something like this!
•Subversion official documentation

Preparation:

You backed up, right?

1) First, start by running svn –version to verify you have Subversion installed. If not, you or your sysadmin should install it for you!

2) In your web root (~), create a directory named svn_import.

3) Within svn_import, create the following directories: trunk, branches, and tags. **

4) As a security precaution, add the following line to a file called .htaccess in your document root: RewriteRule (^|/)\.svn – [F]

5a) If you wish to add your entire site to revision control, use the command cp -R -p -v docroot/* ~/svn_import/trunk/ to copy your entire site into the import directory.
Note: The -p tag on the copy command is important, as some files on your site may have nonstandard permissions that you wish to preserve.

5b) If you only wish to add parts of your site, copy only those files and directories into ~/svn_import/trunk/

Creating and importing:

6) Create the repository: svnadmin create ~/.svnrepos

7) Import your site: svn import ~/svn_import file:///homepath/.svnrepos -m “Initial import”
Note: Yes, file:/// is correct. Make sure you’re using the full system path to your home directory for homepath

Creating your development area:
(optional, but highly recommended)

8) Using whatever means you use to manage your web site, create a subdomain for your web site called dev.yourdomain.com.

9) HTTP password protect your new subdomain, so people don’t go poking around your work in progress. After all, you’re creating this dev area for a little privacy while you’re working.

10) Check out the repository into the beta site document root: svn checkout file:///homepath/.svnrepos/trunk dev_docroot
When this process completes, you should see the message At revision 1.

11) Look over your new dev subdomain. All of your pages *should* work on this new site, but if you hard-coded any full system paths, these ought to be changed to relative or dynamic.

Converting your live site to SVN

12) Create a temporary checkout directory: mkdir ~/svn_stage

13) Check out the repository to the temp dir: svn checkout file:///homepath/.svnrepos/trunk ~/svn_stage

14) If you got this far without backing up your site content, you should do so right now and then kick yourself in the ass for not paying attention to important instructions.

15) Move your repository onto your live content: mv ~/svn_stage/* docroot/
This previous step may seem odd, but the SVN repository you just moved onto the live site contains lots of .svn directories that are required to make your site act like a repository. It also helps ensure the shift doesn’t interrupt your site traffic, and if you opted for #5b, it doesn’t harm the files you didn’t want to add into SVN but still want to keep.

16) Test your fancy new revision control-enhanced web site!

Post-Conversion

17) Remove ~/svn_import

18) Remove ~/svn_stage

19) Edit the file ~/.subversion/config and uncomment the global-ignores line. You may wish to add space-delimited files that you want SVN to ignore. If you chose to follow step 5b, you should add the files and directories you didn’t want to import here.

Usage
•Now that your site is under this wonderful new revision control system, you can FTP all of your file changes into the dev_docroot path and test them on your dev subdomain. Whenever you make a change you want to store to SVN, you should commit your changes with the following command:
svn commit dev_docroot
•If you don’t provide during a commit using the -m flag, you will be prompted for notes about the commit. Add a brief description of the changes you made so you can revisit that version later on.
•Once you have checked in your fancy changes, you can check them out in your changes by running the following: svn update docroot
•Both your regular and beta document root are now repositories. This way, you can technically make and commit changes from either location. Whether or not you choose to do that is up to you, but the entire point of a dev area is that you don’t ever program in the live path again. It is my suggestion that you don’t directly modify SVN-controlled files in your live path.
•Now might be a good time to remind you to RTFM. This manual is well written and contains gobs of good information on how to use SVN.

If you’re used to CVS
First, congrats. You’re on the road to saner and happier revision control.
Next, you should read this.
Perhaps the biggest shift that you should know about is that revisions in SVN are commit-based, not file based. It is not accurate to say “file X is version 56.” You should say “file X was modified in version 43.” The key difference here is that any number of files and directories can be changed in any revision.

As an interesting aside to all of this, I like to keep a repository of every binary I download and install (applications and drivers). So I don’t have to keep the entire collection on my laptop or desktop, I have a media server that is also running SVN for Windows. My laptop and desktop use the SVN server to store all of the binaries I’ve downloaded. I can delete all but the most recent versions of the apps so they don’t appear on my other computers, but I’ll always have a backup copy of old versions within SVN.

* This document was written based on FreeBSD commands. If you are running RedHat or some other linux, the command flags may differ slightly. Refer to your help documentation to verify command flag differences.

**Click here for an explanation of the trunk, branches, and tags directories. If you don’t care about branching or tagging, you really don’t need to worry your little head about this.