How To: Get started quickly using Subversion on Google Code (for Linux)

I had a little Python project I had been developing as a learning exercise and to take it (and myself) just a tad more serious, I decided that it needed project hosting! And version control! Like a real "program"... and stuff. And who knew, maybe people would sit up and pay attention and come begging to work with me and collaborate on this glorious, new... podcast client.

Google Code is - allegedly - a good option for beginners who want to get into project hosting, and though you have a choice between Mercurial and Subversion for version control, the idea seems to be to pick Subversion unless you've got specific large-scale needs.

Now, there's plenty of resources on using Google Code and Subversion, and there's no shortage of resources on Subversion and Linux, either. However, the Google Code stuff tends to refer you to TortoiseSVN (a Windows program) and the Linux-specific articles talk mostly about local repositories (which Google Code is not). So, to fill the gap, here's a quickstart intro to using Subversion with Google Code project hosting on a Linux machine to start up your new project - for those too impatient to properly understand Subversion before seeing their project online.

This step-by-step-guide assumes, that you've got a) a programming project in some sate of readiness (well, as long as you've got some source code files to put up....) b) a Google Code project hosting account, and c) a working knowledge of the command line.

Disclaimer: This does not in any way replace actually getting to know Subversion, e.g by reading the first chapter or two of this well-written and easily accessible introduction to Subversion, which will introduce you to things like conflicts and locks and all that cr*p that you really needn't worry about at this stage. This is just to get you started quickly and - hopefully - painlesslessly, and show you that this stuff isn't really all that complicated.

Step 1: Check to see if you've got Subversion installed.

Well, have you? Apt-go-get-it-yourself or whatever your package manager does. The package is usually just called 'subversion' (well it is in Ubuntu...) It should supply the basic command line tool called 'svn'.

Step 2: Download the source code from your Google Code repository.

But, but, but... I know, that seems illogical, seeing how that one is empty, right? Nevertheless, in order to establish the link and the hierarchy, you first need to pretend to want the version from Google Code. To download is called to 'checkout' and what it does is to establish a 'working copy' on your hard disk. Google kindly supplies you with the initial command needed:

# Project members authenticate over HTTPS to allow committing changes.
svn checkout https://poca.googlecode.com/svn/trunk/ poca --username madchine

When prompted, enter your generated googlecode.com password.

What running this command (notice the prefacing 'svn' - this is the subversion tool; anything that follows is considered subversion commands) would accomplish is to checkout the current version ('revision') of my project and put the files into a local directory named 'poca'.

This local directory is your 'working copy'. It should contain nothing. Do not choose any existing project folder as that just invites confusion. I can obviously choose whatever local directory I want and Subversion will create it for me if it does not exist. How about /home/user/svn/project-name? Do not be alarmed that you're not asked for your password - this will only happen when you try to upload your changes.

You should now have an empty project directory. Empty? Well, not quite. A hidden directory called .svn is placed inside it to keep track of things. But nevermind that for now...

Step 3: Copy your local files into the project directory.

Go ahead, this is pretty straight-forward. Supposing you've been writing on some files in /home/user/python/yaic (yet-another-itunes-clone, anybody?) and your new project directory created in the last step is /home/user/svn/yaic, just do an ordinary copy of all the files and subdirectories from the old directory to the new one.

In order for Subversion to know about these new files in your working copy and that you mean for them to be added to the project's repository, you well... 'add' them. With the project directory as the working directory, do:

svn add *

(or list all the files in the directory individually or whatever...)

Subversion should list all your files preceded by an 'A' - for 'added'.

Step 4: Upload your new files to the Google Code repository.

As in the previous command (add), be sure that you're inside the project directory for this one. To upload is called to 'commit'. Seeing as you supplied Subversion with the Google Code URL when you checkout'ed the original code, you do not need to reenter that information - it is saved in the hidden directory in your 'working copy' project folder. To upload all the files you've told Subversion you wished to see 'added' to the repository, the following line should do:

svn commit --message "Initial upload." --username madchine --password 1234567890AB

Since no specific files are mentioned, all in the working copy are implied. The --message switch indicates a comment for the revision we're committing (one way or the other, a comment must be supplied for the commit to be successful). The --username and --password switches are self-explanatory - use the ones Google have supplied you with.

If it worked Subversion should have spit something like this out:

Adding fileA.txt
Adding mainFile.py
Adding otherFile.py
Transmitting file data ...
Committed revision 2.

"Committed revision 2." Congrats, you've uploaded a new revision - really the first, but Google counts the empty, initial version as revision 1.

Step 5: Point your web browser to http://code.google.com/p/[NAME-OF-PROJECT]/source/browse/#svn/trunk and check to see that your files are there. Slap yourself on the back.

Step 6: Now, start reading a proper introduction.

Such as this one.