To quote from the Subversion Web site:

“The goal of the Subversion project is to build a version control system that is a compelling replacement for CVS in the open source community. The software is released under an Apache/BSD- style open source license.”

Version Control gives you a time machine for your files, enabling you to go back in time to any earlier version, see what changes have been made over time, and revert your work to an earlier version if need be. It also gives you an audit trail of changes and a commented history of those changes, amongst other capabilities.

The easiest way to use Subversion in Microsoft Windows is to use TortoiseSVN  To quote from the TortoiseSVN site:

“TortoiseSVN is a really easy to use Revision control / version control / source control software for Windows. Since it’s not an integration for a specific IDE you can use it with whatever development tools you like.”

TortoiseSVN  is a GUI client shell around Subversion and most anything that can be done on Subversion can be done in TortoiseSVN. TortoiseSVN (TSVN) includes Subversion (SVN), so you don’t necessarily need to download and install it.  I’m very pleased to say that both SVN and TSVN are very well documented, which is atypical in the open source world. As much documentation as there is, I still found it difficult to both comprehend how SVN works and to start using it.

I’ve been using a Version Control System for many years, so I understand the basics, however Subversion takes a different approach to what I’m so used to, which is part of the reason I’ve been stumbling along. The main areas of difference is that SVN works at the directory level and I’m used to working at the file level. And I’m used to having files that are checked out being “locked” so other users can’t edit them, but SVN doesn’t use this model, although it is available.

The intent of this article is to both help me in my quest to better understand SVN/TSVN and to also help folks who find themselves in this same situation.

By the end of this article you will know how to setup and use TortoiseSVN with your existing projects, and hopefully get there without facing the same hurdles I did. You will also know how to use TortoiseSVN with our Programmer’s IDE ED for Windows.

Lets get started and work through setting up TortoiseSVN, placing files under version control and then working with those files. Note that my discussion will revolve around version control use by a single person, so you will need to do some further reading regards multi-person and team use. I’m also focusing on setting up TSVN/SVN to use an existing directory tree of files, not creating a new project from scratch.

Installing TortoiseSVN

Step one is to download and install TortoiseSVN which you will find here http://tortoisesvn.net/downloads

TortoiseSVN integrates into Windows Explorer and is used via. right click context menu’s in Explorer and other applications such as our ED4W. Once TSVN is installed you can right click anywhere in Windows Explorer and choose TortoiseSVN|Help to read the detailed product help.

Creating a Repository

Step two is to Create a Repository to hold your versioned files. An SVN Repository is created in a folder on your local drive or on a networked drive. The repository contains a virtual file system where all of the files you place under version control are held and maintained, along with other metadata such as comments you add about file changes. A repository can be moved to a different location and of course backed up.

There are three ways to access an SVN repository. The simplest and the one I’ll be using in this article is to treat it as a local file system. The other two enable repositories to be stored on remote servers and accessed over the Internet. All three methods use a URL to access the repository, either file://, svn:// or http:// plus secure versions of these such as https://.

You need to decide where you want the repository created (which drive and base folder), then create a new folder to hold it. Right click on this new folder in Windows Explorer and choose TortoiseSVN|Create repository here… For this article the repository is in c:\svnrepos.

 

Leave the default ‘Native filesystem (FSFS)’ selected and click OK.

To learn about suggested Repository Layouts see Chapter 5.2.1 in the TSVN Help.

To create the example repository layout I’m using for this article follow these steps:

1. Right click on c:\svnrepos and select TortoiseSVN|Repo-browser.
2. Right click on “file:///C:/svnrepos” in the Browser window and select ‘Create Folder…’
3. Enter a name based on the project you want to use. eg. “Ruler”
4. Create three folders in this project folder: “trunk”, “branches” and “tags”

You should now have:

 

The “Working Copy”

In addition to the SVN Repository each SVN user has their own “Working Copy” of the repository. This is where you edit files and create new files etc. Note that you never access files in the repository directly, only via. the working copy. In fact if your peak inside the repository with Windows Explorer you can’t even see your files.

Adding an existing set of files to the repository

Our next step is to our add existing files to the SVN repository we just created, so that they can be put under version control. There are two ways to do this.

The commonly suggested method is to use Import – see TSVN Chapter 5.2.2. TortoiseSVN|Import… will import an entire directory tree, including all files, into the repository. I don’t like this approach because you have to Checkout the files to create your ‘Working Copy’, which is fine, except that you can only checkout into an empty directory. This means that if you aren’t putting all files and folders within a directory tree, under version control, you will have to merge the missing files and folders from their original home into the newly created working copy, which is messy and error prone.

