SVN, the Way of the Tortoise

Matt

Oct 13, 2009 • 10 min read

Although, Subversion (SVN) is not new, it is still one of the most widely used version control systems (VCS) available. SVN is a tool that allows users to track the changes of files. Yes, it’s that simple.

Interfacing Your Demons

Like many version control systems, SVN utilizes a command-line interface (CLI) to interact with users. Some users frown upon the command-line; especially, Windows users. However, I want to point out how necessary it is that these tools use the command-line.

After you use a version control system for a good length of time, you should notice that there are routines you follow over and over again. Perhaps you lock certain files before editing them to prevent conflicts with other potential editors on your team. Maybe you always commit your changes when you build a project for release, or when you shut down your computer for the evening. The point is, these are things that can be automated with small scripts through build events or even Windows Task Scheduler. Having a command-line tool is essential to such automation.

On the other hand, there are many times you will want to issue commands to SVN on-demand. A nice graphical user interface can make things much easier and faster for those tasks. Enter TortoiseSVN.

TortoiseSVN and the Shell

I like to think that the tortoise stands for something meaningful. Granted SVN was created as an alternative to CVS, which had TortoiseCVS. For me, it’s all about the shell!

TortoiseSVN Context Menu

TortoiseSVN integrates with the Windows shell. That means a lot in the way of usability. When you right-click a file from anywhere in Windows, you will see contextual items on the menu for TortoiseSVN commands. Personally, I think this gives much more value to the program than those that just mingle with integrated development environments (IDEs). I use SVN to control more than just source code. In fact, I consider my other project assets to be just as important (i.e. original design images, documentation, research, etc.). Integration with the shell means I can open Windows Explorer and start managing my files with TortoiseSVN.

Repositories

Repositories are where your files, and their many versions, are stored. There are many theories on how to organize your repositories, from creating one for each project to creating one for everything. I prefer creating a repository for each solution I am working on. That is, I create a repository for every application, website, or stand-alone library that I work on. My reasoning stems from the fact that I may need to invite new team members into the development process for a given application or website, and I want to be able to ensure they only have access to what they need. It also makes it very easy to move a repository to a remote, shared location in the future.

I do, however, store all of my repositories in a single directory on the computer chosen to host them. This makes for a very clean and trivial backup structure. I can easily backup all of my repositories by simply pointing to this root directory. I name mine, “SVNRepositories”. Aren’t I clever?

Use Templates

As a programmer and architect, I am a huge fan of templates. They make things so much easier. Creating stuff from templates is quicker and less riddled with mistakes. The idea of using templates to create your repositories may seem too trivial to bother with, but it does speed things up and ensures that you stick to a naming convention. Many recommend the following directory structure for repositories.

SVN Structure
- branches
- tags
- trunk

The trunk is where your primary development line will be maintained. You will commit most of your changes to the trunk. You will most often update your working directory from the trunk (more on this soon). The trunk is the latest official version of your solution. There are conflicting views on exactly how to use the trunk, but this is the most widely accepted usage of it.

Branches are there for you to try new things and to experiment with the solution/project. Create a branch when you do not want to mess up the trunk with possible breaking changes. Branching is most common when a new feature is being developed that will take some time to implement. You would create a branch from the trunk and begin working on the branch; committing and updating to and from the branch instead of the trunk. Once the feature is complete, the branch should be merged back into the trunk and become part of the overall solution.

Note: It is good practice to merge the trunk into a developing branch every so often, so the branch can benefit from any changes made on the trunk.

Tags are ideal for marking milestones for the solution/project. It’s a good idea to “tag” each release of the software, documentation, or the like. This allows you to time travel back to a release at a future point if you need to troubleshoot an issue with that old release, or to revert back to a release if things go awry later. For example, a diet-tracking website I am constantly improving upon will soon be sent to a buddy of mine for his personal use. Each time I send him an update, I will tag that release so I can instruct SVN to find the difference between then and now in order to send him a patch.

Create a directory on your computer that has the 3 sub-directories above in it. The sub-directories should be empty. Name the parent directory as your template structure so that you can find it later. I named mine, “SVN Structure”, and have it in a folder named, “Templates”.

New Repositories

Follow these steps to create a new repository that is consistent with the best practices discussed above.

Create a new sub-directory in your SVNRepositories directory. Make sure you give it a meaningful name for the project/solution it will manage.
Right-click the new sub-directory, hover your mouse over the TortoiseSVN context menu, and click “Create repository here”.
You should see a confirmation message that the repository was successfully created.
Navigate to your “SVN Structure” directory template, right-click it, hover your mouse over the TortoiseSVN context menu, and click “Import…”.
Enter/select the URL of the new repository you just created. If the repository is on your network, you will use a URL in the form of file:///X:/SVNRepositories/RepositoryName. Otherwise, use a valid Web URL for the remote location.
Supply a nice message for the import. I recommend, “Structure import.”
Click OK.
Enjoy the log displayed that informs you of the successful addition of the 3 directories and click OK.

Feel free to right-click on any folder and choose the “Repo-browser” item from the TortoiseSVN context menu. After entering/selecting the URL to your repository, you should see the new structure eagerly awaiting files to manage.

