The purpose of this tutorial is to install and get started using TortoiseSVN, a popular Subversion client for Windows.
Why do I want SVN and what are we going to do with it?
There are many reasons why you may want to use SVN (Note: I may use SVN and Subversion interchangeably throughout this tutorial) in WordPress applications:
- to contribute to WordPress you need access to the code
- you develop themes and plugins and want to test the latest changes
- to interact with your theme provider’s updates (i.e. “checkout” themes)
- to keep track of your own changes to themes
- probably a lot more I can’t think of right now
Personally, I’m playing around with Justin Tadlock’s Hybrid Core and need to keep track of what I am doing myself in my theme files.
So today we are going to install TortoiseSVN and also perform a couple basic tasks that you may use. This tutorial only scratches the surface of what you can do using Subversion, and is meant to just get us started and comfortable with the idea.
Download and Install TortoiseSVN
The first step is to download TortoiseSVN. While there are a number of Subversion clients you can use, TortoiseSVN is well documented, popular, and pretty simple to use. And if you can download iTunes or anything else, you can download TortoiseSVN.
To download, let’s go to http://tortoisesvn.net/downloads.html. You can see on the screen that you have the option to download the 32-bit or 64-bit version. To check your systems settings go to Start >> Control Panel >> System & Security >> System and it will display for you. You can see mine in the photo, so I’ll be downloading the 32-bit version.
You will be redirected to SourceForge for the download. Save the file and after it finishes, you will want to check the signature to make sure the file is not corrupted. Open the containing folder of the download and view “Properties” after a right click. Under “Digital Signatures” it should say that it was developed by Stefan Kueng and be “OK”. Now, open the downloaded file and run it on the prompt.
Once you receive the next prompt click “Next”, accept the terms, and “Next” again. You can now browse your computer and install it wherever you like. You may be presented with a security alert and you can see the verified signature again. Click “Install”.
After the Install completes you need to press “Finish” and you have the option to donate to the project if you wish. Easy right?
Now, bookmark this page and after you restart your computer, come back to us so we can get started actually using TortoiseSVN.
Get to know the terminology
I’m going to use the WordPress.org terminology as an example of Subversion at work. With subversion, the first content division will be between the working copy and the repository. The working copy of WordPress is the active version of WordPress, such as 3.0.3. Within the repository are both past and future versions of the working copy.
The WordPress repository is made up of three sections — trunk, tags, and branches. Let’s discuss them in reverse order:
- branches – branches are major versions of WordPress, such as 3.0, 3.1 and so on. Branches are the big releases we all yearn for every 3 to 6 months. All major versions of WordPress back to 1.5 are available in the branches folder of the repository.
- tags – tags are the minor versions — bug fixes, security fixes, simple updates — all the smaller stuff. In WordPress these tags get labels like 3.0.2 and 3.0.3. If thinking of the tree example, a tag may make more sense as a leaf… anyway. It is called tags because every time WordPress (or your themes from the theme repository) is updated the source code is tagged with the version number and the automatic updates inform you to update. All minor releases of WordPress back to 1.5 are available in the tags section of the repository.
- trunk – trunk is where the action is. This is where the ‘bleeding nightlies’ lie (or lay? meh…). All current WordPress files are piled into trunk. This is the part of WordPress where literally hundreds of contributors are testing, patching, and committing code to WordPress. This is the part where future versions come from. For instance, at the time of this writing, the trunk version of WordPress is 3.1-RC1-17163. Trunk is where Subversion is most important.
For Subversion access instructions to WordPress, go here.
But, what will I do with Subversion?
To checkout means you are literally checking out a current version of trunk — the living, breathing, most up to date code. When will you do this? Well, your theme author that supports Subversion may make a minor update that you need but is non-urgent for the vast majority of users. Rather than updating the tag version of the theme, you could just checkout the trunk version and update what you need.
You can see how I did it with the two images on the right, where I go to the directory I want the checkout to be, right click >> SVNCheckout. Then I enter the trunk url and confirm that my checkout directory is in the right place.
How do I know what changed?
This is probably the sexiest thing about Subversion, and TortoiseSVN. TortoiseSVN uses a series of icon overlays (see picture) to describe what has happened to a file from the working copy. After you check out either a working copy or a copy of trunk and start working on them, as the files change, they get the appropriate icons to depict what happened to them.
Cool, right? Even cooler — diff. To diff files is to analyze a marked up copy of the difference between them. With TortoiseSVN there are two ways to diff files. One is to have the two copies of the file in the same folder (this could be useful for analysing your functions.php theme files to the original theme functions.php) and right click >> diff. You can also launch TortoiseMerge, a tool that lets you load files from different directories. Go to Start >> TortoiseSVN >> TortoiseMerge (note TortoiseIDiff is NOT the same thing — it is for images). View the result of comparing the files in the screenshot below.
Contribute, patch, and commit with SVN
In some instances you may have access to patch and commit code yourself. After you alter files that you’ve checked out, you can right click the appropriate files (or directories) and click “Create Patch”. You’ll then save the files with a .patch extension to apply to later via “Apply Patch”. After you apply the patch you get a chance to review the changes before choosing “Patch all” as shown in the screenshot below.
Voila! Your patch is in. An administrator of the repository can then commit the patch to trunk if necessary.
Look at you!
You’re ready to go! You have all the tools you need to start working with Subversion. So what are you waiting on? There are trac tickets to work on!