Luc messaged me earlier yesterday evening and mentioned that he was interested in starting to use some source control on his own code so I thought I’d whip up this post so others could benefit from my set of instructions.
The steps I describe here are suitable for when you are working by yourself and want to have your source versioned. The subversion documentation outlines the steps you need to take to host the repository so others can access it. I may write a post for that too, if there is interest.
The steps in the full text of this post will have you install tortoisesvn — my tool of choice for working with subversion; create a subversion repository, and add a new project to the repository and any existing files you may have. I’ll also describe what you need to backup to ensure you won’t lose any work in the event of a hardware failure.
Step 1: Download and install the latest TortoiseSVN. Once it is installed it will tell you that you need to reboot, unless you’ve installed TortoiseSVN before you don’t have to.
Step 2: Create a directory on your computer that will be used to store all of the important files you’ll check into subversion. This is not where you will be doing work but where all the book-keeping will be taking place. For these steps I’ll use C:\my\svn\repository
Step 3: Right click on said directory, choose TortoiseSVN/Create Repository here. You’ll be asked what kind of repository you want, choose Native File System (FSFS). Make note of where this directory is at, you’ll need it in a few steps. But now leave this directory because you won’t be touching the files here directly anymore.
Step 4: Now we’ll create the directory structure within the virtual filesystem of the repository. I like to organize my repository by project where each project also has a tags, branches, and trunk directory within it so thats what we’ll create here.
Step 4a: Create a directory somewhere; this will be used only temporarily so it doesn’t matter where it resides the name doesn’t matter either.
Step 4b: Create a directory within that one named for your project
Step 4c: Create 3 directories within the one named for your project named: “tags”, “branches”, and “trunk”
Step 4d: If you have existing source for this project place it inside of the “trunk” directory. You should clean it up so that only source files are checked in. bin, obj, and any .user files should be deleted or you’ll just bloat the size of the repository for no good reason.
Step 4e: Go back to the folder containing the directory you created in 4a.
Step 4f: Right click on the directory created in 4a and choose: TortoiseSVN/Import…
Step 5: It will ask for the repository, remember that directory created in step 2? Specify the repository as file:///C:/my/svn/repository/ it is very important that you include three forward slashes after file: and before the drive letter. Click OK.
You should see tortoise begin to process and in the end you will have 4 (or more) directories added to the repository.
We’ve created the repository and added any existing files to it, now its time to get your work area ready to be handled by subversion!
Step 6: Go to where you want your source code for this project to live. In my case all my code lives at D:\projects\<projectname> so I navigate to D:\projects.
Step 7: Right click on an empty place in this folder. Choose SVN Checkout.
Step 8: URL of Repository should still say file:///C:/my/svn/repository/ that you typed when you imported the files. If it doesn’t, type it in here.
Step 9: Click the ellipsis button (…) next to the URL of the repository, this will bring up the repository browser. Expand the folders until you are at <project>/trunk. Select that folder and click OK.
Step 10: Where it says Checkout Directory add the name of your project to what is currently displaying (since I did this in D:\projects\ it currently says D:\projects\ I will modify it to say D:\projects\myproject). Click OK. You will be asked if it is okay to create the directory; tell it yes that it is okay.
And now you’re done. Congrats, you now have a subversion repository on your computer containing all of the files you already had.
IMO, the first thing you should do is set up the filter so that you don’t add files to the repository that shouldn’t be. This goes back to the bin, obj, and .user files you didn’t add to the repository to begin with.
Right click anywhere in Windows Explorer, choose TortoiseSVN/Settings. Set the global ignore pattern to:
bin */bin obj */obj *.suo _ReSharper.* *.resharper *.resharper.user *.user
Now when you use TortoiseSVN files and directories matching the pattern will not be shown.
How do I use TortoiseSVN?
Now that you have the repository set up; its time to make use of it. The bulk of your usage will be to commit changes that fall into 3 categories, files that have been: added, deleted, or changed.
Windows Explorer should now display a green checkmark on the newly created folder for your project. This green checkmark means that the directory and all subdirectories have the latest revision of the files in the repository.
So everyone can follow along at home we’ll add a file, edit it, then delete it from the repository.
Adding a file
Inside of your project directory create a new text file. Call it newfile.txt, go ahead and add some text to this file; it doesn’t matter what. Save the file and close it.
Back in windows explorer you can right click on the file if you only have one file to add or you can right click on the containing directory. Choose TortoiseSVN/Add from the context menu. If you don’t see a Blue + sign on your file hit F5 to refresh the directory. Right now the files are only queued to be added in the next commit to the repository.
Right click on the project directory, choose SVN Commit from the context menu. You will be presented with a dialog that allows you to give a message detailing what changed in this commit at the top, and the ability to select which changes will be committed. Type your message and ensure the files are selected to commit (newfile.txt for example). Click OK. You’ll be presented with a dialog showing the progress as the files are sent to the repository. If all goes well you will be presented with a success message and the new revision number.
Editing a file
Open up the file we just created and make some changes to it. Save the file and close it. Refresh the directory. The file will now be marked with a red exclaimation (!) alerting you that the file no longer matches the latest version in the repository. Let’s fix that.
Right click on the directory and choose SVN Commit. As before when you added the file you can enter a reason for the commit and select the files to commit. Click OK. Same deal as before when you added the file you’ll be presented with a success message if everything went ok.
Refresh the directory containing the files and you’ll see that the blue + has now changed to the green checkmark.
Recovering an older version of a file
Before we get to the deletion of a file; lets talk about how to recover an older version of a file. Now that you’ve added and edited the file newfile.txt we’ll recover the first version. Right click on the file, choose TortoiseSVN/Show Log. You now see a list of all revisions that contain this file. You now have several options available. Right click on one of the log entries, you’ll see several options relating to changing the existing file based on the log entry you clicked.
- Update item to revision: Use this option when you have an old version of the file and want to move up to the one in the revision you selected
- Revert to this revision: Use this option when you have a newer version of the file and want to move everything back to as it was in this revision
- Revert changes from this revision: This one is difficult to explain; but it will mark the file as having a conflict then create 3 additional files that will allow you to manually merge the changes you want to make.
For our purposes select revision 2, the list of actions at the bottom should say that you added the file. Now right click on the revision, and choose “Revert to this revision”. When asked if you are sure, tell it yes. The TortoiseSVN Merge dialog will appear then tell you it has finished. Tell it OK and then OK out of the show log dialog. Refresh the directory and you will see the red ! on the file again telling you that it no longer matches the repository.
As you did before, right click on the directory and choose SVN Commit, provide your log reason and click OK to commit the change. When it is done you’ll notice that the revision doesn’t say 2, this is natural. After all, if you lost all your edits after you revert a file you wouldn’t be able to undo that edit, would you?
Now that you’ve seen how to add, edit, and revert a file we have one more thing to do.
Deleting a file
In explorer delete the newfile.txt file. Right click on the directory and choose SVN Commit. Like before you’ll be presented with the same dialog. This time you will have to manually check the box next to newfile.txt to indicate that it should commit the delete to the repository. Click OK.
Backing up the repository
At the very top of this post I mentioned you would learn how to back up the repository…simple; just zip up the directory you created in step 2 and put the zip file some place safe. If worse comes to worst and you need to restore this backup; just extract the contents of the repository where you want the repository to live then do an SVN Checkout like you did in step 8.
From here the rest is up to you; there is much more that I didn’t cover in this post…perhaps I will be inspired to write a new post in the future.
Update: Stephen Russell on DevelopMentor’s Advanced-DOTNET mailing list posted a link to a blog post that integrates tortoisesvn with Visual Studio 2005. This is supposed to be a light weight approach to integrating the two. If you’re looking for full source control integration then there are a couple options available that I know of.
- VisualSVN is a commercial product that quite a few people on the same list recommended using. The developers also posted a comment here on an earlier blog-post of mine so they are reaching out to community posts.
- AnkhSVN is an open source product that Jason made a comment about and I’ve used in the past with some success. There is also a blog that comments on AnkhSVN as well; but its been dormant for over 6 months now.