Recently a couple friends have asked me how to get started using Subversion to manage their files, so here’s a step-by-step guide to get everything up and running.
Why use Subversion?
Subversion lets you:
- Keep track of every version of a file stored in multiple locations (e.g. desktop, laptop, work machine, etc)
- Synchronize these files so that no changes are lost, no matter which machine the file is last edited on
- Collaborate with other people using the same set of files without losing changes no matter who is editing the files
During undergrad, I always dreaded group projects because everything typically involved the “divide and conquer” methodology. My group members and I would divide up the work and then get together later and combine all of our work. In theory this works great, but in practice, it becomes a major hassle, especially if multiple iterations are involved, because inevitably someone’s work would accidentally get erased or lost.
It wasn’t until I reached grad school (and learned how to use Subversion effectively) that things changed. I had the opportunity to work on a number of group projects (like group papers and presentations) where all members used Subversion to coordinate the files. The final crunch time was much more sane since all changes to the files from all group members could be tracked and merged seamlessly. It really was a night and day difference.
To use Subversion, each “set of files” is called a “repository”. A centralized “Subversion server” must be used, and may contain any number of file repositories. To access these files, any number of “Subversion clients” may be used, typically from different machines. Since Subversion is open-source, a considerable amount of effort has been dedicated to making the system cross-platform. In general a Subversion server may be set up on Linux, Windows, or Mac OSX, and Subversion clients exist similarly for Linux, Windows, and Mac.
When files are retrieved from the server to the client, it is called an “update”, and when new versions of the files are sent to the server from the client, it is called a “commit”.
A typical repository will go through a continuous cycle of update-edit-commit.
In this guide, I’ll explain how to set up both a server and client on Windows. In my experience, the most user-friendly choice is VisualSVN as the Subversion server and TortoiseSVN as the Subversion client.
Install VisualSVN Server
- Go to the VisualSVN Server homepage
- Click on “download now“
- Download the latest version (1.6.1 at the time of this writing). You should have received VisualSVN-Server-1.6.1.msi
- Execute the installer after it has finished downloading
- Accept the license agreement
- In the next screen, leave the default values:
- This will set up a directory C:\Repositories\, where each subdirectory here will be the root directory for that particular file repository. VisualSVN Server will let you set different permissions on each repository (and subdirectories in each repository, but that’s more advanced.)
- You’ll also want to use Subversion authentication (password hashes stored by VisualSVN Server) instead of Windows authentication (VisualSVN integrates with the existing Active Directory domain, if present — this is quite advanced as well.)
- Then just click Install.
- This will bring you to the main VisualSVN Sever management console:
- Notice that there are no repositories, no users, and no groups (yet)
- First we’ll need to create a user that has permission to access the repositories (which ones we’ll assign later)
- Right click on Users and click “Create User…”
- Enter a username (e.g. “matt”) and a password (twice) and click OK:
- Advanced Note: If you have a number of users that will all have the same permissions, it may make sense to create a group and add all of those users to that group. Then when adding permissions to the repositories, you can just add the single group instead of adding each user. (Not shown.)
- Right click on Repositories and click “Create New Repository…”
- Enter a (case-sensitive) repository name and click OK:
- Advanced Note: If you know how to organize and use the typical Subversion directory structure (trunk, branches, tags), then check the box to automatically create those subdirectories in your repository. If you don’t know why you’d need those, then don’t worry about it
Set Repository Permissions
- Now we need to set the permissions of our newly-created Dissertation repository, so right click on Dissertation and click “Properties…”
- We probably don’t want to give everyone read/write access to our Dissertation (:P), so the first thing we do is select Everyone and click “No Access”.
- Now we need to give permission to ourselves, so we click “Add…”, select “matt” and then OK:
- This leaves us with the following screen, showing that user matt has read/write access to the Dissertation repository:
- This is exactly what we’re after! Feel free to tweak to your own needs. VisualSVN makes things incredibly easy to configure (as opposed to the alternative of hand-editing text files.)
Now we have the Subversion server completely installed, configured, and running. The next step is to install a Subversion client so we can access our file repository.
TortoiseSVN is the most useful Subversion client out there. It is an “explorer addin” which adds functionality to your Windows Explorer windows. When you check out a repository (a local copy of the files that you can edit) from the remote Subversion server, it shows the status of each file. Unedited (current) files show up with green checkmarks beside them, files with changes have red X’s, and files not in the repository have question marks. Here’s an example:
You can see that for the most part, no files have been modified. Only LocalSandbox.cs and some files in the Utilities directory have changed since the last version was checked in. The “bin” and “obj” directories have been intentionally excluded from the repository.
- Go to the TortoiseSVN download site
- Download the installer (TortoiseSVN-220.127.116.1161-win32-svn-1.5.4.msi at the time of this writing)
- Accept the license, keep the default settings, and click Install.
- After finishing the installation, it may ask you to reboot:
- Go ahead and click Yes to reboot (since TortoiseSVN gets loaded into Windows Explorer, it actually is crucial to reboot.)
Try Everything Out!
- Create a directory in C:\ (or wherever) called (for example) “RepositoryCheckout”.
- It is crucial that you make the distinction between the repository directory (C:\Repositories\* where the Subversion server stores the internal file repository databases) and the repository checkout directory (C:\RepositoryCheckout\*) where we store the local copy of the files as we’re editing them). The repository directory exists only on the server, and the repository checkout directory exists only on the client, but we have them on the same machine now since we have both the server and the client running.
- Make a subdirectory here called Dissertation:
- Right click on Dissertation and notice the new TortoiseSVN menu items (SVN Checkout and the TortoiseSVN submenu).
- Click on “SVN Checkout…”:
- Now we need to fill in the URL of our repository. To get this, we can back to our VisualSVN Server window. Since you probably rebooted, it’s in Start > All Programs > VisualSVN > VisualSVN Server Manager. Right-click on the Dissertation repository and then click “Copy URL to Clipboard”. Paste this URL into the “URL of repository” textbox in the TortoiseSVN Checkout window.
- In my case the URL was “https://ESL0095:8443/svn/Dissertation/”, though https://localhost:8443/svn/Dissertation/ would have worked just as well. Click OK.
- Because we’re using a secure connection (https instead of plain-old http), TortoiseSVN will ask us if we want to validate an unknown SSL certificate:
- We trust the certificate (VisualSVN Server just installed a self-signed cert by default), so click “Accept permanently”.
- Now we’re prompted for our credentials, so enter the username and password that you configured in the VisualSVN Server management utility before:
- Make sure that the “Save authentication” checkbox is ticked so that you don’t have to enter your username and password for each and every operation in the future.
- This brings up the “Checkout Finished!” dialog box, showing us that our (empty) repository is a Revision 0:
- For good measure, let’s add a file to the repository and commit it.
- Create a file called README.txt in “C:\RepositoryCheckout\Dissertation”:
- Right-click on README.txt > TortoiseSVN > Add… and click OK, then OK:
- This will show a blue plus sign on the file, indicating that it was added to the local repository:
- Now we just need to commit our changes to the local repository back to the Subversion server, so go back up one directory to C:\RepositoryCheckout
- Right-click on the Dissertation folder and select “SVN Commit…”
- Enter a log message describing what changed in this commit:
- After clicking OK, TortoiseSVN will commit our changes to the server and, if successful, indicate that we now have “Revision 1″ of the file repository!
Well, that wraps it up! Hopefully that is enough information to get started using Subversion to keep track of your files. There are a lot more advanced topics I haven’t covered here — if you have questions, feel free to leave a comment.
The best way to learn SVN is just to set up a “sandbox” repository and play around Create files, add files, edit files, commit files, delete files, update files — go so far as to create two folders containing checked-out files (simulating two machines) and mess around with things until you are comfortable and confident enough to trust it with all of your files. It took me a couple hours or so before I felt ready.
Hope that helps!