Absolute basic Subversion for newbies with svnX

Update 11 Oct: Someone from the svnX team actually stopped by to add on to my post. See his comments below.

I’m not a programmer, but occasionally need to do programmer type things. One of these things is to use Subversion to keep collaborate on projects with other people. This is a tutorial on how to use Subversion on your Mac, for non-programmers like me. I’ll only cover the basics and what is absolutely necessary to get started with it. Ready? Let’s dive in.

What is Subversion?

So your latest project requires that you use Subversion (or SVN for short). What the heck is it? Subversion is a version control system that allows its users to keep track and manage changes to documents and files. So for example, if you create a website and track it with Subversion, you will be able to keep track of different versions of your HTML, CSS and JavaScript files, and revert to earlier versions if you need to.

If it’s a team project, you can split the work with different people and work on the same files at the same time. So if there are 2 people making changes to style.css, you can merge the different copies with Subversion to create the latest version. Cool huh?

Install Subversion and svnX

To get started the first step is to install Subversion on your Mac. You can do that by downloading the latest Subversion binary from here:

http://www.open.collab.net/downloads/community/

Next, download and install svnX. This is an open source (free) application that allows you to work with Subversion in a GUI, rather than from the Terminal or command line. Download the latest version of svnX from here:

http://code.google.com/p/svnx/

Basic Subversion concepts with svnX

Repository a.k.a. repo

A Subversion repository is the central place where all files are stored. This repo usually resides on a web server, or a computer in your intranet. The latest version of your project is always on the repo, so if you and your team mates’ computers all crash the project will still be safe. In this tutorial, I’m assuming someone has already set up the repo for you.

Now you need to connect to the repo. Launch svnX and look for the Repositories window. If you don’t see it, press Shift+Command+R. Click the plus button to add a new repo. Fill in your SVN login details and click on the repo name to finish.

Now double-click the repo name. If your login details are correct, a new window will appear and show you the contents of the repo. In the example below, my Demo Repository is still empty because it’s brand new.

Click for larger version

Checking Out

To start editing the project files, you need to download them from the repo to your computer. This is known as checking out the repo.

Working Copy

When you checkout a repo, it gets downloaded onto your computer as a Working Copy. This is where you make your edits and changes. To checkout and create a Working Copy of the project, click the Checkout button in svnX and choose where you want to store the project files.

This will also automatically create an entry in svnX’s Working Copies window.

Updating your Working Copy

Updating your Working Copy syncs your local files to the repo and ensures that it is at the latest version. Remember to update often so that you are working on the latest version of the project files.

Adding files to SVN

If you want a file to be tracked by Subversion, you must first add it to the repo. Let’s assume that I’ve created a file called hello.txt and added it into my local working copy demo folder. svnX will now see the file and highlight it in blue indicating that it has detected a new file. Select the file and click the Add button. hello.txt is now being tracked, but not yet uploaded to the repo.

Committing files and changes

When you make changes to the project – either by adding new files or editing files – the changes have only taken place on your local files (Working Copy). To share this changes back to the central repo, you need to commit the files and changes.

Before committing, be sure to update refresh your Working Copy to the latest version. svnX will then highlight new files that you’ve added and changes. Select the highlighted files and click Commit. A window will appear for you to enter a Commit Message. These are notes to explain the changes in this commit. Click Commit and svnX will send your changes up to the repo.

If you open your repo window you will see the revision number, the date of the commit, the person who made the commit and the commit message. Now if my team members update their working copy, they will get hello.txt.

All of us can work on hello.txt at the same time. When we commit our changes, Subversion will automatically merge them so that hello.txt in the repo will incorporate all the changes and always be the latest version.

Ignore files

Finally, you may want to ignore files in your Working Copy. Let’s say I create a file called _reminders.txt and I place it together with the other files in the Working Copy. svnX will show that there’s a new file and keep nagging you about it.

Fortunately, you can tell Subversion to ignore the file. First, switch to the tree view. This will allow you to see the directory structure. Select the folder the file you want to ignore resides in. Since my _reminders.txt is located in the root of my Working Copy, I have to select the root folder, which is named ‘.’ in svnX.

Next, click Properties and the property dialog will appear. From the dropdown, choos svn:ignore and type in the name of the file(s) you want to ignore in the space at the bottom. Finally click the plus sign. svnX will ask you to confirm that you want to ignore the files. Click OK and svnX will no longer track these files, and will not commit them to the repo.

Click for larger version

Now you try it

The above should be enough for non-programmers to get started with Subversion. I hope that the tutorial was useful. Feel free to ask questions in the comments!


4 Comments on "Absolute basic Subversion for newbies with svnX"

  • f says

    Thank you! It really helped clarify everything for me.

  • svnX says

    You can also checkout by simply dragging a folder from the Repo browser to the Finder.
    Also the ‘Review…’ button is a better ‘Commit’.
    And (new) in svnX 1.3 you can now ‘ignore’ items by choosing ‘Ignore’ from the contextual menu.

    It would be useful to clarify the differences between ‘update’ & ‘refresh’ in the working copy window. You wrote: “Before committing, be sure to update to the latest version. svnX will then highlight new files that you’ve added and changes.”. That statement is a bit confused.
    Subversion will not let you commit a change to a file that has a newer revision in the repo. (It will try & fail – which is fine.) You will need to update that file first. Updating (from the repo) may change the files you have modified requiring you to review your changes & resolve any conflicts. It may also change/add/delete other files & folders in your working copy. (You can choose to update selected or all items as you desire.)
    On the other hand, Refresh just makes the svnX window reflect the current state of your local working copy. (The Auto refresh pref automates this.)
    So – always refresh your working copy before committing. Update it as necessary and typically after a commit.

    • Hi! thanks for stopping by and adding your articles – I’ll be updating my article. It’s great to know that someone involved in the svnX project is actually paying attention to my blog!

Leave a Reply

%d bloggers like this: