Subversion & TortoiseSVN: Installed and started on Windows 2003 server and local machines

An article on installing and implementing Subversion version control software and TortoiseSVN the client interface tool for Windows machines.

Introduction

In this article I will walk through the process of installing Subversion and getting started using this very useful version control tool. I chose Subversion based on its ease of use and understanding, the documentation provided is very easy to understand and navigate through, also you can't beat the cost - FREE.

I've laid out this article in a step by step method using the practices that I feel give the best results for my situation, there are always ways to customize this process and I will mention some of these as the steps progress.

Notes:

To clarify some terminology -

When I mention 'Explorer' or 'explorer' I'm referring to the Windows file manager.

Subversion will be referred to as SVN

TortoiseSVN will be referred to as TSVN

Some of the pictures in this article have been resized.

I've written this article with the beginner in mind, some of the steps and images may seem redundant and unnecessary but I included them so that there would be as little confusion as possible.

The names and aliases used in this article can and probably should be changed to meet your needs.

*There is a One-Step process that installs SVN, TSVN, sets up the service, downloads the documentation, and creates the first repository - http://svn1clicksetup.tigris.org/ I didn't take this route because I wanted a little more control and understanding of what I was putting on my machines.

Now to Business

I. The first thing I recommend is getting yourself a copy of the most recent Subversion Manual. This will be good for future reference when you want to get more involved with the finer points. http:\\svnbook.red-bean.com\, I recommend the .pdf version as this will allow you to save a copy to your desktop, you can also download a one page HTML of the same documentation.

*Note – At the time of this article the documentation that is posted is from SVN version 1.3, but most of the data presented is current with the exceptions of the latest additions. The documentation is still good for use as a reference.

**It's absolutely critical that this file be place here as it needs svnserve.exe to run properly. The other files are not needed for the service to run but you can extract them to the bin file as well for a reference.

c. Open a Command Window

d. Enter 'svnservice –install –daemon - - root "d:\AppRepositories

i. This sets the service to run in the background (daemon) and sets the root directory to the file that holds the repositories (d:\AppRepositories).

e. SVN is now set up as a service

f. Now that SVN is set up as a service on the server you can access it programmatically from the command line and later the TSVN interface using the following format - svn://(ServerName)/(RepositoryName)/ProjectSource/trunk

**Notice that the actual drive (D:/) as well as the folder holding the repositories (AppRepositories) are missing from the command, this is now using the 'root' that was specified in the service creation command.

g. Now to further configure the service go to Start -> Control Panel -> Administrative Tools -> Services

h. Navigate down to SVNService and double click the service. Change 'Startup type:' from manual to Automatic

i. Now SVN will start every time the server boots up.

j. Back in the services screen, click 'Start' in the upper left of the right pane OR click the 'play' icon in the menu tool bar to start the service

c. Within this folder place all project repositories.**It is possible to place several projects within the same repository but I would not recommend this as there is a chance to get some of the code mixed or replaced inadvertently. It might be beneficial to do this if the repositories that will be grouped are similar in style or use the same resources.

d. Also create a folder within the AppRepositories directory named 'config'. This folder will hold the shared passwd file for all subsequent repositories. **This step is not necessary but it makes manageability much easier.

i. 'mkdir d:\AppRepositories\config'

ii. **We'll put the passwd file into this new folder a few steps down the road, when we set up the repositories' configuration.

e. Now create the first repository, I recommend using the same name for the project as the repository name.

i. 'svnadmin create d:\AppRepositories\((ProjectName))'

f. Once the repository has been created we'll need to create another folder within the repository itself to hold the working directory of the project. I've added the subsequent folders for my own benefit as I feel that this method makes it easier to understand.

ii. This subfolder is needed to house the trunk, branches, and tags folders that actually hold the working code. The main repository ((ProjectName)) will still handle the versioning of the project. This folder and those created in the next few steps will need to be created for all repositories.

iii. The trunk folder is where you will store the source code, or working code. The tags folder is used to hold 'snapshots' of the project, i.e. to present version 1.0.22. The branches folder is used to hold the branches of the project, basically the same code but with different functionality, i.e. taking the application in a new direction.

g. Upon creation of the 'ProjectSource' folder a log file will appear in notepad

