SVN. It’s not scary, really. Ok, maybe a little. I know, you are a designer. Color and form are way more your thing. You might even hate code. Alas, your job now requires you to use SVN…. What is it? Why should I use it? HOW DOES IT WORK?! It’s…. it’s… overwhelming!
Never fear, with a basic understanding SVN, you can be up and running with it in no time. After reading this, you can wield even the crappiest of free SVN applications and start enjoying the benefits of version control!
What is SVN?
SVN is common shorthand for Subversion, which is a flavor of ‘source control’. I put source control in quotes, because while it is primarily intended as a tool for managing programming source files (think text files, like Actionscript’s .as files), but it can be used to control any type of file, including complicated formats such as Flash authoring files (FLAs) and output files (SWFs), images, videos and any other type of file on your computer.
Ok, so what do you mean by control?
Glad you asked. In any source control tool, control merely means managing changes made to a file. Whenever a file is updated and saved to the server the new version of that file is created, but all of its previous versions are still available. This means you can always revert any file to a previous version and/or inspect the differences between any two versions of a file. In a nutshell, SVN manages changes made to files and allows those changes to be distributed and used by many different people.
How does SVN work?
We won’t delve into the nitty-gritty details of the how SVN works – to be honest, I am a little foggy on the low level stuff. But, the good thing is, we benefit from this without having to know everything about how it works. Here are the basics:
An SVN setup has 2 main elements:
- a server that contains all of the source files (including all of the different versions)
- a local copy of the files on your computer that you can use and edit
In the SVN lingo, the server is called the repository and the local copy on your computer is called a working copy.
Working copies are created and edited by various users and their changes are committed back to the repository. SVN manages and records all changes to files by creating a new revision of the repository each time changes are committed to it. The most recent revision is called the
Head. Almost always, you will be working directly with the Head. However, if you need to rollback some committed changes, you can checkout a previous revision of the repository or simply revert a particular file back to any revision you’d like.
Along with storing revisions for each file in the repository, SVN also stores a global timeline of all the changes made to a repository as well as individual timelines for each of the files. These timelines track dates and times of the changes, the changes themselves, and any descriptions the committer entered for changes.
The final point to keep in mind: the connection between a working copy and the repository is not magical. While you normally won’t be able to see the hidden folders (named .svn) stored in each folder in your working copy, they are there – and they are important. They contain metadata associating their parent folder with it’s copy on the repository. If you delete these hidden folders, you will not be able to save your changes back to the repository and you will not be able to get any new changes for that folder – SVN will stop working properly. Unless you know what you are doing, you should just leave these folders alone.
So in short, servers with a central collection of files communicate with distributed copies of it’s files that contain special hidden folders. We just dispersed the magic! Now, it might sound intimidating, but it’s really not. Just keep these basics in mind and you’ll be basking in your geeky glory soon enough!
The Basic SVN workflow
Making a Checkout
The only way to make a working copy of a repository on your computer is to perform a ‘checkout’. There are several bits of information you should have ready when you want to make a checkout.
- the address to folder in the repository you want to check out
- your SVN username
- your SVN password
- the destination folder on your computer where you would like to copy the repository files to
With this information, you are ready to perform a checkout. Viola, you will have a working copy on your machine.
An important note about checkouts: checkouts within checkouts are no-no. That is to say, you cannot nest one working copy of a repository inside another working copy of the same or any other repository. If you check out the folder
my_repo from the repository to a folder called
my_local_repo onto your computer, you should not then check out another folder from the repository to a destination inside of your
my_local_repo folder. The reason being, those hidden .svn folders will get all sorts of confused, and likely not allow you to make any checkins, or updates, or anything else. Just keep each working copy independent from others and you are golden.
On a side note, you are free to move and/or rename the your working copies. For instance, if you check out the repository to a folder on your computer called , you could then change the folder name on your computer to without any problems. However, you should not change folder names inside your working copy in this manner. Doing so will result in your working copy thinking that the directory you changed has been deleted, and that a new folder that is already under SVN control (contains that hidden .svn folder) exists. If you need to change a file or folder name inside your repository you can use SVN’s
rename function to do so (pssst… rename info).
Making and committing edits to your working copy
After you successfully make a check out, you are free to edit any files in your working copy. When you are ready to make a commit (aka save) to the repository, you invoke the commit action and supply a description (aka message) of the changes you made. After kicking off the commit, you can monitor the status of the commit. If any warnings or errors occur you will be notified; if the error is big enough that it cancelled the commitment, SVN will loudly notify you.
Commits can fail for a variety of reasons. For example, if you remove or corrupt any of the hidden .svn folders inside your working copy, or, say, the SVN server is unavailable. Another common reason for a failed commit is what is called a ‘conflict’. A conflict occurs when you try to commit a file that has been updated to the repository after the revision you used to make your changes. For instance, if you and I are both editing the same file at the same time, and I check mine in first, when you check in yours, the server will alert you that a newer version of the file exists on the server and you will not be allowed to finish your commit because a conflict exists. (For details about dealing with commits, see the Dealing with (and avoiding) Conflicts section below).
Dealing with and avoiding file conflicts
If after attempting a commit you are presented with a conflict, you will have to perform an
update on your working copy, which will attempt to merge the server’s new changes into your working copy containing your recent changes. If the changes affect different parts of the file’s source code, the server should be able to merge the changes together, which would bring your local copy up to date, while retaining all of your changes. After this, you can commit your file to the server without problem.
If SVN cannot merge your files together (this often happens with non-text based files like FLAs and PSDs) your local files will be placed under ‘conflict’. Don’t fear, you have not lost your new version! However, when you look at the files in your local files system, you will see 2 new files – their names will start with the same file name as the conflicted file, but each will have an extension that represents the SVN revision of each file. The one with the highest numbered extension will be the server’s most recent file, and the one with the lower number will be your local file. Now it’s up to you to decide to either:
- keep the server’s most recent version (revert your recent changes), or
- replace the server’s version with your most recent version, or
- manually merge the changes together
Regardless of your decision, you will need to replace the working file (the one without a numerical extension) with the file you want to keep and delete the other 2 files. Then you can proceed with the commit.
Whew! You now know how to navigate the seas of conflict! But of course, it’s best to avoid that route all together. Avoiding conflicts is best done with good old fashioned communication. You should let your peers know when you are editing a file that they might also be interested in editing. If this low tech solution does not seem to work, there is always the SVN
lock. You can use the
lock command to lockdown access to certain files while you are using them. Just be sure to unlock the files when you are done, or you might have a frustrated team unable to access files while you are taking your bubble bath.
Adding and committing files and folders to your working copy
In addition to editing the current files in your working copy, you can add new files and folders to the repository. When you want to add a new file, you can just create the file anywhere inside your working copy’s hierarchy. When you are ready to commit the files to the repository, you will first do an SVN
add on the new file(s) and then execute a
Adding folders is done in much the same way, however be careful when copying and pasting folders into your working copy from another location. Remember, there are hidden .svn folders that exist in every folder that is part of a working copy. If you copy a folder into your working copy that already contains a .svn folder, you will not be able to commit your file. If you try to add the folder, you will get an error that tells you its already under version control. To proceed with the addition of that folder, you have to either:
- delete all the .svn folders that exist in the problematic folder’s hierarchy (all the .svn folders from all of its child folders), or
- remove the problematic folder, create a clean version of it and copy the files into the ‘clean’ directory
NOTE: If you go with the latter, you will have to manually create all the child folders as well, as copying in a child folder with a .svn folder will give you the same problem.
Making copies of folders in SVN
Sometime you want to duplicate a folder within your working copy. For example, you want to copy a template folder so you can modify its contents into a new project. SVN has a built in function called ‘copy’ for this. It effectively duplicates the target folder without adding any of the hidden .svn folders and gives it whatever name you supply. This is the preferred way to do a folder copy with SVN.
If you accidentally copy/paste/rename a folder inside your working copy without using SVN’s copy, when you try to add the folders to the repository, it will give you the ‘folder already added to SVN error’. You will then have to remove all the hidden .svn folders from within your duplicated folder by hand before you can add it to your repository.
Changing file and folder names in SVN
To change the name of a file or folder in SVN, you use the
move command. This command duplicates the target file, gives it a new name, adds it to the repository and then deletes the target file – effectively renaming the file in the repository.
Exporting the repository
At some point, you might want to export the repository (or a part of it) which will output all of the source files without any hidden .svn folders. This means you will have a replica of the repository code, but it is not a working copy – you will not be able to update it via SVN or commit any changes made to it back to the repository. Executing an export is very similar to doing a checkout. It requires a repository address and a destination on your local computer.
Why should I use SVN
There are a few really good reasons to use SVN. Backing up versions of projects, rapid and stable releases of code updates (read bug fixes), and having a single place where people can find your work are among the best. Perhaps it is best to illustrate the reasons with an example:
- You create a widget with an elegant image viewer according to your client’s original spec
- You commit your changes to SVN, and send the file to the client for review
- After review the client says: “Change it all! I want to see that image viewer in 4D!!”
- You spend 11 hours updating the file making all sorts of changes
- You commit your changes, and ask your friendly dev team to 4d-ify your image viewer
- A developer uses SVN to get all of your source files for the widget, without having to do any additional setup
- She completes your request and commits the changes
- You update your SVN working copy to get her changes, make a few minor tweaks, commit those changes, and resend to client for review
- Surprisingly, the client says: “What was I thinking, that 2d image viewer is way more appropriate… undo all the changes”
- You clench your fists, grit your teeth, and think about what a pain it’s gonna be to take out all the changes
- Then you remember SVN has all your old versions and you breath a sigh of relief and revert your local files to original version and send it out. Knowing that when the client changes his mind and wants the 4D version, you are just a couple clicks away from
A little melodramatic, I know. But there are a few highlights to point out.
* You don’t need to keep each iteration of your project on your computer, you just keep the most up to date one, knowing that you can re-download any previous version at anytime.
* Since the SVN repository is shared, there is no extra set-up required by someone else if they need to access your work. They can easily update the repository and utilize your code/source files in the proper context. It makes collaboration easier.
Ok, now what
SVN originally was designed as a CLI-only program (Command Line Interface). This means, you would open your Terminal and type in text commands like:
svn checkout http://my.ossum.repo/files ~/Desktop/ossumWorkingCopy
Not too hard, but not everyone is comfortable on the command line. Nowadays, there are a plethora of GUI (graphical user interface) applications that are built to assist you in using SVN. Personally, I prefer the CLI because its quick, and I have had enough practice with it to become comfortable. However, since you are likely new to SVN and want to get up and running quickly, let’s rely on a GUI application.
If you are using Windows, the de-facto application seems to be TortoiseSVN. If you are on OSX, there are many applications available. There are free ones and paid ones. Of the free ones, SVNX is the most popular. I hesitate to recommend it though, as I have had my share of problems with it (random post-hook errors, errors when performing copies, local file changes not being recognized by the client, etc…). Of the paid applications, Versions is by far the best choice for the ‘designer’ archetype. It’s about $50 a license, but if you can afford it (or expense it!) and will be using SVN heavily it’s a great choice.