Subversion for absolute beginners

Subversion is a pop­u­lar open-source sys­tem used by soft­ware devel­op­ers, includ­ing the devel­op­ers of WordPress, for version-control. Unfortunately, under­stand­ing Subversion requires delv­ing into the arcane world of ter­mi­nal com­mands. But it’s worth the trou­ble if you’re devel­op­ing a web site or WordPress theme, or even just work­ing on a doc­u­ment, that may need to undergo numer­ous iter­a­tions. Think of Subversion as a kind of per­sis­tent undo that’s even bet­ter than Time Machine.

If you need to col­lab­o­rate on projects using Subversion, you’ll have to have access to an online Subversion server. Setting up a Subversion server online is beyond the scope of this arti­cle (i.e., beats me). Fortunately, there are sev­eral free or inex­pen­sive ser­vices that pro­vide easy access to Subversion online. Of these, based on my very quick sur­vey, Beanstalk seems to be the best. You’ll find a quick intro­duc­tion to using ser­vices like Beanstalk in Chris Nagele’s Vitamin post, Subversion for Designers, which also pro­vides a good gen­eral introduction.

If you’re fly­ing solo, the eas­i­est way to use Subversion is to set it up locally on your com­puter. Creating a Subversion server in MAMP or WAMP is unnec­es­sar­ily com­pli­cated, but if you under­stand a few basics, using Subversion locally is sur­pris­ingly easy.

Here’s a quick tuto­r­ial on how to set up Subversion locally on your Mac (using Subversion on Windows should be similar).

Getting Started

Using Subversion is very sim­i­lar to upload­ing and down­load­ing files from your host using an FTP client (for exam­ple, you can use a Subversion client to download—check out—the lat­est WordPress build; see Using Subversion on the WordPress Codex). Whether you’re work­ing remotely or locally, you’ll need a Subversion server and a Subversion client.

Download and install Subversion.

You can get the lat­est ver­sion of Subversion from CollabNet. The lat­est ver­sion for Mac OSX as I write this is Universal Subversion 1.4.6. Download and run the Subversion installer.

Download and install a Subversion client.

You don’t want to do any more than you have to from Terminal, so you’ll need a Subversion client. Two excel­lent clients for the Mac are ZigVersion and svnX (both are free for non-commercial use). If you’re a Windows user, try TortoiseSVN.

I pre­fer ZigVersion, so I’ll use it for this tuto­r­ial. After you down­load it, license ZigVersion, then watch the excel­lent video, Introduction to ZigVersion.

Create a repository.

Okay, time to fire up Terminal. You’ll need to set up a new project, called a repos­i­tory, which is where Subversion will main­tain all of your files.

1. First, let’s cre­ate a folder to hold our Subversion projects. In the Finder, cre­ate a new Subversion folder in your Home direc­tory and a sub­folder in the Subversion folder for your project repos­i­tory. For this exam­ple, let’s just name the sub­folder Test.
2. Launch Terminal.
3. You should be in your Home direc­tory. Type ls and hit Return to list the files in your cur­rent loca­tion. (For a list of other handy Terminal com­mands, see OS X com­mands.)
4. Create a new repos­i­tory. Type svnadmin create Subversion/Test and hit Return.
5. You’re done with the Terminal (yea!), so you can close it. Open the /Subversion/Test folder in the Finder and you’ll see a num­ber of new files and fold­ers. DON’T TOUCH THESE FILES! From now on, you’ll use your Subversion client to man­age the repository.

Working with Subversion

Now that you have a repos­i­tory, you can start work on your project.

Connect to Subversion

To con­nect to your Subversion repos­i­tory, launch your Subversion client. If you’re using ZigVersion, you’ll see the Connect to a Server window.

Enter the path to your repos­i­tory in the URL for New Server field. For exam­ple, to access the Test repos­i­tory I cre­ated above, I would enter: file:///Users/robert/Subversion/Test. You’ll need to replace robert with the name of your Home directory.

Add and edit files

The repos­i­tory is empty, so lets add some files.

1. If you’re start­ing with a theme or tem­plate (Sandbox, for exam­ple), just drag the theme folder to the ZigVersion window.

   

2. If you want to start with an empty project, click on the root folder, then click on the Check Out but­ton and cre­ate a work­ing folder in the Finder. You can now add files to this folder.
3. After check­ing out the project files, you can double-click them in the ZigVersion win­dow (or in the Finder) to edit them.
4. If you see a ? in the Status col­umn in the ZigVersion win­dow after edit­ing a file, high­light it, control-click and select Add from the popup menu. Once the file has been added, you’ll see an M in the sta­tus col­umn the next time you edit it, which means the file has been modified.

Check in and review your progress

After edit­ing your files, click the Check In but­ton in the tool­bar to update the changes. You can review the changes and add a com­ment in the Review and Check In win­dow. It’s a good idea to add com­ments so you can remem­ber what you were work­ing on. You can check revi­sions at any time by click­ing on the Revision Viewer button.

Learn More

If you’re using ZigVersion, you’ll learn every­thing else you need to know in the Introduction to ZigVersion video and the
Getting Started With ZigVersion manual.

If the ZigVersion man­ual isn’t enough, take a look at Version Control with Subversion, the book on Subversion and, trust me, more than you want to know. The entire book is avail­able for free online and you can also down­load a PDF version.