AnkhSVN Basics Tutorial
I recently finished a TortoiseSVN Basics Tutorial. While TortoiseSVN is great, I really enjoy using a plugin for Visual Studio called AnkhSVN. The benefit of using Ankh is the built-in solution explorer support and pending changes window. If you've used Microsoft's Team Foundation Server before then the Ankh plugin will seem familiar.
Note: If you want to use AnkhSVN you will need a paid version of Visual Studio 2010. The express editions of Visual Studio do not support plugins. Download and install AnkhSVN from http://ankhsvn.open.collab.net/.
- Setting up Beyond Compare with AnkhSVN
- Mapping an Existing Branch / Opening a Project From SVN
- Updating Your Working Copy
- Committing Changes
- Creating a New Branch
- Merging Trunk to Your Branch
- Resolving Conflicts
- Re-integrating a Branch
Setup Visual Studio Source Control Plugin
Open up Visual Studio and navigate to Tools > Options to open the options window.
In the left pane, navigate to Source Control > Plug-in Selection.
In the drop down list you should see AnkhSVN as an option. If you do not see it ensure it has been installed correctly.
Setting up Beyond Compare with AnkhSVN
Note: I love Beyond Compare and you should too. This section will show you how to make Ankh use Beyond Compare for merges and comparisons.
If you don't have Beyond Compare, GET IT NOW!. Don't believe me that you should get it? Fine, stick with TortoiseMerge. I'm sure you'll love it.
Setting up Beyond Compare with Ankh is easy. You don't have to paste any command line arguments like you do with TortoiseSVN. Navigate to Tools > Options again. Go to Source Control > Subversion User Tools.
You should see a set of drop down menus. Set "External Diff Tool" to "Beyond Compare". Set "External Merge Tool" to "Beyond Compare (2-Way)". Leave "External Patch Tool" set to default. Note: If you have TortoiseSVN installed then "External Patch Tool" will be set to TortoiseMerge; that is fine. Also note that "Exernal Merge Tool" has two Beyond Compare options: "Beyond Compare (2-Way)" and "Beyond Compare (3-Way)". You can only do 3-Way if you have Beyond Compare Pro. However, I personally do not like the 3-Way merge; I feel like it over-complicates things. I use 2-Way, but the nice thing about that is if you do have Beyond Compare Pro then you get a 2-Way view plus an Output window toward the bottom.
Click OK to save your changes. Beyond Compare 3 will now be used for comparisons and conflict resolution.
Mapping an Existing Branch / Opening a Project From SVN
One convenient feature of AnkhSVN is that it provides a smooth transition between "mapping" an SVN branch and "opening" a Visual Studio solution. You can accomplish both by navigating to File > Open > Subversion Project.
You will be presented with a dialog allowing you to navigate to a repository URL. Click the little blue world with the yellow plus sign above it to add a repository URL. Once the repository has loaded, navigate to the branch you want to open and find the solution file.
Select the solution file and click "Open". You will see a window allowing you to decide what local folder to map your branch to. Modify "Local Directory" to the location you desire. I am mapping the CodeTunnel project to a new directory called "CodeTunnel".
As Ankh pulls down your branch you will see a window showing a scrolling list of files being downloaded.
When it finishes mapping your local directory it will then open up the locally mapped solution. You will notice in solution explorer that your items now have green check marks next to them.
Updating Your Working Copy
The easiest way to get updates from the repository is to use the "Update" button from within the pending changes window.
After clicking "Update" you will see a dialog pop up and list the files being updated. When it is finished it will disappear. You are also able to start an update by right-clicking in solution explorer. To update the entire solution you would right-click the solution node and select "Update Solution to Latest Version". You can also update individual projects and/or directories by right-clicking them.
As you modify files in your solution Ankh automatically keeps track of these changes. At any time you can open up the "pending changes" window to see what files are waiting to be committed. Solution explorer will also reflect pending changes by decorating changed files with a red square icon.
When you are ready to commit your changes it's a simple matter of clicking the "Commit" button from within the pending changes window.
Creating a New Branch
Creating a new branch is made simple in Ankh. While some things can be done from the pending changes window, the full list of features appears when you right-click something in solution explorer. 99% of the time you are going to want to perform operations like branching and merging on the entire solution (entire working copy). To do that you will always right-click the solution node in solution explorer. To create a new branch from trunk I have opened the Code Tunnel solution the trunk of my repository. Simply right-click the solution node and select Subversion > Branch Solution.
You will be presented with a screen allowing you to specify the URL to branch to. In this example I have created a branch called "Experimental". Leave all the other options on their default values. The only option you might consider changing is the "Switch to Branch after creation" check box. This will switch your working copy to now be mapped to this new branch, instead of the branch it is currently mapped to. This is useful if you do not intend to use the current branch you have mapped and you just want the new one. However, if you do want to keep the current branch the way it is then you will have to map a new branch by following the steps in the [Mapping an Existing Branch / Opening a Project From SVN][#Mapping] section of this article.
A dialog will appear showing the files as it creates a new branch. When it is finished it will disappear. You are then free to go map a new local copy of your new branch, or if you switched your current working copy to the new branch then you can simply begin working. Simple as that!
Merging Trunk to Your Branch
Merging changes from the repository you branched from into your current branch is easy. Simply right-click the solution node in solution explorer and select Subversion > Merge Solution. You will be presented with a merge dialog similar to the one that TortoiseSVN gives you when you do a merge. For our purposes we want the first option "Merge a range of revisions".
Note: Leave "Perform pre-merge best practices check" checked. It will warn you if you have forgotten to do certain things before merging, like committing your changes or updating your working copy.
In the next dialog you will put in the URL to merge from. In this example I will merge trunk into my current branch. Select "All eligible revisions". If you have followed all the best practices mentioned in this article then SVN will automatically know which revisions have been merged before and which have not.
Next you will get some options for your merge. The options are mostly self-explanatory but there are a few things to take into consideration. The first option, "Prompt me for each conflict and let me decide" will open up Beyond Compare for each and every conflict it encounters as it encounters them. Once you save the output and close Beyond Compare Ankh detects changes made and asks if you would like to mark the conflict as resolved. If instead you wish to mark each conflict and resolve them afterward then you can choose "Mark each conflict and let me resolve later". This will allow the merge to continue until completion and let you resolve the conflicts in the pending changes window after it has finished.
The final page in this dialog allows you to review your settings and continue with the merge. There is an option to "Perform Dry-Run". This is the same as TortoiseSVN's "Test merge" option. If you select it then it will pretend to do the merge and show you statistics about the merge, including how many conflicts occurred. Most of the time you will want to just skip this and continue with the merge. Rarely have dry-runs ever changed my mind or forced me to do anything differently when merging.
Once the merge is complete and all conflicts have been resolved, you can now commit your changes to your branch.
In my opinion, AnkhSVN makes it even easier to resolve conflicts than TortoiseSVN does. We discussed above that during a merge you can choose to have Ankh let you resolve each conflict as it discovers them or you can let it mark all conflicts and let you resolve them using the pending changes window after the merge is complete. If you tell Ankh to prompt you for each conflict then as soon as a conflict occurs, Beyond Compare will pop open.
After you save the output and close Beyond Compare Ankh will ask you if you resolved the conflict.
Selecting "Yes" will mark the file as resolved and continue. Selecting "No" will keep the file as conflicted so you can resolve it after the merge is complete. "Cancel" will abort the merge entirely.
Sometimes when you have a big merge and you know you are going to have a lot of conflicts it is just easier to let Ankh mark each conflict so you can resolve it after the merge is finished. Otherwise Beyond Compare would be popping open every two seconds. If you opted to have Ankh simply mark conflicts for later review then you will see them in the pending changes window.
Note: The files that are conflicted will contain some gross looking SVN metadata while they remain conflicted. Don't forget to resolve your conflicts or you could find yourself very confused when your solution refuses to compile because of some weird stuff inserted into your code.
To resolve conflicts in the pending changes window, simply right-click the conflicted file and choose "Edit Conflicts". This will open up Beyond Compare, just like the image in step 1.
After editing the conflicts and saving the result, Ankh will ask you if you resolved the conflict just like in step 1. If you want to take your file or the file coming from trunk, then simply right-click the file and select Resolve > "Using My File" or "Using Their File" depending on which one you want. This will mark the conflict as resolved.
After resolving all your conflicts you are free to commit your changes.
Re-integrate a Branch
Before re-integrating a branch ensure that you have committed all desired changes to your branch.
Merge up from trunk to your branch. Don't forget! You must merge trunk into your branch first before you merge back to trunk. This is an important step because it allows you to get all updates from trunk and resolve conflicts all within your own branch. After you complete the merge you can commit the merge changes to your branch. Once you have the latest from trunk and the merge has been committed, then you can begin re-integration of your branch to trunk.
To begin re-integration open up trunk in Visual Studio, right-click the solution and select Subversion > Merge Solution. This time we are going to select "Reintegrate a branch" in our merge options.
On the next screen put in the URL to your branch in the repository.
On the next screen you will see the merge options that you are familiar with. Leave those the same unless you want to change how Ankh is to handle conflicts for this merge. Note: You shouldn't get any conflicts during this merge since you just barely merged trunk up into your branch before re-integrating your branch back into trunk. However, if you do get conflicts, simply resolve them like you normally would.