I hope I can make this a bit easier to understand for a few people. Versions is simply a Subversion client for the Mac. I wanted to start using it for my personal projects and had the need to work locally. I know this eliminates many of the benefits of Subversion, but it makes sense for me to use it in this way.
As a warning, I’m a bit of a noob when it comes to this. I’m actually hoping I frustrate some experienced Subversion user into sending me an email with a better and more standard way of doing this. That being said, I’ve been using this method for a couple weeks now and seem to be having good results.
To be clear, here is what I’m showing:
- How to organize file structure
- Using Versions to setup a local repository
- Checking out and committing
- Development side vs production side
Get Versions
You can’t start this whole process rolling unless you go get Versions.
Go download Versions
How To Organize File Structure
Let me stress again that we are attempting to work locally. If we were using Subversion for it’s natural purposes we would most likely be checking out a working version from somewhere on the web. Instead we are going to create a “virtual” repository to store all our working files. It will act like an off site server for us. I’ve chosen to use an ActionScript 3 class library for demonstration purposes. I assume you could do something similar with your website files or just about any other coding project.
First, let’s just create a new folder to hold all our working and development files. I have a folder on my HD called “Flash.” Within that folder I have two others called “classes” and “as3repository.” The “classes” folder is for all our working files. These are tested, debugged, and ready to rock. They also will most likely contain classes you’ve pulled from other places on the web. The “as3repository” is your dev section. This is where you will keep all your projects that aren’t ready to be released yet.
Additionally, there are some links at the end of the article that do a good job of explaining the general idea of Subversion file structure.
File Structure
Using Versions To Setup A Local Repository
Okay, now lets go ahead and open Versions. When you initially fire up the program you’ll be presented with the following screen.
The opening screen
You’re going to want to click on “Local Repository” to start defining where you want to place your repository. You’ll be presented with they typical dialogue box asking you where you’d like to save your repository. Browse to your “as3repository” folder that you created earlier. Once in there I like to create/add a new folder that describes the particular project. In this instance I’ll add a folder called “ExampleProject.” Inside of that folder I’m going to name the repository “trunk.” It should look like the following:
Adding your repository
Briefly, Subversion uses a tree analogy that involves the trunk, branches and tags. I guess the tags could be construed as “leaves.” The trunk is where all the magic happens. It’s where you do your primary work and is always under development. The branches can be used in one of two ways. First, if you were working in a team you might each be working on your own branch separately with the ultimate goal of bringing them all together at one point to create the final product. The second way to use a branch is to indicate releases. For example, you get your project to a good stopping point where it’s stable and ready for the wild. You might coin that “Version 1.0″ and create a branch for it. It’s really just a snapshot in time of your current development status. That branch can be checked out by yourself and/or others, but it should never be tinkered on. You go back to your trunk to start working on the next version. We’ll lean towards the second use in our demonstration.
At this point you’ve created your local repository. If you use your Finder to navigate to the ExampleProject > trunk folder you’ll see a bunch of files in there. Do not touch these. These are the files required for the versioning process.
Back in Versions you’ll notice a new “trunk” bookmark on the left hand side.
Your newly created turnk
Go ahead and rename the “trunk” bookmark to “ExampleProject.” Otherwise, we’d eventually have a lot of trunks running around! Now go to where it says “trunk” in the main window, right click, and choose “New Folder.” Call it “branches.” Repeat this step and create a new folder titled “src.” This will just be where we house all our working (dev) source code. Nice. We’ve made some good progress. Moving on.
Checking Out And Committing
Okay, this is the first point where I started to get hung up when I was starting out. I’ve just created two new folders in Versions, but they don’t show up when I browse to my “trunk” folder using the Finder. What gives? This is where Versions starts to work its magic. What we need to do now is checkout our “src” folder. So, go ahead and select the folder and simply click “Checkout.” My advice would be to check this folder out to your “trunk” folder where all the other files Versions created are stored. Your results should look like the following:
Your new bookmark
Now that you’ve checked out your “src” folder you are free to start adding folders and files at will. We’re working on ActionScript classes so we’ll most likely create a file structure like com > hexluv > ExampleProject. We can start adding our ActionScript files and Versions will start to recognize them.
Note: you need to add folders/files in order for them to be versioned. The “Add” icon is in the upper right hand corner of the Versions application. Simply select your new file and click “Add.” If you don’t do this Versions won’t bother versioning the file.
Let’s assume at this point we’ve checked out our “scr” folder and done a lot of productive work on our project. It’s time to check things back in. This process is simple. Just select the various files we’re ready to update and click the “Commit” button in the upper left hand corner. Versions will allow you to add some comments if you so choose. Awesome! We have now begun the process of creating versions of our project that will let us go back infinitely in time and see our changes and revert to them if we want.
The process can be summed up like this:
- Checkout your code
- Make changes and updates
- Commit changes at the end of the day
We are working locally so you don’t need to checkout your code every single time. You just need to start working on your files and commit them when you’re done making your changes.
Development Side vs Production Side
Hopefully it’s clear at this point and you’ve been able to make some progress on your project. Let’s also assume that you have your project ready to rock and want to create a release. This is as simple as copying the contents of your “src” folder and pasting it into the branches folder within Versions. Don’t try doing it in the Finder. Versions will ask you if you want to call it something new and allow you to add notes. I’d suggest calling it “Release-1.0″ assuming it’s your first release. Here’s a visual.
Example with a release
So, we now have a release. We’ve done a bunch of hard work and we want to use this release. All we have to do is checkout the contents of the “Release-1.0″ folder to our ActionScript “classes” folder on our HD. That’s the folder that stores all our production side classes. These are stable and ready to use in projects.
You’re now at a point where you can make use of all your hard work while continuing development in a different location. Awesome? I think so.
Additional Resources
As I mentioned perviously, this is all a bit new to me so I appologize if I missed some stuff. This is just my personal method and I hope that others can find it useful and adapt it to other things besides ActionScript classes. Below you will find smarter people than me that go in to greater depth explaining Subversion.
Why does this stuff have to be so complicated? But, thanks anways.