Monday, July 7, 2008

Starting out with Delphi and subversion

I am always disturbed by the number of programmers I run into who don't use version control. A version control system (VCS) is one of the fundamental tools of a programmer, up there with the ide/compiler, bug tracking and backups.

Subversion, together with the TortoiseSvn plugin for Explorer, is one of the better free VCS solutions available. What follows is a quick guide to setting it up the easy way.

Note: This setup is not suitable if you have a large number of users, or need to provide access across the internet.

Tortoise and Subversion

Subversion is the actual VCS. Typically you would run it as a service and then connect to it with client software such as Tortoise.

Tortoise adds context menus and icon overlays to Explorer allowing control of the VCS. These menus and overlays are also available in programs that use the Explorer menus and icons such as the Delphi File Explorer.

Other clients for Subversion are also available.

If you only have a limited number of users, and do not need remote access, you can use Tortoise without a subversion server. This makes set-up much easier. I am not going to cover setting up the server here, primarily because I haven't used one for 3 years.

My file structure

I have 2 base folders, D:\dev and d:\devother.

D:\devother\ is used for files that are use different version control settings (ie open source projects that I update from their repository such as tiopf).
D:\dev\ is used for everything else; my code, third party components, images etc. Having everything under one folder makes version control easier.

I recommend moving all source under a single base folder, if it is not already. If you have source on a network share, move it into a base folder on a local drive. If you need to share source, place the repository on a shared folder.

Repository

The repository is where the versions are stored. It has a directory structure similar to a file structure.

The subversion book recommends having the following directories at the repository root

/branches/
/trunk/
/tags/

With this layout, your main development takes place under /truck/. Branches and tags go where you would expect. I don't do a lot of branching and tagging, when I do I place the branch directories along side the main project directories instead. Therefore I don't bother with the initial directories and create branch directories as required.

My layout is more like

/components/
...
/projects/
/projects/project 1 v1/
/projects/project 1 v2/
...

This maps to my file structure of

d:\dev\
d:\dev\components\
...
d:\dev\projects
d:\dev\projects\project 1 v1\
d:\dev\projects\project 1 v2\
...
etc

It is reasonably easy to change from one repository layout to another if you change your mind, so choose whichever structure makes sense to you..


Setup
  1. Download and install Tortoise from here.
  2. Open Windows Explorer
  3. Create an empty folder to serve as your repository. This can be local or on a network drive. The location needs to be reasonably safe and easy to back up.
  4. Right click on the folder and click on "Create repository here"
  5. Choose "Native filesystem"
  6. If you want to set up /branches/, /tags/ and /truck/ directories, right click on your repository folder and choose TortoiseSvn -> Repo-browser. Right click on the root directory and choose "Create Folder" for each of the initial directories.
  7. Right click on any folder and choose TortoiseSvn -> Settings
  8. In the Global ignore patterns, enter in the file types that should be ignored by default. Ie things like map files that will (almost) never need to be under version control. I use "*.dcu *.~* dcu temp *.exe *.zip *.bkm *.ddp *.cfg *.dof *.dsk *.ini *.hlp *.gid *.bmp *.png *.gif ~* *.log bin debug release *.map *.chm *.bkf Thumbs.db *.mdb .obj *.elf *.stat *.ddp *.bpl *.map *.GID *.hlp *.opt *.dll *.raw *.BIN *.obj *.pdb *.scc Debug Release *.xml obj *.~* *.backup *.INI *.ArmLog *.KeyLog *.NanoLog *.Stats *.PreARM *.old *.drc *.*~ *.doc *.pdf *.bmp *.jpg *.MRW *.NEF *.ORF *.psd *.X3F __history *.local *.identcache *.bak Thumbs.db *.ldb *.dex *.rar DllDcu *.lck CVS cvs *.txt *.TXT *.jdbg *.HLP *.KWF *.xls *.cnt *.dsm *.dti *.tmp *.lnk *.cbk *.mes"
    Note that the patterns are case sensitive.

Initial Import
  1. Back up your source code!
  2. Right click on your base development folder (I use d:\dev\) and click on "SVN Checkout"
  3. Click on the browse button beside URL and navigate to the repository directory (if you have set up a /trunk/ directory, navigate to this).
  4. Right click on your base development folder (d:\dev\ in my case) and choose TortoiseSVN->Add.
  5. Wait for the Add dialog to populate. The first time it is used, it can take a while to populate. Work your way down the file/folder list.
    If there is something you don't want to add now, uncheck the selection box.
    If you never want to add it, right click on the item and choose "Add to ignore list"
  6. Once you are happy with the selected files and folders, click OK.

    The files are now all added to version control. However they have not yet been saved (committed).
  7. Right click on the base development folder again and choose Commit.
  8. Provide a message.
  9. Uncheck any files you don't want to commit at the moment and click OK.

