Subversion Basics

Assuming you have access to a subversion repository (such as a project on wp-plugins.org like I do), here’s how you can go about using svn to track changes and work collaboratively.

Open Terminal.app. We’re going to be using the command line. If you don’t normally go near the Terminal, don’t panic. Using svn through the command line is easier than it seems.

Check it out

Before we start developing and updating our application, we need to grab a copy of it first. We do this through the checkout command. Checkout, as the name implies, picks up a copy of your application from the repository and downloads it to a location you specify. The checkout command requires to pieces of information. The location of the subversion repository and the location of the folder you wish to download this to. You can omit the latter argument and have subversion download to the current path. For example, if you run cd ~/project/ before using checkout, the contents of the repository will be deposited in ~/project/. Let’s do an example checkout command:

svn checkout http://svn.example.org/turfapp/ ~/projects/turf/

Every subversion command you wish to run must be preceded by svn as in the above example. Running the preceding in the Terminal will download the turfapp project (doesn’t really exist). Now, we’re ready to get to work!

Once we’ve checked out a project, we can make edits and updates to our hearts content.

Ready to Commit?

When you’re happy with the changes made, you may upload your work back to the subversion server. However, if you’re working on a collaborative project, someone may have made a change after you checked out the project. If you upload your copy, it would over-write their work. For this reason, we run the update command.

cd ~/projects/turf/

svn update

This will tell you which revision you have. If everything is fine, we’re good to upload our changes. We do this by running the commit command. With the commit command, you also need to specify a message about what changes you have made.

svn commit -m "Added the Sparkle framework"

The above assumes you’re in the correct directory. The message sent to svn would in the example would be “Added the Sparkle framework”. Make your message descriptive so anyone else (or even yourself in six months time) can tell what you’ve done fairly accurately.

Once you’ve run commit, svn uploads any files that have changed and your updates are saved.

Adding files

Straight add

If you add a file to the working directory, then run commit, you’ll find that svn doesn’t find any changes to update with. Whenever you add files to your working directory that you wish to add to the project, you need to tell svn.

svn add newfile.ext

If the file to be added is in a folder, you’ll also need to specify that:

svn add sources/newfile.h

Or if the resource you’re adding is a folder, you can just specify the path:

svn add headers/extension/

Import

The import command doesn’t require you to have a checked out copy of the project, and it allows you to import a file to the server from any location on your hard drive (whereas add is usually restricted to the working directory). For the import command, you need to know the path to the resource, and the path on the server where it should reside. For a folder, you need to specify the path on the server that the folder will take, rather than the path where it should reside as svn will upload the contents of the folder rather than the folder itself. This can be confusing at first if you’re not aware of it.

The import command will commit the changes you make, so you need to provide a message as well. The overall syntax is:

svn import -m "message about update" /Path/To/Resource/ http://svn.location.on/server/trunk/

Let’s add a file to our project:

svn import -m "Adding about xcode pdf" /Developer/AboutXcode.pdf http://svn.example.corg/turfapp/trunk/resources/

Will result in the file being uploaded to the server at http://svn.example.corg/turfapp/trunk/resources/AboutXcode.pdf.

Deleting files

Now that you can import files, deleting them should be easy. The analog to import is (surprisingly) delete. You can just pass the URL of the file on the server to delete, or you can pass a path to a file in the working directory. If you pass a URL, the change is committed and a message is required. Let’s get rid of that pdf we imported:

svn delete -m "message about deletion" http://svn.example.corg/turfapp/trunk/resources/AboutXcode.pdf

If you specify a path in the working directory and don’t send a message, the change is recorded and snchronized with the server the next time you run commit. For example:

svn delete trunk/resources/AboutXcode.pdf

In which case the change is not reflected on the server until you run:

svn commit -m "summary of changes"

Summary

SVN can be used to coordinate the development of a project. A project needs to be checked out using the svn checkout into a working directory before it can be edited. Updates are saved using the svn commit command, and files can be added using svn add or svn import, while files are removed using svn delete

Some svn commands are analogous to the standard UNIX commands; you can use ls, mkdir, cp etc. to navigate and manage your repository.

That’s it!

You can find out more about subversion at http://subversion.tigris.org. Run svn help or svn help subcommand to learn more about the svn commands.

Have fun!