Source Control
Source Control
SVN
Version 1.0
SoftServe University
SVN
Revision History
Date
June 17, 2008 1.0
Version
Description
Initial version
Author
A.Pereymybida
SoftServe
SoftServe University
SVN
Table of contents
1 What is TortoiseSVN?..........................................................................................................4 1.1 The Repository.................................................................................................................4 1.2 Versioning Models...........................................................................................................5 1.2.1 The Problem of File-Sharing......................................................................................5 1.2.2 The Lock-Modify-Unlock Solution...........................................................................6 1.2.3 The Copy-Modify-Merge Solution............................................................................8 2 Icon Overlays.......................................................................................................................11 3 Importing Data Into A Repository......................................................................................13 3.1 Repository Layout..........................................................................................................13 3.2 Import.............................................................................................................................15 3.3 Checking Out A Working Copy....................................................................................16 3.4 Sending Your Changes To The Repository...................................................................17 3.5 Update Your Working Copy With Changes From Others............................................22 3.6 Resolving Conflicts........................................................................................................24 3.7 Roll back revisions in the repository.............................................................................26 3.7.1 Use the revision log dialog.......................................................................................26 3.7.2 Use the merge dialog................................................................................................26 3.7.3 Use svndumpfilter....................................................................................................27
SoftServe
SoftServe University
SVN
1 What is TortoiseSVN?
TortoiseSVN is a free open-source client for the Subversion version control system. That is, TortoiseSVN manages files and directories over time. Files are stored in a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your files and examine the history of how and when your data changed, and who changed it. This is why many people think of Subversion and version control systems in general as a sort of time machine.
So why is this interesting? So far, this sounds like the definition of a typical file server. And indeed, the repository is a kind of file server, but it's not your usual breed. What makes the Subversion repository special is that it remembers every change ever written to it: every change to every file, and even changes to the directory tree itself, such as the addition, deletion, and rearrangement of files and directories. When a client reads data from the repository, it normally sees only the latest version of the filesystem tree. But the client also has the ability to view previous states of the filesystem. For example, a client can ask historical questions like, "what did this directory contain last
SoftServe For internal use
SoftServe University
SVN
Wednesday?", or "who was the last person to change this file, and what changes did they make?" These are the sorts of questions that are at the heart of any version control system: systems that are designed to record and track changes to data over time.
SoftServe
SoftServe University
SVN
SoftServe
SoftServe University
SVN
The problem with the lock-modify-unlock model is that it's a bit restrictive, and often becomes a roadblock for users:
Locking may cause administrative problems. Sometimes Harry will lock a file and then forget about it. Meanwhile, because Sally is still waiting to edit the file, her hands are tied. And then Harry goes on vacation. Now Sally has to get an administrator to release Harry's lock. The situation ends up causing a lot of unnecessary delay and wasted time. Locking may cause unnecessary serialization. What if Harry is editing the beginning of a text file, and Sally simply wants to edit the end of the same file? These changes don't overlap at all. They could easily edit the file simultaneously, and no great harm would come, assuming the changes were properly merged together. There's no need for them to take turns in this situation. Locking may create a false sense of security. Suppose Harry locks and edits file A, while Sally simultaneously locks and edits file B. But what if A
For internal use
SoftServe
SoftServe University
SVN
and B depend on one another, and the changes made to each are semantically incompatible? Suddenly A and B don't work together anymore. The locking system was powerless to prevent the problemyet it somehow provided a false sense of security. It's easy for Harry and Sally to imagine that by locking files, each is beginning a safe, insulated task, and thus not bother discussing their incompatible changes early on. Locking often becomes a substitute for real communication.
SoftServe
SoftServe University
SVN
SoftServe
SoftServe University
SVN
But what if Sally's changes do overlap with Harry's changes? What then? This situation is called a conflict, and it's usually not much of a problem. When Harry asks his client to merge the latest repository changes into his working copy, his copy of file A is somehow flagged as being in a state of conflict: he'll be able to see both sets of conflicting changes, and manually choose between them. Note that software can't automatically resolve conflicts; only humans are capable of understanding and making the necessary intelligent choices. Once Harry has manually resolved the overlapping changesperhaps after a discussion with Sallyhe can safely save the merged file back to the repository. The copy-modify-merge model may sound a bit chaotic, but in practice, it runs extremely smoothly. Users can work in parallel, never waiting for one another. When they work on the same files, it turns out that most of their concurrent changes don't overlap at all; conflicts are infrequent. And the amount of time it takes to resolve conflicts is usually far less than the time lost by a locking system. In the end, it all comes down to one critical factor: user communication. When users communicate poorly, both syntactic and semantic conflicts increase. No system can force users to communicate perfectly, and no system can detect semantic conflicts. So there's no point in being lulled into a false sense of security that a locking system will somehow prevent conflicts; in practice, locking seems to inhibit productivity more than anything else.
SoftServe University
SVN
While the lock-modify-unlock model is considered generally harmful to collaboration, there are still times when locking is appropriate. The copy-modify-merge model is based on the assumption that files are contextually mergeable: that is, that the majority of the files in the repository are line-based text files (such as program source code). But for files with binary formats, such as artwork or sound, it's often impossible to merge conflicting changes. In these situations, it really is necessary to users to take strict turns when changing the file. Without serialized access, somebody ends up wasting time on changes that are ultimately discarded. While Subversion is still primarily a copy-modify-merge system, it still recognizes the need to lock an occasional file and thus provide mechanisms for this. This feature is discussed later in this book, in the section called Locking.
2 Icon Overlays
Now that you have checked out a working copy from a Subversion repository you can see your files in the windows explorer with changed icons. This is one of the reasons why TortoiseSVN is so popular. TortoiseSVN adds a so called overlay icon to each file icon which overlaps the original file icon. Depending on the Subversion status of the file the overlay icon is different.
A fresh checked out working copy has a green checkmark as overlay. That means the Subversion status is normal.
SoftServe
SoftServe University
SVN
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 readonly 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. Unlike TortoiseCVS (the CVS shell integration) no overlay icon for unversioned files is shown. We do this because the number of icon overlays are limited system wide and should be used economically. In fact, you may find that not all of these icons are used on your system. This is because the number of overlays allowed by Windows is limited to 15. Windows uses 4 of those, and the remaining 11 can be used by other applications. If you are also using TortoiseCVS, then
SoftServe For internal use
SoftServe University
SVN
there are not enough overlay slots available, so TortoiseSVN tries to be a Good Citizen (TM) and limits its use of overlays to give other apps a chance.
Normal, Modified and Conflicted are always loaded and visible. Deleted is loaded if possible, but falls back to Modified if there are not enough
slots.
ReadOnly
is loaded if possible, but falls back to Normal if there are not enough
slots. is only loaded if there are fewer than 13 overlays already loaded. It falls back to Normal if there are not enough slots. Added is only loaded if there are fewer than 14 overlays already loaded. It falls back to Modified if there are not enough slots.
Locked
If a repository contains multiple projects, people often index their layout by branch:
/trunk/paint /trunk/calc /branches/paint /branches/calc /tags/paint /tags/calc
...or by project:
/paint/trunk /paint/branches /paint/tags /calc/trunk /calc/branches /calc/tags
SoftServe
SoftServe University
SVN
Indexing by project makes sense if the projects are not closely related and each one is checked out individually. For related projects where you may want to check out all projects in one go, or where the projects are all tied together in a single distribution package, it is often better to index by branch. This way you have only one trunk to checkout, and the relationships between the sub-projects is more easily visible. If you adopt a top level /trunk /tags /branches approach, there is nothing to say that you have to copy the entire trunk for every branch and tag, and in some ways this structure offers the most flexibility. For unrelated projects you may prefer to use separate repositories. When you commit changes, it is the revision number of the whole repository which changes, not the revision number of the project. Having 2 unrelated projects share a repository can mean large gaps in the revision numbers. The Subversion and TortoiseSVN projects appear at the same host address, but are completely separate repositories allowing independent development, and no confusion over build numbers. Of course, you're free to ignore these common layouts. You can create any sort of variation, whatever works best for you or your team. Remember that whatever you choose, it's not a permanent commitment. You can reorganize your repository at any time. Because branches and tags are ordinary directories, TortoiseSVN can move or rename them however you wish. Switching from one layout to another is just a matter of issuing a series of server-side moves; If you don't like the way things are organized in the repository, just juggle the directories around. So if you haven't already created a basic folder structure inside your repository you should do that now: 1. create a new empty folder on your hard drive 2. create your desired top-level folder structure inside that folder - don't put any files in it yet! 3. import this structure into the repository via a right click on the folder and selecting TortoiseSVN Import... This will import your temp folder into the repository root to create the basic repository layout. Note that the name of the folder you are importing does not appear in the repository, only its contents. For example, create the following folder structure:
C:\Temp\New\trunk C:\Temp\New\branches C:\Temp\New\tags
Import C:\Temp\New into the repository root, which will then look like this:
SoftServe
SoftServe University
SVN
You can also use the repository browser to create new folders directly in the repository.
3.2 Import
Before you import your project into a repository you should: 1. Remove all files which are not needed to build the project (temporary files, files which are generated by a compiler e.g. *.obj, compiled binaries, ...) 2. Organize the files in folders and subfolders. Although it is possible to rename/move files later it is highly recommended to get your project's structure straight before importing! Now select the top-level folder of your project directory structure in the windows explorer and right click to open the context menu. Select the command TortoiseSVN Import... which brings up a dialog box: Figure 5.6. The Import dialog
In this dialog you have to enter the URL of the repository into which you want to import your project. The import message is used as a log message.
SoftServe
SoftServe University
SVN
By default, files and folders which match the global-ignore patterns are not imported. To override this behaviour you can use the Include ignored files checkbox. Refer to Section 5.26.1, General Settings for more information on setting a global ignore pattern. As soon as you press OK TortoiseSVN imports the complete directory tree including all files into the repository. As before, the name of the folder you import does not appear in the repository, only the folder contents. The project is now stored in the repository under version control. Please note that the folder you imported is NOT under version control! To get a version-controlled working copy you need to do a Checkout of the version you just imported.
If you enter a folder name that does not yet exist, then a directory with that name is created. Important You should only check out into an empty directory. If you want to check out your source tree into the same directory that you imported from, Subversion will throw an
SoftServe For internal use
SoftServe University
SVN
error message because it will not overwrite the existing unversioned files with versioned ones. You will have to check out into a different directory or delete the existing sourcetree first. If you want to check out the top level folder only and omit all sub-folders, use the Only check out the top folder checkbox. If the project contains references to external projects which you do not want checked out at the same time, use the Omit externals checkbox. Important If either of these options are checked, you will have to perform updates to your working copy using TortoiseSVN Update to Revision... instead of TortoiseSVN Update. The standard update will include all sub-folders and all externals. It is recommended that you check out only the trunk part of the directory tree. If you specify the parent path of the directory tree in the URL then you might end up with a full hard disk since you will get a copy of the entire repository tree including every branch and tag of your project! Exporting Sometimes you may want to create a local copy without any of those .svn directories, e.g. to create a zipped tarball of your source. Read Section 5.23, Exporting a Subversion Working Copy to find out how to do that.
SoftServe
SoftServe University
SVN
The commit dialog will show you every changed file, including added, deleted and unversioned files. If you don't want a changed file to be committed, just uncheck that file. If you want to include an unversioned file, just check that file to add it to the commit. Items which have been switched to a different repository path are also indicated using an (s) marker. You may have switched something while working on a branch and forgotten to switch back to trunk. This is your warning sign! Commit files or folders? When you commit files, the commit dialog shows only the files you have selected. When you commit a folder the commit dialog will select the changed files automatically. If you forget about a new file you created, committing the folder will find it anyway. Committing a folder does not mean that every file gets marked as changed; It just makes your life easier by doing more work for you.
SoftServe
SoftServe University
SVN
If you have modified files which have been included from a different repository using svn:externals, those changes cannot be included in the same atomic commit. A warning symbol below the file list tells you if this has happened, and the tooltip explains that those external files have to be committed separately. Many unversioned files in the commit dialog If you think that the TSVN commit dialog shows you too many unversioned (e.g. compiler generated or editor backup) files, there are several ways to handle this. You can:
add the file (or a wildcard extension) to the list of files to exclude on the settings page. This will affect every working copy you have. add the file to the svn:ignore list using TortoiseSVN Add to ignore list This will only affect the directory on which you set the svn:ignore property. Using the SVN Property Dialog, you can alter the svn:ignore property for a directory.
Read Section 5.11, Ignoring Files And Directories for more information. Doubleclicking on any modified file in the commit dialog will launch the external diff tool to show your changes. The context menu will give you more options, as shown in the screenshot. You can also drag files from here into another application such as a text editor or an IDE. The columns displayed in the bottom pane are customizable. If you right click on any column header you will see a context menu allowing you to select which columns are displayed. You can also change column width by using the drag handle which appears when you move the mouse over a column boundary. These customizations are preserved, so you will see the same headings next time. Note that due to an implementation detail, you may see two different drag icons, depending on exactly where you position the mouse over the boundary. One has a solid vertical dividing line and the other has two thin vertical lines. Only the solid drag pointer works. Drag and Drop You can drag files into the commit dialog from elsewhere, so long as the working copies are checked out from the same repository. For example, you may have a huge working copy with several explorer windows open to look at distant folders of the hierarchy. If you want to avoid committing from the top level folder (with a lengthy folder crawl to check for changes) you can open the commit dialog for one folder and drag in items from the other windows to include within the same atomic commit. Be sure to enter a log message which describes the changes you are committing. This will help you to see what happened and when, as you browse through the project log messages at a later date. The message can be as long or as brief as you like; many projects have
SoftServe
SoftServe University
SVN
guidelines for what should be included, the language to use, and sometimes even a strict format. You can apply simple formatting to your log messages using a convention similar to that used within emails. To apply styling to text, use *text* for bold, _text_ for underlining, and ^text^ for italics. Figure 5.9. The Commit Dialog Spellchecker
TortoiseSVN includes a spellchecker to help you get your log messages right. This will highlight any mis-spelled words. Use the context menu to access the suggested corrections. Of course, it doesn't know every technical term that you do, so correctly spelt words will sometimes show up as errors. But don't worry. You can just add them to your personal dictionary using the context menu. The log message window also includes a filename and function auto-completion facility. This uses regular expressions to extract class and function names from the (text) files you
SoftServe For internal use
SoftServe University
SVN
are committing, as well as the filenames themselves. If a word you are typing matches anything in the list (after you have typed at least 3 characters), a drop-down appears allowing you to select the full name. The regular expressions supplied with TortoiseSVN are held in the TortoiseSVN installation bin folder. You can also define your own regexes and store them in %APPDATA%\TortoiseSVN\autolist.txt. Of course your private autolist will not be overwritten when you update your installation of TortoiseSVN. If you are unfamiliar with regular expressions, take a look at the online documentation and tutorial at http://www.regular-expressions.info/ . After pressing OK, a dialog appears displaying the progress of the commit. Figure 5.10. The Progress dialog showing a commit in progress
The progress dialog uses colour coding to highlight different commit actions Blue Committing a modification. Purple Committing a new addition. Dark red Committing a deletion or a replacement. Black
SoftServe
SoftServe University
SVN
All other items. This is the default colour scheme, but you can customise those colours using the settings dialog. Read Section 5.26.2.5, TortoiseSVN Colour Settings for more information. Special Folder Properties There are several special folder properties which can be used to help give more control over the formatting of commit log messages and the language used by the spellchecker module. Read Section 5.15, Project Settings for further information. Integration with Bugtracking Tools If you have activated the bugtracking system, you can set one or more Issues in the Bug-ID / Issue-Nr: text box. Multiple issues should be comma separated. Alternatively, if you are using regex-based bugtracking support, just add your issue references as part of the log message. Learn more Section 5.25, Integration with Bugtracking Systems / Issue trackers.
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, 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.
SoftServe
SoftServe University
SVN
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. This is the default colour scheme, but you can customise those colours using the settings dialog. Read Section 5.26.2.5, TortoiseSVN Colour Settings for more information. If you get any conflicts during an update (this can happen if others changed the same lines in the same file as you did and those changes don't match) then the dialog shows those conflicts in red. You can double click on these lines to start the external merge tool to resolve the conflicts. When the update is complete, the progress dialog shows a summary of the number of items updated, added, removed, conflicted, etc. below the file list. This summary information can be copied to the clipboard using CTRL+C. The standard Update command has no options and just updates your working copy to the HEAD revision of the repository, which is the most common use case. If you want more control over the update process, you should use TortoiseSVN Update to Revision... instead. This allows you to update your working copy to a specific revision, not only to the most recent one. Suppose your working copy is at revision 100, but you want it to reflect the state which it had in revision 50 - then simply update to revision 50. In the same dialog you can also choose to update the current folder non-recursively (without all the subfolders) and you can choose whether to ignore any external projects in the update (i.e. projects referenced using svn:externals).
SoftServe
SoftServe University
SVN
Caution If you update a file or folder to a specific revision, you should not make changes to those files. You will get out of date error messages when you try to commit them! If you want to undo changes to a file and start afresh from an earlier revision, you can rollback to a previous revision from the revision log dialog. Take a look at Section B.4, Roll back revisions in the repository for further instructions, and alternative methods. Update to Revision can occasionally be useful to see what your project looked like at some earlier point in its history. But in general, updating individual files to an earlier revision is not a good idea as it leaves your working copy in an inconsistent state. If the file you are updating has changed name, you may even find that the file just disappears from your working copy because no file of that name existed in the earlier revision. If you simply want a local copy of an old version of a file it is better to use the Context Menu Save revision to... command from the log dialog for that file. Multiple Files/Folders If you select multiple files and folders in the explorer and then select Update, all of those files/folders are updated one by one. TortoiseSVN makes sure that all files/folders which are from the same repository are updated to the exact same revision! Even if between those updates another commit occurred. Local File Already Exists Sometimes when you try to update, the update fails with a message to say that there is already a local file of the same name. This typically happens when Subversion tries to checkout a newly versioned file, and finds that an unversioned file of the same name already exists in your working folder. Subversion will never overwrite an unversioned file - it might contain something you are working on, which coincidentally has the same filename as another developer has used for his newly committed file. If you get this error message, the solution is simply to rename the local unversioned file. After completing the update, you can check whether the renamed file is still needed. If you keep getting error messages, use TortoiseSVN Check for Modifications instead to list all the problem files. That way you can deal with them all at once.
SoftServe University
SVN
Also, for every conflicted file Subversion places three additional files in your directory: filename.ext.mine This is your file as it existed in your working copy before you updated your working copy - that is, without conflict markers. This file has your latest changes in it and nothing else. filename.ext.rOLDREV This is the file that was the BASE revision before you updated your working copy. That is, it the file that you checked out before you made your latest edits. filename.ext.rNEWREV This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD revision of the repository. You can either launch an external merge tool / conflict editor with TortoiseSVN Edit Conflicts or you can use any other editor to manually resolve the conflict. You should decide what the code should look like, do the necessary changes and save the file. Afterwards execute the command TortoiseSVN Resolved and commit your modifications to the repository. Please note that the Resolve command does not really resolve the conflict. It just removes the filename.ext.mine and filename.ext.r* files, to allow you to commit your changes. If you have conflicts with binary files, Subversion does not attempt to merge the files itself. The local file remains unchanged (exactly as you last changed it) and you have filename.ext.r* files. If you want to discard your changes and keep the repository version, just use the Revert command. If you want to keep your version and overwrite the repository version, use the Resolved command, then commit your version. You can use the Resolved command for multiple files if you right click on the parent folder and select TortoiseSVN Resolved... This will bring up a dialog listing all conflicted files in that folder, and you can select which ones to mark as resolved.
SoftServe
SoftServe University
SVN
SoftServe
SoftServe University
SVN
SoftServe