(Last modified 10 Oct 2009)
For a long time, I've relied on a small
set of batch files for tracking versions of my various firmware
projects. I have carried them along from the DOS days and was
happy with their features for a long time.
In recent contract jobs, I've wound up using variations of Subversion and ended up liking many of the common features. I especially like those versions that tie into the Windows file explorer and modify a file's icon to track that file's status inside the version-control repository. I finally decided this is something I should use in my own projects and started looking for a suitable suite. I am currently using TortoiseSVN.
Download and install
I started by downloading the current version of TortoiseSVN for Windows 32; I am using version 1.6.5. I went to the TortoiseSVN download page and grabbed the TortoiseSVN package, which includes the SVN core plus the TortoiseSVN GUI and support modules; look for a file named similar to TortoiseSVN-1.6.5.16974-win32-svn-1.6.5.msi.
While you are at it, stop by the tigris.org website and pick up the latest version of the SVN1Click utility; look here. SVN1Click is a GUI-based utility for installing TortoiseSVN. It removes a lot of the confusion and frustration of setting up TortoiseSVN and is highly recommended! Look for a file named similar to Svn1ClickSetup-1.3.3.exe.
Put both of the above files in the same directory (say, c:\tortoise), then double-click the TortoiseSVN file. Note that this file is an MSI installer; you will need Admin rights to install. You may need to track down one or more DLLs in order for the installer to run. I needed to find two of them and add them to my c:\WINNT\system32 folder (I'm running Win2K SP4). Keep adding any missing DLLs and launching the installer until the installer begins working. Once you finish running the installer, you will have installed the core of TortoiseSVN, but it is not yet hooked into Windows Explorer and you do not yet have the graphical interface running. Setting these up are the job of SVN1Click.
Double-click the SVN1Click file. You will see a dialog box open and you will be asked to provide the path to the SVN repository. I chose to put my repository on a network share drive, even though the FAQ warns very strongly against this! In my case, I am the only one using the repository and I want it on the network drive for backup purposes. If you are setting up TortoiseSVN for use in a small business environment, read the FAQ carefully before deciding where to put your repository!
The next dialog box will ask where to install the TortoiseSVN suite of GUI tools; I just took the default.
If all goes well, you should be done. Restart your machine, then open up a folder and right-click on a folder icon. The right-click menu will now contain a set of Tortoise and SVN related operations, such as "SVN Commit..." In particular, you can use the TortoiseSVN/Repo Browser option to browse the repository you have set up.
This is a very cursory view of installing TortoiseSVN. If this doesn't answer all your questions, please use the web to hunt up more info. TortoiseSVN is simple to set up compared to other SVN packages, but that doesn't mean it is easy. I had enough background with other SVN clients that I could work through the setup, but if this is your first contact with an SVN tool, you may need to do some digging and asking about before you get it completely set up.
Using TortoiseSVN
This is the cool part! Every time I edit a source file or modify a schematic that is part of a project in the repository, the icon for that file and for higher-level folders changes to red to show that the repository is out of date. When I have finished working on a project, I can go to the folder for that project, right-click, select SVN Commit... and commit those changes to the repository, complete with logging message explaining what I did. Once the changed files/folders have been committed, the associated icons change to green, showing the repository is now up to date.
The TortoiseSVN toolset include a Diff utility that is very nice. Open a folder, right-click on a file, and select TortoiseSVN/Diff with Previous Version. A side-by-side file viewer will open and you can see the highlighted differences between your working copy and the previous version known to the repository.
If needed, you can use the repository browser to look back through all the previous versions of a project, select a version, and check it out to a working directory. This lets you recover an earlier version to use as a new starting point or to remove recent edits in case you change your mind about a design.
Adding an existing project to TortoiseSVN
Most of the on-line help assumes you are starting from the very beginning when you install TortoiseSVN, and you don't yet have any projects created. This is backwards from my situation; I have lots of projects already set up in their own folders but now I need to move these projects into TortoiseSVN's repository. The steps for doing this are actually straightforward.
Assume you have a folder named c:\projects\datalog328p that contains all of the source code and schematics for a datalogger project and you want to place this project under SVN control in TortoiseSVN. Locate this folder and right-click it, then select TortoiseSVN/Repo Browser.
The browser will start with a dialog box asking for the URL of your repository. Make sure this contains the path to the root folder of your repository, not the path to a previous project folder! In my case, the root of the repository is in file:///M:/SubversionRepository. Click OK.
You should see an explorer window; the left-hand window will show a folder with the name of your repository. If your repository has any projects already in it, you will see folders underneath the repository folder with these projects in them. Right-click on the folder for the repository, then select Create folder.... In the dialog box, enter the project's name (in this case, datalog328p) and click OK. You will be offered a chance to enter a log message if you choose, though this isn't necessary; when ready, click OK. If you expand the repository folder now, you will see a new folder named datalog328p.
Right-click the datalog328p folder, then again select Create folder.... This time, create a folder named trunk. This is a convention established through long practice with SVN and you should maintain it, even if you never intend to have anyone else use your repository. Again, you do not need to enter a log message at this point. Double-click the trunk folder and you will see an empty space in the right-hand side of the explorer window.
In a separate window, open the top-level project folder (in this example, c:\projects\datalog328p), then select and drag all of these files and folders into the right-hand side of the trunk explorer window. You will see a small option box appear; select Copy files to here. You will next see a dialog box asking if you want to finish the copy operation you just started; click Yes. You will next see a box asking you to enter a log message. This log message will be associated with the first version of the project, so I usually type in something like: Baseline version of the datalog328p project. Click OK.
At this point, the repository has a copy of your working files, but you have not yet checked out this project. If you go back to your project folder, you will not see any change to the folder's icon.
Right-click the project folder's icon (c:\projects\datalog328p) and select SVN Checkout.... You will see a dialog box. The first field should contain the path to the root of your repository (in my case, file:///M:/SubversionRepository). The second field should contain the folder where you want TortoiseSVN to place the files you are about to check out; this is the project folder (in this case, c:\projects\datalog328p). Leave the remaining fields unchanged for now, then click OK. You will see a warning dialog that the target folder is not empty; click Yes to proceed with checkout. You will see a text box fill with information about the files being copied from the repository to the target folder. When the copy process is finished, click OK.
Now if you return to the explorer window showing your project folder and refresh this view, you will see a green icon on the project folder, telling you that the repository version of the project matches the working copy found in this folder. This completes the initial checkin and checkout of an existing project.
Here is a screen shot of the repository browser showing my datalog328p project in the repository:
Summary
This is only the barest beginning to using TortoiseSVN, but I wanted to put in a plug for a tool that I now use constantly and cannot believe I lived without. If you do a lot of development, either for hobby or profession, TortoiseSVN offers a flexible, easy to use tool for managing versions of your work. Recommended.
Home
In recent contract jobs, I've wound up using variations of Subversion and ended up liking many of the common features. I especially like those versions that tie into the Windows file explorer and modify a file's icon to track that file's status inside the version-control repository. I finally decided this is something I should use in my own projects and started looking for a suitable suite. I am currently using TortoiseSVN.
Download and install
I started by downloading the current version of TortoiseSVN for Windows 32; I am using version 1.6.5. I went to the TortoiseSVN download page and grabbed the TortoiseSVN package, which includes the SVN core plus the TortoiseSVN GUI and support modules; look for a file named similar to TortoiseSVN-1.6.5.16974-win32-svn-1.6.5.msi.
While you are at it, stop by the tigris.org website and pick up the latest version of the SVN1Click utility; look here. SVN1Click is a GUI-based utility for installing TortoiseSVN. It removes a lot of the confusion and frustration of setting up TortoiseSVN and is highly recommended! Look for a file named similar to Svn1ClickSetup-1.3.3.exe.
Put both of the above files in the same directory (say, c:\tortoise), then double-click the TortoiseSVN file. Note that this file is an MSI installer; you will need Admin rights to install. You may need to track down one or more DLLs in order for the installer to run. I needed to find two of them and add them to my c:\WINNT\system32 folder (I'm running Win2K SP4). Keep adding any missing DLLs and launching the installer until the installer begins working. Once you finish running the installer, you will have installed the core of TortoiseSVN, but it is not yet hooked into Windows Explorer and you do not yet have the graphical interface running. Setting these up are the job of SVN1Click.
Double-click the SVN1Click file. You will see a dialog box open and you will be asked to provide the path to the SVN repository. I chose to put my repository on a network share drive, even though the FAQ warns very strongly against this! In my case, I am the only one using the repository and I want it on the network drive for backup purposes. If you are setting up TortoiseSVN for use in a small business environment, read the FAQ carefully before deciding where to put your repository!
The next dialog box will ask where to install the TortoiseSVN suite of GUI tools; I just took the default.
If all goes well, you should be done. Restart your machine, then open up a folder and right-click on a folder icon. The right-click menu will now contain a set of Tortoise and SVN related operations, such as "SVN Commit..." In particular, you can use the TortoiseSVN/Repo Browser option to browse the repository you have set up.
This is a very cursory view of installing TortoiseSVN. If this doesn't answer all your questions, please use the web to hunt up more info. TortoiseSVN is simple to set up compared to other SVN packages, but that doesn't mean it is easy. I had enough background with other SVN clients that I could work through the setup, but if this is your first contact with an SVN tool, you may need to do some digging and asking about before you get it completely set up.
Using TortoiseSVN
This is the cool part! Every time I edit a source file or modify a schematic that is part of a project in the repository, the icon for that file and for higher-level folders changes to red to show that the repository is out of date. When I have finished working on a project, I can go to the folder for that project, right-click, select SVN Commit... and commit those changes to the repository, complete with logging message explaining what I did. Once the changed files/folders have been committed, the associated icons change to green, showing the repository is now up to date.
The TortoiseSVN toolset include a Diff utility that is very nice. Open a folder, right-click on a file, and select TortoiseSVN/Diff with Previous Version. A side-by-side file viewer will open and you can see the highlighted differences between your working copy and the previous version known to the repository.
If needed, you can use the repository browser to look back through all the previous versions of a project, select a version, and check it out to a working directory. This lets you recover an earlier version to use as a new starting point or to remove recent edits in case you change your mind about a design.
Adding an existing project to TortoiseSVN
Most of the on-line help assumes you are starting from the very beginning when you install TortoiseSVN, and you don't yet have any projects created. This is backwards from my situation; I have lots of projects already set up in their own folders but now I need to move these projects into TortoiseSVN's repository. The steps for doing this are actually straightforward.
Assume you have a folder named c:\projects\datalog328p that contains all of the source code and schematics for a datalogger project and you want to place this project under SVN control in TortoiseSVN. Locate this folder and right-click it, then select TortoiseSVN/Repo Browser.
The browser will start with a dialog box asking for the URL of your repository. Make sure this contains the path to the root folder of your repository, not the path to a previous project folder! In my case, the root of the repository is in file:///M:/SubversionRepository. Click OK.
You should see an explorer window; the left-hand window will show a folder with the name of your repository. If your repository has any projects already in it, you will see folders underneath the repository folder with these projects in them. Right-click on the folder for the repository, then select Create folder.... In the dialog box, enter the project's name (in this case, datalog328p) and click OK. You will be offered a chance to enter a log message if you choose, though this isn't necessary; when ready, click OK. If you expand the repository folder now, you will see a new folder named datalog328p.
Right-click the datalog328p folder, then again select Create folder.... This time, create a folder named trunk. This is a convention established through long practice with SVN and you should maintain it, even if you never intend to have anyone else use your repository. Again, you do not need to enter a log message at this point. Double-click the trunk folder and you will see an empty space in the right-hand side of the explorer window.
In a separate window, open the top-level project folder (in this example, c:\projects\datalog328p), then select and drag all of these files and folders into the right-hand side of the trunk explorer window. You will see a small option box appear; select Copy files to here. You will next see a dialog box asking if you want to finish the copy operation you just started; click Yes. You will next see a box asking you to enter a log message. This log message will be associated with the first version of the project, so I usually type in something like: Baseline version of the datalog328p project. Click OK.
At this point, the repository has a copy of your working files, but you have not yet checked out this project. If you go back to your project folder, you will not see any change to the folder's icon.
Right-click the project folder's icon (c:\projects\datalog328p) and select SVN Checkout.... You will see a dialog box. The first field should contain the path to the root of your repository (in my case, file:///M:/SubversionRepository). The second field should contain the folder where you want TortoiseSVN to place the files you are about to check out; this is the project folder (in this case, c:\projects\datalog328p). Leave the remaining fields unchanged for now, then click OK. You will see a warning dialog that the target folder is not empty; click Yes to proceed with checkout. You will see a text box fill with information about the files being copied from the repository to the target folder. When the copy process is finished, click OK.
Now if you return to the explorer window showing your project folder and refresh this view, you will see a green icon on the project folder, telling you that the repository version of the project matches the working copy found in this folder. This completes the initial checkin and checkout of an existing project.
Here is a screen shot of the repository browser showing my datalog328p project in the repository:
Summary
This is only the barest beginning to using TortoiseSVN, but I wanted to put in a plug for a tool that I now use constantly and cannot believe I lived without. If you do a lot of development, either for hobby or profession, TortoiseSVN offers a flexible, easy to use tool for managing versions of your work. Recommended.
Home