F**king SVN. How does it work?! An SVN primer for the designer folks

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:

  1. a server that contains all of the source files (including all of the different versions)
  2. 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.

  1. the address to folder in the repository you want to check out
  2. your SVN username
  3. your SVN password
  4. 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 my_repo folder from the repository to a folder on your computer called ym_locla_repo, you could then change the folder name on your computer to my_local_repo 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:

  1. keep the server’s most recent version (revert your recent changes), or
  2. replace the server’s version with your most recent version, or
  3. 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 commit.

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:

  1. delete all the .svn folders that exist in the problematic folder’s hierarchy (all the .svn folders from all of its child folders), or
  2. 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:

  1. You create a widget with an elegant image viewer according to your client’s original spec
  2. You commit your changes to SVN, and send the file to the client for review
  3. After review the client says: “Change it all! I want to see that image viewer in 4D!!”
  4. You spend 11 hours updating the file making all sorts of changes
  5. You commit your changes, and ask your friendly dev team to 4d-ify your image viewer
  6. A developer uses SVN to get all of your source files for the widget, without having to do any additional setup
  7. She completes your request and commits the changes
  8. You update your SVN working copy to get her changes, make a few minor tweaks, commit those changes, and resend to client for review
  9. Surprisingly, the client says: “What was I thinking, that 2d image viewer is way more appropriate… undo all the changes”
  10. You clench your fists, grit your teeth, and think about what a pain it’s gonna be to take out all the changes
  11. 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.

cheers!

13 Responses to 'F**king SVN. How does it work?! An SVN primer for the designer folks'

  1. Git, Bazaar, & Mercurial are the new breed of version control systems that many in the developer community are using to replace their older code versioning systems.

    Mercurial commands use “hg”, Git uses the command “git”, and Bazaar’s command is “bzr”.

    I’m not too sure about tools for Bazaar, but, because of the rise of http://github.com, there are two quality OS X GUI tools for interacting with Git repositories:

    1. Tower
    2. GitBox

    Of the two, Tower definitely offers the more powerful GUI.

    Also, bitbucket & Google’s code.google.com are helping along mercurial, which has a few GUI tools for Mac:

    1. MacHg
    2. Murky

    3. MacMercurial

    I’ve only used MacHg, but it’s pretty decent as a GUI interface for Mercurial.

  2. Thanks for calling out the newer version control systems. I haven’t actually used any of them other than SVN myself, and at work we are trying to migrate a lot of the Flash designers to start using SVN for their projects.

    I really should check out git, because, from what it seems, that is what most the interesting community development projects are using these days.

    I have exported git repos before (‘forked’?!) and used the code, but never checked any stuff back into it. Maybe I’ll pick your brain over beers sometime!

  3. Oh, and hopefully a lot of the version control basics covered here would aid in understanding the basics of the others….

  4. 1. Git & Mercurial are different beasts. One can “clone” repos from either mercurial or git. (GitHub, itself, introduced the term “fork” as just a way of referring to a user’s personal “write permission” “clone”.

    2. Absolutely. Knowing any version control system will help when trying to use others. Knowledge is mappable.

  5. SG says:

    If 2 users (let’s say ‘Bill’ and ‘Jane’) check out the same 2-file project, then Bill changes File 1 and commits those changes, when will Jane – who is working on File 2 and thus has no conflict with person Bill’s edits – receive those changes?
    a) automatically while they sleep
    b) automatically or with confirmation the next time they commit changes even if it is to File 2 only
    c) not until either checking out the project completely again or committing edits with a conflict
    d) other?

    I ask because I am confused about whether, when working as a team, “conflict resolution” is something that eventually ends up happening constantly because you keep your checked-out copy of File 1 you checked out 3 months ago, even though it’s been updated 5 times since then, until you yourself try to commit changes to it, or if every time you commit a different file in the project your unedited version of File 1 gets updated with previously committed edits from other users…?

    • Jonathan Greene says:

      Most version control systems (SVN included) will not automatically push checked in changes to all users. That is what the ‘update’ command is for. So using your example, Jane would need to update her working copy to receive Bill’s changes, and vice versa.

      If both Bill and Jane were working locally on the same file, and upon updating SVN could not merge the changes together (say the both made edits to the same lines of code), then SVN report a conflict.

      When SVN reports a conflict, it updates the file(s) in question with annotations describing each version of the conflicting code. It also produces two extra files, whose extensions will be the SVN revision number. If Bill or Jane is notified of a conflict, they will not be able to check the conflicted file until it is resolved.

      Resolving just means you hash out the changes you want implemented in the repository, mark the file as resolved, and check it in.

      • SG says:

        Yes, that makes sense. My question though is more about files that don’t have any conflicts. Do those get updated every time you commit also? If not, does that mean the “best practice” is to always do an update after every commit? Otherwise, that file you did not edit is just a conflict waiting to happen when you do get around to editing it in 3 months because someone else during that time will have edited it since you first checked out the trunk.

        • Jonathan Greene says:

          The only way to update a working copy is to do an update. The best practice is to always do an update before before making a commit. You won’t even be allowed to check in a file that is in conflict. If one file in your commit queue is conflicted, the entire commit will fail.

  6. Cathrine says:

    We use SVN in a project(programming)this was helpful for me.. now i know a little more about the basic commands/functions in SVN.. so thank you Jonathan for explaining a litlebit of how it works :)

  7. JC says:

    Thanks so much. This is a great overview and I have used it to explain the basics to my supervisor and colleagues in a small IT shop. This is so much more accessible than the O’Reilly style official documentation. (Which is also good but is like hitting a brick wall for non-developers.)

  8. Pieter Jacobs says:

    Hi Jonathan; thanks a mil, this was really very helpful! Thanks again!

Leave a Reply

Your email address will not be published. Required fields are marked *

*