Introduction
Subversion is an Open Source application which is used to build version control systems. This document will give a detailed idea about the installation and usage of Subversion by using the tool TortoiseSVN.
Install Subversion Client
TortoiseSVN is a very useful and very easy tool for doing all Subversion repository operations, and is freely available.
For installing TortoiseSVN, follow these steps:
- Download TortoiseSVN from http://tortoisesvn.net/downloads
- Install the application by double clicking the .msi file
- Restart the computer
Accessing the Repository
Right click on the Desktop and from the menu, select TortoiseSVN->Repo Browser, as shown in the figure:
In the new screen, type the URL of the repository, say, http://MyServerName/svn/MyRepos or svn://MyServerName/MyRepos, and click OK.
It will display an authentication screen as shown below, with provision to provide the user ID and password to login to the repository. The Subversion administrator will provide a user ID and password for your repository access.
Check Save authentication for saving the user name and password, and click on OK. Now the following screen will appear displaying the repository contents:
Checking Out a Working Copy
To obtain a working copy, you need to do a checkout from a repository. For checking out a project, right click on any folder inside the repo browser, as shown:
Or, select a directory in Windows Explorer where you want to place your working copy. Right click to pop up the context menu and select the command SVNCheckout... as shown below.
Now it will bring another popup as shown below:
Provide the directory name and press OK. It will checkout (getting the latest version) the selected repository to the checkout directory. If you enter a folder name that does not exist yet, then a directory with that name is created. You should only check out into an empty directory.
Icon Overlay
One of the most visible features of TortoiseSVN is the icon overlays which appear on files in your working copy.
Icon Explanation
- A fresh checked out working copy has a green checkmark as overlay. That means the Subversion status is
normal.
- As soon as you start editing a file, the status changes to
modified and the icon overlay then changes to a red exclamation mark. That way, you can easily see which files were changed since you last updated your working copy and need to be committed.
- If during an update a
conflict occurs, then the icon changes to a yellow exclamation mark.
- If you have set the svn:needs-lock property on a file, Subversion makes that file read-only until you get a lock on that file. Read-only files have this overlay to indicate that you have to get a lock first before you can edit that file.
- If you hold a lock on a file, and the Subversion status is normal, this icon overlay reminds you that you should release the lock if you are not using it, to allow others to commit their changes to the file.
- This icon shows you that some files or folders inside the current folder have been scheduled to be deleted from version control or a file under version control is missing in a folder.
- The plus sign tells you that a file or folder has been scheduled to be added to version control.
Sending the changes you made to your working copy is known as committing the changes. But before you commit, you have to make sure that your working copy is up to date. You can either use TortoiseSVN † Update directly, or you can use TortoiseSVN † Check for Modifications first, to see which files have changed locally or on the server.
If your working copy is up to date and there are no conflicts, you are ready to commit your changes. Select any file and/or folders you want to commit, then TortoiseSVN † Commit....
Now the TortoiseSVN commit dialog will appear.
Clicking on OK will commit your changes to the repository.
Periodically, you should ensure that changes done by others get incorporated in your local working copy. The process of getting changes from the server to your local copy is known as updating. Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update, select the files and/or directories you want, and right click and select TortoiseSVN † Update in the Explorer context menu.
A window will pop up, displaying the progress of the update as it runs.
Changes done by others will be merged into your files, keeping any changes you may have done to the same files. The repository is not affected by an update.
The progress dialog uses colour coding to highlight different update actions:
- Purple
New item added to your WC.
- Dark red
Redundant item deleted from your WC, or missing item replaced in your WC.
- Green
Changes from repository successfully merged with your local changes.
- Bright red
Changes from repository merged with local changes, resulting in conflicts which you need to resolve.
- Black
Unchanged item in your WC updated with newer version from the repository.
If you created new files and/or directories during your development process, then you need to add them to source control too. Select the file(s) and/or directory from your working directory and use TortoiseSVN † Add.
Now it will bring a popup as shown below:
Select the required file(s) and folder(s) and click on OK. After you add the files/directories to source control, the file appears with an added icon overlay, which means you first have to commit your working copy to make those files/directories available to other developers
To add files from outside your working copy, you can use the drag-and-drop handler:
- Select the files you want to add.
- Right-drag them to the new location inside the working copy.
- Release the right mouse button.
- Select the context menu SVN Add files to this WC. The files will then be copied to the working copy and added to version control after clicking the Commit menu item.
Another way to add the files and folder is by using the repo browser; you can directly drag and drop any item into the required location. But it will not update your working copy. You can use the TortoiseSVN† Update option to reflect the newly added items to the working copy.
Delete
If you delete a file/directory using TSVN, the file is removed from your working copy and marked for deletion. The file's parent folder shows a "deleted" icon overlay. You can always get the file back, if you call TortoiseSVN † Revert on the parent folder.
Move
If you want to move files inside a working copy, use the drag-and-drop handler again:
- Select the files or directories you want to move
- Right-drag them to the new location inside the working copy
- Release the right mouse button
- In the popup menu, select the context menu SVN Move versioned files here
After moving, renaming, or deleting, use the SVNCommit option to commit the changes to the repository.
If a file is deleted via the Explorer instead of using the TortoiseSVN context menu, the commit dialog shows those files and lets you remove them from version control too before the commit. However, if you update your working copy, Subversion will spot the missing file and replace it with the latest version from the repository. If you need to delete a version-controlled file, always use TortoiseSVN † Delete so that Subversion doesn't have to guess what you really want to do.
If a folder is deleted via the Explorer instead of using the TortoiseSVN context menu, your working copy will be broken and you will be unable to commit. If you update your working copy, Subversion will replace the missing folder with the latest version from the repository and you can then delete it the correct way using TortoiseSVN † Delete.
You can directly delete any file or folder by using TortoiseSVN repo browser.
By default, Subversion provides a local copy to all users and each user can do their modification. Now the problem is, if a user submits their modification after the submission of another user, Subversion will show a message showing out of date, and so we have to merge those changes to the previous version. That means Subversion works best without locking, using the "Copy-Modify-Merge" methods. But the main problem is in the case of "unmergeable" files; for example, graphics files, if two people change the same file, merging is not possible, so one of them will lose their changes.
For avoiding this problem, a method called "Locking" is used which allows only a single user to modify the repository item.
This can be achieved by doing the following steps.
Set the svn:needs-lock Property to the File(s) or Directory
From the property list window, select the [Add] button.
From the property name combo box, select the svn:need-lock property.
Click on [OK] and submit your changes to the repository by selecting TortoiseSVN † SVNCommit, which is explained above. Now the icon of the property set item is displayed as shown below.
N.B.: For setting the svn:need-lock property for a folder, there is a small difference. The Add property dialog will not display this property in the combo box. So we have to type the property into the editable combo box and check Apply property recursively (if required) for recursively applying the property. The property will not be displayed in the property editor of the folder that we applied, it will list only for the individual subfiles.
We cannot edit a file with the svn:needs-lock property (files with a grey checked icon).
A user cannot edit a file which has the property svn:needs-lock (the files become read-only). So for editing the document, right click on the read-only file and select TortoiseSVN † Get lock and commit the changes to the repository.
Now the locked user gets the privilege to modify the file and submit changes to the repository. Other users cannot edit the file and submit to the repository (like VSS).
For this purpose, right click on the directory in the working folder and select the Add Property editor.
Select the tsvn:logminimize property and set the minimum required length to our required size, say 25, and commit the changes to the repository.
Now each user can commit their changes to this particular directory only after entering comments with minimum 25 charactors length, because the [OK] button will be enabled only after entering a comment with the specified length.
In the above section, we set the minimum comment length and make the comment mandatory. But a user cannot know for how much length the comment is required to enter, and for this purpose, we can mark the width of the comment.
Take the Add Properties editor and select the property tsvn:logwidthmarker as shown, and set the value the same as the log width.
Commit your changes to the repository. Now in all the commit operations in the directory, the commit dialog will mark the width as shown below.
It is very common in software development for changes to be related to a specific bug or issue ID. Users of bug tracking systems (issue trackers) would like to associate the changes they make in Subversion with a specific ID in their issue tracker. This type of associatively is mainly required in the case of code files in which for each bug fix we can commit the URL of the bug system to the subversion.
TortoiseSVN can help the user in two ways:
- When the user enters a log message, a well defined line including the issue number associated with the commit can be added automatically. This reduces the risk that the user enters the issue number in a way the bug tracking tools can't parse correctly.
- When the user browses the log messages, TortoiseSVN creates a link out of each bug ID in the log message which fires up the browser to the issue mentioned.
For integrating TortoiseSVN with a bug tracking system, do the following:
Identify the URL
Normally, a URL for a bug tracking system has an ID part. For example, consider the URL http://tortoisesvn.tigris.org/issues/show_bug.cgi?id=12534.
Here, we can change the ID to a TortoiseSVN internal variable %BUGID%. So the final URL takes the form: http://tortoisesvn.tigris.org/issues/show_bug.cgi?id=%BUGID%.
Apply the URL
For applying the URL to the Subversion working folder, right click on a particular working folder, select Properties, and invoke the Add Property dialog.
Select the bugtraq:url property and enter the above prepared URL as the value of the property. Click on [OK] and again add another property bugtraq:message, and set the same URL as the value and click on OK.
Now the property list dialog should be looking as shown below:
Commit your changes to the repository and your integration with the bug tracking system is almost completed.
Integration in Action
For each commit operation in Subversion, you will get the commit dialog box with a bug-ID/Issue-number edit box, as shown below.
If you have an issue ID for the commit, then enter the bug ID only in the edit box (else keep it blank) and enter the comments in the message, and press OK.
If you put an issue ID, say, 12324, and comment, say, This is a bug message., while taking TortoiseSVN Show Log, the dialog will be displayed as shown below. On clicking the link in the description, it will automatically open the bug tracking system and direct you to the mentioned bug. If you did not put any ID, then there should not be any URL in the description.
Changing the bug number label
For changing the label of the bug-ID/Issue-number edit box in the Commit dialog, select the property bugtraq:label and enter the display text and commit your changes to the repository.
The resulting dialog should look like shown below.
For displaying a warning message box for the blank bug ID input (by default, no message), you can set the property bugtraq:warnifnoissue to yes, as shown below.
Now it will show a message as shown below on committing your changes.
Conclusion
This article will give you a basic idea about the usage of Subversion with the help of a Subversion client tool named TortoiseSVN. For getting a detailed idea about TortoiseSVN and all its features and settings, refer the TortoiseSVN user manual. For finding the TortoiseSVN FAQ, visit http://tortoisesvn.net/faq.
