TOAD and SubVersion - A Quick How To. Norman Dunbar of Dunbar IT Consultants Ltd.

Transcription

1 TOAD and Subversion Introduction This file gives details of how to get your scripts, packages and so on under version control using SubVersion. Specifically I use TortoiseSVN as my GUI of choice - it integrates into Windows Explorer and is accessed via the right-click context menu. My version is 1.3. In addition to TortoiseSVN, you will need an SCC Interface between TOAD and the repository, as I use TortoiseSVN, I also use TortoiseSVNSCC as my SCC provider. Note A SCC is a required interface between your IDE of choice (TOAD) and the Version Control system you wish to use. If you have got a GUI like TortoiseSVN in use then you still cannot get TOAD to connect with your repositories until you install a separate SCC dll and register it. Links To emulate my own system, you will need TortoiseSVN, TortoiseSVNSCC and the Subversion Command Line tools (aka client). TortoiseSVN is available (for free) here : The TortoiseSVNSCC is available (for free) here : b uild zip (The above URL should be all on one line) If TortoiseSVN is not your chosen GUI then you might like to use the commercially available SCC from Push OK at this link : You will need to choose the correct version to match your version of SubVersion. In addition, this SCC may use the SubVersion command line utilities to do its job, so you may need those as well - the blurb is a bit confusing about whether or not the command line tools are needed. They can be found here : Page 1 of 13

2 SubVersion Documentation While not intended to be a complete listing of all known SubVersion web sites and books, the following might prove useful : The 'home' of all things SubVersion is at There is a free book on SubVersion which is a pdf of the O'Reilly book named Version Control with SubVersion and can be found here Another free book from the Bruce Perens' series can be downloaded for free from along with a number of other books from Bruce's series. The SubVersion FAQ is located at And a huge number of helpful links are located here Being open Source, of course, the full source code for SubVersion can be found at der=7495&folderid=0 Note that this is the source code for version 1.4 and the link may have changed as life moves on. You can always start from and follow the Documents and files link on the left. Page 2 of 13

3 Installation There is no particular order required for the installation of the above tools. On my system I used only TortoiseSVN for ages until I needed to create and backup a couple of local repositories for my own use. I found that while I can easily create repositories with TortoiseSVN, I needed the command line tools (as per section 4.2 in the TortoiseSVN help) to get the svnadmin command to do the backups. Once I discovered, from James Parkhurst at Quest, that TOAD could talk to Version Control Systems using an SCC interface, I 'Googled' for a suitable one. Finding the one that linked into TortoiseSVN I figured that it had to be a good choice, downloaded and installed the TortoiseSVNSCC package and all was well. TortoiseSVN Download TortoiseSVN and install it as per the instructions. You will require a reboot because TortoiseSVN integrates itself into the Windows Explorer shell. TortoiseSVNSCC Download the zip file and unzip it to the c:\program files\tortoisesvn folder that you installed TortoiseSVN into. This will create a new folder named, surprisingly, c:\program files\tortoisesvn\tortoisesvnscc. Beneath this there is a bin folder where the executables etc are stored. Open a DOS box, cd to the folder c:\program files\tortoisesvn\tortoisesvnscc\bin and run the command regsvr32 TortoiseSVNSCC.dll as per the readme file. That's it - no reboot required. Command Line Tools This is an optional step. Download the exe file for the correct version of SVN (the same version as TortoiseSVN is the correct one) and run the installer. This installs a number of command line tools, some documentation and all you need to administer SubVersion repositories. Push OK's SCC If you do not use TortoiseSVN then you probably need this SCC to connect TOAD to SubVersion repositories. It is not free - unlike the above - but a 30 day trial licence is available. The file that you download should be the same version as the version of SubVersion that you are using. Install it by running the downloaded *.msi file. When installed, you are prompted to register for a licence on first use. The registration process can be done easily on-line and is a matter of following instructions and prompts on-screen. Almost instantly, you have a registered system and can continue to use it for the next 30 days. Page 3 of 13

4 Warning you are required to stop using this SCC after your 30 day trial is over. If you wish to continue using it, you must purchase a licence. That's all there is to it - you are ready now to use TOAD and SubVersion together. Page 4 of 13

