How To: Subversion Basics
John Ratcliffe-Lee writes in with a question about how to use Subversion to easily keep tabs on a frequently updated software CMS he wants to use. First off, what is Subversion? It's a widely used version control system, or in layman's terms Subversion is a way of keeping separate versions of a code base as it is developed. If a mistake is made, files can be rolled back to a previous version. If one thing isn't quite right, it's possible to view differences between certain versions of the same file to see what's up.
More importantly, SVN as it is commonly called is highly effective when working with multiple developers up to large development teams. SVN is an extremely capable piece of free software (under the Apache License) giving developers control over every aspect of a project. A single code base of hundreds of files can be safely worked on by many people while allowing users to merge files, commit changes, rollback to previous file versions, detect file conflicts and much more.
For example, Skribit relies on SVN to keep everyone organized and working on the same set of code. Developers can easily check the status of their local code version with the most current version with svn status. The screenshot below shows that my copy of the application.css file was modified but not committed, yielding the M marker. Further below, I update my local codebase to the most recent copy by simply typing svn up.
I'm jumping the gun a bit, let me backtrack.
So how does the typical user get started with SVN? Well for one you would need an SVN host - be it your own server or a hosted Subversion provider such as Assembla. However, that's not within the scope of this article. This article is for the person that wants to learn how to get SVN running so they can download (known as checkout in SVN lingo) and keep up to date with freely available open source projects and the like.
Here's John's email and I'm aiming to answer his question about SVN basics with this post:
Anyway, I wanted to ask a favor to see if you knew of any good, really basic guides to using Subversion for first timers.Essentially, I want to start using Chyrp (http://chyrp.net) as the CMS for jratlee.com. Chryp is in it's infancy and updates are pretty frequent. I figured the best way to get rid of that hurdle was to install Subversion. Knowing nothing about it (and Dreamhost's support wiki being more technical than I'd like), do you know of any good how-to stuff out there?
Man your terminal.
From John's email I can see that he will be using SVN on his website's server and not his local computer. In that case, we're going to need to get into the server with SSH. I'm not sure if all webhosts provide users with SSH access, but it can't hurt to ask the support department for login info.It usually goes something like this in the Terminal (Use PuTTY for Windows, and Apps » Utilities » Terminal for OS X):
ssh username@yourdomain.com
You'll be asked for a password and you'll know you're in when you see a prompt.
Now you need to navigate to the directory where you want the SVN files to remain all the time. Once files have been checked out from SVN, it is best to keep them in that directory or you will have to carry out another SVN checkout to create the proper metadata (in the form of .svn folders that you don't want to mess around with) that was lost from moving things around if done improperly. I'm just saying you can avoid problems later on by knowing exactly where you want your files to remain. For example, if you are checking out WordPress from SVN you might keep it in a "blog" folder at the root of your publicly accessible directory (often named public_html, httpdocs or something similar depending on your webhost).
You can find out where you are in your server's file system by typing the command below.
pwd
PWD stands for Print Working Directory and it will do exactly that.
At this point you can poke around to find the public web directory by using commands like ls to list the files and directories in your working directory, and cd to change the directory.
After using the ls command I saw the httpdocs folder, which is my public web directory, and changed to it. Do the same and you can begin to checkout the software you want. You'll need to find the SVN repository URL. For John's example, this can be found on the CMS project's website as is the case with most other open source projects. Now that you have the repository URL you can finally begin the checkout process.
svn checkout http://chyrp.googlecode.com/svn/trunk/ chyrp
Checkout is the command for SVN with the repository URL serving as the source and the last part serving as the destination folder. If you put "chyrp" and you're already in the public web directory on your server, the end result will be that you can access the files at yourdomain.com/chyrp. If you prefer to just dump the files in the root of the public web directory and access files simply at yourdomain.com, you can swap out the folder name for a single dot.
svn checkout http://chyrp.googlecode.com/svn/trunk/ .
If you get an error stating your user account doesn't have the privileges to make a directory, you can run the same command but add sudo to the front. Sudo lets you run commands with the privileges of a super user.
sudo svn checkout http://chyrp.googlecode.com/svn/trunk/ chyrp
This is exemplified in the screenshot below with SVN successfully checking out files to the newly created directory.
Chyrp has another step for checking out the entire project but for most SVN checkouts that's all you really need initially. The only other thing you need to know to update the code is the update command.
svn up
Just run that to get SVN to check for the most recent version and update your code base if it's outdated. However, this won't work if the SVN repository URL you used at checkout was for a tag. A tag in SVN is like a "stable" release that is, well, tagged to mark it as noteworthy among the other revisions. It could be to mark it as a milestone release among other reasons. For example, WordPress version 2.3.3 is a tag (there is also the concept of branch, with 2.3 being a branch and so on).
On the other hand, there is trunk which is like walking through a minefield, especially with new projects. Trunk is live code that is not guaranteed to be stable or secure. The rule of thumb is to never run trunk on a production site. So what was I saying? Oh right, so a PC user, a Mac user and a Linux user walk into a bar.
The point of this being, if you checked out with trunk you can easily update with svn up. If you checked out with anything else, you'll have to switch the repository URL with svn sw.
You must be inside the directory you are dealing with before running this.
svn sw http://somedomain.com/svn/repo/tags/next-version-number
So if I'm running a tag-based SVN directory for WordPress and I need to update it to the latest tag release I can use the line below, with the SVN repository URL being that of the most recent tag release.
svn sw http://svn.automattic.com/wordpress/tags/2.3.3
One More Time
- Assuming you want to checkout an SVN project on your web server, SSH in.
- Navigate to the directory you want to checkout.
- Run the svn checkout command along with the appropriate SVN repository URL and folder name.
- When a new version comes out, simply SSH in and browse to inside the directory where the particular files are and run "svn up". If you are following a tag SVN repository, use the svn sw command in conjunction with the appropriate SVN repository URL.
- You're done!