As a web developer, hopefully you’re already using subversion, and this tutorial is utterly useless to you. If so, good job, and carry on! If you’re a web developer (or web designer, or web programmer, or are in any way creating files that display or do something on the internet) and you’re not using subversion (or any other version control), this tutorial is for you.
Since this is a question that comes up a lot, I’ve scoured the web for a really basic subversion primer, and although many come close (including the outstanding free online book, Version Control with Subversion), some people may feel overwhelmed at such an immense amount of information. Truly, I believe the only flaw in the Version Control with Subversion book is that they don’t include any real life set-up examples when discussing the Subversion Architecture.
There are many different ways you can set up your development environment, so I can understand why they would be hesitant to give specific examples, however some people learn best by seeing examples that relate to their lives, so that’s what I’m going to attempt to do.
The example set-up we’ll be looking at is one in which the developer is currently working either locally or remotely, and using FTP/SFTP to move files to the remote development environment webserver. For example, you either:
- Have a copy of Apache running on your desktop/laptop computer. You store and work on the files on your desktop/laptop, test them locally, and then upload them to your server – or you –
- Make changes to the files locally on your desktop/laptop and test directly in the development space of the webserver (no local webserver) – or you –
- Use a text editor that allows you to pull files from FTP directly. You open them from FTP, make your changes, and save to FTP (no local copy stored at all)
I should mention that the third option here is absolutely the least recommended, especially since you’re not using version control. If your FTP process konks out mid-way through and the file isn’t saved completely, closing your application could mean losing that file forever. (Yeah, I’m looking at you, UltraEdit.) Regardless, if you’re using any of the above scenarios, or something fairly similar, this is aimed at you.
Because the Version Control with Subversion book is so good at explaining so much of this, I’ll be linking to it liberally, and just filing in the blanks where some people may get a little lost.
Disclaimer: This article is a very basic overview of subversion. There are many ways you might have your system and repository set up, and I won’t try to list them all, or even most. I’m going to use what many web developers would consider a “real world” example. You will not walk away from this a subversion guru, or able to deftly administer a subversion server. You will hopefully walk away knowing how to set up a simple repository, connect to it, and begin using svn in your day to day development. If you fuck something up, it is not my fault. Start on a test environment until you get your svn legs and feel pretty comfortable with basic commands.
This article is not a replacement for Version Control with Subversion – more of a supplement for newbies. As you begin to delve further into using subversion, that book will become your bible.
What is Subversion?
According to the Version Control with Subversion book:
Subversion (SVN) is a free/open-source version control system. That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data, or examine the history of how your data changed.
Subversion can operate across networks, which allows it to be used by people on different computers. At some level, the ability for various people to modify and manage the same set of data from their respective locations fosters collaboration. Progress can occur more quickly without a single conduit through which all modifications must occur. And because the work is versioned, you need not fear that quality is the trade-off for losing that conduit—if some incorrect change is made to the data, just undo that change. (more)
This is a pretty good explanation of what it is, but it can be hard to imagine what that actually looks like or how you’d use it in practical terms.
So what can Subversion actually do for you?
It means you can have multiple developers working on a project without fear of one overwriting the other one’s work. Have you ever worked on a project with multiple developers, where everyone is working on the same codebase?
“Hey Bob – I’m working on index.php – don’t touch it for now. I’ll let you know when I’m done, okay?”
or how about
“CRAP! Did you make changes to view.php? You blew out my work! I spent half a day working on that frakking function!”
All of that goes away. Each developer can have their own version of the application or website (called branches), where the changes they make will not impact the other developers, and the changes can then be selectively merged into the main development area, or trunk.
It also means that you have a method by which to track all of the changes you’ve made to any given file. Each time you commit changes to the file, subversion assigns that change a unique revision number. This means that if you ever need to roll a file back to a specific revision, you can easily do so with a simple command.
A good example of where you might need to do this is where you’ve “fixed” a bug that broke something else on the site (and really, who hasn’t done that?). If you know the now-broken functionality was working before, you can roll back to a previous version of the changed file (or any version before that, if needed) to the point where the functionality wasn’t broken.
You can also compare revisions side by side, so if you don’t want to do a full rollback, you can see what changed from one revision to the next to figure out what you (or they) did to break it so you can undo just that part or find a new solution. Plus, since each developer has their own subversion username, you can see who did what (so you know who to fire/berate/pummel/defenestrate).
In short – whether you’re flying solo or working with a team, Subversion can help keep you sane, and bail your ass out when you need it most.
Sounds awesome, right? Let’s get started!
Before we go any further, there are some terms that you’ll need to understand in order to grok Subversion. Don’t worry too much if they are hard to remember – we’ll be using them a lot, and they’ll become second nature to you.
Repository – this is the central location where Subversion keeps all of the information about your files, folders, and revisions. The repository can live on the same server as your development environment if your hosting setup has Subversion installed, or it can live somewhere completely separate.
If your hosting company does not have Subversion installed, you can even use a third-party Subversion host like Beanstalk or Unfuddle, whose sole purpose is to store your repository, and only your repository. Your local files are still on your hard drive, and your development files are still on your webserver.
Working Copy – this is the set of files you work with to make changes to your code, build your application, etc. The working copy usually lives on your hard drive, and would replace the directory you upload from and download to if you were using FTP. Simply put, this is the copy of the files you are meant to be working with. You can have multiple working copies of a site for any single repository, and in fact, you would have multiple versions if you have multiple developers. Each developer would have their own working copy.
Import – Importing in Subversion allows you to pull your existing files into a new repository. So, for example, if you have a site that’s already halfway built before you have the epiphany to use version control, you’d import your existing stuff into the repository.
Check Out – If you already have files in a repository and need to create a new Working Copy, you’d use Check Out.
Update – Using the Update command pulls the most recent version from the repository. If you had multiple developers working on the same files, or if you’re working from multiple computers, you’d want to make sure you update before you start making any edits to the files. If you fail to update before you make changes, you risk running into a Conflict when you Commit. (see below)
Commit – When you’ve made changes to a file or files in your Working Copy and you’re ready to push those changes into the repository, you Commit them.
Conflict – A Conflict occurs when there are changes on both your local version (Working Copy) of a file and the Repository of that file. For example, Sally makes changes to the file sandwich.txt in the repository. Harry has just changed the file in his working copy and commits it. Sally doesn’t update her working copy before committing it and she gets a conflict (since Harry committed his version after Sally’s last Update, and Subversion therefore sees Sally’s version as out of date). More on predicting and resolving conflicts later.
Trunk – the location within your Working Copy where your main project files live.
Branches – individual copies of the project that allow each developer to have their own working version. Changes can be Committed without breaking the Trunk, and are then merged into the Trunk when they are deemed worthy. (More on this in the bonus section of part two.)
The image below gives a very high level view of how Subversion works.
The Repository is your gatekeeper. It is the part of Subversion that makes sure files don’t get over-written with outdated versions, and allows you to work in tandem with other developers without risking stepping on each others toes. Other than through the command line (to execute import, update, commit, and status commands) or through whatever gui application you prefer using, you never access the Repository directly.
How often to Commit?
This is largely a matter of preference. Some developers wait until entire classes or functions are added/edited/etc before committing a file. I personally tend to commit more often, since it gives me a more granular way of seeing what broke something else and rolling it back, etc – but the only wrong way to Commit is to not Commit at all. You do not need to commit every time you change every tiny thing, though. For example, if I had to do some copy changes, I wouldn’t Commit after changing each word. The revisions would be so broken down, it would be hard to find important changes in the sea of revisions.
You (and your team, if you’re working in a group) will find a Commit frequency that works for you, as you become more comfortable using Subversion, so don’t sweat it too much in the beginning.
Now that you know the lingo and what it does, you need to decide how you’re going to set up your subversion workflow. Check out the second part in this series!
Header image comic strip credit: Return to Zero
