Subversion for Visual Studio.Net a.k.a. Making Visual Studio Your Collective Bitch In 25 or so rather simple steps * Index * * So, what is this Subversion thing? * Why Subversion? * Installation o Server o Client * Using the installed Client Software * Notes on using AnkhSVN * Useful URLS This file is also available in plain text format here (http://morph.telspace.co.za/docs/SVN4VSdotNet.txt) or zipped plain text here (http://morph.telspace.co.za/docs/SVN4VSdotNet.zip). * So, what is this Subversion thing? * This question is best answered by the Subversion documentation: "Subversion manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of time machine. Subversion can access its repository across networks, which allows it to be used by people on different computers." That means that multiple developers can work on the same source code base without overwriting each other's work! It even manages those cases where 2 people are working on the same piece of code, by offering the diff to the latest updater, who can then make the appropriate decisions as to what stays and what goes. Subversion works as a client-server configuration, and as such it needs to be setup twice - once on each logical side of the network (the server and client can both be on the same computer). To setup subversion on Windows is a simple matter of running the installation package (downloadable from subversion.tigris.org). Do this for both the client and the server (obviously only once if you're running both on the same machine). It is helpful to have Subversion loaded as a Windows service (only possible under NT, 2000, XP, 2003 and higher), so it starts up before anyone logs in - a typical situation with any server. To accomplish this, download the "SVNService" package from http://heavymetalsoftware.metal.ee (bound to change - if it's invalid, check out the project home at svnservice.tigris.org). Finally, having Subversion (SVN) installed is not enough - we want it all nicely integrated with our system. In order to get Visual Studio.Net to interface with SVN, download AnkhSVN from (you've probably guessed by now) ankhsvn.tigris.org. To get SVN all smoothly integrated with Windows Explorer, get TortoiseSVN from tortoisesvn.tigris.org. * Why Subversion? * Subversion is in many aspects similar to CVS (Concurrent Versioning System) and in the rest, simply better. CVS is a ubiquitous term in the open-source community, where programmers often collaborate over immense distances. As such, CVS - and now Subversion - is a set of tried and trusted collaboration tools that are rated much higher than other similar packages like Visual SourceSafe or SourceVault. * Installation. * Before embarking on the exiting journey of installing and configuring Subversion, we will need the following installation files: * Subversion (http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91) * TortoiseSVN (http://tortoisesvn.sourceforge.net/downloads) * AnkhSVN (http://ankhsvn.tigris.org/servlets/ProjectDocumentList?folderID=4013&expandFolder=4013&folderID=2955) * SVNService (http://heavymetalsoftware.metal.ee/en/index.html) It's probably a good idea to fetch these files before continuing. Of them all, the most important is the actual Subversion installation of course, and for our purposes here AnkhSVN is important too. TortoiseSVN and SVNService are near indispensable, but if you for some reason can not download/install them, you will be able to get by. For more information about the software (their homepages), check out the Useful URLs section. * Server * 1 - Run the setup file for Subversion (at the time of writing: svn-1.3.2-setup.exe) 2 - On your System Properties Dialog (windowsbutton-Break or right-click on My Computer or just use the control panel), on the Advanced tab, click "Environment variables". In the system variable section, double-click the Path entry, and append the subversion application directory (normally c:\program files\subversion\bin) to the variable value string if it's not already there. You can close this dialog now. To ensure the new path is loaded, you can log out and log back in, or restart Windows. 3 - Open a command console (cmd.exe). Type "svnadmin create ", where is the path where you would like your repository to be created. If subversion has succesfully installed, this will create a whole bunch of files and subdirectories under the path you supplied. The repository is a database wherein your projects will be stored, all nicely version controlled. To learn more about the working of subversion, read the help file, which contains the entire O'Reilly book regarding Subversion. Yeah, they are that cool. For the sake of the guide, we will use C:\SVN\Repos as the repository path. 4 - To test whether your installation is working so far, now type svn mkdir file:///c:/svn/repos/test -m "Testing" (yes, three forward-slashes). This will create a directory inside your repository (this is how projects are seperated from each other). To see whether it succeeded, type and run svn ls file:///c:/svn/repos You should see the following: test/ To finish the basic repository configuration you will need to set the user passwords and logins. In the repository direcory (C:\svn\repos) is a subdirectory "conf". The conf subdirectory contains 2 files, svnserve.conf and passwd. Open the svnserve.conf file and remove the "#" from the lines containing [general]; anon-access...; auth-access...; password-db...; and realm... It should be easy to understand what these lines do, if you're confused, read the manual. Save and close the svnserve.conf file and open the passwd file (or whatever file you've specified for password-db). In the password file, remove the "#" sign for the [users] section, and then create = for each user you want to take part in the project. Users will now be required to enter their password whenever they attempt to write to the repository. It's helpful to keep the loginname the same as a user's windows networking username. 5 - Now to install the service. SVN can be made to run in "daemon" mode. This is not as evil as it sounds. Under Unix, a daemon is a program that sits dormant until a request is made from it, then it goes into action an does its thing (normally serving some data back to the requestor). A web server is a typical daemon. To run a daemon of svn, and type "start svnserve -d -r c:/svn/repos". A second (blank) console should open up. Don't close it yet, it contains the daemon process (so dark, hey?). What we have done is to enable the SVN protocol to be called from anywhere on the network. You can now go to a different computer on the same microsoft network and (assuming it has SVN installed as per steps 1-3) run the following command: svn ls svn:/// and it should display exactly like in step 5 ( is the Microsoft Networking name of the computer running svnserve. To test this on your local machine, you can use localhost instead of any computer name). Be sure that your networking is all set up and there aren't any firewalls obstructing port 3690 (svnserve's default port), otherwise you might get problems in this step. After testing, you can close the child window created earlier. 6 - OK, we can see that svnserve works LIKE a service, but it's not quite that. For this purpose, sclerose from heavymetalsoftware has done us the favour of making a little program that will run svnserve as a service, ensuring that the repository is available to people on the network even if there is nobody logged on. You will need Administrator priviledges on the computer where you want to enable this. Now. Open up your copy of the svnservice zip file (you have already downloaded it, haven't you?). This service program requires the .net framework to be installed, so if you don't have that installed on the server computer, you can download it for free from microsoft.com. Installing is a breeze - unzip the files into a nice central place, say C:\SVN\SVNService. Double-click the "install.bat" file. You should see lots of text streaming past in a console window before it closes itself. Next, open up the SVNService.exe.config file in a text editor like notepad or vim, and set the path variables according to your setup. Now go to your "Services" control panel (Control Panel>Administrative tools>Services) and scroll down until you see the Subversion service. You need to actually click "start" or the little play button on the services toolbar to kick the machine into action. To be sure, you can open up the properties for the service and ensure that it starts automatically when Windows starts up. That's it! 7 - There is no step 7 - you have succesfully installed the server component of Subversion. Congratulations! You can now access your repository and add/remove/update files using svn (the command-line client) from anywhere on the local network connected to the server computer. * Client * On the client side, we will need to install subversion, install AnkhSVN for Microsoft Visual Studio.Net, and to make our lives easier in future, install TortoiseSVN. 1 - Install Subversion (at the time of writing: svn-1.3.2-setup.exe) on the client. This is a simple matter of running the .exe (see the server installation above for detail). Test whether Subversion can access the repository by running: svn ls svn:// (run the above from a console, such as cmd or command on Windows 98/95) If it doesn't show (assuming you're following this guide so far without deviation): test/ then ensure you have the Subversion Application directory (normally c:\Program Files\Subversion\bin) in your path. See Server installation for instructions on setting the path. 2 - Install AnkhSVN (at the time of writing: AnkhSetup-0.6.0.2461-snapshot_33.msi). AnkhSVN installs itself as a module in Microsoft Visual Studio.Net, and you should, after running the installation procedure, see it lurking in your Tools menu in Visual Studio. Visual Studio does have a problem with folders (directories, in Microsoft language) that start with a period. Unfortunately for us, Subversion keeps its configuration data stored in ".svn" folders in any version-controlled directory (the client-side working copy of a project in the repository). AnkhSVN does support a workaround for this problem - select the "Edit the AnkhSVN config file" menu option out of Visual Studio, or just directly edit the "ankhsvn.xml" file found in "C:\Documents and Settings\\Application Data\AnkhSVN\". Near the bottom of the config file is a line Remove the comment tags (the bits) to make AnkhSVN create "_svn" administrative folders instead of the usual ".svn" folders. Note, this will mean that you can not use svn directly for any version controlled project you have made using AnkhSVN - although typically you wouldn't anyway. At the time of this writing, the "current" version was 0.5.5.1653, although I consider the development version at 0.6.0.x far superior. It has some bugs, but mostly it's quite stable. 3 - Install TortoiseSVN (at the time of writing: TortoiseSVN-1.3.5.6831-x64-svn-1.3.2.msi or TortoiseSVN-1.3.5.6831-svn-1.3.2.msi, depending on whether or not it's a 64 bit platform you're using.). TortoiseSVN is a great shell enhancement (enchantment?) that lets you update and commit (upload and download equivalents in SVN) your project directly out of Windows Explorer, using right-click context menus and bRiGhT CoLoUrS ! Note, if you enabled the option in AnkhSVN to name Administrative Folders using the leading underscore, you will have to download the "special" version of TortoiseSVN that supports this behaviour instead of the normal version. There is no configuration necessary to get it working, besides deciding whether or not you want to use the _SVN ASP hack. If you intend to use ASP.Net, select that option during installation. * Using the installed Client Software: * I really do recommend reading the Turtle (O'Reilly book: "Version Control with Subversion", included for free in the standard installation. It has Turtles all over the cover.) for in-depth knowledge. That said, a couple of pointers to assist with getting busy with Subversion really quick should be helpful. So far, you have seen a couple of Subversion commands. Here's a summary, with some other useful additions: svnadmin create C:/SVN/Repository Creates an empty repository at the given path. This path should be registered with SVNService, which will use it as the default repository for the computer. This is typically the first step in setting up a Subversion server. svn ls svn://MyComputer This command displays all the files available in the given repository. Note that you can be more specific and list only a certain project's contents by appending "/ProjectName" to the address. This can continue down the directory tree of the project too: "svn ls svn://MyComputer/ProjectName/SubDirectory1/SubDirectory2" will give you a list of the files in the directory "SubDirectory1/SubDirectory2" of project "ProjectName". svn import C:/ProjectDirectory svn://MyComputer/ProjectName This command will copy the contents of the directory C:/ProjectDirectory into the repostory at the path specified (/ProjectName). Usually the first step in creating a project in the repository, if that project already exists locally. svn mkdir svn://MyComputer/ProjectName/Subdirectory1 This command creates a directory (root directories are used to classify projects) called ProjectName in the root of the repository. Similarly, "svn mkdir svn://MyComputer/ProjectName/SubDirectory1" creates a subdirectory in the directory "ProjectName". Note: version numbers in Subversion are applied to a Repository, so if you are really concerned with version numbers, it might be more useful to declare seperate repositories for each project. Read more about this in Chapter 2 of the Turtle. Please note, if you are using the Visual Studio workaround (using "_svn" administrative directories), you should not use the following standard svn program commands. Instead, the 'special' version of TortoiseSVN or AnkhSVN perform most svn commands, and can make use of "_svn" admin directories easily. svn checkout svn://MyComputer/ProjectName C:/My_Projects/ProjectName Creates a local working directory of the project "ProjectName" in the repository at "MyComputer". You should be perfectly able to use this directory for development purposes. Whenever you have made some significant changes(s) to the files thus "checked out", you should run svn commit C:/My_Projects/ProjectName -m "added some changes" this command will tell Subversion to upload all the changes you have made to your local copy of "ProjectName". The -m part of the command contains a message that is entered into the project log that describes the changes made in the update. svn update C:/My_Projects/ProjectName This command fetches the most recent version of "ProjectName", updating your local (working) copy with the changes since your last update/commit. It is a good idea to do an update shortly before you do a commit, so that your changes to the project can take into account any other changes made by co-workers. * Notes on using AnkhSVN: * AnkhSVN is a plugin for Visual Studio. It allows you to work on a Subversion version-controlled project straight out of your IDE, doing updates and commits without ever leaving Visual Studio. There are a couple of things you need to keep in mind though: 1 - The Project file must reside in the same directory or a parent directory of the project file(s). You will get all sorts of abnormalities happening if your project file is in a subdirectory of a project or in an unrelated directory (by default, your project files are created in your C:\Documents and Settings\\My Documents\Visual Studio Projects.) A good method to create a compliant project is to use VS's File>New>New Blank Solution option, and in the Location Box, specify the parent directory of your project folder, using a solution name that is the same as the project folder name. For instance, if you have a project already created in C:\Projects\Treehouse, select C:\Projects in the Location box, and Treehouse as the Name of your solution. If you have already created a project in C:\Projects\Treehouse with a projectfile Treehouse.vbproj, you can now add this project to your solution. More typically, you will now want to create a new project instead. You can, from here on, simply create your projects in the C:\Projects\Treehouse directory. For Web Projects though, a slightly more convoluted sequence is needed. See, when VS creates a new Web Project, it automatically tries to create a subdirectory in your default (local) IIS webserver directory (by default C:\Inetpub\wwwroot). Of course, this messes with our requirement of having the project file in a parent or peer directory of the projects. So to work around this, you need to create a Virtual Directory in IIS (IIS 5 or higher required) of which the Alias must be the name of your project, and the home directory should point ro the directory where you want to create your project. So, to continue the Treehouse example, the project name should be "Treehouse", and the directory "C:\Projects\Treehouse\" or "C:\Projects\Treehouse\Treehouse\" (It's slightly better to put the project in a subdirectory of the solution, allowing you to add further projects to the solution later). After creating this Virtual Directory, you can create a new Web Project in Visual Studio, specifying "http://localhost/Treehouse" in the Location box. Visual Studio will now create all the project files in the right directory (C:\Projects\Treehouse\Treehouse or one directory up, depending on what path you specified in IIS) 2 - New Folders: After creating the folder in Visual Studio you must run an Update on the solution for AnkhSVN to become aware of the directory. After the Update, right-click on the folder (it should have a blue ? icon next to its name) and click on Ankh>Add (a green plus icon). The folder should now have a yellow plus sign icon. You can now create new items inside the folder as normal (unless you want to create more folders, in which case you should repeat this procedure). The new folder and its sub-items will now be uploaded on your next Commit. 3 - Deleting items before Updating them: For web forms, this doesn't cause any problems. However, deleting a new folder before Updating it (as mentioned in item 2) confuses AnkhSVN immensely. It might even cause a crash! If you do accidentally delete a new folder before adding it to Ankh, save the project, go to the project working directory (C:\Projects\Treehouse\Treehouse) and use the standard svn update/commit to fix all the administrative records. If you're using the "_svn" workaround, use TortoiseSVN to fix things up. * Useful URLS: * * Subversion: http://subversion.tigris.org * SVNService: http://heavymetalsoftware.metal.ee * AnkSVN: http://ankhsvn.tigris.org * TortoiseSVN: http://tortoisesvn.tigris.org (look for the "special" version that uses "_svn" administrative folders - EDIT: This hack has now been incorporated into the main TortoiseSVN installation, so now there is only one package that needs to be installed) * This page: http://morph.telspace.co.za/SVN4VSdotNet.html * Another useful guide: Joe White's Mere-Moments Guide to installing a Subversion server on Windows Created: 08 July 2005 AD (Gregorian Calendar) Edit: 26 August 2005 Edit: 22 September 2005 Edit: 06 July 2006