2010FallTortoiseSVN

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?

 * 1) TortoiseSVN website is http://tortoisesvn.net/
 * 2) From the home page of the TortoiseSVN website, go to the Downloads section.
 * 3) Where it says Download Application, there are the options available for downloading TortoiseSVN.
 * 4) Choose the version you want to download depending on whether you're using a 32 or 64 bit Windows OS.
 * 5) When the new page loads a window will pop up with the option to Save File or Cancel. Choose to Save File.
 * 6) The file will now be downloaded.
 * 7) If another window comes up asking Open Executable File, click OK to continue and install.
 * 8) Click Run in the Open File - Security Warning box to proceed with the installation.
 * 9) Follow the setup wizard to install TortoiseSVN. Default settings are sufficient to use through the installation.
 * 10) At the end, click Finish to conclude the TortoiseSVN installation.
 * 11) 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.

Testing Installation
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: 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.
 * 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 multiplication sign 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

If no TortoiseSVN overlay is observed, go to http://tortoisesvn.net/node/97 to learn how to troubleshoot the problem.

How to use TortoiseSVN?
To demonstrate TortoiseSVN features, we use an example of a software project that uses Subversion to control changes to its source code. The project is called DONATE and uses SourceForge.net as a hosting site that provides the Subversion version control service. SourceForge.net 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.

A highly recommended resources is http://harfordhackerspace.org/2009/07/sourceforge-and-tortoisesvn-tutorial/ SourceForge and TortoiseSVN Tutorial by Hartford Hackerspace. They do an excellent job with a very effective tutorial on how to get started with TortoiseSVN.

Checkout
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 SourceForge.net and search for DONATE project. The project's page in SourceForge shows the project summary. See the Summary tab highlighted among the links under the project title: Summary, Files, Support, and Develop.



Step 2: Click on Develop link under the project title to find the project's repository URL. Note that the repository's URL in SourceForge.net is https://unhm-donate.svn.sourceforge.net/svnroot/unhm-donate.



Step 3: On your computer, go to a 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://unhm-donate.svn.sourceforge.net/svnroot/unhm-donate.
 * The Checkout directory is the full path of the folder where you will create a working copy for the unhm-donate 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 kbytes 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 unhm-donate folder. It now has a working copy of the code base in the repository.



Update
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.



Commit
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 sourceforge.net account
 * Go to the project to which you want to commit your contributions.
 * Click on the username of the project's administrator. It's listed by the name of title of the project. On the page of the project's admin, there is a About Me box with a link to Send me a message. Click on that link to email the project administrator a request to give you commit permission. Give the project admin your sourceforge username.

When commit privilege has been granted, then you can make changes to your working copies and then commit them to the repository. Let's see it on an example.

1: Deleting files or folders from the unhm-donate 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. Righ-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 not login into sourceforge.net, you are prompt to do it before the commit action takes place.



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 Code on the menu bar below the project title, and SVN Browse menu item under Code.



Troubleshooting
Windows limits the number of icon overlays that can be used at one time. If you don't see the overlay, it is possible that you have encountered this issue. Check this website for information on how to solve this problem: http://tortoisesvn.net/node/97

Q. What goes in the FAQ section?
The FAQ will collect questions we hear from students who are using TortoiseSVN.