Your files are now under version control. You can revert to any version, perform diffs, see what files are changed and perform all other sorts of good things.

Version controlled files are marked to indicate their status. A full list is given here. The main ones are
  • Committed: Check mark
  • Added: +
  • Changed: !
  • Deleted: x



To come
I will do followup posts explaining
  • How to work with files on an ogoing basis
  • Various delphi integration options

Links
Subversion http://subversion.tigris.org/
Subversion book http://svnbook.red-bean.com/
Tortoise http://tortoisesvn.tigris.org/

15 comments:

David Novo said...

Great post. The only suggestion I would make is to point people to visualSVN Server (http://www.visualsvn.com/server/). It is free, and makes setting up the repository a breeze and allows for providing access over the internet etc.

Sean said...

David,

Thanks. I will look into that for a follow up post.

Ritsaert Hornstra said...

Just our ideas:

I use a single repository for all shared and 3rd party components. All are packages under a single project group so a new developer can setup his Delphi very quickly.

For each customer / product family I create a single repository. This allow me to give the customer read access when needed, backup projects separately etc.

As a build number in the version info I use the project repository revision number and the components repository revision number as the last two numbers in the version info. This allows us to give out small incremental changes within each branch without generating a lot of branches.

techinorg said...

ritsaert mentioned that he used a single repository for all shared and 3rd party components. I am new with Delphi, so I just wonder: How do you manage components that needs to be installed (adding to the registry etc)?

(Here's what I did: http://techinorg.blogspot.com/2008/02/new-use-for-subversion.html)

Jens Fudickar said...

I would suggest to have a look at the actual JCL.

It has an expert which uses TortoiseSVN (CVS also) to integrate the subversion into the delphi environment

Sean said...

Jens,

I will cover the jcl expert (and a few other add ins) in a follow up post. I use the jcl expert myself.

Ritsaert Hornstra said...

@techinorg:

We currently only use open source components but have used installed components. What I (usually me) did was install the components, copy the sources into the tree cleanly and de install the components again. Then build the package from the clean tree and after checking that all works well checkin the new package with the components pas files.

carneyj95 said...

We are using Delphi 2007, SVN and Synchroclient 3.2. We have multiple trunks and versions to deal with and offers a few things tortoise doesn't. Plus it doesn't bog down the system (update/sync) on demand instead of automatically.

Negative...if you are used to Team coherance, get ready for a big letdown. To move things from lets say 'development' to 'testing', you have to export, then submit as a new trunk.

Thomas Mueller said...

Just to plug my own article on that subject:

http://www.dummzeuch.de/delphi/subversion/english.html

rif said...

Some weeks back I wanted to setup a Subversion server for personal use. However I found that it require Win XP, it will for some reason not install on Win 2000. Do you have any idea why Win 2000 won't do? Do you know a simple workaround for running it on Win 2000 anyway?

In case not I will look into installing it on my Linux server instead.

Doei RIF

Sean said...

Rif,

I have posted a few options in http://sourceitsoftware.blogspot.com/2008/07/subversion-server-options.html.

Serg said...

If you are about to write more about TortoiseSVN, please pay attention to the broken repositories. It happens after power failure while making commit. The files themselves seems to be good and I`m quite sure it is possible to restore previous repository state, but TortoiseSVN just refuse to work with the repository.

Sean said...

Serg, I will be writing another couple of posts on subversion. However I have never had that problem, so I don't know how to fix it.

IL said...

Thanks a lot for the post. Somewhat deduplicated ignore pattern: "*.dcu *.~* dcu temp *.exe *.zip *.bkm *.ddp *.cfg *.dof *.dsk *.ini *.hlp *.gid *.bmp *.png *.gif ~* *.log bin debug release *.map *.chm *.bkf Thumbs.db *.mdb .obj *.elf *.stat *.ddp *.bpl *.GID *.hlp *.opt *.dll *.raw *.BIN *.obj *.pdb *.scc Debug Release *.xml obj *.backup *.INI *.ArmLog *.KeyLog *.NanoLog *.Stats *.PreARM *.old *.drc *.*~ *.doc* *.pdf *.bmp *.jpg *.MRW *.NEF *.ORF *.psd *.X3F __history *.local *.identcache *.bak *.ldb *.dex *.rar DllDcu *.lck CVS cvs *.txt *.TXT *.jdbg *.HLP *.KWF *.xls* *.cnt *.dsm *.dti *.tmp *.lnk *.cbk *.mes"

Sean said...

Some of the duplicates are due to case sensitivity (eg *.txt *.TXT), others are just to make really really sure the file is ignored. Or an accident, take your pick:)