5 Configure TOAD. There are a couple of configuration options that need to be set before you can safely use TOAD and the SCC that you have just installed. I'm assuming TOAD version 9.x in the following description. Team Coding Go to View -> TOAD Options. Select Team Coding on the left and set the screen to look like the following : Leave everything in the top section unchecked. This means that you are using Legacy Source Control only and not the TOAD version where each and every database you want to access with VC has to have some TOAD objects installed. In the lower section, select your SCC provider form the drop down list. In my case, I have chosen to use TortoiseSVNSCC. If you have installed the Push OK system, then that will be your choice. The other options in the lower section are personal preference - in my case I want to always get prompted for a message when I add a new file or check in (commit in SVN speak) a file - so I have checked those boxes. Editor Options When using source control for a project, I like to make sure that I do not inadvertently change code in the editor and compile that without saving it back to the file that is under version control. To this end, click on Execute/Compile in the options screen Page 5 of 13

6 and uncheck the option to Allow compiling when source loaded from database. The screen should be similar to the following : On the same screen as above, the option to Set modified flag off after compiling from db. should be checked. This means that you don't have to commit changes to the file after saving it when you didn't actually open it in the first place - you simply compiled from the database. This is not really necessary because of the other option we set to prevent us compiling from the database - but it is a safe guard. TOAD is now configured for use with SubVersion. Page 6 of 13