The second method is to use TortoiseSVN|Repo-browser and Checkout the trunk folder (or a sub-folder) to the base of the directory tree containing our existing files and then Commit that directory to TSVN.

For this example I’ve created a Folder named “RulerSrc” within the “trunk” folder and my existing tree of source files is located in D:\MFC\Ruler. Right click on “RulerSrc” in Repo-browser and select Checkout.

The ‘URL of repository’ will already be set correctly and for ‘Checkout directory’ enter “D:\mfc\Ruler” and press OK. Then press “Yes”  at the “D:\mfc\Ruler” isn’t empty prompt. Windows Explorer will now show “D:\mfc\Ruler” with a checkout overlay image.

 

Now we need to add the files and folders for “D:\mfc\Ruler” to the repository. This is where I faced my biggest hurdle, as I didn’t want to include all of the files and folders in my existing directory tree in the repository. I’m referring to temporary files, such as compiler output files and entire directories such as \Debug and \Release. It took lots of reading and a few posts to the TSVN mailing list before I knew how to handle this.

Excluding files and folders from the repository

It was clear from my reading that you use ‘Add to ignore list’ to inform SVN about which files and folders you don’t want added to the repository. However before ‘Add to ignore list’ can be used on a file or a folder, the parent folder must be added to SVN. As I commented on the mailing list: “This just seems backwards. ie. I have to ‘Add’ things before I can ‘Remove’ sub-things.” It would be far simpler if I could simply submit a list of files and folder paths to ignore, to a folder in the SVN repository.

The SVN Book and TSVN Help both state that you use the Ignore option before using Import or Add, but neither tell you that you can only use Ignore (svn:ignore) on folders that SVN is already aware of. It is basically a chicken and egg situation. See the FAQ item How Can I select files and folders to import. 

TSVN/SVN does enable you to specify a Global list of files and folders to exclude, however this list affects every SVN repository that you create, every project in every repository and every user using the repository. This is fine for files that makes sense to be ignored on a global basis, such as transient and temporary compiler output files, but is too course grained for other exclusion requirements. That said you should definitely setup the TortoiseSVN|Settings|General|Global ignore pattern. Do this now before proceeding. See TSVN Chapter 5.26.1. for details.

 

Adding and excluding files and folders

So back to ignoring files on a per project and per user basis. As I stated above we need start by Adding all of the folders and files we want included in the repository. To do this use TortoiseSVN|Add.

An important point to be aware of is that “Add” doesn’t actually add anything to the repository. In fact you don’t even need access to the repository to use Add, which is an important capability for folks that create new files, but aren’t always connected to the repository. Add simply adds the chosen file or folder name to a list, which is stored in the .svn directories of your local ‘working copy’. When you next Commit your changes, this list is used to help build the list of files to be committed.

Note that TSVN works with three categories of files; Versioned files (those in the repository), Unversioned files (files which aren’t in the repository) and Ignored files (unversioned files which are ignored during Add, Commit etc).

Apart from adding the files and folders “you do want” in the repository, you must also add all of the folders that contain files that “you don’t want” in the repository. Only then can you use ‘Add to ignore list’ for every folder and file that you want excluded from the commit process, and hence the repository.

Don’t add folders for directory trees that you don’t want in the repository. Add their parent folder and then use ‘Add to ignore list’ on the folder to exclude it and its sub-directories.

You don’t actually have to add files here as you can select them when you do the commit. Use whatever works best for you. Folders are the important thing, so we can use ‘Add to ignore list’ on files in any required folder.

If you add a file by mistake use TortoiseSVN|Revert… to remove it from the ‘add list’. And if you ignore a file and then change your mind, use TortoiseSVN|Remove from ignore list.

Note that ‘Add to ignore list’ is not available for files or folders that match the Global ignore list patterns, nor for files added to the queue.

Once you’ve completed the Add and Ignore processes you can finally get the files into the repository.

This picture shows the overlay images in Windows Explorer after we’ve added files and before they are committed.

Getting committed

Whenever you want to update the SVN repository so that it includes the changes you’ve made in your ‘working copy’ you need to commit your changes. To do this right click on “D:\MFC\Ruler” in Explorer and select ‘SVN Commit…’ from the context menu.

