TortoiseSVN Basics Tutorial
I have recently found myself explaining the basics of SVN (more specifically, TortoiseSVN) to some of my peers. This is a simple subject that can rapidly spiral out of control, going from simple to pull-your-hair-out-crazy in no time at all. Below is a comprehensive list of the most basic instructions for using TortoiseSVN to map and manage an SVN repository.
For all of these you will need the latest version of TortoiseSVN from http://tortoisesvn.net/.
- Setting up Beyond Compare with TortoiseSVN
- Mapping an Existing Branch
- Updating Your Working Copy
- Committing Changes
- Creating a New Branch
- Merging Trunk to Your Branch
- Resolving Conflicts
- Re-integrating a Branch
Setting up Beyond Compare with TortoiseSVN
Note: I love Beyond Compare and you should too. This section will show you how to make Tortoise 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.
Right-click anywhere in Windows Explorer and select "Settings" from the "TortoiseSVN" context menu.
In the settings window find the "External Programs" node in the left pane. Select "Diff Viewer".
In both sections select the "External" radio button and paste the following path and command line arguments:
If 64-bit machine:
"C:\Program Files (x86)\Beyond Compare 3\BComp.exe" %base %mine /title1=%bname /title2=%yname /leftreadonly
If 32-bit machine:
"C:\Program Files\Beyond Compare 3\BComp.exe" %base %mine /title1=%bname /title2=%yname /leftreadonly
Next select "Merge Tool" in the left pane.
Again select the "External" radio button, then paste the following path and command line arguments in the field:
If 64-bit machine:
"C:\Program Files (x86)\Beyond Compare 3\BComp.exe" %mine %theirs "" %merged /title1=%yname /title2=%tname /title4="Output"
If 32-bit machine:
"C:\Program Files\Beyond Compare 3\BComp.exe" %mine %theirs "" %merged /title1=%yname /title2=%tname /title4="Output"
Click OK to save your changes. TortoiseSVN will now use Beyond Compare when doing diffs and resolving conflicts.
Mapping an Existing Branch (trunk in this example):
Create a new folder somewhere on your computer named "trunk".
Right-click your new folder and select "SVN Checkout".
In "URL of repository", put in the path to your SVN repository.
Click OK and you will see a window showing each file that it pulls down. If you get any errors (they appear in red) then double check the path to your SVN repository.
Updating Your Working Copy (trunk in this example):
Updating your working copy is easy. Simply right-click the working copy you wish to update and select "SVN Update" from the context menu.
You will be presented with a results window showing every file that is being affected by this update. If there are any conflicts with files that you have not checked in then you can resolve them here.
Committing Changes (to trunk in this example):
After you have made changes to a file you will notice that it's green check mark icon becomes a red exclamation point, indicating that there are pending changes that have not been committed to the repository.
When you are confident that your changes are in working order then you are free to commit them to your repository. Simply right-click the working copy and select "SVN Commit" from the context menu.
You will be presented with a commit window. Write a comprehensive message describing all changes being made in this commit. Double-check the list of files being committed to ensure you are only committing what you intend to. Then click OK.
When you see the results window then you are done and your changes have been committed to the repository.
Creating a New Branch (from trunk in this example):
Ensure the branch you would like to branch from is up to date. Right-click it and select "SVN Update" to get the latest updates.
Right-click the mapped branch that you would like to create a branch from and select "Branch/Tag" from within the "TortoiseSVN" menu item.
You should be presented with a "Copy (Branch / Tag)" window. Modify "To URL:" to the path you want your branch to be created. By default "Specific revision in repository" is selected and the revision number is set to the latest revision. For our purposes we will leave this at default values. Include a log message that others will see when they look at the history of your new branch.
Click OK and Tortoise will begin creating your new branch.
Notice the message it gives you when it finishes. You have two options. Your branch has been created in the repository but it is not mapped on your local hard drive. You can either switch the working copy you just branched from so that it points to the new branch instead of trunk. Or you can create a new folder with your branch name and follow the steps in "Mapping an Existing Branch" to map the new branch to that folder. Most of the time you will want to keep trunk mapped and create a new folder to map your branch to, but if you want to switch the currently mapped trunk folder to your new branch, simply right-click trunk and select "Switch" from the "TortoiseSVN" context menu item. You will be presented with a window that shows the working copy path and the SVN URL it is mapped to. Simply modify the URL to point to your new branch. That's all you have to do.
Merging Trunk to Your Branch (in a normal situation this should be done daily):
Right-click the branch you want to merge to and select "Merge" from the "TortoiseSVN" context menu.
You will be presented with a merge window with three options: "Merge a range of revisions", "Reintegrate a branch", and "Merge two different trees". For the purposes of this section we want the first option, "Merge a range of revisions".
Select "Next" and you will see a screen allowing you to select the URL you wish to merge from. By default it is set to the same URL as the branch you are merging to. Obviously that would be silly to merge the same branch into itself. Modify the "URL to merge from" to point to trunk. Leave all other options alone, we want their defaults.
You will then get a screen with merge options. We do not want to touch any of these options, leave them set to their default values.
If you are worried about the results of the merge you can select "Test merge" in the dialog above. This will perform the same steps as it would in an actual merge but in the end it will only give you statistics about what happened in the merge, but it does not actually perform the merge. This will tell you if you have a lot of conflicts. Usually, even if there are conflicts, we know we are going to perform the merge no matter what anyway so for now let's just skip that and click "Merge". When the merge is finished you will get a screen showing you the results of the merge and allowing you to resolve conflicts if there were any (see "Resolving Conflicts" for more information).
Now that you have finished merging your branch should have pending changes to be committed. REMEMBER: Until you commit your changes by right-clicking your branch and selecting "SVN Commit" your merge only exists in your working copy. If someone else pulls down your branch and you have not committed after doing a merge, then that person will not see the result of your merge. Don't forget to commit after doing a merge and resolving all conflicts.
Resolving Conflicts (updating and merging are common sources of conflicts)
Note: This applies to anywhere conflicts arise, updates and merges are the most common places for conflicts to occur. Conflicts happen when you have modified a file and someone else has modified the same file. When it tries to update/merge that file it sees both changes and marks the file as conflicted, allowing you to decide what to do. To simulate this, I have modified the file in my "Experimental" branch and also modified the same file in my "trunk" branch. I have committed the change in each branch and I will now perform my daily merge from trunk to my branch.
Oh no! We have a conflict. Let's fix it. During the merge when a conflict is encountered, depending on your settings, Tortoise may pop up a window like this: This window allows you to resolve conflicts as they are found during the merge. Here is a description of each option:
Use Local - If you are positive that you want your branch's file and none of the changes coming from trunk, use this.
Use Repository - If you are positive that you want the file from trunk to overwrite any changes your branch may have made to the file since the last merge, use this.
Edit Conflict - This is the most commonly used option. It will open up your diff tool (Beyond Compare 3 in our case) and show you the differences between the file coming from trunk and the one in your branch. If you are not sure which file you want, use this option.
Resolved - This option is only available after you have used "Edit Conflict" and saved the result. Use this when you are satisfied you have resolved the conflict in Beyond Compare.
Resolve Later - This leaves the file marked as conflicted and lets you resolve it later. Use this if you prefer to wait until the merge is done and then resolve this conflict in the result window.
Resolve All Later - This is the same as the previous option except it will prevent this window from appearing if it finds more conflicts during this merge. Use this if you prefer to wait until the merge is done and then resolve conflicts file by file in the result window.
If you don't see the dialog above, don't worry. You will still be notified of conflicts in the result window and you can resolve them here. Simply right-click conflicts in the window and select "Edit Conflict" from the context menu.
You can then use your diff tool (Beyond Compare 3 in our case) to resolve conflicts and save the results. When you are satisfied a conflict has been resolved, right-click the conflict again and select "Mark as resolved" from the context menu. If you want to take a whole file instead of using your diff tool, select either "Resolve conflict using 'theirs'" or "Resolve conflict using 'mine'" from the context menu. Those options will save the respective file and mark the conflict resolved.
Once all conflicts have been resolved you are free to commit your changes.
Re-integrating a Branch ("Experimental" branch merging back to "trunk" in this example):
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 your branch 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 right-click trunk and select "SVN Merge" from the "TortoiseSVN" context menu.
You will see the same window you saw in "Merging Trunk to Your Branch". Only this time we are going to select "Reintegrate a branch" instead of "Merge a range of revisions".
Click "Next" and you will see a place to put in the URL of your branch.
Click "Next" and you will see a window with merge options and the ability to perform a "Test merge". Leave all these set to their defaults and click "Merge". You will see the results of your merge. If you merged trunk into your branch before reintegrating then you shouldn't see any conflicts (unless you were unlucky enough to have someone else commit some changes to trunk in the few seconds between you merging trunk up to your branch and the reintegration back to trunk). If you do have some conflicts, simply resolve them like you normally would.