7 Using Legacy Source Control Once you have your system set up as described above you can use TortoiseSVN (or the command line tools) to check out a local copy of the project's repository (this assumes that one already exists). To do this easily : Create a new folder using Windows Explorer Right-click within this folder and choose SVN Checkout as shown below : In the screen that appears, enter (or select) the repository you want a local copy of, the screen shot below shows an example : The URL of the repository is shown with an protocol. TortoiseSVN supports all manner of network protocols from local (file://) through to SubVersion's own svnserver protocol (SVN://). Simply pick (or type) the repository you want, or if it is local, click the ' ' button to browse to the local folder and OK it. Page 7 of 13

8 The Checkout directory is pre-loaded with the name of the folder you rightclicked on - this directory must be empty or the checkout will abort with an error. Click OK to start the process. All files in the chosen repository will be copied into your chosen local folder, so it could take a wee while - progress messages will be shown. If you navigate to the chosen local folder using Windows Explorer, you will find that a whole load of files have been copied down and a new folder (possibly hidden - I display hidden files in my configuration) named.svn (that's a leading dot) has been created. Note TortoiseSVN users will see that the icons for all these files are subtly different to the normal Windows icons - these can be quite useful in showing that the files are under version control. Now that you have this folder under the protection of SubVersion, you can switch into TOAD and start using the system. Page 8 of 13

9 TOAD's Source Control System We are ignoring the Team Coding part of TOAD which requires objects to be installed in each and every database that you wish to use Team Coding upon. All we are dealing with here is the Legacy system - which, in my opinion is very badly named :o) TOAD has a right-click context menu with an option of source control. This is reflected in the source control toolbar which looks like this : The buttons, shown greyed out at the moment, are as follows (from left to right) : Check file out - fetch a file from source control. Abort check out - revert back to the previous version of the checked out file. Check file in - check a file (the one in the editor) back into source control. Get latest version - Make sure that the current editor file is up to date. Add file - add a new file to the repository. Select active project - select the proper project. When you load a file into TOAD, from a SubVersion managed folder, the toolbar becomes active with no other actions from you required. If I navigate to the folder I just created and filled with files from SubVersion and open any file, the toolbar changes to the following : Now I can use the buttons (or right-click in the editor, select source control and whichever following option I need) to keep my file under control. If you load a file from a non-subversioned folder, the toolbar buttons remain greyed out. Page 9 of 13

10 Brief Overview of Source Control Options Check file out This option is probably redundant. It allows you to fetch a file from source control into the local working folder - but you already did that when you put that folder under version control! Abort check out When you have checked out a file as above, or loaded it from a SubVersioned folder, then made some changes, this option allows you to revert back to the previous version of the file and undo your changes. This will be done even if you have saved the file. Warning if you do choose this option, the file will become read-only and will not be editable in TOAD until you change the attribute using TOAD's right-click -> Read Only menu option. Other version control systems that work via SCC from TOAD also set the file to be read only on an Abort. This seems to be a feature of the SCC interface and not a bug in any particular version control system itself. This option doesn't access the repository, it looks under the files in the (hidden).svn folder and simply copies the version there over the top of the new one in the working folder. TOAD then reloads this reverted copy. Check file in When you have finished editing a file and all changes made have been properly tested, you check the file back into the repository. If you have selected the option to be prompted for a check in message, a dialogue will be shown which allows you to explain what changes were made. Always type something meaningful into this message - it could be very useful in future. Click OK and the file will be sent on its way to the repository - wherever it happens to be. That's it - you won't be prompted to say it worked, but you will/should get any error messages reported if it didn't. Note Using TOAD and SubVersion together in this way highlights a slight problem. You can only check in the current editor file. If you have changed lots of files, it would be nice to be able to check them all in as a single transaction under SubVersion. There is a workaround - see Caveats and Workarounds below for details. Get latest version This is similar to the option above to Abort Check Out however, this one goes directly to the repository and brings down the very latest version of the file from there. Now there are a couple of problems here : Page 10 of 13

11 If you have not saved the file locally, this option does indeed pull down the file (before you made changes) and re-loads TOAD with the unchanged version in an editable format. If, on the other hand, you have saved the changes locally, then this option does nothing - you now have the latest version. You must use the option above to Abort Check Out and reset the read only attribute using the right-click menu be able to edit it again. Add file Sometimes when working on a project, you create a new file. Simply use this button to add the file to the repository for the project. If you have the option set, you will be asked to provide a message to explain why you have created this new file. Please use something honest and meaningful - it may well be useful later in life. When you add a new file within TOAD, what appears to happen is an add followed by a commit (in SubVersion terms, other VCs call this a check in) as the file is fully committed to the repository. Select active project This button is also - apparently - redundant as you have effectively selected the project by the simple action of opening a file from a SubVersion controlled folder. Page 11 of 13

12 Caveats & Work-arounds The interface within TOAD is not set up to allow a project to have many files added or checked-in in a single 'transaction'. This can be a bit of a pain especially if you create or amend hundreds of files as part of a single update to your software. The workaround to this problem is quite simple, save the files as you edit them, but do not check them in (or add them) from within TOAD. When you have made all your changes and tested then to your satisfaction, use the Windows Explorer right-click menu and choose SVN Check in to check everything in. When the prompt for a message appears you will see a list of files being checked back in plus all the new files that have been created. Simply check the check-box alongside each of the new files and they will be added to the repository as new files. Enter the message and OK to commit the changes. The advantage of this method is simple, we are database developers and we know what a transaction is - a single operation which must either work in full, or be rolled back in full. SubVersion works exactly in this way, all the files for a single change will (should) be checked in and/or added together and not one by one in a piece-meal fashion. If we use the TOAD interface then we only check in (or add) the one file that is open in that tab in the MOE and that is committed as a single transaction. This means that we might have problems rolling back that transaction if we have to revert a change out of the repository. Page 12 of 13

13 Credits This document would not have been possible without help and assistance from the following people and/or organisations. Norman Dunbar of Dunbar IT Consultants Ltd, a TeamT member and all-round good guy. He is responsible for writing the above blurb and testing it all out. James Parkhurst of Quest Software Ltd, a QA member of the TOAD team and a very very helpful guy indeed. He's the one who explained to me exactly how TOAD uses the legacy source control system and how it works. In addition, James is happy not to be JTVCG or James The Version Control Guy at Quest. Bruce Perens et al for making their documentation freely available as well as in 'paid for' tree-ware format. I personally found that after having the pdf files of these books that I absolutely had to have the tree-ware version as well. I find those far easier to read in the bath. Tigris.org and Collabnet for SubVersion. The Tortoise guys and girls for one of the best Windows utilities (other than TOAD of course) ever written. Page 13 of 13