1.4 Introducing TortoiseSVN

This is an introduction to SVN, using WANdisco's uberSVN and the trusty Windows client, TortoiseSVN. In fact, you can think of this tutorial as a set of TortoiseSVN water wings, aimed at developers who have been thrown into SVN at the deep end. As well as getting TortoiseSVN installed, it'll show you how to get your working copy in place and your first changes made to the repository.

Upgraded to SVN 1.7, but now your working copy won't update?
See our tutorial on Upgrading your Working Copy.

Installing TortoiseSVN

• 1. Download the latest version of TortoiseSVN - http://www.wandisco.com/SVN/download#tortoise
  It comes in 32-bit and 64-bit flavours, get the one that matches your system.


• 2. Double click the installer file.
  

  Download.

• 3. Click the Run button.
  

  Run!

• 4. You'll see the welcome screen, which will confirm the version of Tortoise that you're about to install. Click Next >
  

  Welcome!

• 5. Read the End-User License Agreement. If you're happy to proceed, click the 'I accept the terms in the License Agreement' radio button and then click Next >.
  

  Agree!

• 6. The Custom Setup screen lets you deselect various elements of the install. Unless you are really low on disk space, it isn't worth worring about this. When you're ready to continue, click Next >
  

  Deselect unwanted bits.

• 7. Click Install.
  

  Install!

• 8. Hey presto! Tortoise is now installed. Click Finish.
  

  Finish!

Checkout your working copy

What's a working copy?
A copy of all or part of a repository that is stored on your computer. You can edit these files however you like, as changes won't apply to the repository until you decide to commit them - usually after you've thoroughly tested them. Your working copy is your own private work area: SVN will never incorporate other people's changes, nor make your own changes available to others, until you explicitly tell it to do so. Bonus!

• 1. Make a new directory for your local copies. Open Windows explorer, go to the new directory and right click within the folder space. The Explorer context menu appears, along with SVN commands that are added with TortoiseSVN.
  Click on the option 'SVN Checkout....
  
  

  SVN Checkout...

• 2. You'll be prompted for the URL of the repository on which you want to work.
  

  Repository URL.

URL of repository

The address of the repository, or portion of a repository for which you want to make a working copy.

Checkout only what you need
If you include in the address a subdirectory, the checkout will ignore anything in the repository that is above the directory. This is very useful as it lets you quickly checkout a small part of a repository that might take a really long time to copy. e.g.

Checkout the whole repository: http://10.2.5.2:9880/zelle/
Checkout just a directory: http://10.2.5.2:9880/zelle/trunk/genshla01/
Checkout just a file: Alas, you can't. SVN needs to organise working copy data using directories as its own 'housekeeping' data needs to live in a hidden subdirectory. There would be no opportunity to create a subdirectory if you checked out only a file. The workaround is to use the "Checkout Depth" option to checkout only directories, then perform selective updates on the things you need.

You can get the repository URL from the repository's screen in uberSVN:

Repository URL from uberSVN.

Checkout directory

This is the location on your local file system where the checkout will occur. By default it will be the location that you're currently focused on in Explorer, however you can change it here.

Checkout Depth

• Fully recursive
  All files, and folders below the checkout point.
• Immediate Children, including folders
  All files and folders, but don't populate the folders.
  
• Only file Children
  Only files, don't checkout folders.
  
• Only this item
  Only checkout the folder, no files or child folders.

Revision

You can get the latest version of the repository, called 'HEAD' (most up-to-date version), or select a specific revision to go back to a version before particular changes.

• 3. When you've finished with these options and you're ready to do the checkout, click OK.


• You'll now see the progress of the checkout. All files and folders that are included in the checkout will be logged.
  

  the files, they are a changing.

Making a change

You change the files in your working copy in the same way you always have, but to apply your changes to the repository you need to perform a SVN Commit, here's how:

• 1. The working copy is now in place on your computer, ready to edit and change to your heart's desire. One of the benefits of Tortoise as a shell replacement is the fact that it can overlay repository files with status icons that tell you the current state of each file.
  


• 2. We'll now make a change to a file. In this example the file 'system.txt' will be modified and saved.
  

  Working copy with no changes yet.



• 3. You'll notice that once saved, 'system.txt' now has a different icon overlayed, showing an exclamation mark in a red circle to denote that it has been changed.
  

SVN Status Overlay Icons
	Normal status - No change has been made to the element.
	Added - Has been introduced to SVN, but not committed yet, so will not be available to other repository users.
	Modified - The element has been modified since it was checked out or updated. It will need to be committed to return to normal status.
	Read-only -The element has been set to read-only. Naturally, you won't be able to commit any changed to such a file.
	Ignored - SVN lets you deal with derived files that shouldn't be managed by version control by setting them as ignored.
	Conflict - The element has been modified and committed, but the commit action failed because SVN was unable to merge the changes. Usually happens when the file has been changed since it was checked out, and SVN is unable to merge both sets of changes.
	Locked - While locking files is contrary to SVN's Copy-Modify-Merge model, it's available if you absolutely don't want sticky fingerprints on important files.
	Unversioned - is an optional overlay that can distinguish all elements that are not under version control, but which have not been explicitly ignored.

When overlays go bad...
The above overlays are really useful, unfortunately, due to a Windows limitation, other utilities that modify the shell may cause the overlays to disappear. You see, Windows 7 can only support 15 different overlay icons. Should you install something like Dropbox, it could displace some of the TortoiseSVN overlays. A re-install of TortoiseSVN won't fix the problem, although if you're brave/foolhardy enough to tinker in the registry, it's possible to mitigate the problem.




• 4. Having tested the change, it's time to add it to the repository. To apply changes to the repository that you've made in your local copy you need to use the SVN Commit command. You can select individual files or their directories, then right click to get the context menu. On the menu, click SVN Commit....
  

  SVN Commmit.



• 5. You'll be prompted for a message to associate with the changes you've made. It's human nature to try to leave this blank because you're in a hurry and can't be bothered, but simple log messages can really help with troubleshooting problems at a later date.
  


• 6. The outcome of the commit will appear in a dialog window. If the commit was successful the repository's revision number will increase. Click OK. That's it, you're working with version control.

Adding something new

If you create a new file or folder, adding it to the repository is a two step process:

• 7. Having created a new file (or folder) you can't just commit it because SVN doesn't yet know it yet. So first, right click the file and choose Add... from the SVN commands.
  


• 8. The added elements should now appear in Explorer with the 'added' overlay icon. Although SVN now knows about the file, you still need to perform a commit. So again, right click the file and choose SVN Commit... from the menu.
  


• 9. It's always good practise to leave a note, whenever you do a commit. While SVN gives you lots of tools for scutinizing file changes, it's nice to have a quick summary to look back on. To complete the commit, click OK.
  


• 10. You'll get a log of the commit, confirming that your new files are now part of the new repository revision.