In the Commit Dialog write a message stating the reason for this commit. Enable ‘Show unversioned files’ if necessary and verify that all of the files you want to place under version control are checked, then click OK. Commit then adds all of our existing files and folders to the repository and Explorer changes as shown here. The Debug folder is in the ignore list, which explains its overlay image.

 

To verify the contents of the repository use TortoiseSVN|Repo-browser.

Following this second method enables you to use your existing files and folders as is, without the issues raised if you were to use Import. I borrowed this from technique from here.

 

Working with the Repository

Ok so now we have an existing project under version control, what next.

• Note: In the scenario I’m writing about here, we have a “Working Copy” in place, but if you don’t, you need to Checkout the relevant directory tree from the repository into an empty directory to create your working copy. Use TortoiseSVN|Repo-browser for this.

You can now edit your files as you normally would. If you create a new file you can use TortoiseSVN|Add to add it to the pending queue, or alternatively select the file from the non-versioned list of files at the next commit.

You can see the changes you’ve made during editing by viewing what’s different between it and a versioned copy of the file in the repository. TortoiseSVN|Diff does this. Diff is also on the right click context menu inside TortoiseSVN|Commit… and TortoiseSVN|Check for modifications…

This picture shows the TortoiseSVN context menu activated on the current file in ED for Windows, ready to do a Diff.

You can use EDs Difference Analysis to view and merge differences by adding it to TSVN. Use TortoiseSVN|Settings|External Programs|Diff Viewer and set the External option along with:
“C:\Program Files\SAIG\ED4W\ED32.exe” -1- -np -nf -diff %base %mine
as shown here.

See TSVN Help section: 5.9. “Viewing Differences” for more information.

When you are satisfied with your editing and want to update the repository so that it includes your changes, it is time to commit the file. If you’ve edited a number of files or added some new files, then it is best to commit the base folder. ie. Right click on the folder in Explorer or EDs Files Tree and choose: SVN Commit… If you just want to commit the changes for a single file, then you can do that as well by selecting the file in Explorer or ED and using SVN Commit…

If you are working with other users then you need to use SVN Update to resolve any conflicts that come about from someone else editing the same files as you have. See TSVN Chapter 5.5. “Update Your Working Copy With Changes From Others” for details.

 

Using ED for Windows with TortoiseSVN

The Windows Explorer TortoiseSVN menu commands can be used directly inside ED for Windows. This enables you to commit a file or a folder, update it, view differences etc.

TortoiseSVN is available from EDs Explorer context menu. To open ED’s Explorer menu right click on whitespace in an editing window, use File|Explorer or right click on a file in the Project window. To access the Explorer menu for a Folder, right click on the Folder in ED’s Files Tree (File|Files Workspace).

 

You can also execute any TortoiseSVN command directly from ED using TortoiseProc.exe as documented in the TSVN Help: Appendix D. Automating TortoiseSVN

To open the TSVN Repository Browser from ED, for a specific repository, you can use:
File|Run Program… “C:\Program Files\TortoiseSVN\bin\TortoiseProc” /command:repobrowser /path:”uri/to/repository” /notempfile

This could be setup as an ED Macro or on a Toolbar button. You could also get ED to prompt for the repository URL.

To commit the current file you would use:
“C:\Program Files\TortoiseSVN\bin\TortoiseProc” /command:commit /path:”<name>” /notempfile /closeonend

Again this can be assigned to a toolbar button, menu etc.

 

Finale

The focus of this article is to help you get an existing code base set up under version control as quickly and easily as possible. However there is a lot more to TortoiseSVN and Subversion than what I’ve covered here. I would urge you to read the Subversion Book and the TortoiseSVN Help thoroughly before committing yourself and your team to using it.

Ruby enables you to do more than other languages in less lines of code and still be reasonably readable, and important asset for any language. The library that is included with Ruby is the most comprehensive I’ve seen, which means there is less searching out other libraries or having to write your own code. The bottom line is simply that you should be more productive writing in Ruby than other languages, which is pretty important in todays fast paced world. And if you can do more with less code, there should be fewer bugs, right!