**On the top line above the '- -' enclosed line enter a description of the action, i.e. 'Initial creation of the projectsource folder to hold trunk, branches, and tags source folders.'

h. Click File -> Save -> close notepad

i. Once the log has been saved and closed the command prompt will display 'Committed revision 1'. Each subsequent change made will be a revision to the repository.

**On the top line of the log file above the '- -' enclosed line enter a description of the action, i.e. 'Initial creation of the tags folder.'

vi. This is revision 4

k. All the necessary folders are now created and in place. The next step is to configure access to the repository. **This step can also be done right after creating the repository

l. Open an explorer window and browse to D:\AppRepository\((ProjectName))\conf

**Note: you will not see the files just added in the explorer window (ProjectSource, trunk, branches, tags) but not to worry they are there but stored in the repository at their respective revisions and still available for access.

m. With the conf file open make a copy of the passwd file and paste it into the config file of AppRepositories that we created earlier.

i. **This step is not necessary, each repository can have its own list of users with their passwords. If you elect to use this method skip to step r.

n. Open the svnserve.conf file.

**If prompted to select which application to view this document in, choose notepad.

o. Under the [general] section, uncomment the auth-access, anon-access, and password-db lines.

i. Delete the '#' symbols, be sure to leave no spaces on the line before the start of the text.

p. Set password-db = '..\..\config\passwd'. This will set the authentication path to the shared passwd file.

q. Click File-> Save -> close the window

r. Now, open the passwd file in the config folder. **When prompted select notepad as the application to use to view the file.

s. Under the [users] section delete the sample users

t. Enter the users that will have access to this repository in the form of username = userpassword. **again make sure that there are no spaces before the first character of text.

i. This will be the only time other than adding new users that you will need to modify the \config\passwd file. Unless of course you're modifying the passwd file for each repository.

a. TSVN is not necessary at the server level as it is pretty much an end user tool but for the sake of completeness I'm including it here. I personally feel that creating repositories with TSVN is easier than using the command lines.

i. TSVN requires the system to reboot, close all windows and then select 'Yes' to reboot now

i. Once the system has successfully rebooted, RDC back into the server or reconnect into the system and open an explorer window.

j. Navigate out to the D:\ drive and right-click in the right pane of the window and create a new folder that will house all the repositories. Name the folder 'AppRepositories'.

k. Open the folder and repeat the folder creation process, this time name the folder the same as the project you intend to version. i.e. 'BrushLog'. Also create a folder with the name 'config', that will hold the shared passwd file.

l. Right-Click on the project folder and roll down to TortoiseSVN> -> and click 'Create repository Here'

m. In the first prompt window select 'NativeFileSystem(FSFS)

i. **I highly recommend using this system for its flexibility and compatibility

n. Click OK, and the repository is now created.

o. Next create the working directory folder by opening the repository folder and right-clicking the right pane of the window and create a new folder that will house trunk, branches, and tags folders. Name the folder 'ProjectSource'.

p. Open the ProjectSource folder and in the right window create three new folders named: trunk, branches, and tags.

q. Open the svnserve.conf file. **If prompted to select which application to view this document in, choose notepad.

r. Under the [general] section, uncomment the auth-access, anon-access, and password-db lines.

i. Delete the '#' symbols, be sure to leave no spaces on the line before the start of the text.

s. Set password-db = '..\..\config\passwd'. This will set the authentication path to the universal passwd file.

t. Click File-> Save -> close the window

u. Now we will need to configure the authentication for the repositories. Open the conf folder in the repository you just created and copy the passwd file to the config folder under the AppRepositories directory.

v. Open the passwd file, when prompted select notepad as the application used to view the file.

w. Under the [users] section delete the sample users. Be sure to leave no spaces between the text and the start of the line. Enter the name and password for the users that will have access to the repositories in the form of username = userpassword.

i. This is the only time that you will need to change this file with the exception of adding new users. Unless you've elected to use separate passwd files for all repositories.

x. The process of creating a repository is now completed using TSVN, note also that in using this method no revisions were completed while adding the files. Also the files are visible within the explorer window.

**Note: Before going on be sure you've completed section IX, a repository must be in place to import

a. Open an explorer window and browse to the folder containing the source code