Working Directories

A working directory is where you make the changes to your files. These are standard directories that have hidden SVN sub-directories tucked away for change tracking and property management. The presence of these hidden directories is what enables the icon overlays and most commands on the TortoiseSVN context menu.

You can have multiple working directories; even for the same repository. In fact, if you are working on the trunk and a branch of your project/solution, you will likely want to have separate working directories, as opposed to switching back and forth between each. Simply, create another directory separate from your current working directory, and checkout the other branch or tag to the new location. Then, you can work in both directories and update/commit to the appropriate trunk/branch/tag for each.

Setting Up in a Clean Working Directory

Consider setting up version control before you begin working on a new project. It will make setup easier, and it will ensure that you can start committing changes immediately.

Setting up in a clean working directory is a cinch! After you have created your repository from the structure template provided earlier, follow these steps.

Create a new directory where you would like to start working on your project/solution (e.g. C:\My Documents\My Projects\New Project).
Right-click the new directory and click “SVN Checkout…”.
Enter/select the URL of your new repository.
Append “/trunk” to the end of your repository URL (i.e. file:///X:/SVNRepositories/RepositoryName/trunk).
Ensure that the checkout directory is set to the one you just right-clicked.
Keep the checkout depth set to “Fully recursive”.
Make sure the “HEAD revision” is selected.
Click OK.
Enjoy the success log and click OK.

You now have a working directory all ready to be filled with files. You may notice that the folder icon for your new working directory has a green check overlaying it (if you do not see it, refresh Windows Explorer until it appears). This indicates that no changes have been made to files in that directory. Considering there are no files, this makes sense.

Setting Up in an Existing Working Directory

If you already began your project and have files inside your working directory, don’t worry. It isn’t too much of a pain to get your working directory synchronized with your new repository.

After you have created your repository from the structure template provided earlier, follow these steps.

Create a new directory, anywhere you’d like, to hold all of your existing project files temporarily. I often just create a temporary folder on my desktop.
Move (not copy, move) all the files and folders that are in your existing working directory to the new temporary directory you created in step 1.
Your existing working directory should be completely empty now.
Right-click the, now empty, working directory and click “SVN Checkout…”.
Enter/select the URL of your new repository.
Append “/trunk” to the end of your repository URL (i.e. file:///X:/SVNRepositories/RepositoryName/trunk).
Ensure that the checkout directory is set to the one you just right-clicked.
Keep the checkout depth set to “Fully recursive”.
Make sure the “HEAD revision” is selected.
Click OK.
Enjoy the success log and click OK.
Move all of your files and folders back to the working directory from the temporary folder you moved them to in step 2.
Feel free to delete the temporary folder after you verify all the files/folders moved over.
If you peek inside your working directory now, you should see a blue question mark image overlaying your file and folder icons . This icon indicates that the files/folders are unknown to your repository at this time. In other words, they are not versioned yet. It’s time to fix that!
Navigate to the parent directory of your working directory, so you can see the working directory in the list of folders. It should have the green check overlay.
Right-click the working directory and click “SVN Commit…”.
Enter a nice message for the initial commit. I recommend, “Initial commit”, or similar.
Select all the files and folders you want to add to the repository (drag a rectangle around them with your mouse, or Shift/Ctrl click them), right-click one of them, and click “Add”.
If there are any files you want to ignore from now on, select them, right-click one, and click “Ignore x items by name”. You may also select a single file and choose to ignore it or all files with the same extension.
Finally, click OK to commit the files to your repository.
Enjoy the success log and click OK.

Your existing working directory is now under version control!

What Next?

After you have a repository setup and a working directory linked to it, there’s not much more to do except…get to work. Just update your working directory, make changes to your files, and commit the changes back to the repository at the end of the day (or sooner if you feel the need). Of course, there are some minor caveats to keep in mind in your daily use.

Special Actions

Adding and editing files under version control is a no-brainer. However, there are special considerations for file renaming and moving. If a file is already under version control and you want to rename/move it or delete it, you must use TortoiseSVN to accomplish this in order for it to properly account for the action. Truthfully, you can just delete files and TortoiseSVN will let you mark those files as deleted the next time you issue a commit. The renames/moves are the real trouble-makers if you just make those changes outside of TortoiseSVN.

If you need to rename or move a file, right-click it, and select “Rename…” from the TortoiseSVN context menu. Enter the new name of the file to rename it, or enter the relative path and file name if you want to move it (i.e. SomeSubDirectory\MyFile.txt). Alternatively, you can right-click-drag (drag with the right mouse button) the file to another folder and select “SVN Move versioned item(s) here”.

This will instruct SVN to delete the original file and add a new one with the new name/location. If you rename/move an entire folder, you must commit the changes before editing any files inside that folder. In addition, make absolutely certain that you do not rename, move, or delete a directory that is under version control except via SVN or TortoiseSVN. Doing so, will change those hidden SVN sub-directories and that would be very bad. For all the details on these actions, read the Deleting, Moving and Renaming section of the Daily Use Guide.