There are however a few things that concern me with the Ruby language. First up whitespace is relevant, which is pretty unusual in a programming language. For example: id = “%x” % (ab * 2) is completely different to: id = “%x” %(ab * 2). In the second fragment there is no space between %(.

My next concern is that you can’t declare variables, you just use them when and wherever. The problem here is that if you make a simple typing mistake you’ll have two (or more) variables instead of the one and probably won’t know until you (hopefully) discover the code isn’t working as expected. For example:

if thelight == 1
  tehlight = 0  # typo
end

The Ruby interpreter won’t complain about this and thelight will never get set to 0. Other dynamic languages also work this way, so Ruby isn’t alone, but PHP for example provides an option where you are forced to declare variables before use. Ruby would really benefit from this.

Ruby + ED for Windows

Developing ED4W language support for Ruby was difficult. Ruby code can be ambiguous when looked at in isolation and this poses many challenges for editor writers. In fact, I spent some time looking at the other editors which support Ruby and was quite surprised at how poorly they faired. Syntax highlighting was often wrong and this is the area which is so important in helping you quickly see mistakes as you are writing, instead of waiting for the Ruby interpreter to point them out and getting wound up waisting time with unnecessary edit-compile cycles.

Aside from extensible syntax highlighting ED4W delivers a range of capabilities to help you write code faster, and not just in Ruby but in a wide range of programming languages. I’ll quickly run through some of these.

This short code fragment was written without pressing the space bar or tab key and without typing and end’s. EDs smart indenting took care of all of the indenting and its code templates filled in the ‘end’ statements.

Another way to automatically complete blocks of code is using code completion. If the example above was:

Then pressing Enter followed by Escape would give you:

And pressing Enter and Escape once more will give you:

Code completion works out what text needs to be added to close the current block of code. It works with simple text such as brackets [ { and ( to add ) } or ] and more complex elements as shown above.

Another important ED feature is shown in these two screen shots and that is the matching if-end and def-end statements are highlighted. I assume all editors these days highlight matching brackets and let you jump to and from the opening and closing brackets, but ED takes this further and enables you to jump between any statements that form blocks of code as shown here.

 

 

 

 

 

 

Statement matching and code completion are two more ways ED helps you code faster. Smartype, Autocorrection and Parameter assistance also come to the party.

Code templates write complete blocks of code for you. You simply type the templates abbreviation or pick it from the Skeleton window and ED does the rest as shown here.

 

 

 

 

 

 

I’ll end this section by touching on some of the other ways ED will help you write code faster. Macros automate text manipulation operations, full Regular Expression search and replace both within and across files and projects, Filter searches to exclude syntax elements such as comments and strings, Difference Analysis highlights changes in files and enables them to be resolved, Persistent bookmarks keep your place across editing sessions, Comment/uncomment blocks of code, Select text by character, column and line, Spell check and correct, Run compilers and navigate through errors in the source, Open include files and Configure and extend ED to work the way you want to.

To finish I want to show you how ED can help navigate around your code and enable you to work directly with modules, classes and methods so that you no longer have to remember which source file they are in or where that file is located. To accomplish this ED has a built-in Source Database Engine (SDB) which parses your source code in the background to build a database of all methods, classes etc., which you can then access in an instant. Lets see how easy this is.

 

 

 

 

 

Class View displays a tree of all modules, classes and methods for all of the Projects which are currently open.

 

 

Double click on any item to open its source file and jump to it. Class View is opened using View|Workspace then click on the Class View tab. To locate a method etc. in the current source file in the class view, right click on whitespace inside the method and choose “Select current item in Class View”.

ED also makes it easy to move around by method, class or module within the current file, by selecting from the drop-down combobox on the Navigate Toolbar. And Goto|Next Function and Goto|Previous Function do what they say.

 

 

To use the Source Database you need to create a Project and add your source files to it. All files in the project are included in the database. The SDB is updated in real time as you edit code, so it always truly reflects the code.

A sample project for the Ruby library source code is included in the ED Download and is placed in C:\Program Files\SAIG\ED4W\Sample Projects. Copy Ruby Source.edp to a working directory and then use Project|Add Project to Workspace to add this to your own project. This will give you instant access to all Ruby modules, methods and classes.

To run Ruby on the current source file, click on the this button  on the Build Toolbar. Use View|Toolbars|Build to open it if necessary. Any errors are shown in the Output window and Goto|Next/Previous Error navigate through the errors in the relevant source files.

There is a lot more to ED that I could tell you about, but would you keep reading! Probably not, so let me wrap this up.

EDs combination of powerful cross language editing capabilities plus source code navigation and browsing will surely help you code faster and not just in Ruby, but in most mainstream programming languages.

PS. Try Ruby! lets you give Ruby a quick 15 minute workout in your Web Browser. Highly recommended.