b. Right-click the folder -> TortoiseSVN> -> Import

i. When using TSVN import(to the server) in this case means the same as export(from the client). This confused me in the beginning.

c. Enter 'svn:\\(servername)\(NameOfRepository)\ProjectSource\trunk' into the Url of repository. You can add a description of the import action in the Import Message window, i.e. Initial import of the (ApplicatioName) source code.

d. At the prompt enter the username and password entered into the passwd file from the repository conf file. This only needs to be done once per session, SVN and TSVN will remember the entries for the duration of the session. Unless you've used separate passwd files, then you'll have to repeat this for each new repository.

e. Click OK and all the files are loaded into the repository and committed at the next revision number (revision 1(TSVN) or 5(SVN command line) depending on the method used to create the repository)

**Note: The total number of files imported is also displayed at the bottom of the window.

a. Open a windows explorer and browse to the C:\ drive, right-click the right pane and create a new folder. Name the folder SVN.

b. Open the SVN folder, right-click in the right pane and create a new folder with the same name as your repository

c. Right-click the new folder -> SVN Checkout

d. In the 'Url of repository' enter 'svn:\\(ServerName)\(RepositoryName)\ProjectSource\trunk'

**Note: In the bottom section of the window it is possible to specify a previous revision of the project by specifying a revision number. The default is the latest committed version.

e. Click OK

