What is TortoiseSVN?
TortoiseSVN is a Windows OS utility integrated with Windows file Explorer. It provides a client application to a Subversion server. TortoioseSVN is developed under the GPL. This means that it is completely free, including the source code.
How to install TortoiseSVN?
- TortoiseSVN website is http://tortoisesvn.net/
- From the home page of the TortoiseSVN website, go to the Downloads section.
- Where it says The current version is 1.6.15, there are the options available for downloading TortoiseSVN.
- Choose the version you want to download depending on whether you're using a 32 or 64 bit Windows OS. Click the blue button with "TortoiseSVN xx-Bit".
- When the new page loads a window will pop up with the option to Save File or Cancel. Choose to Save File.
- The file will now be downloaded.
- If another window comes up asking Open Executable File, click OK to continue and install.
- Click Run in the Open File - Security Warning box to proceed with the installation.
- Follow the setup wizard to install TortoiseSVN. Default settings are sufficient to use through the installation.
- At the end, click Finish to conclude the TortoiseSVN installation.
- An installer Information window appears and asks if you wish to restart the system now. Any important ongoing processes or applications should be taken care of before clicking Yes. Clicking No lets you restart manually when you are ready to restart the computer.
Right-click on any folder or file in the file system of your computer and you should see options for using TortoiseSVN.
Folders and files that are under version control are displayed in Windows file Explorer with icon overlays that indicate their version control status. The overlays are:
- Green check mark for local copies that are in sync with files and folders in the repository on the server
- Red exclamation point for modified local copies that have been edited since the last checkout or update
- Red x for local folders from which local files and subfolders have been deleted since the last checkout or update, or for a local folder that is missing files and folders which have been pushed to the server repository meanwhile.
- Blue plus sign for local copies that have been added to the local working copy and are under version controlled
- Yellow triangle with a black exclamation point for local copies that show a conflict upon update with its corresponding counterpart on the repository server
Two other overlays, gray check mark and a yellow lock are used to lock a file in order to prevent others from committing changes to a particular file.
If no TortoiseSVN overlay is observed, go to http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-wcstatus.html to learn how to troubleshoot the problem.
How to use TortoiseSVN?
To demonstrate TortoiseSVN features, we use an example of the example code hosting on Google Code which uses Subversion to control changes to its source code. The project is called unhmdb and uses [Google Code] as a hosting site that provides the Subversion version control service. Google Code has the project's repository, which is the place where the code base is stored. Individual developers use the repository to obtain working copies of the code base on their computers. You must be a project member to modify or add files to the repository (The owner of the project can grant permission to be a member).
By checking out a working copy from the repository, developers replicate the code base on their computers. This operation is done only once.
Step 1: Go to http://code.google.com/hosting/ and search for unhmdb project. The project's page in Google Code shows the project summary. See the Summary tab highlighted among the links under the project home tab. The other tabs are: Downloads, Wiki, Issues, and Source.
Step 2: Click on Source tab under the project title to find the project's repository URL. Note that the repository's URL in Google Code is https://unhmdb.googlecode.com/svn/trunk/.
Step 3: On your computer, create a new folder where you want to have a working copy of the repository, Right-click on that folder. TortoiseSVN options are shown:
Select SVN Checkout...
Step 4: In the Checkout window:
- The URL of repository is the repository's URL. In our case, this is https://unhmdb.googlecode.com/svn/trunk/.
- The Checkout directory is the full path of the folder where you will create a working copy for the unhmdb folder and corresponds to the path of the folder you have right-clicked to get to the TortoiseSVN options. You can change it by either editing the text field or by browsing to another location - click on the ... icon to the right of the text field. When done, click OK and wait for the checkout process to finish.
- Upon checkout completion, the checkout window displays a list of all files that were checked out, how many kilobytes were transferred, how long the transfer took, and how many files and folders were transferred.
Step 5: To see the results of the operation, check your unhmdb folder. It now has a working copy of the code base in the repository. Also the folder should have a green checkmark overlay. Note: If you have specified a checkout location on a removable drive and no icon overlays display, see the bottommost #FAQ section on this page.
An update operation is always necessary before you start making your own local changes, to make sure that you have the most recent copy. To update your working copy with any changes made to files in the repository:
- Right-click the local file or folder in your local copy for which you want an update.
- Click on SVN Update.
To commit changes that you have made to any files in your working copy, you must have commit privileges granted by the administrator of the repository on the Subversion server.
- Create a Google Code account.
- Go to the project to which you want to commit your contributions.
- Contact the owner of the project to add you as a member.
When commit privilege has been granted from owner, then you can make changes to your working copies and then commit them to the repository.
1: Deleting files or folders from the unhmdb working copy causes a red exclamation point icon overlay to mark the working copy folder.
2: After creating new subfolders, a blue question mark icon overlay marks those subfolders: donate-app and donate-db. Be sure that you right click and create a new folder when adding a subfolder, drag and dropping another folder from a different directory will cause alot of problems.
3: The newly created folders must be added to version control. Right-click on the working copy folder to add them all at once and select TortoiseSVN and Add...
4: TortoiseSVN Add window lists the two additions and awaits confirmation.
5: Successful addition to version control of the two folders is completed is shown in a add status window.
6: The working copy has blue plus icon overlays for the newly added folders.
7: Now, we are ready to commit these changes. Right-click on the working copy folder and select SVN Commit...
8: A commit window prompts you to
- Enter a message that summarizes the changes. You must write a concise and informative message.
- Make changes to what it's being committed. A list of items and their commit status are displayed to allow for modifications.
9: If you are not logged into Google Code, you are prompted to do it before the commit action takes place. The password is not your password you type in on Google, but one that Google generates. It can be found under the Source tab in the project hosting site, by clicking googlecode.com password.
10: A commit log shows what changes were made to the repository as the result of the commit action.
10b: If you do not have commit access, then the commit log lists an error.
11: Back to the local working copy, the icon overlays are green checks to show that the working copy and repository are now in sync.
12: The newly made revision to the repository can be seen by clicking on the Source tab and then selecting Changes.
CIS 505 Practical Example
It is highly advised that you first read all prior sections of this wiki page before attempting this practical example, as this will alleviate having to explain the basic functionality of using TortoiseSVN.
The URL of the Google project hosting site for the CIS 505 projects is at http://code.google.com/p/unhm-cis-505/. Go here.
Checkout a Sample Project
The very first thing that you need to ensure is that you have been made a project participant with commit access, which will enable you to utilize SVN (subversion) control to make changes to the contents of your project folder (a process called committing). As a project participant of unhm-cis-505, if you click on the Source tab under the project title, you should see the below screen:
Concern yourself with the https://unhm-cis-505.googlecode.com/svn/trunk/ URL, and the "When prompted, enter your generated googlecode.com password." notice. The googlecode.com password is required for members to commit changes. If you have a gmail email address, you only have to type the username and not the @gmail.com...?
You should see Checkout, Browse, and Changes directly underneath the Source tab. Click Browse to view the file structure of the repository.
The project folders in the repository have been setup in the following manner: fmc1 for Food Material Costing team 1, fmc2 for Food Material Costing team 2; md1 and md2 for the two Member Directory teams; finally, ts1 and ts2 are for the two Tire Service teams.
For our example, we are going to be checking out the contents of the sample-project folder in order to see how you will go about checking out your team specific project folder. Follow the subsequent steps to see how it's done.
On your computer, create a new folder where you want to have a working copy of the repository. Using Eclipse, I created sample-project folder in the cis505 Eclipse project.
For this step to work you must have TortoiseSVN installed.
- Minimize Eclipse.
- Go to the folder created at previous step using any file browser on your computer (such as Windows Explorer for Windows).
- Right-click on that folder and, from the context menu that appears, select SVN Checkout.
TortoiseSVN Checkout window is displayed.
- Remember the https://unhm-cis-505.googlecode.com/svn/trunk/ URL?
- Make sure that you copy and paste it to specify the URL of the repository.
- But WAIT!
- Since we only want to checkout the sample-project folder from within the repository, we have to provide additional path parameters, namely cis505/practice/sample-project/. https://unhm-cis-505.googlecode.com/svn/trunk/cis505/practice/sample-project/ is the URL you should specify. Press the OK button.
- Upon checkout completion, the checkout window displays a list of all files that were checked out, how many kilobytes were transferred, how long the transfer took, and the number of files and folders that were transferred. The following is a screenshot of a successful checkout:
- Verify that your local copy of the repository has the structure and content of the code base in the repository. * * * Files and folders on your local machine should be identical to what you see on the project hosting site.
- Local folder should have a green checkmark overlay.
Note: If you have specified a checkout location on a removable drive and no icon overlays display, see the bottommost #FAQ section on this page.
Congratulations, you now know how to checkout a specific folder from within the unhm-cis-505 google code repository!
URLs for Individual Teams
If you were successful practicing with TortloiseSVN checkout command for the sample-project example above, now you are ready to check out the code base of your team project.
- Start with creating in Eclipse a folder that has the name of your team project: fmc1, fmc2, md1, md2, ts1, or ts2. Place this folder in the cis505 Eclipse project.
- Using a file browser on your computer, right click on the newly created folder
- Select TortoiseSVN checkout option.
- The repostiory URLs for the individual project teams are:
- md1: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/md1/
- md2: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/md2/
- ts1: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/ts1/
- ts2: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/ts2/
- fmc1: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/fmc1/
- fmc2: https://unhm-cis-505.googlecode.com/svn/trunk/cis505/fmc2/
Follow the same steps to checkout your team project code bases as for the sample-project folder.
Team members must know who committed and what project material. More importantly, any team member must know why these modifications were made.
It is of MAXIMUM important that you provide a log message with EVERY CHANGE you commit!
See below for an example that shows the TortoiseSVN commit log prompt and an appropriate log message.
- My icon overlays are not displaying over a checked out folder location on a removable drive.
- Answer: To remedy this problem, go to Tortoise SVN -> Settings -> Icon Overlays and check off the box for "Removable Drives" in the Drive Types section.
- When receiving a (405 Method Not Allowed) after attempting to checkout a folder it's possible that the URL of the repository is not correct. Ensure that you are logged into Google Code then go to source -> checkout. The checkout URL needs to be HTTPS as seen in the screenshot below.