f. This adds all the source code at the current(most recent) revision. The window shows the total number of files added to your directory (Added: ##) and the revision number.

**Note: Every file in this folder has a green check icon on it, this means that this file appears as is from the repository. This icon will change if the file is modified to a red '!' and will remain thus until the file is committed back to the repository on the server.

g. You've now got a working copy of the source code that you can modify, change, or reinvent at your leisure with no worries about 'accidentally' losing everything.

a. When you're ready to save your changes back to the repository browse out to the working directory and right click the folder -> SVNCommit

**Notice that all the changed files are marked with a red '!', this is just TSVN's way of letting you know you've done some work.

b. TSVN allows you to select which file you'd like to commit back into the repository, either a single control, many code pages, or the entire working code.

You can commit any files you choose (not always all of them), but when you commit the files you selected, they are all committed or not at all (When an error occurs for example). *(SDragon42, 3/23/07)*

i. If you are working on a project as part of a team and other members have checked out and checked back in code before you complete yours and your code is not compatible TSVN will display an error. At this point I recommend right-clicking the folder -> TSVN -> Check-for-Modifications. For more on the capabilities of TSVN see the manual.

**Simply checking for changes made to the files is not sufficient to have a compatible working compilation, an Update is required on the working copy to get the latest code from the repository. *(SteveKing, 3/23/07)*

**Note: A cool feature of TSVN is that when you're ready to commit the changes back to the repository all the files that are being sent appear in the lower part of the commit window, and by double-clicking a particular file you can see what exactly was changed between revisions.

ii. Click OK

iii. Enter your username and password from the passwd file

iv. All the changed files are now updated in the repository and loaded into the next revision. The revision number is displayed in the window. Each revision holds all the files for each project; the difference is what is displayed below.

Conclusion

Up to this point you have come far enough to use the basic functionality of SVN with TSVN. Of course there is lots more that can be done with SVN and maybe I'll cover that in a later article, but until then everything is in the documentation that you've downloaded.

Getting the ball rolling is the hardest part of using SVN, once you start incorporating it into your development cycle you'll realize just how easy and beneficial these tools are.

Credit where Credit is due

This article would not be what it is without some help and guidance from some who are more experienced and knowledgeable than myself. First let me thank the CP community for being the supportive and encouraging place that it is for programmers. Second I have a couple shout outs to two individuals that helped me to get not only this article off the ground by providing very poignant research direction but also to complete the work that led to the article in the first place.

Hans Dietrich - for providing very well written articles and suggestions

I have Visual SVN they provider a server for free. Simple install then just a management console to set up all your repo stuff. Very easy. I would say it takes under 2~3mins to install and have a server up and running with your repo.

They also provide a plugin for Visual Studio that I personally prefer to Ankh (Although it is a good program and works well). You need Tortoise installed and the plugin works along side that. I like having the control in windows not just Visual Studio.

The plugin isnt free but the server is but I would recommend the plugin. The server will work without it absolutely fine, it will work with Ankh,Tortoise anything

For this article I intended the folder D:/AppRepositories to be the parent directory for all the subsequent repository projects. After creating the parent directory all you have to do is create a project folder, named 'yourProjectNameToBeRevisioned', and follow the steps to create the repository by either using TSVN or the SVN command line (steps VIII or VII, respectively).

Another short cut that I came up with was writing a batch file that is used in a winform application to automatically create the repositories, it's pretty basic to do but very helpful. Google will show you the way.

When I first setup Subversion on our server, we experienced bad performance and commits tend to fail. After two or three weeks of trying out different combinations of client and server versions we finally found out that the virusscanner was locking files while scanning. After excluding the repository folder from the virusscanner the performance was excellent and all commits were successful.

I had not run into nor heard of any problems coming up via a virusscanner, thanks for the tip. I'll maybe add it into a tips/tricks section, with credit to the source of course, the next time I update the article.

If you plan on sharing your code base with remote users, or want to be able to access the code base from remote locations, you should configure your firewall to route TCP 3690 traffic to the Subversion server. Then strong passwords are essential!

For those who does not have personal experience with using SVN and VS2003 for Web application development here is one trick you should know. When you check out your project from a repository SVN creates a hidden folder inside you project's folder. This hidden folder may have a name either _svn or .svn. The name used depends on a setting of the local copy of TortoiseSVN installed on your machine. If you develop a web application (ASP.NET) with IIS 6 using VS2003 (that still does happen a lot) you don't want to have a hidden folder to be named .svn. You will have a lot of troubles trying to load a web project from the IIS virtual directory with absolutely meaningless error message in VS2003. So the solution is simple: go to TortoiseSVN settings and on a General tab check "Use '_svn' instead '.svn' directories" checkbox. This problem does not happen with VS2005.

I read through your article. It is great to see a Subversion article for beginners. I have used Subversion for about a year and really like it.

However, I just want to check a thing about the repository creation with TortoiseSVN.
In the article above, it looks as if you create the trunk/branch/tag folders through just creating them right in the repository using Explorer.
In "my" Subversion world, I create those folders elsewhere and then use TSVN "Import" command in order to import those folders into the repository. This will add the folders to the repository data rather than just creating the folders in the repository folder. I THINK just adding the folders there in the way you do is a mistake.

Of course, I might have misunderstood how you did, but then, others might too.

I create those folders elsewhere and then use TSVN "Import" command in order to import those folders into the repository

This is very interesting, I hadn't thought of doing it this way.

CarlG wrote:

I THINK just adding the folders there in the way you do is a mistake

As I mentioned at the top of the article I wrote this article from MY perspective and the methodologies that I used were the best fit for my situation. I do realize that SVN and TSVN are flexible enough allow many different configurations as to how repositories are set up.

That's the great thing about working with development tools and code development in general, if you don't think something is done right or efficient enough you can try a new way and get 'er done right for you.

First.. great article. My team came across your article as we were troubleshooting why its not possible to connect to a SVN server from a client using SVN://. Your article explains this nicely and easily.

I also create the folders differently. I use the Repo Explorer to create the folders (trunk, ...) right in the repo and then import/export code as per the appropriate folder.
Creating repo folders inside the repo explorer is also the approach I use when I branch and want to create a branch folder named as per the branch I am coding for (like RB-1.2 for release branch, TRY-2.3, ...)

Great work. I think your article should be added to the SVN home page as a must read for windows developers as it would for sure save as coming from VSS a lot of time and effort going over the change in paradigm

b. TSVN operates under an all or nothing commit policy, which means you have to commit all the files changed back to the repository or none will get posted.

The commit dialog in TSVN lets you choose which files you want to commit and which ones not. We put great efforts to make exactly this work.

i. If you are working on a project as part of a team and other members have checked out and checked back in code before you complete yours and your code is not compatible TSVN will display an error. At this point I recommend right-clicking the folder -> TSVN -> Check-for-Revisions. For more on the capabilities of TSVN see the manual.

After you get an error about your working copy being out-of-date (because someone else posted a newer version of a file you changed and wanted to commit), you have to update your working copy. Just checking isn't enough.