Surround SCM. User Guide Version

Transcription

1 Surround SCM User Guide Version

2 Copyrights 2015 Seapine Software, Inc. All rights reserved. Defect Scribe, QA Wizard Pro, Resource Thief, Seapine CM, SoloBug, SoloSubmit, Surround SCM, and TestTrack are trademarks or registered trademarks of Seapine Software, Inc. in the United States and other countries. Borland and StarTeam are trademarks or registered trademarks of Borland, Inc. in the United States and other countries. Delphi and JBuilder are trademarks or registered trademarks of Embarcadero Technologies, Inc. in the United States and other countries. Acrobat Reader is a registered trademark of Adobe, Inc. in the United States and other countries. Sun, JVM, Java, JavaScript, and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. Apple, Mac, Mac OS, Macintosh, Objective-C, and Safari are registered trademarks of Apple Computer, Inc. Microsoft, Windows, Windows NT, Windows Server, Windows Vista, MS Windows, Active Directory, Internet Explorer, Outlook, SQL Server, Visual SourceSafe, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Linux is a trademark of Linus Torvalds. Red Hat, Red Hat Enterprise Linux, and Fedora are registered trademarks of Red Hat, Inc. in the United States and other countries. SUSE is a registered trademark of Novell Inc. in the United States and other countries. Debian is a registered trademark of Software in the Public Interest, Inc. Ubuntu is a registered trademark of Canonical Ltd. IBM, ClearCase, and all other IBM brand and product names are service marks, trademarks or registered trademarks of IBM Corporation or its subsidiaries in the United States and other countries. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. PVCS, Serena PVCS Professional Suite, and Serena PVCS Version Manager are registered trademarks of Serena Software, Inc. All other product names mentioned herein are the trademarks of their respective owners. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission of Seapine Software, Inc. Your license agreement with Seapine Software, Inc., which is included with the product, specifies the permitted and prohibited uses of the product. Any unauthorized duplication or use of this software, in whole or in part, in print, or in any other storage and retrieval system is forbidden. Information in this document is subject to change without notice and does not represent a commitment on the part of Seapine Software, Inc. Unless otherwise noted, all companies, products, street addresses, and persons contained herein are purely fictitious. Mention of third-party companies and products is for informational purposes only and does not constitute an endorsement. Seapine Software, Inc Cintas Boulevard Mason, OH (513) documentation@seapine.com

3 Contents What's New 1 Getting Started 3 Starting Surround SCM 3 Managing server connections 4 Adding server connections 5 Editing server connections 6 Deleting server connections 6 Surround SCM interface 7 Setting general user options 8 Changing your password 10 Managing Working Directories 11 Setting working directories for repositories 11 Configuring working directories 12 Adding working directories 12 Editing working directories 13 Deleting working directories 13 Opening working directories 14 Setting the file manager on Linux 14 Getting and Viewing Files 15 Getting files 15 Understanding file status 17 Viewing files in Surround SCM 17 Setting viewer/editor options 17 Editing viewer/editor settings 18 Deleting viewer/editor settings 19 Changing the internal viewer/editor text options 19 Opening local files from Surround SCM 19 Modifying Files 21 Checking out files 21 Creating local directories 22 Undoing check out 23 Editing files in Surround SCM 24 Checking in updated files 24 Rolling back files 27 Adding files to Surround SCM 28 i

4 Setting custom fields 31 Changing multiple custom fields 32 Changing workflow states 33 Moving files 34 Renaming files 35 Removing files 35 Restoring removed files 36 Deleting files permanently 37 Comparing and Merging Files 39 Viewing file differences 39 Merging files 40 Merging unrelated files 42 Running file differences reports 43 Viewing image file differences 45 Setting diff/merge options 46 Configuring diff application options 47 Configuring merge application options 48 Editing diff/merge application options 49 Deleting diff/merge application options 49 Configuring diff/merge application settings 49 Performing Code Reviews 51 About the code review process 51 Understanding code review status 53 Managing code reviews 53 Creating code reviews 54 Adding files to code reviews 55 Selecting code reviews 59 Removing files from code reviews 59 Starting code reviews 60 Opening code reviews 60 Editing code reviews 61 Reviewing files in code reviews 62 Reviewing changes between file versions 62 Reviewing files 64 Adding review comments to files 65 ii

5 Editing and deleting review comments 66 Addressing code review comments 66 Viewing unaddressed review comments 67 Searching for code reviews 67 Running code review reports 68 Viewing code reviews files are included in 71 Deleting code reviews 72 Viewing File Information 73 Using the file details pane 73 Viewing line-by-line file changes 74 Working with annotate results 75 Viewing file history 76 Viewing file history details 78 Viewing graphical file history 79 Viewing general file information 80 Viewing checked out file information 80 Viewing shared file information 80 Viewing file custom field information 81 Setting Up Notifications 83 Adding notifications 83 Editing notifications 86 Duplicating notifications 86 Disabling and enabling notifications 86 Deleting notifications 86 Customizing Surround SCM 89 Customizing the Source Tree window 89 Setting Source Tree options 90 Setting file information display options 91 Customizing shortcut menus 92 Customizing toolbars 93 Changing the user interface mode 94 Changing defaults for Surround SCM dialogs 94 Setting Get Files dialog defaults 95 Setting Check In Files dialog defaults 96 Setting Check Out Files dialog defaults 97 iii

6 Setting Undo Check Out Files dialog defaults 97 Setting Add Files dialog defaults 98 Grouping file extensions 99 Adding file extension groups 100 Setting Shelve Files dialog defaults 100 Managing Repositories 103 Creating repositories 103 Viewing differences between repositories and working directories 104 Resolving missing moved and renamed items 107 Pushing changes to repositories 108 Renaming repositories 109 Moving repositories 110 Cloaking and uncloaking repositories 111 Viewing cloaked repositories 112 Removing repositories 112 Restoring repositories 113 Deleting repositories permanently 114 Sharing Files Between Repositories 117 Breaking shares 118 Viewing Repository Information 119 Viewing repository history 119 Viewing general repository information 120 Viewing repository shadow folders 121 Using Changelists 123 Creating changelists 123 Adding file actions to changelists 124 Managing changelists 124 Viewing changelist details 125 Working with pending changelists 125 Renaming changelists 127 Removing changelists 128 Editing changelist file actions 128 Moving changelist actions 128 Removing changelist file actions 129 Adding comments to changelist files 129 iv

7 Committing pending changelists 129 Working with committed changelists 130 Searching for committed changelists 131 Viewing changelist file differences 132 Merging changelist files 133 Rolling back changelist actions 135 Rollback changelist action resolutions 137 Selecting changelists 139 Using Labels 141 Configuring labels 141 Creating labels 143 Viewing labels 144 Editing labels 144 Duplicating labels 145 Hiding labels 145 Deleting labels 145 Labeling files 146 Selecting labels 147 Searching for labels 147 Viewing label differences 148 Viewing label history 149 Running labeled files reports 150 Removing labels from files 151 Using Shelves 153 Shelving files 153 Adding files to existing shelves 155 Managing shelves 156 Creating shelves 157 Editing shelves 158 Deleting shelved files and shelves 158 Viewing shelved file differences 158 Unshelving files 159 Branching 161 About branches 161 When to branch 162 v

8 Branching example 163 Branch status icons 165 Creating branches 166 Using branch templates 168 Including and excluding repositories for new branches 169 Selecting branch templates 170 Merging Files Between Branches 173 Deciding between promoting, rebasing, and duplicating 173 Viewing branch differences 173 Copying files across branches during check in 176 Running branch differences reports 177 Promoting branches 180 Promote preview 182 Promote actions 184 Promoting files 185 Rolling back promoted files 188 Rebasing branches 189 Rebase preview 192 Rebase actions 193 Rebasing files 194 Rolling back rebased files 197 Duplicating selected changes across branches 198 Duplicate changes preview 200 Duplicate changes actions 201 Tracking duplicated changes 201 Viewing Branch Information 203 Viewing branch history 203 Viewing branch history details 203 Viewing general branch information 204 Viewing the graphical branch tree 205 Finding Files 207 Searching for files 207 Adding restrictions 209 Adding text restrictions 209 Using regular expressions 210 vi

9 Adding number restrictions 212 Adding date restrictions 212 Adding multiple list selection restrictions 213 Adding condition restrictions 214 Adding event restrictions 214 Adding label restrictions 215 Adding TestTrack item number restrictions 216 Adding security group restrictions 216 Adding branch and repository restrictions 217 Adding action restrictions based on user and date 217 Searching for text in files 219 Differences between indexed and non-indexed searches 221 Text search examples 223 Configuring filters 225 Adding filters 225 Applying filters to the source file list 227 Editing filters 227 Duplicating filters 227 Deleting filters 228 Browsing to files and repositories 228 Bookmarking files, repositories, and branches 229 Managing bookmarks 230 Creating and Running Reports 231 Report types 231 Configuring reports 232 Creating reports 233 Creating code review coverage reports 234 Creating history reports 237 Creating list reports 239 Creating security group reports 242 Creating trend reports 244 Creating workflow progress reports 245 Charting report data 247 Adding external reports to Surround SCM 247 Editing reports 248 vii

10 Duplicating reports 248 Deleting reports 249 Running reports 249 Running quick reports 249 Saving the source file list 250 Printing the source file list 251 Integrating with TestTrack 253 Configuring TestTrack connections 253 Adding TestTrack connections 253 Editing TestTrack connections 254 Deleting TestTrack connections 254 Entering TestTrack login information 255 Attaching source files to TestTrack items 255 Viewing TestTrack items 257 Adding TestTrack issues 258 Editing TestTrack issues 259 Fixing TestTrack issues 259 Finding files attached to TestTrack items 260 Analyzing issue risk in files 261 Selecting TestTrack items 263 Integrating with Third-Party Applications 265 Setting integration options 265 Setting plug-in directories 266 Integrating with IDEs and applications that support SCCI 267 Integrating with issue tracking tools 268 Entering issue tracking login information 268 Attaching source files to external issues 268 Viewing external issues 270 Fixing external issues 270 Using the Windows Explorer and Mac Finder integrations 270 Using the Windows Explorer plug-in 271 Using the Mac Finder plug-in 272 Integrating with CMIS 273 Setting Up Surround SCM 275 Starting the Seapine License Server 275 viii

11 Starting the Surround SCM Server 276 Controlling Security and User Access 277 Security levels 277 Security examples 278 Controlling access with security groups 279 Adding security groups 280 Viewing security groups 282 Editing security groups 282 Duplicating security groups 283 Deleting security groups 283 Controlling access to specific repositories 283 Controlling access to specific branches 285 Setting branch security commands 286 Managing users 286 Adding users 287 Retrieving global users 289 Viewing users 289 Editing users 290 Deleting users 290 Viewing licenses in use 290 Voiding check out 291 Configuring the Surround SCM Server 293 Setting general global server options 294 Securing communication between clients and the Surround SCM Server 296 Configuring RSA key exchange 299 Setting server merge options 300 Activating third-party issue tracking plug-ins 301 Setting logging options 302 Setting server options 302 Setting notification options 303 Setting Seapine License Server options 304 Setting automatic software update check options 305 Checking for new Surround SCM versions 307 Scheduling data purges 307 Setting general mainline options 308 ix

12 Supported keywords 310 Setting changelist server options 311 Setting minimum comment lengths for actions 312 Setting auto-detect and ignore file options 312 Configuring default user options 314 Configuring Custom Fields 317 Adding custom fields 318 Editing custom fields 319 Deleting custom fields 319 Restoring deleted custom fields 319 Automating Actions with Triggers 321 Trigger examples 322 Configuring triggers 322 Adding triggers 323 Adding triggers to run executables 326 Adding triggers to prevent events 327 Adding triggers to append comments to events 328 Adding triggers to users 329 Editing templates 330 Adding triggers to set workflow states 332 Adding triggers to set custom field values 332 Editing triggers 333 Adding trigger actions 333 Editing trigger actions 334 Deleting trigger actions 334 Duplicating triggers 335 Disabling and enabling triggers 335 Deleting triggers 335 Configuring Workflows 337 About workflows 337 Workflow example 337 About the default workflow template 339 Customizing workflows 340 Planning your workflow 341 Automating workflows 341 x

13 Configuring workflow states 341 Adding workflow states 342 Editing workflow states 343 Deleting workflow states 343 Restoring deleted workflow states 343 Configuring workflow templates 344 Adding workflow templates 344 Adding states to workflow templates 345 Removing states from workflow templates 346 Editing workflow transitions 346 Editing workflow templates 347 Duplicating workflow templates 347 Deleting workflow templates 348 Diagramming workflows 348 Setting the default workflow 349 Setting workflows for specific repositories 349 Configuring Code Review Settings 351 Configuring Shadow Folders 353 Adding shadow folders 353 Editing shadow folders 355 Refreshing shadow folder contents 355 Deleting shadow folders 355 Maintaining Branches 357 Managing branch attributes 357 Indexing branches for optimized searches 360 Managing the indexing server 360 Turning branch indexing on or off 361 Viewing branch index details 362 Viewing the indexing server log 363 Renaming branches 364 Hiding and unhiding branches 364 Freezing and unfreezing branches 365 Inactivating and activating branches 365 Modifying templates for existing branches 366 Changing branch type 367 xi

14 Changing branch caching 368 Setting branch caching server options 369 Removing branches 370 Restoring removed branches 370 Deleting branches permanently 371 Managing Mainline Branches 373 Creating mainline branches 373 Renaming mainline branches 374 Overriding server options for specific mainline branches 374 Moving repositories to different mainline branches 376 Moving mainline branches to different databases or servers 378 Copying mainline branches to different databases 379 Removing mainline branches 380 Restoring removed mainline branches 380 Restoring RDBMS mainline branches 381 Restoring non-rdbms mainline branches 382 Deleting mainline branches permanently 383 Maintaining Surround SCM Databases 385 Creating Surround SCM tables 385 Setting the default server database location 386 Converting the server database to a different type 386 Changing the server database location 388 Adding RDBMS connections 389 Editing RDBMS connections 391 Deleting RDBMS connections 391 Backing up Surround SCM databases 391 Locking databases for backups 392 Resolving database issues 392 Setting database analyze and repair options 392 Analyzing and repairing databases 394 Repairs for common database issues 396 Working with the Surround SCM Server Log 397 Server log levels 398 Managing Mail 399 Resending mail 399 xii

15 Deleting mail 399 Configuring TestTrack Integration 401 Enabling TestTrack integration 401 Syncing field labels with TestTrack 401 Setting TestTrack integration options for repositories 402 Upgrading Surround SCM 405 Upgrading mainline branches 405 Upgrading old mainline branches 405 Upgrading non-rdbms mainline branches 406 Resolving custom field and workflow issues 407 Upgrading RDBMS connections 409 Upgrading legacy labels 409 Deleting legacy labels 411 Using Proxy Servers 413 About proxy servers 413 Starting the Surround SCM Proxy Server 414 Configuring proxy servers 415 Adding proxy servers 416 Editing proxy server settings 418 Deleting proxy servers 419 Setting proxy server options 419 Managing the Surround SCM Web Server 421 Starting the Surround SCM Web Server 421 Managing the Surround SCM CMIS Server 423 Starting the Surround SCM CMIS Server 423 Starting the Surround SCM CMIS Admin Utility 423 Configuring CMIS Server options 423 Adding CMIS repositories 424 Editing CMIS repositories 425 Deleting CMIS repositories 426 Troubleshooting Surround SCM CMIS Server issues 426 Using the Surround SCM API 427 Avoiding conflicts with the Surround SCM Client and CLI 427 Using the C API 427 Using the Java API 428 xiii

16 Using the.net API 429 Appendix A: Security Commands 431 General security commands 431 Admin security commands 433 Users security commands 436 Security Groups security commands 437 Files security commands 437 Branch security commands 439 Appendix B: Environment Variables 445 Appendix C: Accessing WebDAV Directories 449 Web browser 449 Windows network place 450 Mac OS X Finder 452 Linux filesystem path 453 Glossary 455 Index 459 xiv

17 What's New Surround SCM includes the following key features. For a complete list of features, enhancements, and bug fixes, check out the release notes. New code review reports You can create and run new code review reports to analyze information about specific code reviews and gain insight about your review process. Code review reports include historical information about a code review and files in it. Use these reports to review unaddressed comments, review your code review process, or save process information for audits. See Running code review reports, page 68. Code review coverage reports include information about file versions in code reviews and if the files are approved or still in review. Use these reports to determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. See Creating code review coverage reports, page 234. Add bookmarks to use in any branch You can now add bookmarks that navigate to the repository or file in the branch selected in the Source Tree window instead of saving a specific branch in the bookmark. See Bookmarking files, repositories, and branches, page 229. Other enhancements Show or hide files with different timestamps in the Working Directory Differences dialog box. See Viewing differences between repositories and working directories, page 104. Edit files in pending changelists from the Pending Changelists window or pane. See Working with pending changelists, page 125. View the number of files in a shelf in the Shelves window and Edit Shelf dialog box. See Managing shelves, page 156. When starting a code review that contains unaddressed comments, you are now prompted to confirm starting the review. This can help you identify if the review contains comments you addressed, but forgot to mark as addressed before restarting the review. See Starting code reviews, page 60. Set the minimum number of characters for comments entered when users perform specific actions instead of using the same minimum for all actions. See Setting minimum comment lengths for actions, page 312. Perform non-indexed searches for text in files on indexed branches. See Searching for text in files, page 219. See Differences between indexed and non-indexed searches, page 221 for information about the differences between the types of searches. 1

18

19 Getting Started Following are some common tasks you should complete to get started with Surround SCM. If you need help installing Surround SCM, see the Surround SCM installation help. Note: If you are an administrator, you must set up the Surround SCM Server before users can work with source control files. See Setting Up Surround SCM, page Start Surround SCM, add a server connection, and log in. Source files are stored on servers. The first time you start Surround SCM, you need to add a connection to the Surround SCM Server you want to access. Ask an administrator for the server name and address. See Starting Surround SCM, page 3 and Managing server connections, page Familiarize yourself with the Surround SCM interface. See Surround SCM interface, page If you are working with files that are already in Surround SCM, you may perform the following tasks: Optionally create a workspace branch to isolate your changes from other users. Workspace branches are private and allow you to work with files without affecting file versions used by other users. See Creating branches, page 166. Set working directories for the Surround SCM repositories you will use. A working directory is a local or network directory where you make changes to files under source control. You must map a repository to a working directory before you can work with files. See Setting working directories for repositories, page 11. Get files to add local copies to a working directory or another directory. See Getting files, page 15. Check out files so you can modify them. See Checking out files, page 21. Check in files to share changes with other users. See Checking in updated files, page 24. If you use non-exclusive check outs, you should diff and merge files to make sure changes are checked in correctly. See Comparing and Merging Files, page If you are working on a new project or part of a project, and need to add files to Surround SCM, you may perform the following tasks: Optionally create a workspace branch to isolate your changes from other users. See Creating branches, page 166. Create repositories to organize files. If you want to use the same repository structure as a directory structure, you can automatically add repositories when you add files. See Creating repositories, page 103. Add files to Surround SCM. See Adding files to Surround SCM, page As you become more familiar with Surround SCM, you may want to configure user options. You can customize the Surround SCM interface and user options, such as your login preferences and default settings for dialog boxes, to help you work more efficiently. See Customizing Surround SCM, page 89 and Setting general user options, page 8. Starting Surround SCM Make sure the Seapine License Server and Surround SCM Server are running before you start Surround SCM. 3

20 Managing server connections If this is your first time using Surround SCM and you have not set up any users, you can log in as the default administrative user. The username is Administrator and there is no password. Note: If you try to log in to Surround SCM and the Seapine License Server is not running or is not found, you are prompted to log in using the local SCM admin password. This allows you to log in and verify the Seapine License Server settings. 1. Windows Choose Programs > Seapine Software > Surround SCM > Surround SCM Client. Mac Double-click the Surround SCM Client icon in the Applications/Surround SCM folder. Linux Enter /usr/bin/scmgui The login dialog box opens. 2. Select the Server you want to connect to. If you need to add a server, see Adding server connections, page Enter your Username and Password or select Use single sign-on to log in with your network credentials. Ask your Surround SCM administrator for information about single sign-on. Note: Single sign-on is only available for Windows and Mac. 4. Select Always login with this username and password to automatically log in to the selected server. Tip: To clear this option, choose Tools > User Options > General and clear the Always login with this username and password option. You can also clear the option the next time you log in. 5. Click Connect. You are logged in and ready to start using Surround SCM. Note: If a valid Surround SCM license is not found on the Seapine License Server, you are prompted to enter a serial number. Enter a serial number in the Add License dialog box and click OK. Managing server connections Surround SCM source files are stored on servers, which you need to set up access to. A list of all the servers you have added is displayed on the Setup Server Connections dialog box. 1. Choose File > Connect to Server to open the Surround SCM login dialog box. 2. Click Setup. The Setup Server Connections dialog box opens. 4

21 Adding server connections 3. Select a server and click Top, Move Up, Move Down, or Bottom to reorder the list. You may want to move the servers you access most frequently to the top of the list. 4. Click Find to find all Surround SCM Servers on the local network. When the search is complete, the Available Surround SCM Servers dialog box opens. To find servers with an IPv6 address, select Include IPv6 in scan and click Refresh. Select an available server and click Add to create a connection without manually entering the address or port number. Enter a unique name for the server and click OK. Click Close when you finish adding available servers. 5. Click Add to create a server connection. See Adding server connections, page Select a server and click Edit to change the information. See Editing server connections, page Select a server and click Delete to delete the connection. See Deleting server connections, page 6. Note: If you configure multiple server connections and need to access a different server, you can connect without closing. Choose File > Connect to Server to open the Surround SCM login dialog box. Select the server you want to connect to and click Connect. Adding server connections You need to add a connection to access Surround SCM Servers that source files are stored on. Your Surround SCM administrator can provide the server address and port number. 1. Choose File > Connect to Server to open the Surround SCM login dialog box. 2. Click Setup. The Setup Server Connections dialog box opens. 3. Click Add. The Add Surround SCM Server dialog box opens. 5

22 Editing server connections 4. Enter a Server name. Use a descriptive name, such as a department name, to make it easy to identify the server. 5. Enter the Server address and Server port number. Surround SCM clients connect to the server on this port via TCP/IP. The default port number is Valid values are Note: If you received a server settings file from your Surround SCM administrator, import it instead of manually entering the information. Click Import, select the XML file and, click Open. The Server address, Server port, and Public key fingerprint fields are automatically populated. The public key provides additional security required to connect to the Surround SCM Server. Contact your Surround SCM administrator for additional help. 6. Click OK. The server connection is added and you return to the Setup Server Connections dialog box. 7. To change the order of the servers displayed in the login dialog box, select a server and click Top, Move Up, Move Down, or Bottom. 8. Click Close when you finish. Editing server connections You can edit the Surround SCM Server name, address, or port number. 1. Choose File > Connect to Server to open the Surround SCM login dialog box. 2. Click Setup. The Setup Server Connections dialog box opens. 3. Select the server and click Edit. 4. Make any changes and click OK. Deleting server connections You can delete any server connections you no longer use. 1. Choose File > Connect to Server to open the Surround SCM login dialog box. 2. Click Setup. The Setup Server Connections dialog box opens. 3. Select the server and click Delete. 6

23 Surround SCM interface You are prompted to confirm the deletion. 4. Click Yes. The server is deleted. Surround SCM interface The Source Tree window displays the branches, repositories, and source files in Surround SCM. The actions available in this window depending on the function you are performing and your security permissions. You may want to take some time to familiarize yourself with the Source Tree window before working with files. You can customize this window as you become more comfortable working in it. See Customizing the Source Tree window, page 89. # Area Use to: Menu bar Access all Surround SCM actions. Toolbars Branch menu Access the most commonly used Surround SCM actions. To display or hide a toolbar, choose View > Toolbars and the toolbar name. You can also add buttons to the custom toolbar to include actions you frequently perform. See Customizing toolbars, page 93. Switch between branches. Only branches you can access are displayed in the menu. 7

24 Setting general user options # Area Use to: Branches tree Repositories tree Source file list Shortcut menus File details pane Activity Log tab Pending Changelists tab View available branches in a tree hierarchy. Many users hide the Branches tree and use the Branch menu to access branches. To hide the Branches tree, choose View and clear the Branch Tree option. Icons indicate branch type and status. See Branch status icons, page 165. View available repositories in a branch. View all source files in a selected repository. You can customize the columns to display the information you need. You can also filter the list to display specific files and search for files by name. See Customizing the Source Tree window, page 89. Quickly perform common actions. Shortcut menus open when you right-click windows and trees. You can customize the actions available in the Branches tree, Repositories tree, and source file list shortcut menus. See Customizing shortcut menus, page 92. View the selected file s properties, history, check out status, sharing information, custom fields, and a preview of local image files. See Using the file details pane, page 73. View information about the actions you perform on files, such as the file check out location. View pending changelists and commit changes. You can right-click a changelist or file to perform an action on it. See Working with pending changelists, page 125. Setting general user options Surround SCM user options can be customized to help you work more efficiently. For example, you can automatically log in to Surround SCM. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the General category. 8

25 Setting general user options 2. Select any Server Connection options. These are the same options in the Surround SCM login dialog box, except for the file compression option. Always login with this username automatically logs in to the current Surround SCM Server using the specified username and password. Use single sign-on automatically logs in to the current Surround SCM Server using your network credentials. Ask your Surround SCM administrator for more information. Use external authentication prompts for your credentials when logging in. Ask your Surround SCM administrator for more information. Compress file transfers compresses data during file transfers, which is helpful if you have a slow connection to the Surround SCM Server or proxy server (e.g., you connect to the server via an ISP). Compression works best on certain types and sizes of files. This option may slow performance because of the time needed to compress and decompress files. 3. Select a Text File Format option. Select Append end-of-line if necessary to ensure text files end with an end-of-line character. 4. Select a File comparison option. Surround SCM compares files before updating the file status or retrieving files from the server when a get or check out is performed. By timestamp checks the timestamp to see if the file was modified after it was retrieved. By timestamp and CRC checks the timestamp and performs a CRC (Cyclic Redundancy Checksum) check. This method is slower than the timestamp option. The difference is noticeable when recursively getting or checking out all files. 5. Select View HTML reports in external web browser to view reports in a browser instead of the internal viewer. 6. Select Override local computer name to override the computer name cached by the Surround SCM and enter a new name. 9

26 Changing your password Select this option if you always want Surround SCM to use a specific computer name instead of the operating system value. When Surround SCM starts, it caches the computer name from the operating system. In some cases, the operating system may return the computer name inconsistently between sessions, which can cause working directory issues or prompt you that files were checked out to a different computer during check in. For example, this may occur if you use a dual boot system and each boot configuration has the same computer name, but the operating systems have a different directory structure. 7. Click OK to save the changes. Changing your password You may be able to change your Surround SCM password. You cannot change your password if it is centrally managed by LDAP. Ask your Surround SCM administrator for help. 1. Choose Tools > Change Password. The Change Password dialog box opens. 2. Enter the current password. 3. Enter and confirm the new password. 4. Click OK to save the changes. 10

27 Managing Working Directories A working directory is a location on a local or network drive that a Surround SCM repository is mapped to. When you check out a file, a writable copy is added to the working directory and you can make changes to this copy. You must set a working directory before you can work with files. Setting working directories for repositories You must map a repository to a working directory before you can work with files. When you get or check out files, they are saved in the working directory. Note: You can also manage working directories with the working directory editor. See Configuring working directories, page Select the repository you want to set the working directory for. 2. Choose Repository > Set Working Directory. The Set Working Directory dialog box opens. 3. Enter a Working directory path or click Browse to select a directory. 4. Select Allow child repositories to inherit this working directory if you want child repositories to use the same directory. The working directory is set automatically when subrepositories are added. 5. Select Inherit working directory from parent to use the parent repository s working directory. The working directory is set as <parent s path> \ <repository name>. 6. Select Get files to working directory to retrieve a copy of the files to the working directory. Files in subrepositories are also copied to local directories if the Allow child repositories to inherit this working directory option is selected. If the local directories do not exist, you are prompted to create them. See Creating local directories, page Click OK to set the working directory. Note: You are prompted to resolve conflicts if you reuse a working directory. Click Remove to remove the existing setting and switch the working directory to the new repository. Click Don't Remove to keep the existing setting and then select a directory not used for other repositories. 11

28 Configuring working directories Configuring working directories Use the working directory editor to add, edit, or delete working directories from one location. 1. Choose Tools > Working Directories. The Working Directories dialog box opens. A list of working directories is displayed. Select a Computer to filter the list. 2. Click Add to add a working directory. See Adding working directories, page Select a working directory and click Edit to change it. See Editing working directories, page Select a working directory and click Delete to delete it. See Deleting working directories, page Click Close to close the Working Directories dialog box. Adding working directories Add working directories to specify the local or network directories to map repositories to. When you check out files, writable copies are added to the corresponding working directory. 1. Choose Tools > Working Directories. The Working Directories dialog box opens. 2. Click Add. The Surround SCM Repository Browser opens. 3. Select a branch and repository and click OK. The Add Working Directory dialog box opens. 12

29 Editing working directories 4. Enter a Working directory path or click Browse to select a directory. Note: Working directory conflicts occur if you reuse a working directory. To resolve a conflict, create a new local directory or select a directory that is not used for other repositories. 5. Select Allow child repositories to inherit this working directory if you want child repositories to use the same directory. The working directory is automatically set when subrepositories are added. 6. Click OK. The working directory is set. Editing working directories Edit a working directory to change the local or network directory to save writable file copies in and the child repositories inherit settings. 1. Choose Tools > Working Directories. The Working Directories dialog box opens. 2. Select a working directory and click Edit. The Edit Working Directory dialog box opens. 3. Make any changes. 4. Click OK to save the changes. Deleting working directories You can delete a working directory set up on any computer you used. 1. Choose Tools > Working Directories. The Working Directories dialog box opens. 2. Select a working directory and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The working directory is deleted. 13

30 Opening working directories Opening working directories You can open working directories from Surround SCM to help save time locating files on your computer. The directory automatically opens in Windows Explorer or Mac OS X Finder. On Linux, you need to configure a file manager. See Setting the file manager on Linux, page 14. Note: You cannot open directories for multiple files with different working directories. 1. Right-click a file or repository and choose one of the following options: Windows Choose Open Containing Folder. Mac Choose Reveal in Finder. Linux Choose Open Working Directory. The working directory for the selected file or repository opens. Note: If the menu option is not available, you need to add it to the repository or file list shortcut menu. See Customizing shortcut menus, page 92. Setting the file manager on Linux If you use Linux, you need to configure the file manager used to open working directories from Surround SCM. See Opening working directories, page 14. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the File Manager category. 2. Enter File manager command used to open the file manager and any command line arguments, or click Browse to select the path. The %1 variable is replaced with the working directory path when you select the Open Working Directory command. The variable is automatically added to the command if you do not enter it. 3. Click OK to save the changes. 14

31 Getting and Viewing Files If you want to view files without making any changes, you can get read-only copies of files from Surround SCM. You can also view text, binary, and image files directly in Surround SCM or another application that you choose. Getting files Get files when you want to view a file but do not need to make any changes. A read-only copy of the file is created in the specified directory. After you get a file, the local copy does not stay in sync with the file on the Surround SCM Server. For example, if you get a copy of a file on Monday and another developer changes it on Wednesday, the server copy and local copy are out of sync. You have to get the file again to get the updates. 1. Select the files or repository and choose Activities > Get. The Get Files dialog box opens. 2. Select the Location you want to retrieve the files to. The working directory is the default location. Click Browse to select a different directory. 3. Select Recursive to include all child repositories. Files in the selected repository and any child repositories are copied to the working directory. 4. Optionally expand the Get based on area to select options for retrieving files based on version, timestamp, label, or workflow state. Latest version gets the latest server version. Timestamp gets files based on the selected date and time. Label gets files based on the selected label. Click Select to search for a label. See Selecting labels, page 147. Latest version in state gets the latest version based on the selected workflow state. Optionally select Include removed files when you get files based on timestamp, label, or the latest version in a state. You may want to include removed files to ensure you have a complete set of files. 15

32 Getting files 5. Optionally expand the Advanced options area to select advanced get options. 6. Select Make files writable to get the files in read-write mode. 7. Select Force file retrieval from server to get the server copy. Surround SCM checks the local copy of the file to determine if the file is current. Select this option if you want to retrieve a new copy of the file from the server even if the local copy is current. 8. Select Merge should first attempt auto-merge to enable auto-merges. You are only prompted to manually merge files if auto-merge fails. 9. Select an Overwrite option to specify what to do if the local file and server file are different or how to handle modified files in the working directory that were removed from the server. Prompt prompts you to replace the file, skip the file, or merge the server and local files. If you merge the files, the get operation finishes after the files are reviewed and merged. If you get a repository to the working directory, this option prompts you to delete or skip the file. Replace automatically overwrites the local file with the server file or deletes the local file if it was removed from the server. Skip skips the file. 10. Select a File timestamp option. The timestamp is set on the local files when they are retrieved from the server. Current sets the timestamp to the current date and time. Modified sets the timestamp to the date and time that the files were last modified. Check in sets the timestamp to the date and time that the files were last checked in. 11. Click OK to get the files. The files are copied to the specified directory. 16

33 Understanding file status Tip: If the local directory does not exist, you are prompted to create it. See Creating local directories, page 22. Understanding file status The status of local files in your working directory is displayed in the Source Tree window Status column. The information in this column can help you determine if local files are out of sync with the Surround SCM Server. When you get or check out files, the.myscmserverinfo file in your working directory is updated. Surround SCM compares this file to the working directory files to determine the status. Status Current Missing Modified Old Old, Modified Working directory conflict Unknown Explanation The local file is the same as the current Surround SCM Server file. The file was not found on your computer. The local file was modified and does not match the Surround SCM Server file. A newer version was checked in and the local file is no longer current. A newer version was checked in after you modified the local file. This happens if you check out a file, modify it locally, and another user checks in a new version. Surround SCM cannot determine the working directory location. This happens if you set the same working directory for two or more branches or another user sets a working directory in the same location you did (for example, a shared network drive). Surround SCM cannot determine the file status. This happens if the.myscmserverinfo file is removed or modified. Viewing files in Surround SCM When you view a file, the associated viewer or application opens. See Setting viewer/editor options, page Select the file. 2. Choose Activities > View File. A read-only copy of the file opens in the selected viewer or application. Setting viewer/editor options You can select the applications you want to use to view or edit text, binary, and image files. You can also edit default view/edit settings or add settings for specific file types. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the View/Edit File category. 17

34 Editing viewer/editor settings 2. Click Add. The View/Edit Settings dialog box opens. 3. Select a View/Edit option. View applies the settings to viewing files and Edit applies the settings to editing files. 4. Enter the File extensions you want to associate with the application. Separate multiple extensions with a semicolon. 5. Select how you want to open the files. Internal viewer/editor uses the internal viewer. Associated application opens the application associated with the file. (Windows/Mac only) Selected application opens the selected application. Click Browse to select an application. 6. Click OK to save the changes. Editing viewer/editor settings You can edit viewer/editor settings to change the default application to open associated files. 1. Choose Tools > User Options then select the View/Edit File category. 18

35 Deleting viewer/editor settings 2. Select a view/edit file setting and click Edit. 3. Make any changes. 4. Click OK to save the changes. Deleting viewer/editor settings View/edit file options that start with 'All Other' cannot be deleted. 1. Choose Tools > User Options then select the View/Edit File category. 2. Select a view/edit file setting and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The file setting is deleted. Changing the internal viewer/editor text options You can change the internal viewer/editor to use any font installed on your computer and a specific number of spaces for tabs. 1. Choose Tools > User Options then select the View/Edit File category. 2. Click Choose Font to select the default font options. The Select Font dialog box opens. 3. Select any font options and click OK. 4. Enter or select the number of spaces to set as the Tab width. The default value is 8 spaces. 5. Click OK to save the changes. Opening local files from Surround SCM You can open local copies of files in working directories from Surround SCM to help save time locating files on your computer. Files open in the application specified in the operating system. 1. Select the file and choose Activities > Open Local File. The file opens in the associated application. 19

36

37 Modifying Files Check out files when you need to make changes. Edit the files and then check in the changes when you are done or are ready to share the changes with other users. If you create new files as you work, add them to Surround SCM to make them available to others. Depending on your security permissions, you may be able to move, rename, and remove files in Surround SCM. Checking out files When you check out a file, Surround SCM copies a read-write version of the file to the working directory. This allows you to edit the file and make changes to it. 1. Select the files or repository and choose Activities > Check Out. The Check Out Files dialog box opens. 2. Enter any Comments, such as the reason for checking out the file. 3. Select Exclusive check out to prevent other users from checking out the files or repository. This option is only available if Surround SCM is configured to allow multiple check outs. 4. Select Recursive to check out all files from the selected repository and all subrepositories. 5. Optionally expand the Changelist options area to select options for checking in files as part of a changelist. Files you add to a changelist during check out are checked in when the changelist is committed. For example, if a change affects multiple files in multiple repositories, add the files to the changelist during check out so all files are checked in as one unit. See Adding file actions to changelists, page Optionally expand the Advanced options area to select other check out options. 21

38 Creating local directories 7. Select Force file retrieval from server to check out the server copy of the files. Select this option if the local file status is 'current' and you know that it is not. This can occur if there is a problem with the.myscmserverinfo file. 8. Select an Overwrite option to specify what to do if the local file and server file are different or how to handle modified files in the working directory that were removed from the server. Prompt prompts you to replace the file, skip the file, or merge the server and local files. If you merge the files, the check out operation finishes after the files are reviewed and merged. Replace automatically overwrites the local file with the server file. Skip skips the file. Note: If you skip retrieval of a writable file that is old (out of sync with the server), you will lose any changes that are in the old file when you check it in. 9. Select a File timestamp option. This timestamp is set on local files when they are retrieved from the server. Current sets the timestamp to the current (time of retrieval) date and time. Modified sets the timestamp to the date and time the files were last modified. Check in sets the timestamp to the date and time the files were last checked in. 10. Click OK. The files are checked out. If the local and server files are different and you chose to merge the files, the merge application opens. The check out operation finishes after you review and merge the files. If the local directory does not exist, you are prompted to create it. See Creating local directories, page 22. Creating local directories When you get or check out files, you are prompted to create a local directory if it does not exist. 1. In the Create Local Directory dialog box, select a create option. Create directory creates the local directory. Create all directories creates a local directory for each repository. Skip repository skips the get or check out on the repository and does not create a local directory. Skip and cloak repository skips and cloaks the repository. Cloaked repositories are skipped when performing a recursive get, check in, check out, or undo check out. See Cloaking and uncloaking repositories, page

39 Undoing check out 2. Click OK. Undoing check out If you modify a file but decide you do not want to save changes, you can undo the check out. This discards changes, checks in the file, and does not create an entry in the revision history. Note: You cannot undo the check out on files included in a pending changelist. See Using Changelists, page Select the files or repository and choose Activities > Undo Check Out. The Undo Check Out Files dialog box opens. 2. Select a File overwrite option to specify what happens if a writable file is found in the working directory. Depending on the option, changes are lost when you undo the check out. This action cannot be undone. Get original version replaces the local file with the original server version. Get latest version replaces the local file with the latest server version. Leave local file leaves the local file as is. 3. Select Make files writable to leave a read-write copy of the file in the working directory. 4. Select Recursive to automatically undo the check out for the selected repository and all child repositories. This option is only available for repositories. 5. Click OK. The file is no longer checked out. 23

40 Editing files in Surround SCM Note: If files are in a pending changelist, you are prompted to remove them from the changelist before undoing the check out. Click Remove Files and Undo Check Out to remove the files from the changelist before undoing the check out. Click Skip Files to keep the files checked out and in the changelist. Editing files in Surround SCM When you edit a file, Surround SCM checks out the file, opens the viewer or application, and opens a writable copy of the file. See Setting viewer/editor options, page Select the file and choose Activities > Edit File. The file opens in the selected editor or application. 2. Make any changes. 3. Click Save, Check In, and Close to check in the file after you save it. Click Save to save the file without checking it in. Checking in updated files Check in updates files with changes, removes the lock on the files, makes changes available to other users, and increments the version number by one. Check in files whenever you are able to successfully build with the changes and your changes do not break other areas of the code. If you use multi-user check outs, it may be necessary to merge files frequently. Checking in regularly reduces the complexity of these merges, making it easier to resolve conflicts. Checking in often also allows other users to access changes. 1. Select the files or repository and choose Activities > Check In. The Check In Files dialog box opens. 2. Enter any Comments, such as changes made to the files. 3. Select Apply comments to all to use the same comments for all files. 24

41 Checking in updated files If you clear this option, the Check In Comments dialog box opens after the first file is checked in. You can enter a separate comment for each remaining file to check in or select Apply comments to remaining files to apply a comment to all remaining files. 4. Select Recursive to check in files from the selected repository and all subrepositories. 5. Expand and select any additional check in options. Changelist options Select changelist options to check in files as part of a changelist. See Adding file actions to changelists, page 124. Check in as part of the following changelist adds the files to a selected changelist. Select a changelist from the list or select <New changelist> to create a new changelist. View pending changelists after check in opens the Changelists dialog box to display pending changelists. Code review options Select Add new version to code review to add the updated file versions to a code review. Select a code review from the list or select <New code review> to create a new code review. See Creating code reviews, page 54. Click Select to view code review details and determine which review to add the files to. See Selecting code reviews, page 59. Note: If you are checking in files as part of a changelist, the files are added to the code review after the changelist is committed. Local file options Select local file options to indicate how to handle local files after the check in. Get file after check in retrieves a read-only copy to the working directory. You may want to get files if keyword expansion is turned on, changes are auto-merged, or files are not checked in from a 25

42 Checking in updated files working directory. Keep checked out checks in changes and keeps the files checked out. Leave local copy as is checks in the file and leaves the working directory copy as is. Remove local copy checks in the file and deletes it from the working directory. Make files writable leaves a read-write copy of the file in the working directory. Advanced options Select advanced options to change workflow states, label files, skip the merge process, and update version numbers when files are checked in. Change state when version updated changes the workflow state to the selected state. Select the state to set on the files. You may also want to select the Update version even if no change is made option. If you do not select this option, the check out operation is canceled for files that were not modified. Attach actions are not performed, check in triggers do not run, and the file state does not change. If you are checking in the file as part of a changelist, the state changes after the changelist is committed. Label applies the selected label to the files. Select a label from the list or select <New label> to create a label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Optionally select Update label with selected version to remove the label from earlier versions when applying it to the new version. If you are checking in the file as part of a changelist, the file is labeled after the changelist is committed. Skip server auto-merge checks in files without merging changes. The checked in file becomes the new version even if another user changed and checked in the file after you checked it out. Update version even if no change is made increments the version number even if no changes were made. If this option is not selected, the file is unchanged, and you are labeling the file, the label is applied to the file version in the working directory. 26

43 Rolling back files 6. Click Differences to view differences between the file you are checking in and the working directory copy. See Viewing file differences, page Click Attach to attach files to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page Click OK. Surround SCM automatically merges changes when files are checked in. If there are conflicts, the merge application opens. See Merging files, page 40. Rolling back files Roll back files if you need to revert to a previous file version. Any changes made to a file are discarded. The version number increments even though the contents are the same as a previous file version. For example, the current version is 5 and you roll back to version 3. After the rollback, the new version is 6. Version 3 and version 6 have the same contents. When you roll back a shared file, all the shared files are affected. If you only want to change the file in the specified repository, break the share then roll back the file. 1. Select the file and choose Activities > History. The History dialog box opens. 2. Select the file version you want to roll back to and click Rollback File. The Rollback File dialog box opens. 3. Enter any comments and click OK. The file is rolled back to the selected version. The version number increments by one and a rollback file action is added to the file history. Note: By default, the workflow state of the new file version is the same as the most recent file version. If the Rollback state with file rollback option is selected for the workflow template, the new file version is in the same state as the version rolled back to. 27

44 Adding files to Surround SCM Adding files to Surround SCM You can add individual files or an entire directory to Surround SCM. When you add a directory, a repository with the same name is created on the Surround SCM Server and files are added to this repository. Surround SCM optionally repeats the process recursively for all subdirectories. 1. Select the repository you want to add files to and choose Activities > Add Files. The Add Files dialog box opens. The files and folders in the selected repository s working directory that have not yet been added to the repository are displayed. If a working directory is not set for the repository, the contents of your default directory are displayed. 2. Select a drive or directory from the Look in list and then browse to the directory you want to add files from. Tip: You can prevent adding files with specific names and extensions. See Setting auto-detect and ignore file options, page Click to change how files are displayed. List displays the filename only. Details displays the filename, size, and last modified date. Show All Files displays all files in the directory. If this option is not selected, hidden files and files with extensions you are prevented from adding are not displayed. 28

45 Adding files to Surround SCM Note: There are two additional Linux options: Hidden Files to displays all files that start with a period and Symbolic Links displays all files with symbolic links. 4. Select a Files of type option to display files with specific file extensions, such as C# files. File types are organized in groups. You can add file extensions to existing groups and create new groups to quickly access file types you work with most often. See Grouping file extensions, page Select the files or folders you want to add. If you know the filename, enter it in the File name field. You can also use wildcard characters to find files. For example, enter *.txt in the File name field to display all text files in the selected directory. Press Ctrl+A to select all files and folders to add. Ctrl+click each item to select multiple files or folders to add To add files from a folder, double-click the folder to open it and then select the files. To quickly add one file, select any options and then double-click the file. 6. Click the Comments tab to enter comments about the files you are adding. 7. Click the Custom Fields tab to set custom field values. See Setting custom fields, page 31. You may not have access to this tab depending on your security permissions. 8. Select Recursive if you are adding a directory and want to automatically add all subdirectories and files. 9. Expand and select any additional options for adding files. Changelist options Select changelist options to add the files as part of a changelist. Select Add as part of the following changelist and select a changelist. See Adding file actions to changelists, page 124. Select View pending changelists after add to view the pending changelist. 29

46 Adding files to Surround SCM Code review options Select code review options to add the files to a code review. Select Add new version to code review and select a code review. Select <New code review> to create a new code review. See Creating code reviews, page 54. Click Select to view code review details and determine which review to add the files to. Note: If you are adding files as part of a changelist, the files are added to the code review after the changelist is committed. Local file options Select local file options to indicate how to handle local files after the add. Select Get files after add to create a read-only copy of the files in your working directory. This option is only enabled if a working directory is set for the repository. Select Make files writable to get the files in read-write mode. Select Check out files after add to immediately check out the files. Select Exclusive check out to prevent other users from checking out the files. This option is only available if Surround SCM is configured to allow multiple check outs. Advanced options Select advanced options to set workflow states, label files, overwrite removed server files, and detect 30

47 Setting custom fields file type when adding files. Select Set state when file added and select the workflow state to set on the files when they are added. If you do not select a state, the default state is used. See Changing workflow states, page 33. Select Label and select a label if your organization uses labels. Select <New label> to create a label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Optionally select Update label with selected version to remove the label from earlier file versions when applying it to the new version. Select Overwrite file if found removed to overwrite a removed server file with the same name as the file you are adding. If this option is selected and a removed file with the same name is found on the server, the server copy is replaced with the local file. If this option is not selected, and the local file matches a removed server file, you are prompted to replace the file or skip the add. Select a File type. Auto Detect is the default. You can also select Text, Binary, Mac Binary, UTF-8 Text, or UTF-16 if you need to explicitly set the file type. Note: If you are adding files as part of a changelist, the files are labeled after the changelist is committed. 10. Click Attach to attach the file to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page Click OK. The files are added to Surround SCM. Setting custom fields Custom fields capture additional file information that your organization wants to track, such as the person assigned to work on a file, a file description, or the person who owns the file). These fields can be displayed in the Source Tree window and the file Properties dialog box, and can be used in filters, triggers, and reports. For example, with custom fields, you can filter on all files assigned to you for review across all repositories. Note: See Configuring Custom Fields, page 317 for information about creating custom fields. Custom field values can be set when files are added and on the Custom Fields tab in the file Properties dialog box. 31

48 Changing multiple custom fields To set custom field values when adding files, click the Custom Fields tab and select any values. See Adding files to Surround SCM, page 28. To set custom field values in the Properties dialog box, select a file and choose Activities > Properties. Click the Custom Fields tab and select any values. See Viewing file custom field information, page 81. Keep the following in mind: The default custom field value is set when files are added to Surround SCM and when added during a promote or rebase. You may be able to change the default value when adding files depending on security permissions. When baseline or workspace branches are created, custom fields can be set to the default values or values can be copied from the parent branch. When snapshot branches are created, custom field values are automatically copied from the parent branch. See Creating branches, page 166. Promoting and rebasing does not change the custom field values set on files that already exist in the destination branch. You can only set one custom field value for shared files. You can view custom values on the Custom Fields tab in the file details pane or add custom field columns to the source file list. See Using the file details pane, page 73 and Customizing the Source Tree window, page 89. Information is only displayed for custom field values that are set. For example, if a custom check box field is not selected, a value is not displayed in the source file list. If a custom check box field is selected, Yes is displayed in the source file list. Changing multiple custom fields Bulk field changes allow you to easily update multiple custom field values at the same time. You can set a field to a new value or the default value. You can also append, prepend, and replace values in text custom fields. 1. Select the files or repository you want to change custom fields for and choose Activities > Advanced > Bulk Custom Field Changes. The Bulk Custom Field Changes dialog box opens. All custom fields are displayed. 32

49 Changing workflow states 2. Make any changes. The available options depend on the custom field type. To set the field to a new value, select Set to value and enter a value. To set the field to the default value, select Set to default value. To add text to the beginning of a text field value, select Append and enter the text. To add text to the end of a text field value, select Prepend and enter the text. To replace a text field value, select Replace and enter the text you want to search for. Enter the replacement text in the With field. To keep the current field value, select <Do not change>. 3. Select Set custom fields recursively to change the field values on all files in the selected repository and all subrepositories. 4. Click OK. The field values are changed. Changing workflow states Depending on the workflow and your security permissions, you can manually set the workflow state on files or a repository when you complete work. You can also change a file s workflow state in the following areas: Properties dialog box See Viewing general file information, page 80. Add Files dialog box See Adding files to Surround SCM, page 28. Check In Files dialog box See Checking in updated files, page 24. History dialog box See Viewing file history, page 76. Note: Users must have the Change State security permission to set file states. You may not want to enable state security if you use triggers to automatically set states. State changes are displayed in the file History dialog box. See Viewing file history, page Select a file or repository and choose Activities > Advanced > Change State. The Change State dialog box opens. 2. Select a New State for the file. This list includes the current state and the states the file can move to. 33

50 Moving files Note: If you select a repository, the New State list displays all states in the workflow. If any of the files in the repository cannot move to the selected state, the state does not change for any of the files. 3. Enter any Comments about the state change. 4. Select Recursive to apply the state change to all files in the selected repository and all subrepositories. 5. Click OK. The state is changed. Moving files You can move files from one repository to another in the same branch. Keep the following in mind: You cannot move files to a repository that includes a file with the same name. You cannot move files that are checked out or in a changelist. Moving a shared file adds the move action to the history of the base file and all shared links without breaking the share. Moved files can be promoted and rebased. If the moved file is a shared base file, the promote or rebase preview displays the move action as the reason. If the moved file is a shared link, the promote or rebase preview displays the new file action as the reason. Shares are maintained after promoting or rebasing. 1. Select the files and choose Activities > Move Files. The Move Files dialog box opens. 34

51 Renaming files 2. Select a Destination Repository to move the files to. 3. Enter any Comments, such as the reason for moving the files. 4. Optionally expand the Changelist options area to select options for moving the files as part of a changelist. See Adding file actions to changelists, page Click OK. The files are moved. Renaming files 1. Select a file and choose Activities > Rename File. The Rename File dialog box opens. 2. Enter a New Name and any Comments. 3. Optionally expand the Changelist options area to select options for renaming the file as part of a changelist. See Adding file actions to changelists, page Click OK. The file is renamed. Removing files When a file is removed, its contents are not deleted from Surround SCM and it can be restored. 1. Select the files and choose Activities > Remove File. The Remove Files dialog box opens. 35

52 Restoring removed files 2. Enter any Comments, such as the reason for removing the files. 3. Select Permanently destroy files to delete the selected files from Surround SCM. 4. Optionally expand the Changelist options area to select options for removing the files as part of a changelist. See Adding file actions to changelists, page Click OK. You are prompted to confirm the removal. 6. Click Remove. Note: If you remove a shared file, you are prompted to confirm the removal. Shared files cannot be restored after they are removed, but you can share the base file again to restore the share. Click Yes to remove the file. The file is removed from the repository. It is also deleted if you chose to destroy the file. Tip: To view a list of removed files, select the repository that contained the files. Choose Activities > Properties and then click the Removed Items tab. Restoring removed files 1. Select the repository that contains the file you want to restore and choose Activities > Properties. The Properties dialog box opens. 2. Click the Removed Items tab to view a list of removed files and repositories. 36

53 Deleting files permanently 3. Select a file and click History to view the file history. Click Properties to view the file properties. 4. Select the files you want to restore then click Restore. The Restore Files/Repositories dialog box opens. 5. Enter any Comments, such as the reason for restoring the files. 6. Click OK to restore the files. Deleting files permanently Destroyed files are permanently deleted from Surround SCM and cannot be restored. 1. Select the repository that contains the files you want to destroy and choose Activities > Properties. The Properties dialog box opens. 2. Click the Removed Items tab. This tab includes a list of all removed files and repositories. 3. Select a file and click History to view the file history. Click Properties to view the file properties. 4. Select the files you want to destroy and then click Destroy. The Destroy Files/Repositories dialog box opens. 37

54 Deleting files permanently 5. Enter any Comments, such as the reason for destroying the file. 6. Click OK. You are prompted to confirm the deletion. 7. Click Yes. The file is permanently destroyed. 38

55 Comparing and Merging Files When you are ready to check in file changes, you may need to compare the file in your working directory with the current version in Surround SCM to review the differences. If you are using non-exclusive check outs and other users made changes to the same files, you can diff and merge file versions to ensure all changes are properly added to Surround SCM. Viewing file differences After you make changes to a file, but before you check it in, you may want to compare the file to the server copy and reconcile any differences. This process of diffing and merging is crucial when you use non-exclusive check outs. You can diff files to compare, accept, or reject differences between two file versions. Suppose that you check out version 1 of a file non-exclusively to work on the spell check functionality. Jane checks out the same file version to work on the HTML conversion functionality. Jane checks in her changes before you do and Surround SCM updates the file to version 2. When you check in the file, Surround SCM sees that it is based on version 1, but the current server copy is now version 2. The server tries to automatically merge the files. If the auto-merge fails, you are prompted to perform a local merge to resolve the issues. See Merging files, page 40. You can diff files at different points of the development process, such as when you are fixing bugs. For example, you fix a printing error in an application. Three weeks later, a customer reports another bug that seems to be related to the earlier printing issues. Since you made your changes, two other developers also made bug fixes to the same file. You can diff the current server version against the earlier versions to see exactly what changed with each bug fix. Note: You can annotate files to see specific changes made between file versions. The change, user who made the change, when the change was made, and the Surround SCM action that changed the file version are displayed. See Viewing line-by-line file changes, page Select the file and choose Activities > Differences. The Differences dialog box opens. Read-only information is displayed in the File to Compare area. 39

56 Merging files 2. Select a Version. If you have the file checked out, you can use the version of the checked out file or the current server file. This helps you determine changes made to the file since checking it out. If you do not have the file checked out, the current server file version is displayed and cannot be changed. 3. Select a Second File option. Copy in working directory compares the server file with the working directory file. Selected file compares the server file with a file you select on your local drive. Click Browse to select a file. 4. Click Advanced to select a branched file, historic file version, or unrelated file. The Second File area expands with the following options: Branched file compares the selected file to a branched version. Historic version compares the current version to the selected historic version. Unrelated file compares the file to any other file on the Surround SCM Server. Click Browse to select a file. See Merging unrelated files, page Click Differences. The differences application opens. Note: You can change the application Surround SCM uses to diff files. See Configuring diff application options, page 47. Merging files You can merge files to compare, accept, or reject differences between files and combine the changes. Surround SCM automatically merges changes when files are checked in. If there are conflicts, you are prompted to manually merge the files. 40

57 Merging files Note: You can specify the application Surround SCM uses to merge files. See Configuring merge application options, page Select the file and choose Activities > Merge. The Merge dialog box opens. 2. Select Copy on server to merge changes with the latest version on the Surround SCM Server. 3. Click Advanced to select a branched file, historic file version, or unrelated file. The Second File area expands with the following options: Branched file merges changes with the selected branched file version. Historic version merges the current version with the selected historic file version. Unrelated files merges the current version with another file on the Surround SCM Server. See Merging unrelated files, page Clear Merge should first attempt auto-merge to manually merge the changes. 5. Click Merge. If the file to merge into is checked out, the merge application opens. If the file is not checked out, the Check Out Files dialog box opens. 41

58 Merging unrelated files The files are merged and the merge application closes. If you checked out files during the merge, you are prompted to check in the files when the merge is complete. Merging unrelated files You can merge unrelated files so they both contain the same information. This is helpful for merging similar files with different filenames or merging files that have a common ancestor but are in unrelated branches. For example, changes are made to the XYZ.txt file in the Branch B/Common Files repository. Similar changes must also be made to the ABC.txt file in the Branch A/Code/Common Files repository. Merge the files to share the changes. 1. Select the file and choose Activities > Merge. The Merge dialog box opens. 2. Click Advanced. The Second File area expands with additional options. 3. Select Unrelated files. 4. Click Browse to select the file to merge from. The Surround SCM Repository/File Browser opens. 5. Select a branch, repository, and file, and then click OK. You return to the Merge dialog box. 6. Click Merge. If the file to merge into is checked out, the merge application opens. If the file is not checked out, the Check Out Files dialog box opens. Note: If Surround SCM identifies a common ancestor for the selected files, a 3-way merge is performed. Otherwise, the 2-way diff application is used. The files are merged and the merge application closes. 42

59 Running file differences reports The Merge Check In dialog box opens if you checked out the file when starting the merge. Click Yes, check in file to check in the file. Click No, keep file checked out if you do not want to check in the file. Running file differences reports File differences reports include the differences between two or more versions of a text file. You can run these reports when viewing file history. See Viewing file history, page Select a file and choose Activities > History. The History dialog box opens. Tip: You can also view file differences in a History report. See Creating history reports, page Select the files to include in the report. 3. Click. The Generate File Differences Report dialog box opens. 43

60 Running file differences reports 4. Select a Version to Include option. Selected version to selected version displays differences between the file versions selected in the History dialog box. For example, if you select versions 2 and 3, the report displays the differences between the two versions. If you select versions 2, 3, and 5, the report displays differences between versions 2 and 3, and versions 3 and 5. Selected version to previous version displays differences between the selected file version and the previous version. For example, if you select version 3, the report displays differences between versions 2 and 3. If you select versions 2, 3, and 5, the report displays differences between versions 1 and 2, versions 2 and 3, and versions 4 and 5. All versions in this branch displays the differences between all file versions in the branch. For example, if the branch contains 5 versions of the file, the report displays differences between versions 1 and 2, versions 2 and 3, versions 3 and 4, and versions 4 and Select any additional report Options. Ignore case differences in file contents excludes differences in character case. Ignore whitespace excludes any whitespace differences (spaces and tabs). Ignore changes in the amount of whitespace excludes additions or deletions to existing whitespace (spaces and tabs). Ignore blank lines excludes inserted or deleted blank lines. Include report header information includes a header with the report date, branch, repository, and file. 6. Select an Output Format. 44

61 Viewing image file differences When you view differences, you may also want to see the parts of the files near the lines that differ to help you understand what changed. This is the context. If you are distributing new versions of files in the form of diff output, use one of the output formats that show context so users can easily apply the differences. Enter the number of Output lines of context to display before and after each change. The default is 3 lines. Select Unified format to display the differences with limited context lines. This format excludes redundant context lines. Select Context format to display the differences with context lines. This format shows several lines of context around the lines that differ. It is the standard format for distributing updates to source code. 7. Click OK. The report opens. 8. Click Save As to save the report or Print to print it. 9. Click OK when you finish. Symbol meanings The following symbols indicate differences in a differences report. Symbol Meaning! A line that is part of a group of lines that changed between the two versions (context format only) + Inserted line - Deleted line Viewing image file differences You can diff image files to view differences between file versions. 1. Select the file and choose Activities > Differences. The Differences dialog box opens. 2. Select a Second File option or click Advanced to select a branched file, historic file version, or unrelated file. 3. Click Differences. The Image Comparison viewer opens. 45

62 Setting diff/merge options 4. Click a view button to change how differences are displayed. You can also zoom in or out or enter a percentage to increase or decrease the magnification. Button Use to: View images side by side View images top over bottom View combined differences, which is the result of subtracting the pixel values of one image from the other View the high contrast result of subtracting the pixel values of one image from the other. This view can help you identify subtle color differences. Display the images at actual size Zoom in Zoom out 5. Click Close when you finish. Setting diff/merge options You can select the utilities you want to use to diff and merge files. You can also change the default diff/merge application settings and configure settings for specific file types. 46

63 Configuring diff application options Configuring diff application options You can change the default application for diffing files or add a diff application for specific file types Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Diff/Merge category. 2. Click Add. The Diff/Merge Settings dialog box opens. 3. Select Diff from the Diff/Merge list. 4. Enter the File extensions to associate with the diff application. Separate extensions with a semicolon. 5. Select a Compare with option. Binary comparison uses the internal binary file comparison utility to perform a byte-to-byte comparison between two binary files. Integrated Guiffy uses Guiffy to compare two text files. See the Guiffy help ( for more information. Integrated image compare uses the internal utility to compare image files. Microsoft Word uses Word s compare/merge utility. (Windows only) 47

64 Configuring merge application options Selected application uses an application you select. Click Browse to select the application. The %1 and %2 diff parameters are automatically added to the application path to identify the files to diff. When diffing two files, %1 indicates the server file and %2 indicates the local file. You can change these parameters. Note: You may need to add different parameters for the diff application to work correctly. Refer to the diff application documentation for information about the command line requirements for integrating with source code management applications. 6. Click OK to save the changes. Configuring merge application options You can set the application to use for merging specific file types. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Diff/Merge category. 2. Click Add. The Diff/Merge Settings dialog box opens. 3. Select Merge from the Diff/Merge list. 48

65 Editing diff/merge application options 4. Enter the File extensions to associate with the merge application. Separate extensions with a semicolon. 5. Select a Two-way merge with option. Integrated Guiffy uses Guiffy. See the Guiffy help ( for more information. Microsoft Word uses Word s compare/merge utility. (Windows only) Selected application uses an application you select. Click Browse to select a different merge application. The %1 and %2 merge parameters are automatically added to the application path to identify the files to merge. %1 indicates the server file to merge from and %2 indicates the merge to file. Note: You may need to add different parameters for the merge application integration to work correctly. Refer to the merge application documentation for information about the command line requirements for integrating with source code management applications. 6. Select a Three-way merge with option. If you browse to select an application, %1, %2, and %3 merge parameters are automatically added to the application path to identify the files to merge. %3 indicates the common ancestor file. 7. Click OK to save the changes. Editing diff/merge application options You can edit diff/merge application options to change the diff or merge application to use when working with specific file types or files with specific extensions. 1. Choose Tools > User Options then select the Diff/Merge category. 2. Select a diff/merge setting and click Edit. The Diff/Merge Settings dialog box opens. 3. Make any changes. 4. Click OK to save the changes. Deleting diff/merge application options Default diff/merge options, which begin with All Other, cannot be deleted. 1. Choose Tools > User Options then select the Diff/Merge category. 2. Select a diff/merge setting and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The setting is deleted. Configuring diff/merge application settings You can configure settings for Guiffy, the diff/merge application integrated with Surround SCM. You can also select a Microsoft Word document comparison option. 49

66 Configuring diff/merge application settings Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Application Settings from the Diff/Merge category. 2. Select any Guiffy Configuration options. Enter the Java runtime path or click Browse to select a directory. Enter the Guiffy path or click Browse to select a directory. Enter the amount of memory you want Guiffy to use. The default is 64 MB. Select the Guiffy language to use. <Default> indicates that Guiffy will select the language. Select Use Seapine default Guiffy toolbars to display only the Guiffy toolbars used in Surround SCM. 3. Select a Microsoft Office Configuration option. Compare and Merge displays differences as tracked changes. Side by Side compares documents side-by-side. 4. Click OK to save the changes. 50

67 Performing Code Reviews Code reviews provide a way to group related files or changes and request feedback from others without affecting the current file contents. Reviewers can provide comments directly in the code review. All review information is stored in Surround SCM and can be referenced as users work with source files. Code review authors are typically users who make file changes, create the review, and add files to it. When the review is ready, the author starts it to notify the reviewers. The reviewers add comments to the files and changes, and then mark files as completed when they finish reviewing them. When all reviewers complete the review, authors address the review comments and submit the revisions for another review until all files are approved. See About the code review process, page 51. About the code review process As authors and reviewers perform tasks, files move through the code review process and the review status changes. See Understanding code review status, page 53. The following flowchart illustrates the built-in code review workflow, which uses triggers to automatically users when reviews are started and completed. Note: You can add triggers to automate additional code review and file actions, such as setting custom field values when review events are performed or setting workflow states based on the status of individual files in code reviews. See Automating Actions with Triggers, page 321. Common tasks Following are details about code review tasks that move files through the review workflow. 1. Create a code review to group files that need review 51

68 About the code review process Authors are responsible for submitting changes for review and incorporating review feedback. Authors typically create their own code reviews. For example, you may want to create a code review before making changes so it is available as you work with the files, or you may want to wait to create the code review until you are ready to check in multiple related files that need review. Administrators or team leads may want to create code reviews for other users. For example, at the beginning of a release, the team lead may want to create a review for each new feature and select the authors and reviewers before files are updated. See Creating code reviews, page Add files to the review New code reviews have a Work in Progress status. You can add files to reviews when adding and checking in files to Surround SCM. You can also add files to reviews from the Code Review and Source Tree windows and when viewing file history, promoting or rebasing files, or analyzing risk of files attached to issues. See Adding files to code reviews, page 55. Tip: If you use TestTrack or a third-party issue tracking tool, you can analyze risk to identify potential problems in source files attached to issues and identify files that may need code review. See Analyzing issue risk in files, page Start the review When all files needing review are added to the code review, start it to indicate it is ready for review and automatically the reviewers. See Starting code reviews, page 60. The code review status changes to Awaiting Review. 4. Reviewers review files and add comments Reviewers open the code review and add comments for authors to address. See Reviewing files in code reviews, page 62. When they finish reviewing individual files, they mark them as completed in the code review. The authors are notified that the code review is complete after all reviewers complete their reviews. Note: You can also review files and add comments to them any time without using the code review process. See Reviewing files, page 64 and Reviewing changes between file versions, page Authors address review comments Files with unaddressed review comments have a Needs Attention status. Authors make the necessary changes to these files, replace the file in the code review with the updated version, and then mark the comments as addressed. See Addressing code review comments, page Repeat the review until all files are approved After all the review comments are addressed, restart the review. The review process may repeat multiple times. Reviews are approved when all reviewers approve all files in them. Tip: Reports can help you analyze code review data. Code review reports include historical information about a code review and files in it. Use these reports to review unaddressed comments, review your code review process, or save process information for audits. See Running code review reports, page 68. Code review coverage reports include information about file versions in code reviews and if the files reviews are complete or still in progress. Use these reports to determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. See Creating code review coverage reports, page

69 Understanding code review status Understanding code review status The status of a code review is displayed in the Code Review window Status column. Individual review file status is also displayed. Information in this column can help you determine where files are in the review process. Following are the code review statuses. Status Work in Progress Awaiting Review Needs Attention Approved Explanation Authors are adding files to a review. The code review is started and contains files that need review. An about the review is automatically sent to reviewers. The review is complete and contains files with unaddressed comments. An about the resulting review status is automatically sent to authors. All files in the review have been reviewed and approved. An about the resulting review status is automatically sent to authors. Following are the statuses for files in code reviews. Status Awaiting Review Needs Attention Approved Explanation The selected reviewers need to review the file. Files remain in this status until all the reviewers review them. The status changes when the last reviewer marks the file as completed. The file contains unaddressed comments. The file was reviewed and does not contain any unaddressed comments. Managing code reviews You can create code reviews, add files to reviews, start the review process, open reviews, report on reviews, and delete reviews from the Code Reviews window. Note: Administrators can configure code review settings for individual repositories to require or prevent users from adding files to reviews when adding or check in files to Surround SCM. See Configuring Code Review Settings, page Choose View > Code Reviews. The Code Reviews window opens. 53

70 Creating code reviews 2. Select the Mainline branch that contains the reviews you want to work with. 3. Select a Filter to limit the reviews displayed. You can view reviews requiring your action, unapproved reviews you are an author for, unapproved reviews you are a reviewer for, all unapproved reviews, or all approved reviews. All reviews on the mainline branch that match the criteria are displayed. To search for a review, select <Advanced find>. See Searching for code reviews, page Click Create Review to add a new review. See Creating code reviews, page Click Add Files to select files by changelist, label, or TestTrack item to add to the review. See Selecting related files to add to code reviews, page 58. Note: You can also add files to reviews from the Source Tree window and when performing file actions. See Adding files to code reviews, page Select a review and click Open Code Review to open it. See Opening code reviews, page Select a review and click Start Code Review to notify reviewers that files are ready for review. See Starting code reviews, page To report on reviews, select a Report on Code Reviews option and click Report On. See Running code review reports, page Select a file or review and click Delete to remove the file from the review or delete the review. See Removing files from code reviews, page 59 and Deleting code reviews, page 72. Note: You can revert reviews to the Work in Progress status if no reviewers have reviewed any files. Open the review, clear all the reviewers, and click Apply. Authors are automatically notified that the review is terminated. Creating code reviews You can create code reviews to group related files and changes that need review. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Click Create Review. The Create Code Review dialog box opens. 54

71 Adding files to code reviews 3. Enter a Review name. 4. Select the review Authors. Authors are responsible for making code changes, submitting changes for review, and addressing reviewer feedback. Authors can add files to the review and mark comments as addressed when the review is complete. The selected authors automatically receive an if the review needs attention. 5. Select the Reviewers. Reviewers are responsible for reviewing code changes and adding comments to files included in the review to provide feedback. The selected reviewers automatically receive an about the review when it starts. 6. Enter any Notes, such as the reason the files need to be reviewed. 7. Click OK. The review is added and the status is set to Work in Progress. Authors can now add files to the review. See Adding files to code reviews, page 55. Adding files to code reviews Add files to code reviews when other users need to review them. The following information explains how to perform reviews from the Source Tree window. You can also add files to reviews when performing the following actions. Adding files to Surround SCM Checking in updated files Working with changelists Keep the following in mind: Promoting or rebasing changes Viewing file history Analyzing issue risk Selecting related files to add to reviews You can only add files to unapproved reviews. If you have security permissions to edit other authors' code reviews, you can add files to any unapproved reviews. Otherwise, you must be the author to add files to the review. How the file is added to the code review affects how the contents are displayed during the review. If the file is added to the review from the Source Tree window or when adding files or analyzing risk, the entire file contents are displayed for review. If the file is added to the review when checking in changes, viewing file history, or promoting or rebasing files, the differences between file versions are displayed for review. See Reviewing files in code reviews, page Select a file and choose Activities > Code Review > Add to Code Review. You can also drag files to code reviews from the Source Tree window to quickly add the current version to a review. 55

72 Adding files to code reviews The Add to Code Review dialog box opens. 2. Select the Code review to add the files to. To create a new review, select <New code review> and enter the review details. See Creating code reviews, page 54. To add the file to an existing review, select the review from the list or click Select to view review details and determine which review to add the file to. See Selecting code reviews, page 59. The authors, reviewers, and notes for the selected review are displayed. Click the Files tab to view files already in the review. Click the History tab to the view the review history. 3. Click OK. The file is added to the review. Note: After all files needing review are added, start the review to notify the reviewers. See Starting code reviews, page 60. Other ways to add files to code reviews Adding files You can add new files you are adding to Surround SCM to code reviews. When the files are opened in a review, the entire file contents are displayed. See Adding files to Surround SCM, page Expand the Code review options in the Add Files dialog box. 2. Select Add to code review and select the review to add the file to. To add the file to a new review, select <New code review>. The Create Code Review dialog box opens when you add the file. See Creating code reviews, page 54. To add the file to an existing review, select the review from the list or click Select to view code review details and determine which review to add the file to. See Selecting code reviews, page 59. Checking in updated files You can add updated files to code reviews when you check in changes. When the files are opened in a review, 56

73 Adding files to code reviews the differences between file versions are displayed. See Checking in updated files, page Expand the Code review options in the Check In Files dialog box. 2. Select Add new version to code review and select the review to add the file to. To add the file to a new review, select <New code review>. The Create Code Review dialog box opens when you check in the file. See Creating code reviews, page 54. To add the file to an existing review, select the review from the list or click Select to view code review details and determine which review to add the file to. See Selecting code reviews, page 59. Working with changelists You can add all files in a changelist or individual files from a committed changelist to code reviews. When the files are opened in a review, the differences between file versions are displayed. See Managing changelists, page Select a changelist or file in a committed changelist in the Changelists dialog box. 2. Click Add to Code Review. If you selected a pending changelist, the Select Code Review dialog box opens. Select the review to add the files to after the changelist is committed. See Selecting code reviews, page 59. If you selected a committed changelist or file, the Add to Code Review dialog box opens. To create a new review, select <New code review> and enter the review details. See Creating code reviews, page 54. To add the files to an existing review, select the review from the list or click Select to view review details and determine which review to add the files to. See Selecting code reviews, page 59. Promoting or rebasing changes You can add files to code reviews after promoting or rebasing changes between branches. When the files are opened in a review, the differences between file versions are displayed. See Merging Files Between Branches, page Select a file in the Promote Status or Rebase Status dialog box and click Add to Review. The Add to Code Review dialog box opens. 2. Select the Code review to add the files to. To create a new review, select <New code review> and enter the review details. See Creating code reviews, page 54. To add the file to an existing review, select the review from the list or click Select to view code review details and determine which review to add the file to. See Selecting code reviews, page 59. Viewing file history You can add file versions to code reviews when viewing historical file information. When the files are opened in a review, the differences between file versions are displayed. See Viewing file history, page Select a file version in the History dialog box. 2. Click a button to add the file version to a review or review the changes. 57

74 Adding files to code reviews To add the file version to a review, click. Select the review in the Add to Code Review dialog box or create a new review. See Selecting code reviews, page 59 and Creating code reviews, page 54. To review the changes in the file version, click. You are prompted to add the file version to a review when you add the first comment. See Adding review comments to files, page 65. You can add the file version to an existing review or create a new review. See Selecting code reviews, page 59 and Creating code reviews, page 54. Analyzing issue risk You can add files to code review when analyzing issue risk to indicate they may need attention. When the files are opened in a review, the entire file contents are displayed. See Analyzing issue risk in files, page Select a file in the Analyze Risk dialog box. 2. Click a button to add the file to a review or review the file. To add the file to a review, click. Select the review in the Add to Code Review dialog box or create a new review. See Selecting code reviews, page 59 and Creating code reviews, page 54. To review the file, click. You are prompted to add the file to a review when you add the first comment. See Adding review comments to files, page 65. You can add the file to an existing review or create a new review. See Selecting code reviews, page 59 and Creating code reviews, page 54. Tip: You can also drag files to code reviews from the Analyze Risk dialog box to quickly add the current version to a review. Selecting related files to add to code reviews You can select related files to add to code reviews by changelist, label, or TestTrack issue, test case, or requirement. When the files are opened in a review, the differences between file versions are displayed. 3. Choose View > Code Reviews. The Code Reviews window opens. 4. Select the review to add files to and click Add Files. The Add Files to Code Review dialog box opens. 5. Select a source type in Select files and versions by list and then select a source to display files from. 58

75 Selecting code reviews Changelist displays files included in the selected committed changelist. Select a changelist from the list or click Select to search for a changelist or view changelist details. See Selecting changelists, page 139. Label displays files with the selected labeled applied to them. Select a label from the list or click Select to search for a label or view label details. See Selecting labels, page 147. Issue, Test Case, and Requirement display files attached to the selected TestTrack item. Select an item from the list or click Select to search for an item or view item details. See Selecting TestTrack items, page Select the files to add to the review and click Add to Code Review. The files are added to the review. Selecting code reviews You can view code review details to make sure you add files to the correct review. 1. Click Select next to the code review field in the Add to Code Review or file action dialog box, such as the Add Files dialog box. The Select Code Review dialog box opens. Reviews you have permission to add files to are displayed. 2. Click Create Review to create a new review. See Creating code reviews, page Select a code review and click Select to use it. Removing files from code reviews You can remove files from code reviews without affecting the file contents. For example, you may need to remove a file added to the wrong review. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Expand the review that contains the file you want to remove. 3. Select the file to remove and click Delete. You are prompted to confirm the deletion. 4. Click Yes. The file is removed from the review. 59

76 Starting code reviews Starting code reviews After all files that need review are added to a code review, start it to notify the reviewers. An is automatically sent to reviewers to explain that the review is ready and includes the review name, authors, notes, and due date. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Select a review and click Start Code Review. The Start Code Review dialog box opens. Note: If the review has unaddressed comments and is in a Needs Attention state, you are prompted to confirm starting the review. This can help you identify if the review contains comments you addressed, but forgot to mark as addressed before restarting the review. 3. Enter or select a Due date. 4. Select the Reviewers. 5. Optionally make any changes to the review Notes, such as requests for the reviewers. 6. Click Start Review. The review status changes to Awaiting Review and the reviewers are notified about the review. You can edit started reviews to change the name, notes, authors, or reviewers. You can also revert reviews before any files are reviewed to change the due date. To edit the review information, open it, make any changes on the Properties tab, and click Apply. See Editing code reviews, page 61. To change the due date, revert the review to the Work in Progress status before any files are reviewed. Open the started review, clear all the reviewers, and click Apply. The review status changes to Work in Progress and an is sent to authors to notify them that the review is terminated. You must start the review again after making any changes. Opening code reviews Open code reviews to view general information, the review history, the files needing review, and to provide review feedback. 1. Choose View > Code Reviews. The Code Reviews window opens. 60

77 Editing code reviews 2. Select a code review and click Open Code Review. The Code Review window opens. 3. Optionally select a filter to display the files you want to review. You can view all files in the review, all unapproved files, files needing attention, and files you need to review. 4. Double-click a file to open it. The file contents or differences between versions open in a new tab. Comments made by other reviewers are also displayed. 5. Optionally review the file and add any comments. See Reviewing files in code reviews, page Click the Properties tab to view general review information. 7. Click the History tab to view the review history. Editing code reviews You can edit code review names, notes, authors, and reviewers, even after reviews are started. For example, you may want to add additional reviewers or provide additional information in the review notes. Note: You cannot edit a review in a Needs Attention or Approved status. If a review needs attention, you must restart it after addressing review comments. If a review is approved, you can create a new review to request additional feedback. See Starting code reviews, page 60 and Creating code reviews, page Choose View > Code Reviews. The Code Reviews window opens. 2. Select the review and click Open Code Review. 3. Make any changes on the Properties tab. 4. Click OK to save the changes. If you added reviewers to a review that already started, an is automatically sent to the added reviewers when the changes are saved. 61

78 Reviewing files in code reviews Reviewing files in code reviews You can review the changes made between file versions or review entire files in code reviews. If changes in a file version were added to the review, the version number is included in the review information. When you open the file for review, the differences between versions are displayed. See Reviewing changes between file versions, page 62. If an entire file was added to the review, all file version numbers are included in the review information. When you open the file for review, the most current file version is displayed. If comments were added outside of the code review process, those comments are also displayed. See Reviewing files, page 64. Note: You can also add comments to source files without using the code review process. You are prompted to add the file to a review when you add the first comment. If the comments are related to an existing review, add the files to it. If a review does not exist, create one and select the author who needs the feedback. The comments are available when the author views their unapproved code reviews, but you may want to separately notify the author that you added comments to make sure they address them. Reviewing changes between file versions You can review changes made between code review file versions. The latest file version in the code review is compared to the version before the oldest version in the review. For example, if versions 3, 6, and 8 are in the review, differences between versions 2 and 8 are displayed. As you review the changes, you can select different versions to display to view only the changes made between specific versions or since you last reviewed the file. Note: You can also review entire files without highlighted changes. See Reviewing files, page Open the code review and double-click the file you want to review. Differences between file versions open in a new tab in the Code Review window. 62

79 Reviewing changes between file versions 2. Click Previous Change and Next Change to go to the previous or next change. 3. To compare different versions, select a Version from the list to display in each area. Versions not included in the review are displayed in gray. If you are reviewing updates after a review was restarted, versions less than or equal to the last version you reviewed are displayed in italics. 4. Click a view button to display the differences side by side, top over bottom, or combined. You can also view the file without the differences highlighted. Button Displays: Differences side by side Differences top over bottom Differences combined in a single file One file version without highlighted differences 5. If you are reviewing an image file, click a button to change how differences are displayed or enter a percentage to change the magnification. See Viewing image file differences, page To find text in the file, enter the text in the search field and click Find. 7. Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page Click Previous Comment and Next Comment to go to the previous or next comment. Note: The content that a comment applies to may move to a different line as the file is updated and reviewed again. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 9. Select a comment and click Mark Addressed to address it or click Address All to address all comments. See Addressing code review comments, page Select Show addressed comments to view comments the author already addressed from other reviews. 11. Select Completed when you finish reviewing the file. You can only mark files as completed if you are a reviewer in the code review. To add review comments to a file marked as completed, clear the Completed check box. You can add comments as long as at least one file in the review is not complete. When you complete the last file needing review, you are prompted to confirm you are finished reviewing all files. Click Yes to confirm your entire review is complete. If all files are marked completed, you can no longer add or edit comments in the review. The file status changes to Needs Attention or Approved when all reviewers complete the review. See Understanding code review status, page

80 Reviewing files Reviewing files You can review entire files in a code review. For example, you may want to review all the file contents before a new set of changes are made to existing files. Note: You can also perform ad hoc reviews when viewing files in the Source Tree window or analyzing risk of files attached to issues. Select a file and choose Activities > Code Review > Review File. You are prompted to add the file to a code review when you add the first comment. See Adding files to code reviews, page Open the code review and double-click the file you want to review. The file opens in a new tab in the Code Review window. Note: Depending on how the file was added to the review, the differences between file versions may be displayed by default. Click to view the entire file without the highlighted differences. 2. To find text in the file, enter the text in the search field and click Find. 3. To view another version of the file, select the Version from the list. Versions not included in the review are displayed in gray. If you are reviewing a file after a review was restarted, the last version you reviewed and earlier versions are displayed in italics. 4. If you are reviewing an image file, click a button to change how differences are displayed or enter a percentage to change the magnification. See Viewing image file differences, page

81 Adding review comments to files 5. Click a view button to display the differences between the latest file version and the version before the oldest version in the review. You can also select different versions to compare. See Reviewing changes between file versions, page Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page Click Previous Comment and Next Comment to go to the previous or next comment. Note: The content that a comment applies to may move to a different line as the file is updated and reviewed again. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 8. Select a comment and click Mark Addressed to address it or click Address All to address all comments. See Addressing code review comments, page Select Show addressed comments to view comments the author already addressed from other reviews. 10. Select Completed when you finish reviewing the file. You can only mark files as completed if you are a reviewer in the code review. To add review comments to a file marked as completed, clear the Completed check box. You can add comments as long as at least one file in the review is not complete. When you complete the last file needing review, you are prompted to confirm you are finished reviewing all files. Click Yes to confirm your entire review is complete. If all files are marked completed, you can no longer add or edit comments in the review. The file status changes to Needs Attention or Approved when all reviewers complete the review. See Understanding code review status, page 53. Adding review comments to files You can add comments to files when performing code reviews to identify content that needs attention. Note: After a file is added to a code review, any user can add comments to it. 1. When reviewing a file or changes, select the content you want to comment on and click Add Comment. The Add Comment dialog box opens. 2. Enter the comment. 3. Select Comment addressed if the comment does not need to be addressed later. This option is only available if you are the author. 65

82 Editing and deleting review comments For example, you may want to add a comment to mention a specific change you made to address a review comment. You can mark the new comment as addressed so it does not affect the overall review status. 4. Click OK. The comment is added and saved in the code review. Note: If you need to make changes to a comment, you can edit, move, or delete it. See Editing and deleting review comments, page 66. Editing and deleting review comments You can edit, move, and delete your own comments in code reviews. 1. Right-click a comment when reviewing a file or changes. 2. Choose an option to modify it. To edit a comment, choose Edit. Make any changes and click OK. To delete a comment, choose Delete. You are prompted to confirm the deletion. To move a comment, choose Move and then select the new location for the comment in the file contents. You are prompted to confirm the move. Addressing code review comments Review comments can help you determine what changes are needed in files. After making the changes, you can mark the comments as addressed to keep track of comments that still need attention. Note: You can address comments you add to a review. You must be the review author to address comments added by other users. 1. Open the code review. See Opening code reviews, page Double-click the reviewed file. The file and review comments open in a new tab in the Code Review window. 3. To display only unaddressed comments, clear Show addressed comments. 4. Review the comments and make the requested changes. Note: The content that a comment applies to may move to a different line as the file is updated. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 5. Add the updated file to the code review. See Adding files to code reviews, page Repeat steps 1 and Select the comment you addressed and click Mark Addressed or click Address All to address all comments. 66

83 Viewing unaddressed review comments Note: If you address the wrong comment, you can change it back to unaddressed. Double-click the comment, clear Comment addressed, and click OK. Viewing unaddressed review comments You can check if a file has unaddressed review comments to make sure they are addressed before files are added, promoted, or rebased across branches. For example, if a file was added to a code review from a baseline branch and then promoted to the mainline branch, users retrieving the file from the mainline can view the unaddressed review comments to see what changes other users still need to make to the file. 1. Select the file in the Source Tree window and choose Activities > Code Review > View Unaddressed Comments. The View Unaddressed Comments window opens. 2. Make sure the corresponding Version is selected to view the content the comment applies to. The version the comment was added to and the line number is displayed next to the comment. You can only view the current version and versions that include unaddressed comments. 3. Close the window when you finish. Searching for code reviews You can search for code reviews based on status, author, reviewer, and files awaiting review by user. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Select <Advanced find> in the Filter list. 67

84 Running code review reports The Advanced Find dialog box opens. 3. Select the criteria that reviews must meet to pass the filter. The Restriction dialog box opens. The options change based on the selected restriction. 4. Select the restriction value. 5. Click OK. 6. Repeat steps 3-5 to add additional restrictions. 7. Click Find. Reviews that meet the criteria are displayed and the Find results filter is applied. Running code review reports When working with code reviews, you can run reports to view historical information about a code review and files in it. Use these reports to see unaddressed comments, review your code review process, or save process information for audits. You can run the following types of code review reports: Summary reports include a list of code reviews and the files in them. Detail reports include more detailed information about each code review, the files in it, and comments added to the files. Tip: Code review coverage reports are also available. Use these reports to see file versions in code reviews and if the individual file reviews are complete or still in progress. This report can you help you determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. See Creating code review coverage reports, page Choose View > Code Reviews. The Code Reviews window opens. 2. Select the Mainline branch that includes the files and code reviews. 3. Select a Report on Code Reviews option. 68

85 Running code review reports All code reviews includes all reviews in the report. Selected code reviews only includes specific reviews. Select the code reviews to include. To limit the reviews displayed, select a Filter. To search for a review, select <Advanced find>. See Searching for code reviews, page 67. Tip: All files in a selected code review are included in detail style reports. To only include specific files, select the files to include in the review. 4. Click Report On. The Code Review Report dialog box opens. 5. Select an Output format. Reports can be formatted in HTML or plain text format. 6. If the selected output format is HTML, select a Stylesheet to format the report. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Code review report stylesheets are stored in the StyleSheets/CodeReview directory in the Surround SCM application directory on the Surround SCM Server. 7. Select a report type. See Examples, page

86 Running code review reports Summary style report includes general information about the review, including the name, status, due date, authors, reviewers, and notes. Detail style report includes detailed information about the review and files in it. Select any of the following options for these reports. Include unaddressed comments includes all unaddressed comments for a file. Include addressed comments includes all addressed comments for a file. Include commented file contents with # lines of context includes the specified number of context lines from the file before and after a comment. Including context lines can help you understand more about the code a comment applies to. Context lines are only included for comments in text files and not binary files. 8. Select a Sort comments by option to indicate the order to display review comments in the report. Location in file organizes comments in the same order they are in the file. Timestamp organizes comments based on date and time, from oldest to newest. 9. Click Run. The report opens. 10. Click Save As to save the report or Print to print it. These options are only available in the internal report viewer. If an HTML report opens in a browser, you can save, export, or print the report from the browser. 11. Click Close when you finish. Examples Summary style report The following example is a summary style code review report in HTML format. Detail style report The following example is a detail style code review report in HTML format. It includes unaddressed comments only, commented file contents with two lines of context, and sorts comments by the location in the file. 70

87 Viewing code reviews files are included in Viewing code reviews files are included in You can view the code reviews that files are included in when viewing file history and analyzing risk of files attached to issues. See Viewing file history, page 76 and Analyzing issue risk in files, page Select the file or version and click. The View Code Reviews dialog box opens. Only code reviews that include the selected file or version are displayed. 2. If you are viewing a review from a risk analysis, select a review and click Open Code Review to open it. See Opening code reviews, page Click Close when you finish. 71

88 Deleting code reviews Deleting code reviews You can delete code reviews that are no longer used. For example, you may need to delete a review created by mistake or delete approved reviews that are no longer needed to free up server space. Note: We do not recommend deleting code reviews because all review history is also deleted. Before deleting a review, make sure users do not need access to it. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Select a code review and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The code review is deleted. 72

89 Viewing File Information Surround SCM stores historical file information you can review to understand each action performed on a file, where files are checked out to, if files are shared between repositories, and custom field settings. See Viewing file history, page 76. You can also annotate files to view line-by-line changes to files between versions. See Viewing line-by-line file changes, page 74. Using the file details pane The file details pane provides a convenient way to work with files and access file commands. It displays file properties, history, check out status, sharing information, custom fields, and a local preview of image files. 1. In the Source Tree window, choose View > File Details Pane. The file details pane opens. 2. Select a file. Information about the file is displayed. 3. Click the Properties tab to view file information, such as branch, filename, size, and workflow state. 4. Click the History tab to view history information. You can also access commands to work with a historic file version. See Viewing file history, page Click the Check Out tab to view the check out information, such as the user who checked out the file, check out time, and check out location. 6. Click the Sharing tab to view shared file information. 7. Click the Custom Fields tab to view custom field information. 8. Click the Local Preview tab to preview an image file in your working directory. This tab is disabled if the selected file is not an image. 73

90 Viewing line-by-line file changes A warning is displayed if the file in the working directory is different from the server file. Viewing line-by-line file changes Line-by-line annotation helps you trace the history of file changes and provides better support for code reviews, audits, and similar processes. Annotation helps you identify new or changed lines between versions, who made the change, when it was made, and the action that caused the change. Tip: Diff the files if you need to compare, accept, or reject differences between file versions. See Viewing file differences, page Select a file. Note: The only Unicode files you can annotate are UTF-8 and UTF Choose Activities > Annotate. The Annotate dialog box opens. 3. Select a Version to annotate. Latest version uses the latest server version. Historic version uses the selected server version. Timestamp uses the current server version based on the selected date and time. Label uses the version with the selected label. Click Select to search for a label. Latest version in state uses the latest version based on the selected workflow state. Note: If you annotate a file in a snapshot branch, the Version to annotate field is set to the selected version in the parent branch and the field is read-only. 4. Select a Show changes since option. Changes are displayed for the version after the selected version and all versions up to the selected version to annotate. For example, if you select to annotate version 10 and select version 5 in this field, annotations are displayed for versions 6 through 10. Historic version uses the selected server version. You can also enter a version. Select All to display changes for all files, including version 1. Note: If you select All, it can take several minutes to annotate the files if there are many revisions or the file size is large. 74

91 Working with annotate results Timestamp uses the current server version based on the selected date and time. Label uses the server version with the selected label. You can also enter a label. Click Select to search for a label. See Selecting labels, page 147. Latest version in state uses the latest version based on the selected workflow state. You can also enter a state. 5. Click Annotate. A progress indicator opens. When the annotation is complete, the Annotate window opens. See Working with annotate results, page 75. Working with annotate results Information about annotated files is displayed in the following columns in the Annotate window. Column User Version Event Type Change Type Line # Content Description User who made the last change to the line Version of the file the change was included in Event that caused the change, such as check in or promote Type of change made to the line (add or modify) File line number New or changed content Consecutive lines with the same version number are grouped, indicated by different background colors. All lines in a group share the column information displayed in the first row of the block. Only the Content column information is different. Note: If Surround SCM cannot annotate a line, a dash (-) is displayed and the line is grayed out. Deleted lines are not annotated. You can perform the following actions in the Annotate window: 75

92 Viewing file history To add or remove a column, right-click a column and select the column from the menu. To move a column, drag it to the new location. Click a value in the User, Version, Timestamp, or Event Type columns to select all rows that contain the same value. This can help you see the relationship between changes. For example, click a version in the Version column to select all changes made in the selected version. Mouse over a line to open a pop-up window that includes all annotation information and comments entered when the event was performed. This can help you see information in columns hidden in the Annotate window. If the event type is Promote or Rebase, click the link in the Event Type column to annotate the version that was promoted or rebased. To search the Content column, enter a word or phrase in the Find field and click Find. Click Find again to go to the next match. To go to a specific line, click Go To, enter the line number, and click OK. Viewing file history Surround SCM stores all of the activities performed on a source file. You can view a file s history and work with a historic version of the file. 1. Select a file and choose Activities > History. The History dialog box opens. If you select an image file, it is displayed in the lower right corner for Add, Check In, Promote, Rebase, and Rollback events. Click the Thumbnail button to view thumbnails. Note: You can change the columns in the History dialog box. To display a column, right-click a column and select the column you want to add from the menu. Click and drag the column to change its location. To hide a column, right-click a column and select the column you want to hide. The Version and Action columns cannot be hidden. 2. Select a Filter by user option. You can view actions performed by a specific user or all users. 76

93 Viewing file history The System user is used by triggers to change workflow states and custom field values. 3. Select a Filter by action option. You can view specific actions, only actions that changed the file contents, or all actions performed on the file. 4. Select Additional events to display all file workflow events, custom field values, or label events. 5. Expand the parent branch file history for Add from branch and Rebase events, or child branch file history for Promote from events. File changes in the ancestor branch after the add, promote, or rebase are not included. Tip: The file version changes when you check in, promote, and rebase files. Select the File contents changed filter to view files with content changes. 6. Select a file version and click a button to perform an action. Button Action View history details for the selected version. See Viewing file history details, page 78. View differences for the selected versions. See Viewing file differences, page 39. Generate a report of differences between versions. See Running file differences reports, page 43. Retrieve a copy of the selected version. See Getting files, page 15. Check out the selected version. See Checking out files, page 21. View the selected version. See Viewing files in Surround SCM, page 17. Edit the file. See Editing files in Surround SCM, page 24. Revert to a previous file version. See Rolling back files, page 27. View branches that contain changes made in the selected version. See Tracking duplicated changes, page 201. Review changes made in the selected version. See Reviewing changes between file versions, page 62. Add the selected version to a code review. See Adding files to code reviews, page 55. View code reviews for the selected version. See Viewing code reviews files are included in, page 71. Attach the selected version to an item in TestTrack item or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page

94 Viewing file history details Button Action View the TestTrack item the selected version is attached to. See Viewing TestTrack items, page 257. View the committed changelist. This option is only enabled if the action was performed as part of a changelist. See Working with committed changelists, page 130. Set the workflow state for the file. See Changing workflow states, page 33. Label the selected version. See Labeling files, page 146. View labels applied to the selected version. See Viewing labels, page Click Close when you finish. Note: You can also view removed file history. Select a repository and choose Activities > Properties. Click the Removed Items tab. Select a file and click History. Viewing file history details When you view detailed historical information about the file, the information displayed depends on the file action performed on the selected version. For example, if you view a version with a Change custom field action, the old and new custom field values are displayed. 1. Select the file and choose Activities > History. 2. Select a file version and click Details. The read-only History Details dialog box opens. 3. If the file is attached to an issue, click View to view the issue. 4. Click Edit Comments to modify the comments entered for the file action and click OK to save the changes. Note: Depending on your security permissions, you may only be able to edit comments you entered. 78

95 Viewing graphical file history 5. Click OK to save the changes. Viewing graphical file history The graphical history provides a visual representation of a file's version history. You can view actions that caused the version number to change, trace when changes were promoted, rebased, and duplicated across branches, and view file details at any stage in the history. 1. Select a file and choose Activities > Graphical History. The Graphical History window opens. The version graphic displays the branches that include the file along the vertical axis and a timeline of the file history along the horizontal axis. Each file version is displayed as a node including the version number and an icon for the action performed at that version. Arrows between nodes indicate if the file was promoted, rebased, or duplicated. 2. Select the Branches you want to display. The branches that include the file version are selected by default. Click and drag the zoom slider to zoom in and out. Click a node to view file version details in the Details pane. Click and drag the outlined box in the Navigator to view a specific area in the history. 3. To view differences between file versions, Ctrl+click two file versions, right-click, and choose Differences. See Viewing file differences, page Click Save As to save the graph or Print to print it. 79

96 Viewing general file information Viewing general file information The General properties tab includes basic file information, such as comments and the last modified date. 1. Select a file and choose Activities > Properties. 2. Click the General tab. 3. Depending on security permissions, you may also be able to expand keywords, change the file type, and override the workflow to set a different state. Viewing checked out file information The Check Out properties tab includes information about a checked out file. 1. Select a checked out file and choose Activities > Properties. 2. Click the Check Out tab. 3. Click OK when you finish. Viewing shared file information The Sharing properties tab includes information about where a file is shared from and where it is shared to. 1. Select a file and choose Activities > Properties. 2. Click the Sharing tab. This tab is only enabled if you selected a shared file. 80

97 Viewing file custom field information Viewing file custom field information The Custom Fields properties tab includes the custom field values that can be set for the file. 1. Select a file and choose Activities > Properties. 2. Click the Custom Fields tab. This tab includes read-only custom fields information. Depending on your security permissions, you may be able to set the field values. See Setting custom fields, page

98

99 Setting Up Notifications You can create notifications to be automatically notified of changes. For example, you can be notified when files are checked in to a specific branch. Before you create a notification, define the files, users, or custom field values the notification should consider and the event or activity that causes the to be sent. In some cases, you may receive multiple s if you set up user notifications that are similar to system notifications, which are typically configured by the Surround SCM administrator. You may receive a large number of s if you create too many notifications. 1. Choose Tools > My Notifications. The My Notifications dialog box opens. 2. Select Show shared triggers where I am an recipient to display any system notifications you are set to receive. Yes is displayed in the Shared column for system notifications. 3. Click Add to create a notification. See Adding notifications, page Select a notification and click Edit to change it. See Editing notifications, page Select a notification and click Duplicate to duplicate it. See Duplicating notifications, page Select a notification and click Disable to disable it. See Disabling and enabling notifications, page 86. Tip: Select a disabled notification and click Enable to enable it. 7. Select a notification and click Delete to delete it. See Deleting notifications, page 86. Adding notifications Add notifications to be automatically notified of file, code review, or code review file changes. For example, you can add a notification to be informed when files are checked in to a specific branch. 1. Choose Tools > My Notifications. The My Notifications dialog box opens. 2. Click Add. 83

100 Adding notifications The Add My Notification dialog box opens. 3. Enter a Notification Name. 4. On the Trigger When tab, select the events that cause the to be sent. 5. Click the Preconditions tab to set the condition that files must meet to send the . 84

101 Adding notifications 6. Select a precondition. The Precondition dialog box opens. You can add preconditions based on branch and repository, filename, committed changelists, workflow states, users performing file events, security groups for users performing file events, or custom field values. Note: The in branch [<all branches>] and in repository [<all repositories>] precondition is selected by default. An is sent for every file if you do not select additional preconditions. The Precondition dialog box does not open if you select the 'is part of a changelist commit' precondition. 7. Enter or select the precondition values. Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding restrictions, page Click OK. The precondition values are added. The values are displayed in the conditions list and the Summary field. 9. Repeat steps 6-8 to select any additional preconditions. To change a precondition value, double-click the value in the list. When you add more than one precondition, Surround SCM treats them as and conditions. Triggers only fire when all of the selected preconditions are met. 10. Clear Enabled if you do not want the notification to be active. 11. Select Disable notification after it runs once if you only want the to be sent once. 12. Select Consolidate multiple file events into one to send one for all files the notification runs on. An is sent for each file if this option is not selected. 13. Click Edit Template to modify the default template. See Editing templates, page Click OK to add the notification. 85

102 Editing notifications Editing notifications You can edit notifications to change the event that causes the to be sent or the condition that files must meet to send the Choose Tools > My Notifications. The My Notifications dialog box opens. 2. Select a notification and click Edit. The Edit My Notification dialog box opens. 3. Make any changes. To edit a value on the Preconditions tab, double-click the value. Click Edit Template to modify the template. See Editing templates, page Click OK to save the changes. Duplicating notifications If you need to create an notification similar to an existing one, save time by duplicating and editing an existing notification. 1. Choose Tools > My Notifications. 2. Select a notification and click Duplicate. The notification is duplicated and added below the selected notification. 3. Select the new notification and click Edit. 4. Make any changes. 5. Click OK to save the changes. Disabling and enabling notifications If you do not want an notification to be sent, you can disable it temporarily instead of deleting it. You can also enable disabled notifications. 1. Choose Tools > My Notifications. The My Notifications dialog box opens. 2. Select a notification and click Disable or Enable. The notification is disabled or enabled. Deleting notifications You can delete notifications if they are no longer used. If you do not want an notification to be sent, you can disable it temporarily instead of deleting it. See Disabling and enabling notifications, page Choose Tools > My Notifications. The My Notifications dialog box opens. 2. Select a notification and click Delete. 86

103 Deleting notifications You are prompted to confirm the deletion. 3. Click Yes. The notification is deleted. 87

104

105 Customizing Surround SCM You can customize Surround SCM to display information that is important to you. You can also configure user options to help you work more efficiently. Customizing the Source Tree window The Source Tree window displays information in a column format. You can customize the window and set up the columns to display information you need. Note: If the computer has multiple users, changes you make to the Source Tree windows and other windows are saved for each user. Changing column contents 1. Right-click a column heading. The menu displays all the available fields. Checkmarks indicate columns that are currently displayed. 2. Select a column from the menu. The column is added and the file information is displayed. Note: To remove a column, right-click a column and select the column in the menu. 3. Click and drag the column to change its location. Changing column widths 1. Move the cursor to the divide bar between the column headings. The cursor changes to a resize cursor. 2. Click and drag the divide bar to change the width of the column to the left of the divide bar. 89

106 Setting Source Tree options Sorting columns You can perform a primary sort to organize files based values in the selected column. You can also perform a secondary sort to further organize files based on another column value. For example, you may want to sort files by status and then by last check in date. 1. Click a column heading to perform a primary sort. or is displayed next to the heading. Click the column heading again to toggle the sort order. 2. Shift+click a column heading to perform a secondary sort. or is displayed next to the secondary sort heading. Shift+click the column heading again to toggle the sort order. Displaying and hiding panes You can display and hide the Branch tree, file details pane, Activity Log tab, Pending Changelists tab, and status bar in the Source Tree window. Choose View and then select the pane you want to display or hide. Setting Source Tree options You can set options to control the information displayed in the Source Tree window. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Source Tree category. 2. Select any General options. Automatically refresh view every controls how often the Source Tree should automatically refresh. Enter the refresh interval in minutes. You can also choose View > Refresh to manually refresh the view. Hide snapshot branches hides snapshot branches in the Branch menu and Branches tree. Select this option if you do not work with snapshot branches. 90

107 Setting file information display options Show hidden branches displays hidden branches in the Branch menu and the Branches tree. Select this option if you need to access a branch that is not displayed. You can work with hidden branches if they are active. Clear List recursively option when selecting a different branch and different repository automatically clears the List recursively option when you select a different branch or repository in the Source Tree window. 3. Select a Default Double-Click Action. View server copy opens a read-only copy of the most recent file version on the Surround SCM Server. Edit checked out file or view server copy if file is not checked out opens the local copy of the file for editing if it is checked out. If the file is not checked out, a read-only copy of the most recent file version on the Surround SCM Server opens. Check out file and edit local copy checks out the file and opens the local copy for editing. Note: When you double-click a file, the associated viewer or application starts. See Setting viewer/editor options, page 17 to change the applications used to view and edit files. 4. Select a Default Drag-and-Drop Action. Share automatically shares files between two locations. See Sharing Files Between Repositories, page 117. Move automatically moves files to a location. See Moving files, page 34. Prompt prompts you to select if you want to move or share files. Note: This option only applies to drag-and-drop actions performed in the Surround SCM Source View. It does not apply to dragging files into or out of Surround SCM. 5. Click OK to save the changes. Setting file information display options You can select the information displayed under thumbnail images and in pop-up text when you mouse over a file. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Display File from the Source Tree category. 91

108 Customizing shortcut menus 2. Select Thumbnail File Details options to set the information displayed under thumbnails. 3. Select Show pop-up file information to enable file information in pop-up windows displayed in the Source Tree window when you mouse over a file. 4. Select the Pop-up File Details options to set the information displayed in pop-up windows. 5. Click OK to save the changes. Customizing shortcut menus You can customize the available items on the branch, repository, and file list shortcut menus. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Branch Menu, Repository Menu, or File List Menu from the Source Tree category. 92

109 Customizing toolbars 2. Select the item you want to add in the Available menu items list and click the right arrow to move it to the Current menu items list. To remove an item, select it in the Current menu items list and click the left arrow to move it to the Available menu items list. 3. Select an item in the Current menu items list and click Top, Move Up, Move Down, or Bottom to change the display order. You can also move the <separator> to divide the menu. 4. Click OK to save the changes. Note: Click Reset to reset the shortcut menu items. Customizing toolbars The default toolbar, which is named Custom, includes buttons for the most commonly used actions. You can add or remove buttons to the toolbar and change how buttons are displayed. You can also display or hide other built-in toolbars, such as the Activities or Bookmarks toolbar. Customizing toolbar options You can change how toolbar buttons are displayed. 1. Choose View > Toolbars and select a display option. Icon/Text Displays icons and text on toolbar buttons. Icon Displays icons on toolbar buttons. Text Displays text on toolbar buttons. 2. Select Use Small Size to reduce the toolbar icon size. Displaying and hiding toolbars 1. To display a toolbar, choose View > Toolbars and select the toolbar to display. 2. To hide a toolbar, choose View > Toolbars and select the toolbar to hide. 93

110 Changing the user interface mode Note: On Mac OS X, only the default toolbar is available. To display it, choose View > Show Toolbar. To hide it, choose View > Hide Toolbar. Changing the custom toolbar You can add buttons to the custom toolbar to access actions you frequently use. 1. Choose View > Toolbars > Customize Toolbar (Windows and Linux) or View > Customize Toolbar (Mac OS X). The Customize Toolbar dialog box opens. All available buttons and the default custom toolbar are displayed. Note: On Mac OS X, the toolbar button used to open the Properties dialog box is named Info. 2. Select an item and drag it to the custom toolbar. You can also add the following items to the toolbar to group items: Separator Adds a vertical line to separate toolbar sections. Spacer Adds a space between toolbar buttons. Flexible Spacer Adds a space that you can resize between toolbar buttons. 3. Select a Show option to control how toolbar buttons are displayed. Icon/Text Displays icons and text on toolbar buttons. Icon Displays icons on toolbar buttons. Text Displays text on toolbar buttons. 4. Select Use Small Size to reduce the toolbar icon size. 5. To remove an item, drag it off of the toolbar. 6. To reset the toolbar, drag the default toolbar from the Customize Toolbar dialog box to the custom toolbar. Changing the user interface mode Surround SCM Source View windows can be organized in a single parent window or as individual windows. We recommend using the default mode for your operating system. 1. Choose View > User Interface Mode and select an option. SDI displays multiple windows individually. Each window contains the same toolbars as the parent window, but only the parent window contains Surround SCM menus. The Activity Log and Pending Changelists tabs are displayed in one Information window for all open Source View windows. If the Code Reviews, Shelves, Users, or Security Groups windows are open, they are displayed as individual windows. This is the default mode for Mac OS X. MDI displays multiple windows in one parent window. Only the parent window contains Surround SCM menus and toolbars. This is the default mode for Windows and Linux. Changing defaults for Surround SCM dialogs To save a step when you work with files, you can set the options that are enabled or disabled by default in dialog boxes. For example, you can enable exclusive check outs. 94

111 Setting Get Files dialog defaults Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the File Dialog Defaults category. 2. Select any Changelist defaults to automatically select changelist options in file action dialog boxes. See Using Changelists, page 123. Perform actions as part of changelist enables the use of changelists when performing file actions. If this option is enabled, <New changelist> is automatically selected in file action dialog boxes unless the option to remember last selected changelist is also enabled. View pending changelists after action opens the Changelists dialog box to display all your pending changelists after performing file actions. Remember last selected changelist selects the last changelist used when performing a file action. 3. Select Display advanced Merge/Differences dialog to automatically expand advanced options in the Merge and Differences dialog boxes. See Viewing file differences, page 39 and Merging files, page Select Always create local directories without prompting to automatically create local directories when you get or check out files if the directories do not exist. 5. Select Remember last selected code review to automatically select the last used code review when adding or checking in files, or adding files to code reviews. 6. Click OK to save the changes. Setting Get Files dialog defaults You can configure the default settings to use in the Get Files dialog box. See Getting files, page 15. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Get Files from the File Dialog Defaults category. 95

112 Setting Check In Files dialog defaults 2. Change any default settings for the Get Files dialog box. Force file retrieval from server gets the server copy. Merge should first attempt auto-merge automatically merges file version if needed. You are only prompted to manually merge files if auto-merge fails. Make files writable leaves the files in the working directory in read-write mode. Recursive includes all child repositories in the get. Overwrite option specifies what to do if the local file and server file are different and how to handle modified files in the working directory that were removed from the server. File timestamp sets the timestamp on local files retrieved from the server. 3. Click OK to save the changes. Setting Check In Files dialog defaults You can configure the default settings to use in the Check In Files dialog box. See Checking in updated files, page 24. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Check In Files from the File Dialog Defaults category. 2. Change any default settings for the Check In Files dialog box. 96

113 Setting Check Out Files dialog defaults Update version even if no change is made always updates the file version. Apply comments to all uses the comment field value for each file. Add changes to code review adds checked in files to a code review. Prompt to link with TestTrack (IDE integrations only) prompts you to attach files to TestTrack items. Warn if checked out to a different computer prompts you to confirm the check in if files are checked out to a different computer. Recursive checks in files from the selected repository and all child repositories. Handle local files after check in indicates how to handle local files after check in. Select an option from the list. If you choose to get a local or server copy, you can also select Make files writable to leave a read-write copy of the files in the working directory. 3. Click OK to save the changes. Setting Check Out Files dialog defaults You can configure the default settings to use in the Check Out Files dialog box. See Checking out files, page 21. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Check Out Files from the File Dialog Defaults category. 2. Change any default settings for the Check Out Files dialog box. Exclusive check out prevents other users from checking out the files. This option is only available if Surround SCM allows multiple check outs. Force file retrieval from server checks out the server copy. Recursive checks out files from the selected repository and all child repositories. Overwrite option specifies what to do if the local file and server file are different. File timestamp sets the timestamp on local files retrieved from the server. 3. Click OK to save the changes. Setting Undo Check Out Files dialog defaults You can configure the default settings to use in the Undo Check Out Files dialog box. See Undoing check out, page

114 Setting Add Files dialog defaults Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Undo Check Out Files from the File Dialog Defaults category. 2. Change any default settings for the Undo Check Out Files dialog box. Recursive automatically reverts the check out for the selected repository and all child repositories. Handle local files indicates how to handle local files after the check out is undone. Select an option from the list. If you choose to get the original or latest version, you can also select Make files writable to leave a read-write copy of the files in the working directory. 3. Click OK to save the changes. Setting Add Files dialog defaults You can configure the default settings use in the Add Files dialog box. See Adding files to Surround SCM, page 28. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Add Files from the File Dialog Defaults category. 2. Change any default settings for the Add Files dialog box. 98

115 Grouping file extensions Recursive adds files from the selected directory and all subdirectories. Get files after add creates a read-only copy of the files in the working directory. Select Make files writable to leave a read-write copy of the files in the working directory. Check out files after add immediately checks out the files after they are added. Select Exclusive check out to prevent other users from checking out the files. This option is only available if Surround SCM allows multiple check outs. Overwrite files if found removed overwrites removed files. If this option is not selected and a file matches a removed file, you are prompted to replace the file or skip it when adding files. Add files to code review immediately adds files to a code review after they are added. 3. Click OK to save the changes. Grouping file extensions You can create a group of file extensions to use when filtering the file listing in the Add Files dialog box and refining searches in the Find In Files window. This helps you quickly locate the files to add to Surround SCM or specify file types when searching for text in files. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Add/Find In Files Extensions category. 2. Click Add to create a group of file extensions. See Adding file extension groups, page Select a group and click Edit to edit a file extensions group. 4. Select a group and click Top, Move Up, Move Down, or Bottom to change the display order. 5. Select a group and click Delete to delete a file extensions group. 6. Click OK to save the changes. 99

116 Adding file extension groups Adding file extension groups Create file extension groups to organize related file types to easily find them in lists in Surround SCM. These groups are used to filter file types in the Add Files dialog box and refine searches in the Find in Files window. 1. Choose Tools > User Options then select the Add/Find In Files Extensions category. 2. Click Add. The File Extension Settings dialog box opens. 3. Enter a Description of the file extension group you are adding. 4. Enter the File extensions to include in the group. Use a semicolon to separate multiple extensions. 5. Click OK to add the group. 6. Click OK to save the changes. Setting Shelve Files dialog defaults Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select Shelve Files from the File Dialog Defaults category. 2. Select any default settings for the Shelve Files dialog. Select Recursive to shelve files from the selected repository and all child repositories. Select View Shelves window after shelving files to open the Shelves window after files are shelved. 100

117 Setting Shelve Files dialog defaults Select a Handle local files option. Select Make files writable to leave a read-write copy of the files in the working directory. 3. Click OK to save the changes. 101

118

119 Managing Repositories Repositories organize Surround SCM by grouping together files and subrepositories. Your company s needs and business processes dictate how you set up repositories. You may want to answer the following questions before you start creating repositories: Should a new repository be created for each product, each component, etc.? Who can create Surround SCM repositories? Who can access advanced Surround SCM repository actions, such as promoting? Who is responsible for maintaining repositories? Creating repositories Before you add files to Surround SCM, you need to create a repository to store the files in. A repository is a collection of files and subrepositories that help you organize source code and other files managed with Surround SCM. 1. Choose Repository > Create Repository. The Create Repository dialog box opens. The Branch field displays the branch you are creating the repository in. The Parent repository field displays the repository you are creating the repository in. 2. Enter the New repository name. Repository names cannot contain the following characters: \, /, *,? 3. Enter any Comments, such as the reason for creating the repository. 4. Set a working directory and select any inherit options. A working directory is a location on your computer or network that a repository is mapped to. 103

120 Viewing differences between repositories and working directories Enter a Working directory path or click Browse to select a directory. Select Allow child repositories to inherit this working directory if you want child repositories to use the same directory. Select Inherit working directory from parent to use the parent repository's working directory. 5. Optionally expand the Changelist options area to select options for creating the repository as part of a changelist. See Adding file actions to changelists, page Click OK. After creating a repository, you need to add source files to it. See Adding files to Surround SCM, page 28. Note: If the branch uses a template, you cannot create a repository with the same name as a repository excluded in the template. To add the excluded repository to the branch, modify the branch template to include it. See Modifying templates for existing branches, page 366. Viewing differences between repositories and working directories You can diff a repository to see differences between Surround SCM and your working directory. You can also perform actions on files and repositories while viewing the differences. Tip: If your working directory contains many changes and you want to update Surround SCM to match it, you can push changes to the repository to perform multiple actions at the same time. See Pushing changes to repositories, page Select the repository and choose Repository > Working Directory Differences. The Working Directory Differences dialog box opens. 104

121 Viewing differences between repositories and working directories 2. Click to switch between tree view and list view. 3. Select Recursive to show all files in the repository and any subrepositories. 4. Select any Files to show options to control which files and repositories are included in the list. Different contents shows files in the working directory that are different from the repository. Different timestamps shows files in the working directory with a different timestamp than the repository. The file contents are the same. Identical shows files that are the same in the working directory and repository. Missing locally shows files and subrepositories in the repository that are missing from the working directory. Missing from Surround SCM shows files and repositories in the working directory that have not been added to Surround SCM. If a filename or extension matches an excluded value and this option is selected, the file is shown if the Excluded by filename or extension option is also selected. 105

122 Viewing differences between repositories and working directories Excluded by filename or extension shows all files regardless of name or extension even if Surround SCM is configured to ignore some filenames and extensions when adding files. If a local file name or extension matches an excluded value and this option is selected, the file is displayed if the Missing from Surround SCM option is also selected. In cloaked repositories includes files in cloaked repositories. Note: Click Expand All to expand all repositories with differences. Click Collapse All to collapse all expanded repositories. 5. Select a file or repository and click a button to perform an action. Button Use to: More information Differences Merge View Compare the current file version in Surround SCM with the copy in the working directory or another version to see the differences between them. Merge the file in the working directory with the file in Surround SCM. View the file. You can view the local or Surround SCM file. Viewing file differences, page 39 Merging files, page 40 History View the file or repository history. Viewing file history, page 76 and Viewing repository history, page 119 Properties View the file or repository information. Viewing general file information, page 80 and Viewing general repository information, page 120 Get Retrieve a copy of the file or repository to the working directory. Getting files, page 15 Add Add the file or repository to Surround SCM. Adding files to Surround SCM, page 28 Check In Check in the file to Surround SCM. Checking in updated files, page 24 Shelve Shelve the file or repository in Surround SCM. Shelving files, page 153 Remove Delete the missing file or directory from the working directory. If you select a local file or directory, you are prompted to confirm the deletion. If you select a server file or repository, the Remove Files or Remove Repository dialog box opens. Removing files, page 35 and Removing repositories, page

123 Resolving missing moved and renamed items Button Use to: More information Resolve Missing Resolve file differences if a file or repository was moved or renamed. Ctrl+click the old and new item and then click Resolve Missing. Resolving missing moved and renamed items, page Click Save As to save the differences list or click Print to print it. 7. Click Close when you finish. Resolving missing moved and renamed items Moved and renamed files and repositories are treated as unique items. When diffing working directories, Surround SCM displays local and server copies of the same item as missing. For example, if a file was moved from one working directory to another, the server copy is displayed as missing locally and the local copy is displayed as missing on server. If you have move and rename security permissions, you can perform one action to resolve differences between moved and renamed items, and maintain historical information for both items. Note: You can only resolve one difference. If an item was moved and renamed, you must manually resolve the separate actions. Resolving moved item differences 1. In the Working Directory Differences dialog box, Ctrl+click the original and moved items. 2. Click Resolve Missing. 3. Click Move Local to move the local copy to a different directory or click Move Server to move the server copy to a different repository. If you are moving the local copy, you are prompted to confirm the move. Click Yes to move the local copy and resolve the difference. If you are moving the server copy, the Move Files or Move Repository dialog box opens. The destination repository is automatically selected based on the local copy location. Enter any Comments, optionally set any Changelist options, and click OK to move the item and resolve the difference. Resolving renamed item differences 1. In the Working Directory Differences dialog box, Ctrl+click the original and renamed items. 2. Click Resolve Missing. 3. Click Rename Local to apply the server copy name to the local copy or click Rename Server to apply the local copy name to the server copy. If you are renaming the local copy, you are prompted to confirm the rename. Click Yes to rename the local copy and resolve the difference. If you are renaming the server copy, the Rename Files or Rename Repository dialog box opens. Enter any Comments, optionally set any Changelist options, and click OK to rename the item and resolve the difference. 107

124 Pushing changes to repositories Pushing changes to repositories You can push changes to repositories to update Surround SCM to match your working directory. For example, if you use third-party source libraries that are frequently modified when new versions are available, you can push changes to simultaneously move, create, and add files and repositories in Surround SCM. Note: Pushing changes is a one-way update and does not affect working directory contents. If you want to perform a two-way comparison to view all differences between local and server copies, and update working directories and repositories, diff the repository and working directory. See Viewing differences between repositories and working directories, page Select the repository and choose Repository > Push to Repository. The Push to Repository dialog box opens. 2. Click the display mode button to switch between tree view and list view. 3. Click Expand All to expand all repositories with differences. Click Collapse All to collapse all expanded repositories. 4. Select a file and click a button to review the information. Button Use to: More information Differences Compare, accept, or reject differences between file versions. Viewing file differences, page

125 Renaming repositories Button Use to: More information View View the local or server copy of changed files. Viewing files in Surround SCM, page 17 and Opening local files from Surround SCM, page 19 History View the file history. Viewing file history, page 76 Properties View the file properties. Viewing general file information, page Select the files with changes you want to push to Surround SCM. All files and repositories with changes are automatically selected. The corresponding actions, such as remove, add, and check in, are performed to push the changes to the repository. Clear any items you do not want to include. 6. Enter any Comments, such as the reason for pushing changes to the repository. 7. Expand the Changelist options to select options for pushing changes as part of a changelist. See Adding file actions to changelists, page Click Attach to attach the files with changes you want to push to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page Select Save As to save the list of pushed changes or click Print to print it. 10. Click Push. The selected changes are pushed to the repository. If you selected to push changes as part of a changelist, the changes are pushed to the repository after the changelist is committed. See Committing pending changelists, page 129. Renaming repositories You can rename repositories as needed, but subrepositories cannot use the same name as others in the same parent repository. Note: If the branch uses a template, you cannot rename a repository to use the same name as a repository excluded in the template. 1. Select the repository and choose Repository > Rename Repository. The Rename Repository dialog box opens. 109

126 Moving repositories 2. Enter a New Name and any Comments. 3. Expand the Changelist options to select options for renaming the repository as part of a changelist. See Adding file actions to changelists, page Click OK. The repository is renamed. Moving repositories You can move a repository to a different parent repository in the same branch. Keep the following in mind: You cannot move repositories that include files that are checked out or in a changelist. You cannot move repositories if the destination repository includes a subrepository with the same name or if a repository with the same name is excluded in the branch template. The move action is added to the repository history but not to file or subrepository history. Note: To move a repository to a different mainline branch, you need to export it. See Moving repositories to different mainline branches, page Select a repository and choose Repository > Move Repository. The Move Repository dialog box opens. 110

127 Cloaking and uncloaking repositories 2. Select a Destination Repository to move the repository to. 3. Enter any Comments, such as the reason for moving the repository. 4. Click OK. The repository is moved. Cloaking and uncloaking repositories You can cloak repositories to skip them when you recursively get, check in, check out, or undo check out. All subrepositories are also cloaked. For example, the Project A repository contains Code, Testing, and Documentation subrepositories. You do not use any files in the Testing repository, but you frequently recursively get the Project A repository. You can cloak the Testing repository to skip it when you get the Project A repository. Note: Cloaked repositories are specific to the computer they are cloaked on and the logged in user. Files in cloaked repositories are not displayed when recursively viewing files in the source file list or working directory differences. 1. Select a repository and choose Repository > Cloak Repository. The repository is cloaked. 111

128 Viewing cloaked repositories 2. To uncloak a repository, select it and choose Repository > Uncloak Repository. The uncloaked repository is included next time you recursively get, check in, check out, or undo check out. Viewing cloaked repositories You can view a list of all cloaked repositories. 1. Choose Tools > Cloaked Repositories. The Cloaked Repositories dialog box opens. 2. To uncloak a repository, select the repository and click Uncloak. You are prompted to confirm the uncloak. 3. Click Yes. The repository is uncloaked. 4. Click Close to close the Cloaked Repositories dialog box. Removing repositories Remove a repository if it is no longer needed, but you want to keep it in case you need to use it again later. When a repository is removed, its contents are not permanently deleted and can be restored. 1. Select the repository and choose Repository > Remove Repository. The Remove Repository dialog box opens. 112

129 Restoring repositories 2. Enter any Comments, such as the reason for removing the repository. 3. Select Force recursive remove to remove the repository and all files and subrepositories. 4. Select Permanently destroy repository to delete the repository from the hard drive. If you select Force recursive remove, this option changes to Permanently destroy repository and contents. 5. Expand the Changelist options to select options for removing the repository as part of a changelist. See Adding file actions to changelists, page Click OK. 7. Confirm the removal. If you are removing a repository but not destroying it, click Remove to remove it. The repository is removed but not deleted from the Surround SCM Server. Note: To view a list of removed subrepositories, select a repository and choose Activities > Properties and then click the Removed Items tab. If you are removing and destroying a repository from a branch that does not use a template, click Destroy to remove and permanently delete it. The repository is deleted and cannot be restored. If you are removing and destroying a repository from a branch that uses a template, select a destroy option and click Destroy. Destroy repository only destroys the repository. Destroy repository and exclude from branch template destroys the repository and removes it from the branch template, which also excludes it from the branch structure. The repository is deleted and cannot be restored. Note: If you destroy the repository without removing it from the branch template, the repository is added to the branch when the child branch is rebased later if it still exists on the parent branch. Restoring repositories You can restore repositories that were removed from Surround SCM. 1. Select the repository that contains the removed repository you want to restore. 2. Choose Activities > Properties. The Properties dialog box opens. Make sure you are viewing repository properties and not file properties. 3. Click the Removed Items tab. This tab includes a list of all removed repositories and files. 4. Select the repository you want to restore. 113

130 Deleting repositories permanently Tip: Click History to view repository history. Click Properties to view repository properties. 5. Click Restore. The Restore Files/Repositories dialog box opens. 6. Enter any Comments, such as the reason for restoring the repository. 7. Select Recursive restore to recursively restore all subrepositories and files. 8. Click OK. The repository is restored. Deleting repositories permanently When a repository is removed, it remains in the Surround SCM database unless it is destroyed. You may want to destroy repositories that are no longer needed to free up space in the database. Destroyed repositories are permanently deleted from Surround SCM and cannot be restored. Note: You can also remove and destroy repositories at the same time. See Removing repositories, page Select the repository that contains the subrepository you want to destroy. 2. Choose Activities > Properties. The Properties dialog box opens. Make sure you are viewing repository properties and not file properties. 3. Click the Removed Items tab. Tip: Click History to view repository history. Click Properties to view repository properties. 4. Select the repository you want to destroy and click Destroy. The Destroy Files/Repositories dialog box opens. 114

131 Deleting repositories permanently 5. Enter any Comments, such as the reason for destroying the repository. 6. Click OK. You are prompted to confirm the deletion. 7. Click Yes. The repository is destroyed and cannot be restored. 115

132

133 Sharing Files Between Repositories When you share a file, one copy of the file exists in multiple repositories. The file used to create the share is the base file and the copies created in other repositories are share links. When the base file is updated, all repositories reflect the updates simultaneously. Actions performed on the share links are applied to the base file. When a file is shared, the file history, filename, custom field values, and workflow state are maintained. Only the file location is different. If a file or repository is shared in a branch, any subsequent branches maintain the defined shared files. Sharing is a useful feature with many applications. For example, if a EULA file is identical across several projects, the EULA text file or Word document can be shared in each project repository. If an update is made to the EULA file then those updates are automatically included in the next release of any of the projects that contain the shared document. Tip: Surround SCM Shares Explained provides more information about sharing. 1. Select the file or repository you want to share and choose Activities > Share Files. The Share Files dialog box opens. 2. Select the repository you want to share the files with. Expand the repositories tree to view subrepositories. 3. Select Recursive to recursively share all files in a repository. 4. Enter any Comments, such as the reason for sharing the files. 5. Click OK. The files are shared. The file is displayed in each repository. 117

134 Breaking shares Breaking shares When a shared file is broken, or unshared, the two files function as unique copies and store any future changes independent of one another. Breaking shares can also be propagated between branches. If you break a share in the mainline branch and rebase the file that was broken, it is possible to have that break share operation replicated to the child branch. Tip: To move a file in Surround SCM, share it to the new location then remove the original copy. The share is broken and the file and its history now only exist in the new location. 1. Select the file or repository you want to unshare and choose Activities > Break Shares. The Break Shares dialog box opens. 2. Select Break shares recursively to recursively break all shared files in a repository. 3. Enter any Comments, such as the reason for breaking the shares. 4. Click OK. The files are no longer shared. 118

135 Viewing Repository Information Surround SCM stores historical repository information that you can review to understand details about when a repository was created, the number of files and subrepositories in a repository, the associated working directory, the actions performed on a repository, and the shadow folders used in a repository. See Viewing repository history, page 119. Viewing repository history History provides a way to view actions performed on a repository. 1. Select the repository and choose Activities > History. Note: You can also view the history for removed repositories. Select a repository and choose Activities > Properties. Click the Removed Items tab. Select a repository and click History. The History dialog box opens. Tip: You can change the columns displayed. To display a column, right-click a column and select the column you want to add. Click and drag the column to change its location. To hide a column, rightclick a column and select the column you want to hide. 2. Select any Filter by options to narrow the displayed actions. Filter by user limits the history performed by the selected users. The System user is used by triggers to change workflow states and custom field values. Filter by action limits the history to the selected actions performed. Filter by date limits the history to the specified time period. 3. Select Include file history to display actions performed on the files in the repository. 119

136 Viewing general repository information 4. Select List recursively to recursively display all files in the selected repository and subrepositories that meet the selected filter criteria 5. Select an action and click Details to view more information. The read-only History Details dialog box opens. 6. Click Edit Comments to modify the comments entered for the action and click OK to save the changes. Note: Depending your security permissions, you may only be able to edit comments you entered. 7. Click Close to return to the History dialog box. 8. Click View Changelist to view the committed changelist. This option is only enabled if the action was performed as part of a changelist. See Working with committed changelists, page If file history is included, select a file and click File History to view the history. See Viewing file history, page 76. Viewing general repository information You can view general information about a repository including the working directory, number of files in the repository, and number of subrepositories. 1. Select a repository and choose Activities > Properties. The Properties dialog box opens with the General tab selected. This tab includes read-only information about the repository. 120

137 Viewing repository shadow folders Viewing repository shadow folders You can view a list of all shadow folders in a repository. A shadow folder contains a reference copy of the current files in a repository. See Configuring Shadow Folders, page Select the repository and choose Activities > Properties. 2. Click the Shadow Folders tab. A read-only list of all shadow folders for the repository is displayed. 121

138

139 Using Changelists Changelists are used to group related file actions and allow for atomic transactions where all actions are treated as one unit. For example, you can use changelists to track files that were changed to fix a specific issue or manage updates made to files related to a large functional component. You can create changelists when you perform actions on files and repositories. See Creating changelists, page 123. The actions are added to a pending changelist and files and repositories are not made in Surround SCM until the changelist is committed. Before committing changelists, you can work with pending changelists to view the details, modify any actions included in it, attach it to a TestTrack item, or add it to a code review. See Managing changelists, page 124. To update the files and repositories in a pending changelist, commit the changelist. When you commit a changelist, all actions included in it are performed as a single transaction. If an action in a changelist fails, the entire operation is canceled. See Committing pending changelists, page 129. You can also use changelists to undo a group of related actions. For example, if you checked in multiple files related to the same bug fix as part of a changelist but you need to rollback the files because the changes affected other functionality, you can use the changelist to rollback all the changes at the same time without having to rollback files individually. See Rolling back changelist actions, page 135. Note: The Surround SCM administrator or another high-level user sets access to changelists. See Setting changelist server options, page 311. Creating changelists You typically create changelists when checking in updated files, but you can also create them when: Checking out, adding, moving, renaming, or removing files Creating, renaming, or removing repositories Pushing changes to repositories 1. Expand the Changelist options in the action dialog box. 2. Select <New Changelist> from the <file action> as part of the following changelist list. The Name Changelist dialog box opens when you perform the action. 3. Enter a New changelist name. 4. Click Attach to attach the changelist to items in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page Click OK. 123

140 Adding file actions to changelists The changelist is created and the action is added to it. The changelist is pending and the action is not performed until you commit the changelist. See Committing pending changelists, page 129. Adding file actions to changelists You can add file actions to new or existing changelists when you perform the action. For example, when you check in files, you can add the check in action to a changelist from the Check In Files dialog box. The files are checked in when the changelist is committed. The following example adds a file rename action to a changelist. You follow the same steps regardless of the action. 1. Select the file and choose Activities > Rename File. The Rename File dialog box opens. 2. To add a file action to a changelist, expand the Changelist options area and select an option. Select Rename as part of the following changelist and select the changelist you want to add the action to. Select <New changelist> to create a changelist. Select View pending changelists after rename if you want the Changelists dialog box to open after the action is added to the changelist. 3. Click OK. The file action is added to the changelist. Note: If changelists are required, the changelist options are always displayed. You can also set default changelist options for dialog boxes. See Changing defaults for Surround SCM dialogs, page 94. Managing changelists Pending changelists contain groups of files with actions that have not yet been made in Surround SCM. Committed changelists contain files with actions that have been made in Surround SCM. You can work with pending and committed changelists in the Changelists dialog box. 124

141 Viewing changelist details To view changelists, choose Tools > Changelists and then select a filter from the Filter changelists by list. The available actions depend on the selected changelist type. To work with pending changelists, select the My Pending or Pending for User filter. You can modify actions in the changelist, commit it to perform the actions on all files in it, add comments to files in it, attach it to a TestTrack item, or add it to a code review so the changes are reviewed after they are committed. See Working with pending changelists, page 125. To work with a committed changelist, select the My Committed, Committed by User, or All Committed filter. You can add files in the changelist to labels or code reviews, duplicate changes across branches, and rollback changes to undo actions performed when a changelist was committed. See Working with committed changelists, page 130. Viewing changelist details You can view details about changelists and actions. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select a changelist or file and click View Details. The read-only Changelist Details dialog box opens. Note: If the changelist is attached to a TestTrack item, information about the item is displayed. If the changelist is attached to an issue, click View to view read-only issue details. 3. Click Previous or Next to view details about additional changelists and files. Working with pending changelists You can view pending changelist details and modify actions before committing changelists. You can also perform other actions on pending changelists, such as renaming them or adding them to code reviews. 125

142 Working with pending changelists Note: To view or work with committed changelists, see Working with committed changelists, page Choose Tools > Changelists. The Changelists dialog box opens. 2. Select My Pending from the Filter changelists by list to work with your pending changelists. You may also be able to view or perform actions on other users' pending changelists. The corresponding changelists are displayed. A TestTrack icon is displayed next to changelists and files attached to TestTrack items. 3. Select a changelist or file and click the button for the action you want to perform. Tip: You can also use the Pending Changelists tab to view and work with pending changelists. To open it, choose View > Pending Changelists. Right-click a changelist or file and select the action to perform. Button Use to: More information View Details Commit Changelist View details about the changelist or file actions. Commit the changelist, which perform actions on all files in the changelist at the same time. Viewing changelist details, page 125 Committing pending changelists, page

143 Renaming changelists Button Use to: More information Rename Changelist Remove Changelist Set Comment Attach Edit Action Details Move Action Remove Action Rename the changelist. Remove the changelist and all related file actions. Add comments to the file or all files in the changelist. Attach the file or changelist to an item in TestTrack or an external issue tracking tool. Changelists and files are attached to items when changelists are committed. The Attach button is only available if at least one selected changelist file includes an Add or Check In action. Change the file action options. Move the file action to another changelist. Remove the file action from the changelist. Renaming changelists, page 127 Removing changelists, page 128 Adding comments to changelist files, page 129 Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page 268 Editing changelist file actions, page 128 Moving changelist actions, page 128 Removing changelist file actions, page 129 Differences Compare the file to another version. Viewing changelist file differences, page 132 Edit File Edit the file. Editing files in Surround SCM, page 24 Merge Merge the file with another version. Merging changelist files, page 133 Add to Code Review Add the changelist to a code review. Adding files to code reviews, page Select a changelist and click Save As to save it. You can save changelists in HTML, tab-delimited, or comma-delimited formats. 5. Select a changelist and click Print to print it. 6. Click Close when you finish. Renaming changelists You can rename pending changelists. 1. Choose Tools > Changelists. 127

144 Removing changelists The Changelists dialog box opens. 2. Select the changelist and click Rename Changelist. The Rename Changelist dialog box opens. 3. Enter a new name and click OK. The changelist is renamed. Removing changelists You can remove pending changelists and all actions associated with them. Removing a changelist does not delete any files, it only deletes the pending file actions. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the changelist and click Remove Changelist. You are prompted to confirm the removal. Note: If the changelist includes pending check ins, you are prompted to undo the check out after removing the changelist. Click Remove and Undo Check Out to undo the check out after the changelist is removed or Remove Only to remove the changelist and keep the files checked out. 3. Click Yes. The changelist and all of the actions associated with the pending changelist are removed. Editing changelist file actions You can edit changelist file action options. If files have the same action type, you can edit details for multiple files at the same time. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the file and click Edit Action Details. The corresponding file action dialog box opens. For example, the Check In dialog box opens if you select a file with a Check In action. 3. Make any changes. 4. Click OK to save the changes. Moving changelist actions You can move actions from one changelist to another. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the files and click Move Action. The Move Actions dialog box opens. 128

145 Removing changelist file actions 3. Select the Destination changelist you want to move the files to. You can also create a new changelist. See Creating changelists, page Click OK. The file actions are moved. Removing changelist file actions You can remove file actions from changelists. Removing an action from a changelist does not affect file changes in the working directory or change the file status. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the file and click Remove Action. You are prompted to confirm the removal. Note: If you are removing check in actions, you are prompted to undo the check out on files. Click Remove and Undo Check Out to undo the check out after the action is removed or Remove Only to remove the action and keep the files checked out. 3. Click Yes. The actions are removed. Adding comments to changelist files You can add comments to files in a changelist. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the files or changelist and click Set Comment. If you select a changelist, the comment is added to all the files in the changelist. The Set Comments dialog box opens. 3. Enter the comments. 4. Click OK. The comments are added to the selected files. Committing pending changelists Changelist actions are not performed until you commit the changelist. When you commit a changelist, all files in the changelist are submitted to the server at the same time. 129

146 Working with committed changelists 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the changelists and click Commit Changelist. The file actions are submitted to the server. If the transaction is successful, the changelist is removed from the pending list and added to the committed list. If a transaction fails, an error is displayed. Correct the errors and recommit the changelist. Working with committed changelists Surround SCM stores a list of all committed changelists for reference. You can view committed changelist details and perform them, such as adding then to labels or code reviews, duplicating changes across branches, or rolling back actions. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select My Committed from the Filter changelists by list. You may also be able to view other users' committed changelists or all committed changelists. The corresponding changelists are displayed. You can also search for committed changelists to further narrow the list. See Searching for committed changelists, page Select a changelist or file and click the button for the action you want to perform. Button Use to: More information View Details View details about the changelist or file actions. Viewing changelist details, page 125 Get Retrieve a copy of the file or all files in the changelist. Getting files, page

147 Searching for committed changelists Button Use to: More information History View the file history. Viewing file history, page 76 Differences View differences between the version of the changelist file and the version the action modified. Viewing file differences, page 39 View File View the file. Viewing files in Surround SCM, page 17 Add to Label Add to Code Review Duplicate Changes Rollback Changes Label the file or all files in the changelist. You can only label files with Add or Check In actions. Add the changes to a code review. Duplicate changes to another branch. Rollback changelist actions. Labeling files, page 146 Adding files to code reviews, page 55 Duplicating selected changes across branches, page 198 Rolling back changelist actions, page Select a changelist and click Save As to save it. You can save changelists in HTML, tab-delimited, or comma-delimited formats. 5. Select a changelist and click Print to print it. 6. Click Close when you finish. Searching for committed changelists You can search for committed changelists based on changelist name, filename, and date committed to further narrow the changelists displayed. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select a committed changelist filter in the Filter changelists by list. The corresponding committed changelists are displayed. 3. Select <Search> in the Filter changelists by list to specify additional filter criteria. The Changelist Search dialog box opens. 131

148 Viewing changelist file differences 4. Select the criteria that changelists must meet to pass the filter. The Restriction dialog box opens. The options change based on the selected restriction. 5. Select the restriction value. 6. Click OK. 7. Repeat steps 4-6 to add additional restrictions. 8. Click Search. Changelists that meet the criteria are displayed and the Search results filter is applied. Viewing changelist file differences You can diff files to compare, accept, or reject differences between two file versions. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the file and click Differences. The Differences dialog box opens. 3. Select a Second File option. 132

149 Merging changelist files Copy in working directory compares the server file with the working directory file. Selected file compares the server file with a file you select. Click Browse to select a file. 4. Click Advanced to select a branched file, historic file version, or unrelated file. The Second File area expands with the following options: Branched file merges changes with a branched version. Select a file from the list. Historic version merges the current version with a specific historic version. Select the version from the list. Unrelated files merges the current version with any other file. Click Browse to select a file. See Merging unrelated files, page Click Differences. The differences application opens. Merging changelist files You can merge files to compare, accept, or reject differences between files and combine the changes into a new file. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select the file and click Merge. The Merge dialog box opens. 133

150 Merging changelist files 3. Select Copy on server to merge changes with the latest version on the Surround SCM Server. 4. Click Advanced to select a branched file, historic file version, or unrelated file. The Second File area expands with the following options: Branched file merges changes with a branched version. Select a file from the list. Historic version merges the current version with a specific historic version. Select the version from the list. Unrelated files merges the current version with any other file. Click Browse to select a file. See Merging unrelated files, page Select Merge should first attempt auto-merge to enable auto-merges. You are only prompted to manually merge files if auto-merge fails. 6. Click Merge. If the file to merge into is checked out, the merge application opens. If the file is not checked out, the Check Out Files dialog box opens. 7. The files are merged and the merge application closes. The Merge Check In dialog box opens if you checked out the file when starting the merge. 134

151 Rolling back changelist actions If you want to check in the file, enter any comments then click Yes, check in file. If you want to keep the file checked out, click No, keep file checked out. Rolling back changelist actions You can rollback changes to undo actions performed when changelists were committed. Actions can be rolled back individually or all at once. For example, if you checked in several files when committing a changelist and then needed to rollback all the files, you can rollback the changes to undo them instead of rolling back each file. Before you rollback changes, you can review information about the actions performed, resolutions available when rolling back, and potential conflicts. The actions you can perform depend on the rollback status and your security permissions. See Rollback changelist action resolutions, page 137 for information about why actions will or will not rollback. 1. Choose Tools > Changelists. The Changelists dialog box opens. 2. Select a committed changelist and click Rollback Changes. The Rollback Changes dialog box opens. 135

152 Rolling back changelist actions 3. Select a file or repository and click a button review the information. Review the information closely if changes were made after the changelist was committed to determine how rolling back actions may affect files. Button Use to: More information View Details View details about the changelist and action performed. Viewing changelist details, page 125 Differences Compare file versions. Viewing file differences, page 39 History View the file history. Viewing file history, page 76 Properties View the file properties. Viewing general file information, page 80 Note: The filename or repository path may be empty if an action was performed as part of a changelist in Surround SCM 2009 or earlier. These actions must be rolled back manually. Select an action and click View Details to view the file or repository path and then rollback the individual file or perform an action to update the repository. 4. Enter any Comments, such as a reason for undoing the change. 5. Click a rollback resolution button. Button Use to: More information Rollback Changes Undo the changelist action. 136

153 Rollback changelist action resolutions Button Use to: More information Merge Locally Rollback File Rollback All Manually merge file versions. If the action you want to rollback changed file contents, you may need to manually merge the files to maintain changes made after the changelist was committed. Force a rollback to the previous file version. When rolling back files, any changes made after the changelist was committed are discarded. Roll back all the actions. Merging files, page 40 Rolling back files, page Click Save As to save the rollback results or click Print to print the results. 7. Click Close when you finish. Rollback changelist action resolutions The following icons indicate the status of actions rolled back or to be rolled back in changelists. Icon Action status Successfully rolled back Will rollback Will rollback with potential conflict Will not rollback Following are changelist actions and corresponding rollback resolutions based on status. Keep the following in mind. The Reason is 'Already rolled back' if an action was already rolled back. The Reason is 'File/Repository not found' if an action was performed as part of a changelist in Surround SCM 2009 or earlier. These actions must be manually rolled back. Select an action and click View Details to view the file or repository path, and then rollback the file or perform an action to update the repository. Changelist action Status Rollback resolution Reason Add Remove file -- Remove file No resolution required New file added, not latest version File removed 137

154 Rollback changelist action resolutions Changelist action Status Rollback resolution Reason Check In Rollback change -- Merge locally Rollback file No resolution available Auto-merge conflict Binary file changed, not latest version File removed Create Repository Remove repository -- Remove repository No resolution required Repository not empty Repository removed Destroy No resolution available File destroyed Destroy Repository No resolution available Repository destroyed Move Move file -- Move file No resolution available Repository different than moved to repository File removed Move Repository Move repository -- Move repository No resolution available Repository different than moved to repository Repository removed Remove Restore file -- No resolution required No resolution available File no longer removed File destroyed Remove Repository Restore repository -- No resolution required No resolution available Repository no longer removed Repository destroyed 138

155 Selecting changelists Changelist action Status Rollback resolution Reason Rename Rename file -- Rename file No resolution available Name different than renamed to File removed Rename Repository Rename repository -- Rename repository No resolution available Name different than renamed to Repository removed Selecting changelists You can view changelist details and search for a changelist to use when selecting files to add to a code review, or duplicating or tracking across branches. 1. Select the Changelist filter to work with files from a changelist and click Select. The Changelists dialog box opens. 2. Select a filter from the Filter changelists by list. You can display all committed changelists, your committed changelists, or committed changelists by user. You can also search for committed changelists. See Searching for committed changelists, page Select changelist or file and click View Details to view the details. See Viewing changelist details, page Select a changelist and click Select to use it. 139

156

157 Using Labels Labels are text tags that can be used to mark files with related revisions. They are typically created to correspond with an event or milestone that involves a group of files, such as an issue fix, build, or release. Labels are commonly used for retrieving file revisions associated with a specific change included in a build. For example, a developer makes a code change to fix an issue and applies the 'Bug Fix 4219' label when he checks in the file. The build manager can perform a get based on the 'Bug Fix 4219' label and build a patch that includes the fix. Using labels makes it easier to get files, create branches, and rebase files and branches on a group of related files in different repositories. You can also search for files, generate reports, and create triggers based on labels. When you create a label, you can make it available in a mainline branch or in a specific branch. This allows you to reuse the same label name in other branches. Labels can be applied to any files, including historical versions, in the branch. You can create and apply labels independently or at the same time as you perform the following file actions: Add files Get files Check in files Promote files or branches Duplicate changes to a branch View a committed changelist View file history Tip: Snapshot branches, which are similar to labels, can also be used to capture the state of files at a specific point in time, but you cannot check out, check in, or merge files into a snapshot branch. Your use of snapshot branches or labels depends on your organization's processes. Configuring labels You can add new labels, manage existing labels, and work with labeled files from the Labels dialog box. 1. Select the mainline branch to configure labels for. 2. Choose Tools > Labels. The Labels dialog box opens. 141

158 Configuring labels Note: Legacy labels created in Surround SCM 2008 or earlier are not displayed if they have not been upgraded. See Upgrading legacy labels, page Select a Filter labels by option. All Labels displays all labels for all branches. Search For File searches for labels by branch, repository, filename, and version. See Searching for labels, page Select any label display options. Show hidden labels displays hidden labels. Only show my labels only displays labels you created. 5. Click Add to create a label. See Creating labels, page Select a label and click the button for the action you want to perform. Button Use to: More information View View the label details. Viewing labels, page 144 Edit Edit the label to rename it, change the branches it is available in, or remove it from files. Editing labels, page 144 Delete Delete the label. Deleting labels, page 145 Duplicate Duplicate the label. Duplicating labels, page 145 Differences Compare two labels to determine the missing, different, or identical files between the labels. Viewing label differences, page

159 Creating labels Button Use to: More information Attach Attach labeled files to an item in TestTrack or an external issue tracking tool. Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page 268 Add to Code Review Toggle Hidden Add labeled files to a code review. Adding files to code reviews, page 55 Hide or unhide the label. Hiding labels, page Click Close when you finish. Creating labels Create a new label when you need to mark related file revisions in a branch, such as files affected by a bug fix. This is helpful when related files are stored in different repositories and you need a way to group the files. You can create labels for a mainline branch or a specific branch. The label can only be applied to labels in the branch it is created in. Note: You can also create labels when you add, check in, and promote files, or label a file version in a committed changelist or the file history. 1. Select the mainline branch to create the label in. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Click Add. The Create Label dialog box opens. 4. Enter a Label name and Label description. 5. Select a Label Scope option. Mainline makes the label available to all branches in the selected mainline branch. The mainline branch name is read-only. Branch makes the label available only to the selected branch. Click Browse to select a branch. 143

160 Viewing labels 6. Select Hidden to hide the label. Users cannot apply hidden labels to files or repositories. 7. Click OK to save the changes. Viewing labels You can view labels to see the files the label is applied to and the label history. 1. Select the mainline branch that includes the label. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click View. The read-only View Label dialog box opens. 4. Click the Files tab to view the files that the label is applied to. 5. Click the History tab to view the label history. Editing labels You can edit a label to rename it, change the branches it is available in, or remove it from files. You can change the branches that a label is available in based on the following rules: If the label is not applied to any files, the availability can be changed to the mainline branch or a selected branch in the mainline branch. If the label is available and applied to files in a specific branch, the availability can only be changed to the mainline branch. If the label is available in the mainline branch and applied to files in one child branch, the availability can only be changed to that child branch. If the label is available in the mainline branch and applied to files in more than one child branch, the availability cannot be changed. 1. Select the mainline branch that includes the label. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click Edit. The Edit Label dialog box opens. 4. Make any changes. 5. Click the Files tab to view the files the label is applied to. Select a file and click Remove to remove the label from it. See Removing labels from files, page Click the History tab to view the label history. See Viewing label history, page Click OK to save the changes. 144

161 Duplicating labels Duplicating labels If you need to create a label that is similar to an existing one, you can save time by duplicating and editing an existing label. 1. Select the mainline branch that includes the label you want to duplicate. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click Duplicate. The Create Label dialog box opens. 4. Enter a Label name. 5. Make any other changes. 6. Click OK to save the changes. Hiding labels Hide a label if you do not want users to be able apply it to files or perform actions based on the label. 1. Select the mainline branch that includes the label. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click Toggle Hidden. The label is hidden. Note: To unhide a label, select Show hidden files in the Labels dialog box, select the label, and click Toggle Hidden. Deleting labels You can delete labels that are no longer used. When you delete labels, the label history is also deleted. Note: If you want to make labels unavailable to users, you can hide them instead of deleting them. This allows you to maintain the label history. See Hiding labels, page Select the mainline branch that includes the label you want to delete. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click Delete. You are prompted to confirm the deletion. This action cannot be undone. 4. Click Yes. The label is deleted. 145

162 Labeling files Labeling files You can apply labels to files to group them with related versions in a branch. For example, you can label a set of files that are all affected by the same issue fix. You can label the current file version on the Surround SCM Server or the version in your working directory. A label can only be applied to one version of a file. Note: You can also label files in committed changelists, in file history, and when you add, check in, or promote files. 1. Select the files or repository and choose Activities > Advanced > Add Label. The Add to Label dialog box opens. 2. Select a Label. Select <New Label> to create a label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page Enter any Comments, such as the purpose of the label. 4. Select the File Version to apply the label to. Current version applies the label to the current file version on the server. Version in the working directory applies the label to the file version in the working directory. Only select this option if you want to label modified files in the working directory that have not been checked in. 5. Select Update label with selected version to remove the label from earlier file versions. 6. If you are labeling a repository, select Recursive to apply the label to the selected repository and all child repositories. 7. Click OK. 146

163 Selecting labels The label is applied to the files. Selecting labels You can view label details and search for a label to use when working with files. For example, you may want to review the label details before applying it to files or using it to select files to add to a code review. 1. Click Select next to the label field in the Add to Label or file action dialog box, such as the Add Files dialog box. The Select Label dialog box opens. 2. Select a Filter labels by option. All Labels displays labels for all branches. Search For File allows you to search for labels by branch, repository, filename, and version. See Searching for labels, page Select any label display options. Show hidden labels displays hidden labels. Only show my labels only displays labels that you created. 4. Click Add to create a label. See Creating labels, page 143. Note: You cannot create labels in this dialog box if you are getting files. 5. Select a label and click View to view details. See Viewing labels, page Select a label and click Select to use it. Searching for labels If you do not know the name of the label you want to apply, you can search for labels based on branch and repository, filename, and file version. Note: If you need to search by label name, perform an advanced find. See Searching for files, page In the Select Label dialog box, select Search For File in the Filter labels by field. The Label Search dialog box opens. 147

164 Viewing label differences 2. Select a restriction to set the search criteria. The Restriction dialog box opens. The options change based on the selected restriction. 3. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The restriction values are displayed in the restrictions list and the Summary field. Note: To change a restriction value, double-click the value in the restrictions list. 5. Repeat steps 2-4 to add additional restrictions. 6. Click Search. Files that meet the criteria are displayed in the Select Label dialog box. The Find Results filter is applied. Viewing label differences You can compare two labels to determine the missing, different, or identical files between the labels. If the labels are applied to different file versions, you can diff the files to determine the content differences. If a bug is introduced in a build, this can help with troubleshooting. 1. Select the mainline branch that includes the labeled files. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Ctrl+click the two labels you want to compare. 4. Click Differences. The Label Differences dialog box opens. 148

165 Viewing label history 5. Select any options to control which files are displayed. Show missing files displays files that do not have one of the labels applied. Show files with different versions displays files with different contents between the labels. Show identical files displays files with identical contents between the labels. 6. Select a file and click Differences to compare file versions. See Viewing file differences, page Click Save As to save the label differences or click Print to print the differences. Viewing label history Surround SCM stores all of the activities performed on a label, including applying and removing file labels. You can view the label history to see the actions performed on a label and the user who performed them. 1. Select the mainline branch that includes the label. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click View. The View Label dialog box opens. 4. Click the History tab. Actions performed at the same time are combined. For example, if 10 files are added at the same time and a label is applied when the files are added, only one action is displayed for all files. 149

166 Running labeled files reports Running labeled files reports Labeled file reports include a list of files and versions a label is applied to. Use these reports to view labeled files that correspond to a milestone, such as a test or release. 1. Choose Tools > Reports.The Reports dialog box opens. 2. Click Labeled Files Report. The Generate Labeled Files Report dialog box opens. 3. Click Set to select a different branch and repository. 4. Select the Label to report on. 5. Select Recursive to include all subrepositories. 6. Select Hide repositories that do not contain files to exclude empty repositories. 7. Click OK. The report opens. 8. Click Save As to save the report or Print to print it. 150

167 Removing labels from files 9. Click OK when you finish. Removing labels from files When you remove a label from a file, the file is longer grouped with related files. The file label history is maintained with the label. See Viewing label history, page Select the mainline branch that includes the labeled files. 2. Choose Tools > Labels. The Labels dialog box opens. 3. Select a label and click Edit. The Edit Label dialog box opens. 4. Click the Files tab. 5. Select a label and click Remove. The Set Comments dialog box opens. 6. Enter any comments and click OK. The label is removed and you return to the Edit Label dialog box. 7. Click OK to save the changes. 151

168

169 Using Shelves Shelves are temporary containers on the Surround SCM Server where you can store new and modified files before adding or checking them in to Surround SCM. You can use shelves to back up your work or to share files with other users before they are checked in. Shelved files are not versioned and historical information is not tracked. For example, you may want to create a shelf if your work on files is interrupted by other tasks, but you are not ready to check in the recent changes. You may also want to shelve files and share the shelf with other users who need to informally review your changes before you check them in for a code review. The method you use to shelve files depends on file status and if a shelf is already available. If you want to shelve files already under source control in a new or existing shelf, shelve the files from the Source Tree window. See Shelving files, page 153. If you want to add files that are not under source control, or modified files that are already under source control, to an existing shelf, shelve files from the Shelves window. Files must be in a working directory to be shelved. See Adding files to existing shelves, page 155. Note: You can also shelve modified or missing files from the Working Directory Differences dialog box. See Viewing differences between repositories and working directories, page 104. When you are ready to continue work on shelved files, unshelve the files to a working directory and then check them in to Surround SCM when the changes are complete. See Unshelving files, page 159. Shelving files Shelve files to store them in Surround SCM without adding or checking them in. You can only shelve files that are modified from the current version or missing from Surround SCM. Note: Use the Shelves window to shelve files that are not under source control. See Adding files to existing shelves, page Select the files or repositories to shelve and choose Activities > Shelve Files. The Shelve Files dialog box opens. 153

170 Shelving files 2. Select a Shelf to store the files in. The list includes shelves you own and shelves shared with you by other users. Select <New shelf> to create a shelf. See Creating shelves, page Expand the Local file options to select options for handling local files. Get original version replaces the local file with the original Surround SCM version and reverts the check out if files are checked out. Get latest version replaces the local file with the latest Surround SCM version and reverts the check out if files are checked out. Leave local file leaves the local file as is. Make files writable leaves a read-write copy of the file in the working directory. 4. Select View Shelves window after shelving files to open the Shelves window after files are shelved. 5. Select Recursive to shelve all new and modified files in the selected repository and all subrepositories. This option is available only if you are shelving from a repository. 6. Click OK. The files are shelved. 154

171 Adding files to existing shelves Note: After a file is shelved, only other files from the same branch can be added to the shelf. However, you can unshelve files across branches. For example, you may add new files to a shared shelf from the working directory for a workspace branch. Other users can unshelve those files to the working directory associated with their workspace branch or a baseline branch on the same mainline branch. See Unshelving files, page 159. Adding files to existing shelves You can add modified and new files in your working directory to existing shelves. Tip: You can also drag files from your working directory or the Source Tree window to a shelf in the Shelves window. 1. Choose View > Shelves. The Shelves window opens. 2. Select a shelf to store files in and click Shelve Files. The Add to Shelf dialog box opens. 3. Select the files to shelve. 4. Expand the Local file options to select options for handling local files. Get original version replaces the local file with the original Surround SCM version and reverts the check out if files are checked out. Get latest version replaces the local file with the latest Surround SCM version and reverts the check out if files are checked out. Leave local file leaves the local file as is. Make files writable leaves a read-write copy of the file in the working directory. 5. Select Recursive to shelve all new and modified files in the selected directory and all subdirectories. 155

172 Managing shelves Note: Recursively adding files to a shelf ignores directories that do not have a matching repository on the branch. Only modified and new files are added. 6. Click OK. The files are added to the shelf. Note: After a file is shelved, only other files from the same branch can be added to the shelf. However, you can unshelve files across branches. For example, you may add new files to a shared shelf from the working directory for a workspace branch. Other users can unshelve those files to the working directory associated with their workspace branch or a baseline branch on the same mainline branch. See Unshelving files, page 159. Managing shelves You can work with shelves and shelved files in the Shelves window. 1. Choose View > Shelves. The Shelves window opens. Tip: The number of files in a shelf is displayed in parentheses in the Change column. 2. Select a Mainline branch and optionally select a filter to view shelves you have access to. 3. Click Create Shelf to add a shelf. See Creating shelves, page Select a shelf or file and click a button to perform an action. Button Use to: More information Shelve Files Unshelve Files View File Add files to the shelf. Retrieve the file or all files in a shelf to a local or working directory. View the shelved file. Adding files to existing shelves, page 155 Unshelving files, page

173 Creating shelves Button Use to: More information Differences Edit Shelf Compare, accept, or reject differences between the shelved a file in another location. Edit the shelf to change the name, description, owner, and sharing settings, and manage the files in the shelf. Viewing shelved file differences, page 158 Editing shelves, page 158 Delete Remove the file from the shelf or delete the shelf. Deleting shelved files and shelves, page 158 Creating shelves Shelves are temporary containers on the Surround SCM Server where you can store new and modified files before adding or checking them in to Surround SCM. When you create a shelf, you are the only user who can add files to it by default. You can change the owner after the shelf is created. See Editing shelves, page 158. Note: You can also create shelves when shelving files in the Source Tree window and the Working Directory Differences dialog box. See Shelving files, page 153 and Viewing differences between repositories and working directories, page Choose View > Shelves. The Shelves window opens. 2. Click Create Shelf. The Create Shelf dialog box opens. 3. Enter a Shelf name and Description. 4. Select Enable sharing to allow other users to view and unshelve files from the shelf. 157

174 Editing shelves All users shares the shelf with all users. Selected users shares the shelf with only the selected users. 5. Click OK. The shelf is added. You can now add files to it. See Adding files to existing shelves, page 155. Editing shelves You can change the name, description, owner, and sharing settings for shelves, and manage the files in a shelf. You can only edit shelves you own depending on your security permissions. 1. Choose View > Shelves. The Shelves window opens. 2. Select a shelf and click Edit Shelf. The Edit Shelf dialog box opens. 3. Make any changes. 4. Click OK to save the changes. Deleting shelved files and shelves You can delete shelves and files from shelves that are no longer used. Before deleting a shared shelf, make sure users do not need access to it. Deleting a shelf also deletes any files stored in it. 1. Choose View > Shelves. The Shelves window opens. 2. Select a shelf or file and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The shelf or file is deleted. Viewing shelved file differences You can diff shelved files to compare, accept, or reject differences between the file stored in the shelf and the file in another location. Note: You cannot diff shelved files that are not yet under source control. 1. Choose View > Shelves. The Shelves window opens. 2. Select a shelved file and click Differences. The Differences dialog box opens. Read-only information is displayed in the First File area. 158

175 Unshelving files 3. Select a Second File option. Server version of the shelved file compares the shelved file with the current file version in Surround SCM. Copy in working directory for branch compares the shelved file with the file in the working directory for the selected branch. Branched file compares the shelved file with branched version. Select a file from list. 4. Click Differences. The differences application opens. Unshelving files Unshelve files when you complete work and are ready to check them in, or when you need to retrieve a local copy of files. You can unshelve files from shelves you own and shelves that are shared with you by other users. 1. Choose View > Shelves. The Shelves window opens. 2. Select a shelf or file and click Unshelve Files. If you select a shelf, all files in the shelf are retrieved. The Unshelve Files dialog box opens. 159

176 Unshelving files 3. Select the Branch to unshelve files from. The branch the file was shelved from is selected by default. Click Override to select a different branch. 4. Select the Location you want to retrieve files to. The working directory for the repository in the selected branch is selected by default. Click Browse to select a different location. 5. Select Remove files from shelf to remove files from the shelf after they are retrieved. This option is only available if you own the shelf. 6. Select Delete empty shelf to delete the shelf if it is empty after the files are retrieved. This option is only available if you own the shelf. 7. Click OK. The files are copied to the specified directory. Depending on the selected options, files may also be removed from the shelf and the shelf may be deleted. 160

177 Branching Branching provides easy and effective management of source files throughout the development lifecycle. Branches facilitate parallel development, capture the state of files at a specific milestone, and organize repositories and files. Surround SCM does not impose a branching process on users your use of branching depends on your company s needs and business processes. See Maintaining Branches, page 357 for information about advanced branching actions, such as promoting or viewing branch differences. About branches A branch is a separate line of development that uses an existing repository and the files in that repository as a starting point. When a branch is created, the files in both branches are identical. As file contents change, the branched files become different from each other. Use branches when you need to make changes to source files without affecting existing files. When you branch a repository, changes can be promoted to or rebased from associated branches. Note: Do not create a repository when you mean to create a branch. For example, when you are ready to release a product and start development on a new version, do not create a repository for the release code. Create a branch instead. Surround SCM includes mainline, baseline, workspace, and snapshot branches. Tip: Icons indicate the branch type and status. See Branch status icons, page 165 Mainline branch A mainline branch is the top-level branch that contains all source files, labels, other branches, and repositories. The Surround SCM administrator is generally responsible for creating mainline branches. At least one mainline branch must be created before files can be added to Surround SCM. Files cannot be shared across mainline branches. See Creating mainline branches, page 373. Baseline branch A baseline branch is a public branch used for collaborative development. Allowing check outs on a baseline branch lets all users directly check out and make changes to the baseline code. Changes made to the baseline branch affect everyone who accesses that branch. Create a baseline branch whenever it is necessary to make separate changes to the code in the mainline branch. For example, your company develops software and a customer requires a feature to integrate with another vendor s reporting tool. Create a baseline branch so you can customize the software for that customer without affecting all customers. 161

178 When to branch Baseline branches are generally created at the feature freeze (when feature development for the next release is complete) and code freeze (when the product is ready for review) milestones. Workspace branch A workspace branch is a private branch used to track and isolate changes made by an individual. Users create their own workspace branches. The branch that a workspace is created from is its parent branch. Other users are not affected by any changes made because the work done in the private branch. When a user finishes making changes, changes are promoted from the workspace branch to the baseline, or parent, branch. Changes can also be rebased from the baseline branch to a workspace branch. Create a workspace branch to work on bug fixes, work on new features individually, experiment with files, or perform research without affecting other users. For example, Suzy creates a workspace branch to fix bugs. When she finishes fixing bugs, she promotes her changes to the baseline branch and moves on to development for the next software release. Snapshot branch A snapshot branch is a read-only, static branch that generally corresponds to a project milestone, such as a QA build or final release. Most Surround SCM actions, such as check out, check in, and merges, are disabled in snapshot branches. Create a snapshot branch when you need to capture the state of files and the repository structure at a moment in time. For example, you may create a snapshot branch for different builds, such as alpha and beta testing, final releases, or to record custom code delivered to a customer. This can help you tell exactly which versions of files went into a build. For example, Greg is doing daily development builds. He creates a snapshot branch after each successful build to help detect differences between builds. Snapshot branches also provide an easy way to retrieve all the code used in older builds. You can create a snapshot branch based on the latest file version, latest version in a specific workflow state, a label, or a timestamp. When to branch Create a baseline branch when you need to make separate changes to the baseline code. Baseline branches are most commonly created at the feature freeze and code freeze development milestones, but they can also be created for other reasons, such as a beta release or to separate a group of developers working on a large feature. To keep branches in sync, changes can be promoted into common ancestor branches and changes from ancestors can be rebased into the new branches. Feature freeze The feature freeze milestone, which is when feature development for the next release is complete, is an ideal time to create a child branch from the baseline. Branching at this point lets the development team focus on different responsibilities. Developers working on issue fixes for the current release can make changes in the feature freeze branch, while developers working on new features for the next release can continue working in the baseline branch. After issues are fixed in the feature freeze branch, promote the changes to the baseline branch so the next product release includes the issue fixes. Make sure the feature freeze branch is read-only or create a snapshot branch to ensure developers do not inadvertently make any changes. 162

179 Branching example Code freeze The code freeze milestone, which is when the product is ready for release, is the next time to create a branch. Creating a code freeze branch from the feature freeze branch captures the code to be released. Developers should only be allowed to make critical bug fixes in the code freeze branch. If a critical bug is found, it can be fixed in the code freeze branch and promoted into both the feature freeze and baseline branches. Make the code freeze branch read-only after the product is released to ensure the released code is captured. This branch can be useful later if it is necessary to rebuild a previous release. Feature branches Branches can also be created for a specific feature that affects a large amount of code. Creating a feature branch allows developers to work on the feature without their changes affecting other developers. When feature development is complete, rebase the baseline branch code into the feature branch so the new feature can be tested along with any new or changed baseline branch code. After testing is complete, promote the feature branch changes to the baseline branch so they are included in the next release. Branching example The following example illustrates how branching can be used in a typical software development environment. Development starts on WysiCalc, a new product developed by the WysiCorp company. The WysiCorp Products (mainline) branch contains the repositories, source code, and associated files for all the company s products. All feature development takes place in this branch. After development is complete for the first WysiCalc release, a baseline branch named WysiCalc 1.0.x is created from the WysiCalc repository. This branch represents the feature freeze milestone in the development process. 163

180 Branching example Developers fix issues in the WysiCalc 1.0.x branch. Developers can also create private workspace branches where they fix issues and then promote the changes to the WysiCalc 1.0.x branch. Feature development for the next major WysiCalc release continues in the WysiCorp Products (mainline) branch. When WysiCalc is ready for release, a baseline branch named WysiCalc is created from the WysiCalc 1.0.x branch. This branch represents the code freeze milestone in the development process. Critical issue fixes for the release are made in the WysiCalc branch and promoted to both the WysiCalc 1.0.x and WysiCorp Products branches. After the product is released, the WysiCalc branch is made read-only and a snapshot branch named WysiCalc Final Release is created to ensure the released code is captured. This process of branching and promoting changes continues for all major and minor releases. 164

181 Branch status icons Branch status icons The following icons indicate the status of branches in various areas of Surround SCM, including the branches menu and tree in the Source Tree window. Icon Indicates: More information Mainline branch About branches, page 161 Baseline branch Snapshot branch Workspace branch Frozen mainline or baseline branch Freezing and unfreezing branches, page 365 Frozen workspace branch Mainline branch with indexing on for text-based searches Indexing branches for optimized searches, page 360 Baseline branch with indexing on for text-based searches Frozen mainline or baseline branch with indexing on for text-based searches Mainline branch that cannot load because a database error occurred or the branch is in an old format Upgrading old mainline branches, page

182 Creating branches Icon Indicates: More information Baseline, snapshot, or workspace branch that cannot load because a database error occurred Removed baseline branch Removed snapshot branch Only used in the Branch Maintenance dialog box. See Managing branch attributes, page 357. Removed workspace branch Creating branches Create a branch when you need to make changes to source files without affecting existing files. When you create a branch, you can: Copy a selected repository and all subrepositories from the parent branch to the new branch. For example, if the Design subrepository is selected in the WysiCorp Development repository, the root repository in the destination branch is WysiCorp Development/Design. Include or exclude specific repositories from the parent branch. For example, you can select multiple repositories to include from the parent branch and exclude subrepositories you do not need. The selected repositories are used as the template for the branch structure, which you can use when creating new branches later. See Using branch templates, page Select a branch and repository to create the new branch from. If you do not want to include or exclude specific repositories in the new branch, make sure the repository to use as the root repository in the new branch is selected. To include all repositories in the new branch, make sure the root repository in the parent branch is selected. 2. Choose Branch > Create Branch. 166

183 Creating branches The Create Branch dialog box opens. The read-only Parent branch field displays the mainline or parent branch name. The Repository field displays the path to the selected repository that will be used as the root repository in the new branch unless a template that includes multiple repositories at the same hierarchy level is used. 3. Select a Template option. To copy only the selected repository and all subrepositories from the parent branch to the new branch, select <None>. To use the same template as an existing branch, select it from the list or click Select to view the available templates. See Selecting branch templates, page 170. To select the specific repositories to include or exclude in the new branch, select <New template> and then click Modify to select the repositories. See Including and excluding repositories for new branches, page Enter the New branch name. Branch names cannot contain the following characters: \, /, *,? 5. Enter any Comments, such as the purpose of the new branch. 6. Select a Branch type. The list includes branch types you have security permissions to create. See About branches, page Select a Create branch based on option. Latest version creates a branch from the latest version of each file. Timestamp creates a branch based on the selected last check in timestamp. Label creates a branch based on the selected label. Labels are not copied to files in the new branch. Click Select to search for a label. See Selecting labels, page

184 Using branch templates Latest version in state creates a branch from the latest version of each file in the selected workflow state. If you are creating a branch based on timestamp, label, or the latest version in a state, select Include removed files to copy removed files from the parent branch to the new branch. For example, if you are creating a snapshot branch, you may want to include removed files to make sure you have a complete set of files. 8. Expand the Custom field options to set custom field options for files in the new branch. These options are not available for snapshot branches. Set custom fields to their default values sets the custom field values on files in the new branch to the default values defined on the Surround SCM Server. Copy custom field values from the parent branch copies the custom values set on files in the parent branch to files in the new branch. If you are creating a branch based on timestamp or label, files in the new branch use the custom field values set on the latest version of the files in the parent branch. Note: Custom field values and workflow states are always copied from the parent branch when you create a snapshot branch. 9. Click OK. The branch is created. Using branch templates You can use branch templates to select specific repositories to include or exclude on a baseline, workspace, or snapshot branch. For example, you can configure a template to select multiple repositories from the parent branch to include in the child branch and exclude subrepositories you do not need. When a template is configured for a new branch, the selected repository structure can be used for other branches created from the same parent branch later to include or exclude the same repositories. However, when a branch is created with a template, any changes made to the template for the specific branch later do not affect other branches that use the same repository structure. Repository structure for branches that use templates If a branch uses a template, the root repository for the branch depends on the repositories included in the template. If only one repository is included, it becomes the root repository in the branch. This is the same structure as branches that do not use templates. For example, if the Code subrepository is selected in the WysiCorp Development mainline branch, the root repository in the child branch is WysiCorp Development/Code. If multiple repositories at the same hierarchy level are included, a virtual root repository is created as a placeholder to show the path to the shared parent repository for all repositories included in the branch. For example, if the Code and Documentation subrepositories are included in the template for a branch created from the WysiCorp Development mainline branch, the repositories are added as subrepositories under the WysiCorp Development virtual root repository in the child branch. 168

185 Including and excluding repositories for new branches Note: indicates a virtual root repository in the branch. You can use this repository to perform recursive file actions, such as getting, checking out, or checking in all files, but you cannot add files or repositories to it. Applying templates to branches You can select specific repositories to include or exclude when creating new branches. You can also update the properties for existing branches to modify the repository structure. To select the specific repositories to include or exclude in a new branch, configure a new template when creating the branch. See Including and excluding repositories for new branches, page 169. To change the repositories included in an existing branch, update the template in the branch properties. See Modifying templates for existing branches, page 366. Including and excluding repositories for new branches You can specify the repositories to include and exclude for a new branch when creating it. For example, you may want to create a branch that includes multiple repositories from a mainline branch, but also exclude some subrepositories you do not need. The selected repository structure is the template for the new branch. You can use the same repository structure again to include and exclude repositories in new branches. Note: You can also select the template used by another branch created from the same parent branch when creating a branch. See Selecting branch templates, page Select <New template> in the Template field when creating a branch. 2. Click Modify. The Branch Template dialog box opens and displays the parent branch repository structure. 169

186 Selecting branch templates 3. Select the repositories to include in the branch template. 4. Select a subrepository and click Exclude to remove it from the template. To include an excluded subrepository in the template, select it and click Include. 5. Click OK. The selected repositories and included subrepositories are copied to the new branch when it is created. Excluded subrepositories are not copied to the new branch. Note: If you need to change the repositories included on the branch later, you can update the template in the branch properties. For example, you may need to include new repositories added to parent branch after the child branch was create to rebase files. See Modifying templates for existing branches, page 366. Selecting branch templates You can use the same template as an existing branch created from the same parent branch to include and exclude specific repositories. This eliminates the need to configure a template to include or exclude repositories in a new branch. For example, the WysiWrite 1.1 branch may include only the Code/WysiWrite and Documentation/Online Help/WysiWrite repositories and exclude subrepositories in the Code and Online Help repositories for other products. You can choose to use the template from the WysiWrite 1.1 branch when creating the branch for the WysiWrite 1.2 release because it already includes the required repositories. 1. Click Select in the Create Branch dialog box. The Select Branch Template dialog box opens. Branches that use a template from the selected parent branch and the included and excluded repositories are displayed. Note: If multiple branches include and exclude the same repositories, only the branch that most recently used the repository structure is displayed. 170

187 Selecting branch templates 2. Select the branch with the template to use for the new branch. 3. Click Select. The template is applied to the branch when it is created. 171

188

189 Merging Files Between Branches After you check in file changes, you may need to merge the changes to other branches to make them available to other users. You can merge files between branches by: Promoting changes from a child branch up to the parent branch. See Promoting branches, page 180 and Promoting files, page 185. Rebasing changes from a parent branch down to a child branch. See Rebasing branches, page 189 and Rebasing files, page 194. Duplicating a set of changes made in one branch and applying them to another branch in the same mainline branch. When you duplicate changes, you choose the changes between two versions to merge into another branch. See Duplicating selected changes across branches, page 198. Deciding between promoting, rebasing, and duplicating To determine if you should promote, rebase, or duplicate file changes, consider what changes you want to merge and the relationship of the branches you want to merge changes between. Promoting merges all changes in a branch to a parent branch. All changes made starting at version until a point you choose, such as a timestamp or state, are merged to a parent or ancestor branch. For example, you may want to promote changes when you have completed work on your workspace branch and you want to make the changes available in a mainline branch. See Promoting branches, page 180. Rebasing is the same as promoting except all changes are merged to a child branch. For example, as you work with files on your workspace branch, you may want to rebase changes from the mainline to ensure you have all the latest changes from other users. See Rebasing branches, page 189. Because promoting and rebasing merge all changes in a branch, you should use promote and rebase to synchronize two branches. If you only want to merge specific changes, you should duplicate the changes. Duplicating allows you to select a specific set of changes, such as changes associated with a changelist or issue, and merge them with any other branch on the same mainline branch. You can also select the file versions to use when duplicating changes, which allows you to specify the exact changes to merge. For example, you may want to duplicate the changes for a bug you fixed on your workspace branch to the baseline branch for an upcoming build without merging any unrelated changes. See Duplicating selected changes across branches, page 198. Viewing branch differences You can compare two branches to determine differences between repositories and files. For example, you fixed a bug on the WysiCalc 1.0.x branch. The fix also affects the developers working on version 2.0. You want to make this fix available to them, but first you want to see how the WysiCalc 1.0.x branch is different from the mainline branch. Tip: You can only diff branches that are in the same mainline branch and have at least one repository in common. 1. Select a branch or repository. If you select a repository, differences between the two branches are only displayed for the selected repository. 173

190 Viewing branch differences 2. Choose Branch > Branch Differences. The Branch Differences dialog box opens. 3. Select the branch you want to compare Branch 1 to from the Branch 2 list. You can also click Browse to select a branch. Expand the branch to view the child branches. 4. Select Recursive to display all repositories and files. 5. Click Show Differences. The Branch Differences dialog box opens. Branch 1 contents are displayed in the left pane and Branch 2 contents are displayed in the right pane. 174

191 Viewing branch differences The Differences column displays the reason for the difference. Column contains <Differences> Description The repository contains files that are different. Expand the repository to view specific differences. Color Gray Identical The file contents are the same. White (or default background color) Changed The file contents are different. Yellow Renamed The file was renamed in one branch. Green Moved The file was moved from one branch to another. Blue Removed The file was removed from one branch. Red Missing The file exists only in one branch. Red Excluded The file was excluded from one branch based on the template applied to it. Gray Note: If you do not have access to a repository in one of the branches, <restricted> is displayed instead of the repository and filenames. 6. Select any display options. Show identical files displays files with identical contents. Show missing files displays files missing from one branch but available in the other branch. If a file never existed in a branch, a filename is not displayed. If the file was removed from a branch, <removed> is displayed. Show moved files displays files moved from one branch to another. Show changed files displays files with different contents. Show renamed files displays files renamed in one branch but have a different name in the other branch. Show excluded files displays files excluded from one branch based on the template applied to it, but included in the other branch. 7. Select a file or repository and click the button for the action you want to perform. Button Use to: More information Differences Compare a changed file with the file in the other branch. You can only diff binary files if a diff application is configured for the file extension. Viewing file differences, page 39 and Setting diff/merge options, page

192 Copying files across branches during check in Button Use to: More information Diff Report Generate a branch differences report. Running branch differences reports, page 177 View View a read-only copy of the file. Viewing files in Surround SCM, page 17 History View the file or repository history. Commands such as Edit File, Check Out File, and Rollback File are not available in the History dialog box because they can change the file version. Viewing file history, page 76 and Viewing repository history, page 119 Properties View the file or repository properties. Viewing general file information, page 80 and Viewing general repository information, page 120 Remove Remove a missing file or repository from a branch. Removing files, page 35 and Removing repositories, page 112 Restore Restore a removed file or repository in the branch. Restoring removed files, page 36 and Restoring repositories, page 113 Rename Promote Rebase Rename a file or repository to use the name in the other branch. Update a file in the ancestor branch with changes from the child branch. Update a file in the child branch with changes from the ancestor branch. Renaming files, page 35 and Renaming repositories, page 109 Promoting files, page 185 Rebasing files, page 194 Merge Merge a changed file with the file in the other branch. Merging files, page 40 Copy Copy a changed file to the other branch. Copying files across branches during check in, page Click Close when you finish. Copying files across branches during check in When you view branch differences, you can copy a file from one branch to another. See Viewing branch differences, page Select a changed file and click Copy. The Copy Check In dialog box opens. 176

193 Running branch differences reports 2. Enter any Comments, such as the reason for copying the file. 3. Click Attach to attach the file to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page Click OK. You return to the Branch Differences dialog box. The file is copied to the branch. If the file exists in the destination branch, it is checked in as the current version. The copied file overwrites the existing file. It is not merged with the existing file. If the file does not exist in the destination branch, it is added and checked in as the current version. If a file s parent repository does not exist in the destination branch, it is automatically added when the file is copied. Only the file contents are copied to the destination branch, not the file history. Note: When you copy a file, it is merged into the file in your working directory. You can check in the file immediately or at another time after resolving any merge conflicts. Running branch differences reports Branch differences reports include file differences between two related branches. You can run these reports when comparing branches. See Viewing branch differences, page Select a branch or repository. 2. Choose Branch > Branch Differences. The Branch Differences dialog box opens. 177

194 Running branch differences reports 3. Select the branch to compare the selected branch (Branch 1) with from the Branch 2 list. You can also click Browse to select a branch. 4. Select Recursive to include all subrepositories and files. 5. Click Show Differences. The Branch Differences dialog box opens. 6. Select a repository or two or more files and click Diff Report. The Generate Branch Differences Report dialog box opens. 178

195 Running branch differences reports 7. Select any additional report Options. Ignore case differences in file contents excludes differences in character case. Ignore whitespace excludes any whitespace differences (spaces and tabs). Ignore changes in the amount of whitespace excludes additions or deletions to existing whitespace (spaces and tabs). Ignore blank lines excludes inserted or deleted blank lines. Limit number of differences to maximum of limits the number of differences included in the report to the specified number. 8. Select an Output Format. When you view differences, you may also want to see the parts of the files near the lines that differ to help you understand what changed. This is the context. If you are distributing new versions of files in the form of diff output, use one of the output formats that show context so users can easily apply the differences. Enter the number of Output lines of context to display before and after each change. The default is 3 lines. Select Unified format to display the differences with limited context lines. This format excludes redundant context lines. Select Context format to display the differences with context lines. This format shows several lines of context around the lines that differ. It is the standard format for distributing updates to source code. 9. Click OK. The report opens. For information about report symbols, see Running file differences reports, page Click Save As to save the report or Print to print it. 11. Click Close when you finish. 179

196 Promoting branches Promoting branches Promoting is the process of updating an ancestor branch with changes made in a related branch. Promoting merges changes from the child branch up to the parent branch. Promote the branch when you finish making changes to source files and are ready to share your changes. This ensures the ancestor branch includes the most current files and other users have access to your changes. For example, Michelle works in her workspace branch. She finishes developing the new features assigned to her and completes informal testing. She knows Jack, the QA manager, wants to start formal testing, so she promotes her branch. Jack then rebases her changes into the QA Build branch and starts testing. You can promote changes to any ancestor branch. For example, Pat finishes making bug fixes in the Version 1.5 branch. This branch was created from Version 1, but he does not want to promote changes to Version 1. Instead, Pat promotes to WysiApp, which is the parent branch for Version 1 and the grandparent branch for Version 1.5. When the team starts development on Version 2, the branch is created from WysiApp. This ensures Pat s Version 1.5 bug fixes are included in the Version 2 code. Note: Custom field values and workflow states set on files in the ancestor branch do not change when promoting. Files added to the ancestor branch when promoting are set to the default custom field value and workflow state defined on the Surround SCM Server. 1. Select the branch you want to promote and choose Branch > Promote Branch. The Promote Branch dialog box opens. 2. Select an Ancestor to promote to branch. You can promote changes to any ancestor branch. 3. Enter any Comments, such as the reason for promoting the branch. 4. Select a Promote files based on option. Latest version promotes the latest version of each file. Timestamp promotes changes from the specified timestamp. 180

197 Promoting branches Label promotes changes from the selected label. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels on files in the parent branch are not copied to the child branch. Latest version in state promotes changes from the latest version of each file in the selected workflow state. Snapshot promotes changes from the selected snapshot branch. 5. Select Skip server auto-merge to promote all files and overwrite the ancestor branch files. 6. Click Preview. The Promote Preview dialog box opens. Files that will be promoted, files that will not be promoted, and files with conflicts are displayed. You can perform actions to resolve conflicts based on the file status and your security permissions. See Promote preview, page Select Label promoted files in destination to label the files in the ancestor branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels are only added to files that are successfully promoted, force promoted, or merged locally. Files that are removed, renamed, or in broken shares are not labeled. Any promote comments you entered are also added to the label history. 8. Select a file and click Promote File to promote it or click Promote All to promote all files. 181

198 Promote preview The Promote Status dialog box opens. You can perform many of the same actions available in the Promote Preview dialog box. Promote preview You can view file status, files that will or will not be promoted, and files with conflicts. The actions you can perform depend on the file status and your security permissions. 1. Click Preview on the Promote Branch or Promote Files dialog box. The Promote Preview dialog box opens. 182

199 Promote preview 2. Select a file and click a button to perform an action. Button Action More information Differences Compare the file versions in the specified From branch and To branch file. Viewing file differences, page 39 History View the file history. Viewing file history, page 76 Properties Attach Add to Code Review View the file properties. Attach the file to an item in TestTrack or an external issue tracking tool. You can only attach successfully promoted files that changed the version number on the destination branch. Files removed, renamed, or in broken shares cannot be attached. Add the file to a code review. You can only add successfully promoted files that changed the version on the destination branch. Files removed, renamed, or in broken shares cannot be added to reviews. Attaching source files to TestTrack items, page 255 and Attaching source files to external issues, page 268 Adding files to code reviews, page

200 Promote actions Button Action More information Promote File Promote the file. You can view files that were promoted or were not promoted, and files with conflicts. You can also perform actions to resolve conflicts and promote files. Promoting files, page 185 Merge Locally Manually merge the files. Merging files, page 40 Remove Parent Break Share Force Promotion Remove the file from the parent branch. If you promote a file that was removed from the child branch, you may need to remove it from the parent branch. Unshare a file. Promote the file and overwrite the parent branch file. Removing files, page 35 Breaking shares, page Select Label promoted files in destination to label files in the ancestor branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels are only added to files that are successfully promoted, force promoted, or merged locally. Files removed, renamed, or in broken shares are not labeled. Any promote comments you entered are also added to the label history. 4. Click Promote All to promote all files. The Promote Status dialog box opens. You can view files that were promoted, files that were not promoted, and files with conflicts. You can also resolve file conflicts. 5. Click Save As to save the results list or click Print to print it. 6. Click Close when you finish. Promote actions Following are promote actions and corresponding reasons. 184

201 Promoting files Action Will promote/promoted Will not promote/could not promote User action required None Reason New file New repository New file because target removed New repository because target removed Modified file Modified file (renamed) Modified file (moved) Modified file (moved and renamed) Modified requiring merge Modified requiring merge (renamed) Modified requiring merge (moved) Modified requiring merge (moved and renamed) Moved Renamed Moved and renamed Will remove/removed Share conflicts with removed file File checked out Binary files are different Binary files are different (renamed) Binary files are different (moved) Binary files are different (moved and renamed) Name conflicts with existing file or repository Unable to determine common ancestor for merge Denied by trigger Auto-merge conflict Auto-merge conflict (renamed) Auto-merge conflict (moved) Auto-merge conflict (moved and renamed) File checked out Will not remove/did not remove Will not remove (renamed)/did not remove (renamed) Child share broken Parent share broken Broke parent share Broke child share Security settings do not allow this action New file because target removed New repository because target removed Promoting files Files can be promoted without affecting other items in the branch. When you finish making changes, promote changes back to the parent branch. See Promoting branches, page Select the files you want to promote and choose Branch > Promote File. 185

202 Promoting files The Promote Files dialog box opens. 2. Select an Ancestor to promote to. You can promote changes to any ancestor branch. 3. Enter any Comments, such as the reason for promoting the files. 4. Select a Promote files based on option. Latest version promotes the latest version of each file. Timestamp promotes changes from the specified timestamp. Label promotes changes from the selected label. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels on files in the parent branch are not copied to the child branch. Latest version in state promotes changes from the latest version of each file in the selected workflow state. Snapshot promotes changes from the selected snapshot branch. 5. Select Skip server auto-merge to promote changes and overwrite changes in the parent branch. 6. Select Recursive to promote the file to the selected repository and all subrepositories. 7. Click Preview. The Promote Preview dialog box opens. Files that will be promoted, files that will not be promoted, and files with conflicts are displayed. You can resolve conflicts based on the file status and your security permissions. See Promote preview, page

203 Promoting files 8. Select a file and click Attach to attach it to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 255 or Attaching source files to external issues, page 268. You can only attach files that were successfully promoted and changed the version number on the destination branch. Files removed, renamed, or in broken shares cannot be attached. 9. Select Label promoted files in destination to label the files in the ancestor branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels are only added to files that are promoted successfully, force promoted, or merged locally. Files removed, renamed, or in broken shares are not labeled. Any promote comments you entered are also added to the label history. 10. Select a file and click Promote File to promote it or click Promote All to promote all files. The Promote Status dialog box opens. You can perform many of the same actions available in the Promote Preview dialog box. 187

204 Rolling back promoted files Rolling back promoted files You can undo a promote by rolling back promoted files. For example, if feature changes promoted to a branch cause problems and there no time to troubleshoot the feature, you can roll back the promoted files. 1. Select the branch that was promoted to and choose Branch > Rollback Promote. The Rollback Promote dialog box opens. 2. Select the branch you want to rollback changes from. 3. Enter any Comments, such as the reason for rolling back the changes. 4. Click Preview. The Rollback Promote dialog box opens. This dialog box includes a list of all files promoted to the selected branch. 188

205 Rebasing branches 5. Select a file and click a button to perform an action. Button Use to: More information Differences Compare file versions. Viewing file differences, page 39 History View file history. Viewing file history, page 76 Properties View file properties. Viewing general file information, page 80 Rollback Rollback the selected file. Rolling back files, page 27 Merge Locally Force Remove Manually merge the files. Merging files, page 40 Remove the file from the rollback list. 6. Click Save As to save the rollback results list or click Print to print the list. 7. Click Rollback All to rollback all the files. 8. Click Close when you finish. Rebasing branches Rebasing detects and merges changes from the parent branch down to the child branch. This ensures the child branch includes the most current files. For example, Cathy and Jon work on bug fixes in their workspace branches. Jon completes his work and promotes changes to the parent branch. Cathy needs his changes to fix a bug. She rebases from the parent branch to merge Jon s changes into her workspace branch. Rebasing only applies new changes to branches. It does not copy file contents from branch to branch. An internal flag tracks the file version that was last rebased from. If a version in the parent branch is flagged because it was already rebased to the child branch, the file cannot be rebased until the version changes in the branch it was rebased from. It does not matter if the file contents are different. See No Files to Rebase in Surround SCM for information. Note: Custom field values and workflow states set on files in the child branch do not change when rebasing. Files added to the child branch when rebasing are set to the default custom field value and workflow state defined on the Surround SCM Server. 1. Select the branch you want to rebase changes to and choose Branch > Rebase Branch. The Rebase Branch dialog box opens. 189

206 Rebasing branches 2. Enter any Comments, such as the reason for rebasing the branch. 3. Select a Rebase branch based on option. Latest version rebases from the latest version of each file. Timestamp rebases from the specified timestamp. Label rebases from the selected label. Click Select to view label details or search for a label. See Selecting labels, page 147. Latest version in state rebases from the latest version of each file in the selected workflow state. Snapshot rebases from the selected snapshot branch. Note: Labels on files in the parent branch are not copied to the child branch. 4. Select Skip server auto-merge to rebase all files and overwrite any changes in the current branch. 5. Click Preview. The Rebase Preview dialog box opens. Files that will be rebased, files that will not be rebased, and files with conflicts are displayed. You can resolve conflicts based on the file status and your security permissions. See Rebase preview, page

207 Rebasing branches 6. Select a file and click Rebase File to rebase it or click Rebase All to rebase all files. The Rebase Status dialog box opens. You can perform many of the same actions available in the Rebase Preview dialog box. 191

208 Rebase preview Rebase preview You can view file status, files that will or will not be rebased, and files with conflicts. The actions you can perform depend on the file status and your security permissions. 1. Click Preview on the Rebase Branch or Rebase Files dialog box. The Rebase Preview dialog box opens. 2. Select a file and click a button to perform an action. Button Action More Information Differences Compare the branch file versions. Viewing file differences, page 39 History View the file history. Viewing file history, page 76 Properties View the file properties. Viewing general file information, page

209 Rebase actions Button Action More Information Attach Add to Code Review Rebase File Attach the file to an item in TestTrack or an external issue tracking tool. You can only attach files that were already successfully rebased and changed the version number on the destination branch. Files removed, renamed, or in broken shares cannot be attached. Add the file to a code review. Rebase the file. Attaching source files to TestTrack items, page 255 and Attaching source files to external issues, page 268 Adding files to code reviews, page 55 Rebasing files, page 194 Merge Locally Manually merge the files. Merging files, page 40 Break Share Force Rebase Unshare the files. Rebase the file and overwrite the child branch file. Breaking shares, page Select Label rebased files in destination to label files in the parent branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels are only added to files that are successfully rebased or merged locally. Files removed, renamed, or in broken shares are not labeled. Any rebase comments you entered are also added to the label history. 4. Click Rebase All to rebase all files. The Rebase Status dialog box opens. You can view files that were or were not rebased and files with conflicts. You can also access actions to resolve file conflicts. 5. Click Save As to save the results list or click Print to print it. 6. Click Close when you finish. Rebase actions Following are rebase actions and corresponding reasons. 193

210 Rebasing files Action Will rebase/rebased Will not rebase/could not rebase User action required None Reason New file New repository Modified file Modified file (renamed) Modified file (moved) Modified file (moved and renamed) Modified file requiring merge Modified file requiring merge (renamed) Modified file requiring merge (moved) Modified file requiring merge (moved and renamed) Moved Renamed Moved and renamed Will remove/removed Share conflicts with removed file File checked out Binary files are different Name conflicts with existing file or repository Unable to determine common ancestor for merge Invalid ancestor for merge Base file for share not found Denied by trigger Auto-merge conflict Auto-merge conflict (renamed) Auto-merge conflict (moved) Auto-merge conflict (moved and renamed) New file because target removed New repository because target removed Child share broken Parent share broken Broke parent share Broke child share Security settings do not allow this action New file because target removed Rebasing files Rebase files when you need to make sure you have the most recent copy of the files including changes made by other users. See Rebasing branches, page 189. Rebasing only applies new changes to branches. It does not copy file contents from branch to branch. An internal flag tracks the file version that was last rebased from. If a file version in the parent branch is flagged because it was already rebased to the child branch, the file cannot be rebased until the files version changes in the branch it was rebased from. It does not matter if the file contents are different. See No Files to Rebase in Surround SCM for information. 194

211 Rebasing files 1. Select the files you want to rebase and choose Branch > Rebase Files. The Rebase Files dialog box opens. 2. Enter any Comments, such as the reason for rebasing the files. 3. Select a Rebase files based on option. Latest version rebases the latest version of each file. Timestamp rebases changes from the specific timestamp. Label rebases changes from the selected label. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels on files in the parent branch are not copied to the child branch. Latest version in state rebases changes from the latest version of each file in the selected workflow state. Snapshot rebases changes from the selected snapshot branch. 4. Select Skip server auto-merge to rebase all changes and overwrite any changes in the child branch. 5. Select Recursive to rebase the file to the selected repository and all subrepositories. 6. Click Preview. The Rebase Preview dialog box opens. Files that will be rebased, files that will not be rebased, and files with conflicts are displayed. You can resolve conflicts based on the file status and your security permissions. See Rebase preview, page

212 Rebasing files 7. Select a file and click Rebase File to rebase it or click Rebase All to rebase all files. The Rebase Status dialog box opens. You can perform many of the same actions available in the Rebase Preview dialog box. 196

213 Rolling back rebased files Rolling back rebased files You can undo a rebase by rolling back rebased files. The version number increments even though the contents are the same as a previous version. For example, if you rebase changes to your workspace branch and then discover there is a conflict with a new feature, you can rollback the rebased files. Note: By default, the workflow state of the new file version is the same as the most recent version. If the Rollback state with file rollback option is selected for the workflow template, the new version is in the same state as the version rolled back to. 1. Select the branch that was rebased to and choose Branch > Rollback Rebase. The Rollback Rebase dialog box opens. 2. Enter any Comments, such as the reason for rolling back the files. 3. Click Preview. The Rollback Rebase dialog box opens. A list of all files that were rebased to the selected branch is displayed. 4. Select a file and click a button to perform an action. Button Use to: More information Differences Compare file versions. Viewing file differences, page 39 History View file history. Viewing file history, page 76 Properties View file properties. Viewing general file information, page 80 Rollback Rollback the selected file. Rolling back files, page 27 Merge Locally Force Remove Manually merge the files. Merging files, page 40 Remove the file from the rollback list. 197

214 Duplicating selected changes across branches 5. Click Save As to save the rollback results list or click Print to print the list. 6. Click Rollback All to rollback all the files. 7. Click Close when you finish. Duplicating selected changes across branches Duplicate changes to choose a set of changes made in one branch and apply them to another branch. You can select specific files with changes to duplicate or you can duplicate changes based on a changelist, issue, or label. Specific changes can be duplicated to any branch in the same branch tree without promoting changes to a common parent first. For example, Steve makes a change in his workspace branch that fixes an issue related to two different products. He can duplicate the changes in files attached to the issue to each product's baseline branch without merging all other changes he made in his workspace branch. After duplicating, he can track the changes to make sure the changes are included in all branches that contain files attached to the related issue. Note: Only changes that affect the file version, such as changes to file contents or file addition and removal, can be duplicated. 1. To duplicate changes associated with specific files, select the files and choose Branch > Duplicate Changes. To duplicate changes associated with a changelist, issue, or label, choose Branch > Duplicate Changes. The Duplicate Changes dialog box opens. 2. Select the branch that contains the changes in the From Branch list. If you selected files before opening the Duplicate Changes dialog box, the branch containing the files is already selected. 3. Select the To Branch to duplicate the changes to. 4. Select a Select files and versions by option. If you selected files with changes before opening the Duplicate Changes dialog box, <Selected files> is selected and the files are displayed. Changelist duplicates changes associated with the selected changelist. Click Select to search for a changelist or view changelist details. See Selecting changelists, page 139. Issue duplicates changes associated with files attached to the selected TestTrack issue. Click Select to search for an issue or view issue details. See Selecting TestTrack items, page

215 Duplicating selected changes across branches Label duplicates changes associated with the selected label. Click Select to search for a label or view label details. See Selecting labels, page Select a file and click in the Differences between versions column to select different historical file versions to duplicate changes from. If multiple actions incremented the file version number, you can change the file versions to duplicate from to ensure that all changes are duplicated and to avoid automerge conflicts. The History dialog box opens. Ctrl+click two file versions and click Select Versions. 6. Click Track Changes to view the branches that include the selected changes. The Track Changes dialog box opens. You can view changes in branches by changelist, issue, or label. See Tracking duplicated changes, page Click Preview. The Duplicate Changes Preview dialog box opens. Files that will be duplicated, files that will not be duplicated, reasons for duplicating, and the file versions that will be used to duplicate changes are displayed. See Duplicate changes preview, page Select Label changed files in destination to label the files in the destination branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page 147. Labels are only added to files that are successfully duplicated, force overwritten, or merged locally. Any duplicate comments you entered are also added to the label history. 9. Select a file and click Duplicate Changes to duplicate it or click Duplicate All to duplicate all files. The Duplicate Changes Status dialog box opens. You can perform many of the same actions available in the Duplicate Changes Preview dialog box. 10. Click Close when you finish. 199

216 Duplicate changes preview Duplicate changes preview You can view file status, files with changes that will or will not be duplicated and the reason, and the file versions that will be used before duplicating changes. The actions you can perform depend on the file status and your security permissions. 1. Click Preview on the Duplicate Changes dialog box. The Duplicate Changes Preview dialog box opens. 2. Select a file and click a button to perform an action. Button Use to: More information Differences Compare the From and To branch file versions. Viewing file differences, page 39 History View file history. Viewing file history, page 76 Properties View file properties. Viewing general file information, page 80 Duplicate Changes Duplicate file changes to the destination branch. Duplicating selected changes across branches, page 198 Merge Locally Force Overwrite Manually merge the files. Merging files, page 40 Duplicate the file changes and overwrite the file in the destination branch. 3. Select Label changed files in destination to label files in the destination branch. Select a label or select <New label> to create a new label. See Creating labels, page 143. Click Select to view label details or search for a label. See Selecting labels, page Click Duplicate All to duplicate all file changes. 200

217 Duplicate changes actions The Duplicate Changes Status dialog box opens. You can view files with duplicate actions and reasons. See Duplicate changes actions, page Click Save As to save the results list or click Print to print it. 6. Click Close when you finish. Duplicate changes actions Following are the duplicate changes actions and corresponding reasons. Action Will duplicate / Duplicated Will not duplicate / Could not duplicate User action required None Reason New file Removed file Modified file Binary files are different Destination file does not exist Changes already applied in branch Auto-merge conflict Changes already applied in branch Tracking duplicated changes You can view which branches contain changes associated with changelists, issues, labels, or selected files to track where the changes were duplicated. For example, you may want to make sure all the changes you made to the labeled files in your workspace branch are duplicated to the mainline branch. Files that include changes list the version number where the change is included. Note: Only file changes promoted, rebased, or duplicated in Surround SCM 2011 or later can be tracked. 1. To track changes associated with specific files, select the files and choose Tools > Track Changes. To track changes associated with a changelist, issue, or label, choose Tools > Track Changes. The Track Changes dialog box opens. 201

218 Tracking duplicated changes 2. Select a Branch. 3. Select a Track changes for option. If you selected files with changes before opening the Track Changes dialog box, <Selected files> is selected and the files are displayed. Changelist tracks changes associated with the specified changelist. Click Select to search for a changelist or view changelist details. See Selecting changelists, page 139. Issue tracks changes associated with files attached to the specified TestTrack issue. Click Select to search for an issue or view issue details. See Selecting TestTrack items, page 263. Label tracks changes associated with the specified label. Click Select to search for a label or view label details. See Selecting labels, page Click Save As to save the results list or click Print to print it. 5. Click Close when you finish. 202

219 Viewing Branch Information Surround SCM stores historical information about branches that you can review to understand when and why a branch was created, when it was last modified, and the actions performed on the branch. See Viewing branch history, page 203. You can also view the graphical branch tree to view the entire branch structure and understand the relationship between other related branches and the mainline branch. See Viewing the graphical branch tree, page 205. Viewing branch history 1. Select the branch and choose Activities > Properties. 2. Click the History tab. 3. Select a Filter by user or Filter by action option to narrow the list of actions. 4. Select an action and click Details to view additional history information. See Viewing branch history details, page 203. Viewing branch history details When you view branch properties, you can also view additional historical information about the branch. 1. Select the branch and choose Activities > Properties. 2. Click the History tab. 3. Select a Filter by user or Filter by action to narrow the list of actions. 4. Select an action and click Details. The read-only History Details dialog box opens. 203

220 Viewing general branch information 5. Click Close to return to the Properties dialog box. Viewing general branch information You can view general information about a branch, such as its attributes and when and how it was created. You may also be able to modify branch attributes and comments. Note: The available fields and information depend on the branch type. 1. Select the branch and choose Activities > Properties. The Properties dialog box opens. 2. On the General tab, select any branch Attributes. See Managing branch attributes, page

221 Viewing the graphical branch tree 3. Select Allow case-sensitive file and repository names to use case-sensitive names for all repositories and files in the selected mainline branch. Only select this option if all users access the mainline branch using the Surround SCM Client on Linux. You are prompted to confirm that you want to use case-sensitive file and repository names. Note: Enabling this option may cause problems if users access the mainline branch using the Windows or Mac Surround SCM Client. For example, Linux recognizes TEST.TXT and Test.txt as different files. Windows and Mac recognize these as the same file and do not allow the files to be saved in the same directory. When users get the files to a working directory, only one of the files can be retrieved. 4. Enter any Comments about the branch. You may not have access to set branch attributes or enter comments depending on your security permissions. 5. Click OK to close the Properties dialog box. Viewing the graphical branch tree The graphical branch tree provides a visual representation of the relationship between branches in a mainline. 1. Select a branch and choose Branch > Graphical Branch Tree. The Graphical Branch Tree window opens. 205

222 Viewing the graphical branch tree 2. Select the Branches you want to display. Each branch is displayed as a node. Click and drag the zoom slider to zoom in and out. Click a node to view branch details in the Details pane. Click and drag the outlined box in the Navigator to view a specific area in the branch tree. 3. To view differences between branches, Ctrl+click two branch nodes, right-click, and choose Branch Differences. See Viewing branch differences, page Click Save As to save the graph or Print to print it. 206

223 Finding Files Surround SCM makes it easy to find the files you need to work with. You can search for files by name, field values, or other data, and search for text in file contents. You can also use filters to save and apply search criteria you frequently use, use addresses to go directly to files and repositories, and bookmark the files, repositories, or branches you use most often. Searching You can search for files based on a variety of criteria, such as filename, version number, and file type. See Searching for files, page 207. You can also search for specific phrases or text in file contents. See Searching for text in files, page 219. Filtering If you or other team members frequently search for files using the same criteria, create a filter to save the search. For example, you may want to create a private filter to view all files in the Awaiting Review workflow state so they can be added to a code review. See Adding filters, page 225. Filters are used to narrow the files displayed in the source file list. You can use private filters you create or public filters other users created. See Applying filters to the source file list, page 227. Going directly to a file or repository You can click or copy and paste an address from a notification to go directly to repositories and files. See Browsing to files and repositories, page 228. Bookmarking You can bookmark files, repositories, and branches you use most often to quickly access them from the Bookmarks menu. See Bookmarking files, repositories, and branches, page 229. Searching for files You can search for files based on a variety of criteria, such as filename, version number, and file type. You can use any combination of the available criteria to perform more complex searches. To search for text in files, see Searching for text in files, page 219. Tip: Use the Filename Search field above the source file list to quickly search for files by name. Filename searches are not case sensitive and cannot include wildcard characters. 1. Choose Edit > Advanced Find Files. The Advanced Find dialog box opens. 207

224 Searching for files 2. Select a Restriction to set the criteria files must meet. The Restriction dialog box opens. The options change based on the selected restriction. 3. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the Restrictions list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 5. Add any additional restrictions. 6. Select Search recursively to search the selected repository and any subrepositories. 7. Click Find to search the files. Files that meet the criteria are displayed. The Find files results filter is applied. Tip: Create a filter or report if you frequently use the same criteria to perform a search. Filters allow you to save search criteria and apply it to the source file list. Reports allow you to save search criteria and set output options so you can analyze the data. See Applying filters to the source file list, page 227 and Creating reports, page

225 Adding restrictions Adding restrictions Restrictions are criteria that files must meet to be included in filter results, advanced find results, and reports. You can combine multiple restrictions to perform more complex searches. For example, you can create a restriction to find files checked in to a specific repository in the past week by a specific user. Surround SCM includes the following restriction types. Restriction type Text Number Date Multiple list selection Condition Limits results to files with: Text that does or does not match text or a regular expression. See Adding text restrictions, page 209. Numbers that do or do not match a number or number in a range. See Adding number restrictions, page 212. Dates that do or do not match a date, date range, or time period. See Adding date restrictions, page 212. Values that do or do not match selected values. See Adding multiple list selection restrictions, page 213. Attributes that do or do not match a condition. See Adding condition restrictions, page 214. Event File events that do or do not match events. See Adding event restrictions, page 214. Label TestTrack item number Security group Branch/repository Actions based on user and date Labels that do or do not match text or a regular expression. See Adding label restrictions, page 215. TestTrack items that do or do not match a number or number in a range or list. See Adding TestTrack item number restrictions, page 216. Events performed by users in a security group. See Adding security group restrictions, page 216. Locations in a repository for a specific branch or across all branches. See Adding branch and repository restrictions, page 217. File actions performed by users on a date or in a date range. See Adding action restrictions based on user and date, page 217. Note: Triggers and notifications include preconditions, which are similar to restrictions. If a file meets the criteria in a precondition, triggers are fired or notifications are sent. See Setting Up Notifications, page 83 and Configuring triggers, page 322. Adding text restrictions Text restrictions limit results to files that do or do not include a specific text string or regular expression. These restrictions are used to locate files based on filename, check out location, check out computer, file label, and other text-based data. For example, you can create a restriction to find files checked out to C:\Design. 209

226 Using regular expressions 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select does or does not to indicate if the files include matching text. 3. Select a matching option. Match includes files with text that matches the specified text string. Match regular expression includes files with text that matches the specified regular expression. 4. Enter the value or regular expression. Surround SCM supports Perl-style regular expressions. See Using regular expressions, page 210. Tip: You can use wildcards in the search value, even if the match regular expression option is not selected. Use an asterisk (*) to search for zero or more occurrences of the previous character. Use a question mark (?) to search for zero or one occurrences of the previous character. For example, in a filename restriction, *.cpp finds all files with a.cpp extension. 5. If you entered text, select Match case to match the case of the text. 6. Click OK to add the restriction. Using regular expressions You can use regular expressions in text-based restrictions to search for files. For example, you can use a regular expression in the filename restriction to locate files based on one or more file extensions. Surround SCM supports Perl-style regular expressions. The following list includes regular expression characters commonly used to match text patterns in Surround SCM. To match: Use: Example Any single character. ab. matches ab followed by any character, such as abc or ab_ Zero or one occurrences of the previous character Zero or more occurrences of the previous character One or more occurrences of the previous character? colou?r matches color or colour * a.* matches a followed by any number of characters, such as ab, abb, aab, or aabb + ba+ matches b followed by any number of occurrences or a, such as ba, baa, or baaa 210

227 Using regular expressions To match: Use: Example A specified number of occurrences of the previous character Any single character included in a set of characters {...} ba{3} matches baaa baa{3,} matches b followed by three or more occurrences of a, such as baaa, baaaa, or baaaaa [...] [abc] matches a, b, or c Any single character not included in a set of characters [^...] [^abc] matches any character except a, b, or c Any single character in a specified range Any single whitespace character (space, tab, new line) [ - ] [a-z] matches any lowercase character [0-9] matches any digit, 0-9 \s v\s matches v followed by a whitespace character Any single non-whitespace character \S v\s matches v, not followed by a whitespace character Any single digit (same as [0-9]) \d v\d matches v followed by a single digit, such as v1 Any single non-digit (same as [^0-9]) \D v\d matches v that are not followed by a digit, such as v_ The following symbols are also helpful for creating regular expressions. To: Use: Example Separate two or more alternatives to perform an OR search (gray grey) matches gray or gray Group several items as a single unit (...) (file ) matches file1, file2, file3, or file4 Escape special characters for literal interpretation (modify the meaning of the following character) \ file\.txt matches occurrences of file.txt Examples You want to send an notification when files with the.c or.h extension are checked in to a specific branch. Use the following regular expression in the filename restriction to indicate that the trigger applies to all files with a.c or.h extension: (.*\.c) (.*\.h) You want to find all files that contain the string log with a.doc or.xls extension. Use the following regular expression in the filename restriction:.*log.*\.(doc xls) You want to find all files that start with the string log and include a number. Use the following regular expression in the filename restriction: log.*\d.* You want to find all published web files with spaces to rename them and remove the spaces. Use the following regular expression in the filename restriction:.*\s.* 211

228 Adding number restrictions You want to find all files with 129 or more characters and rename them. Use the following regular expression in the filename restriction:.{129,} Adding number restrictions Number restrictions limit results to files that do or do not include a specific number or number in a range. This restriction is used to locate files based on version, size, integer custom field values, float custom field values, and other number-based data. For example, you can create a restriction to find all version 2 files. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select is or is not to indicate if the files include the specified number or a number in the specified range. 3. Select an option to specify the numbers to include. Equal to only includes numbers equal to the specified number. Less than only includes numbers less than the specified number. Greater than only includes numbers greater than the specified number. Between only includes numbers in a specified range. 4. Enter the number or range. 5. Click OK to add the restriction. Adding date restrictions Date restrictions limit results to files that include a specific date or date in a time period. This restriction is used to find files based on last modified date, last check in date, time/date, and other date/time-based data. For example, you can create a restriction to find all files modified in the last two weeks. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select is or is not to indicate if the files include the specified date or time period. 212

229 Adding multiple list selection restrictions Note: If the restriction is for a date/time custom field, select is not set to include files with date/time custom fields that are not set to a value. 3. Select the time period to search. Equal to, before, after, or between includes files relative to the specified date or time period. A specific time period includes files from the selected period, such as last week or last year. In the last or next includes files for a specified number of hours, days, weeks, months, or years relative to the current date/time. 4. Click OK to add the restriction. Adding multiple list selection restrictions Multiple list restrictions limit results to files that do or do not include all or selected values in a list. This restriction is used to locate files based on checked out by user, status, workflow state, file type, list custom field values, Surround SCM user custom field values, and other values. For example, you can create a restriction to find all files with a modified status. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select is in list or is not in list to indicate if the files include the selected users. 3. Select an option to indicate the values to include. If you are adding a user restriction, Current user includes files for the logged in user. All includes files with one or more values in the list. Selected includes files with one or more selected list values. Note: Click Select All to select all values or click Select None to clear any selected values. 213

230 Adding condition restrictions 4. Click OK to add the restriction. Adding condition restrictions Condition restrictions limit results to files with check box custom fields that are selected or cleared, or files that are shared or not shared. For example, you can create a restriction to find all shared files. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select is or is not to indicate the condition to search for. For example, if you are creating a restriction on a check box custom field, select is checked to include files with the check box field selected. 3. Click OK to add the restriction. Adding event restrictions Event restrictions limit results to files with all or selected file events performed on them, such as check in. You can also search event comments to perform a more specific search. For example, you can create a restriction to find all promoted files that include login changes in the event comment. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 214

231 Adding label restrictions 2. Select is in list or is not in list to indicate if the files include the selected events. 3. Select an option to indicate the events to search for. All events includes files with one or more events in the list. Selected events only includes files with one or more selected events. Note: Click Select All to select all values or click Select None to clear any selected values. 4. Select Search comments and enter text or a regular expression to include files with matching event comments. Surround SCM supports Perl-style regular expressions. See Using regular expressions, page 210. Does or does not indicates if the files include matching text. Match searches using the specified text string. Match regular expression searches using the specified regular expression. If you entered text, select Match case to match the case of the text. 5. Click OK to add the restriction. Adding label restrictions Label restrictions limit results to files with labels that do or do not include a label that matches text or a regular expression. For example, you can create a restriction to find all files with the WysiWrite Build 3 label. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select does or does not to indicate if the files include matching text. 3. Select a matching option. Match includes labels that match the specified text string. Match regular expression includes labels that match the specified regular expression. 4. Enter the text or regular expression. To select the label from a list, click Browse. Select a mainline branch, select the label, and click OK to add the label to the restriction. Note: Surround SCM supports Perl-style regular expressions. See Using regular expressions, page If you entered text, select Match case to match the case of the text. 6. Click OK to add the restriction. 215

232 Adding TestTrack item number restrictions Adding TestTrack item number restrictions TestTrack item number restrictions limit results to files attached to TestTrack issues, requirements, and test cases in a specific project that are equal to, less than, or greater than a specified number or in a range or list of numbers. For example, you can create a restriction to find all files attached to issues numbered in a project. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select the TestTrack Connection that corresponds to the project you want to search. 3. Select is or is not to indicate if the files are attached to items with the specified number or number in the specified range or list. 4. Select an option to specify the numbers to include. Equal to only includes items equal to the specified number. Less than only includes items less than the specified number. Greater than only includes items greater than the specified number. Between only includes items within the specified range. In list only includes items in the specified list. 5. Enter the item number or range. If In list is selected, separate multiple item numbers with commas. 6. Click OK to add the restriction. Adding security group restrictions Security group restrictions limit results to files with actions performed by users in a specific security group. For example, you can create a restriction to find files with actions performed by the QA security group. 1. Select a restriction in the Advanced Find, Add Filter, or Add Report dialog box. The Restriction dialog box opens. 2. Select is or is not to indicate if files include events performed by the selected security group. 3. Select the security group. 216

233 Adding branch and repository restrictions 4. Click OK to add the restriction. Adding branch and repository restrictions Branch and repository restrictions limit results to files in a repository on a specific branch or across all branches. For example, you may want a trigger to run only when actions are performed on files in the Code repository on the mainline branch. 1. Select a branch and repository restriction in the Add Report dialog box. The Surround SCM Repository Browser dialog box opens. 2. Select a branch and repository option. Current branch and repository only includes files in the current branch and repository. Selected branch and repository only includes files in a selected branch and repository. Note: This option may not be available for some branch and repository restrictions. 3. Select a branch and repository. 4. Select Browse repositories across all branches include files in the selected repository for all branches. This option is not available if Current branch and repository is selected. 5. Select Recursive to recursively include files in all repositories. 6. Click OK to add the restriction. Adding action restrictions based on user and date Action restrictions limit results to file actions performed by all users, selected users, or the current user by date. For example, you can create a restriction for a public report to include the files checked in by the current user in the past five days. When the report is generated, it only includes the files checked in by the user who generates the report. 1. Select the users have performed actions in date range restriction in the Add Report dialog box. The Filter By Action dialog box opens. 217

234 Adding action restrictions based on user and date 2. Select any Filter by Users options. Is in list or is not in list indicates if the files include the selected users. Current user only includes actions performed by the logged in user. All users includes actions performed by all users. Selected users only includes actions performed by the users selected in the list. Note: The System user is used by triggers to change workflow states and custom field values. 3. Select any Filter by Actions options. Is in list or is not in list indicates if the files include the selected actions. All change actions includes actions that caused the file version to increment. The following change actions are included: Add, Check in, Promote from, Promote from with merge, Rebase, Rebase with merge, Remove, Rollback file, Rollback promote, and Rollback rebase. All actions includes all actions. Selected actions only includes the selected actions. Note: Click Select All to select all actions or click Select None to clear any selected actions. 4. Select any Filter by Dates options. 218

235 Searching for text in files Is or is not indicates if the files include dates that match the specified date or time period. All dates includes files with any date. Equal to, before, after, or between includes files relative to the specified date or time period. A specific time period includes files from the selected period, such as last week or last year. In the last or next includes files for a specified number of hours, days, weeks, months, or years relative to the current date/time. 5. Click OK to add the restriction. Searching for text in files You can search for text in files to quickly find and open files you need to work with. For example, if you want to change the value for a product name variable, you can search for the variable in the source code files to identify files that need to be updated with the new value. Keep the following in mind. You can search using text phrases with or without wildcards or regular expressions. If you enter a phrase, the exact phrase is searched for. If you enter a phrase with spaces, the entire phrase is searched for, not the individual words. For example, if you enter 'WysiCorp Products', only files that contain the exact phrase are returned. Files that contain only 'WysiCorp' or only 'Products' are not returned. If you enter one search term, only files that contain the exact term are returned with only whole word matches. For example, if you enter 'WysiCorp', files that contain 'WysiCorp.h' or 'WysiCorporation' are not returned. Whole words are defined in the Unicode Standard Annex Word Boundaries. You can use wildcards for more flexible searching. Only current file versions are searched. Historical file versions are not included in searches. Text file results include the lines where a match was found. A maximum of 100 matching lines are returned per text file. For large text files, only the first 100,000 lines are searched. For long lines in text files, only the first 1,000 characters of the line are parsed. Matching lines are not included in the results for binary files. If the file type for binary files is changed to Text in the file properties, incorrect search results may be returned. A message is displayed under the Location field if you select a branch that is not indexed, with indexing in progress, or with a corrupt index. You can continue the search, but it may take longer or return limited results. Indexing branches improves performance and search results. The Surround SCM administrator manages branch indexing. See Indexing branches for optimized searches, page Choose Edit > Find in Files. The Find in Files window opens. 219

236 Searching for text in files 2. In the Search area, enter or select the Search Criteria. Location specifies the branch and repository to search. If a repository is selected when the Find in Files window was opened, it is set as the location by default. Click to select a different location. Do not use index searches without using the index if an indexed branch is selected. You may want to select this option if you are searching for punctuation and the results do not include files you expect them to. Keep in mind that non-indexed searches only include text files in the results and may be slower. See Differences between indexed and non-indexed searches, page 221 for information about how indexed and non-indexed searches work. Search for phrase specifies the text to search for. You can enter up to 128 characters. To include wildcards or regular expressions in the search, select the corresponding option in the Use list. If you choose to use regular expressions, this field changes to Search for regular expression. Tip: See Text search examples, page 223 for examples using wildcards and regular expressions. Recursive searches for the specified text in all files in the selected repository and all subrepositories. Match case matches the exact case of the specified text. Only applies to text files. Binary file searches are always case insensitive. Case-sensitive searches may return results from binary and large text files that do not match the exact case of the specified text. Search cloaked repositories also searches files in cloaked repositories. This option is selected if the search location is set to a cloaked repository. If this option is not selected, files in cloaked repositories are not searched. 3. Select any Refine Search options to further refine the search. 220

237 Differences between indexed and non-indexed searches By extension only searches files with the specified file extensions. You can select extensions to include from the list or enter them. Separate multiple extensions with a comma. Select *.* to search all file extensions. Exclude extensions excludes files with the specified file extensions. You can select extensions to exclude from the list or enter them. Separate multiple extensions with a comma. Tip: File extension lists are organized by groups. You can add file extensions to existing groups and create new groups to quickly select file types in searches. See Grouping file extensions, page 99. Limit results to specifies the maximum number of results to display. The default and minimum value is 50. This value only limits the number of results displayed, not the number of results found. If more results are found, the Show more results button is available in the Results area. 4. Click Search. Files with content that matches the search criteria are displayed in the Results area. If you did an indexed search, a relevance value indicates how closely the results match the search criteria. Click Show more results to view additional results if the number to display is limited. To narrow the results by filename, enter text in the Filename search field. Click to select a recently used filename. Click to clear the filename search. Expand a file to view all lines where the text was found. Click Expand All to expand all results or click Collapse All to collapse all expanded results. To sort the results, click a column heading. or is displayed next to the heading. Shift+click a column heading to perform a secondary sort. or is displayed next to the secondary sort heading. Click or Shift+click the column heading again to toggle the sort order. To preview the text in file contents, select the file. The contents are displayed in the Preview area. If multiple results are found in the same file, click to go to the next match or to go to the previous match. Note: You can only preview content for text files. To view content for a binary file, open it in the associated application. To open a file, select it and click Open. To go to the file in the source files list, select it and click Go To File. To save the results list in HTML or CSV format, click Save As. 5. Click Reset to clear all options and perform a new search. 6. Click Close when you finish. Differences between indexed and non-indexed searches Surround SCM supports indexed and non-indexed searches for text in files. See Searching for text in files, page 219. Indexed searches return results more quickly and include binary files, but you may need to use nonindexed searches depending on your needs. The following information can help you understand more about indexed versus non-indexed searches. 221

238 Differences between indexed and non-indexed searches Non-indexed searches Non-indexed searches only look for matches in text files using a line-by-line search. Binary files are not searched. When you search, Surround SCM opens each text file and parses it for the exact phrase you entered as the search term. These searches can be slow if the branch or repository you are searching contains thousands of files. Indexed searches Indexed searches look for matches in text and binary files. Performing indexed searches requires running the indexing server and turning on indexing for branches that searches are performed on. See Indexing branches for optimized searches, page 360. Indexed searches have two steps: 1. A search engine-style search is performed by the indexing server. The server looks for the individual words you entered as the search term to narrow the list of potential file matches and assigns a relevance value. 2. Each text file included as a result from step 1 is opened and searched for the exact phrase you entered as the search term. This is a line-by-line search similar to a non-indexed search except the search is performed on a smaller subset of files, which makes the operation much faster. The indexed search results contain binary files that pass step 1 and text files that pass step 2. Binary files contain the search term in close proximity, but may not have an exact phrase match. Tip: If indexing is turned on for a branch, you can still perform a non-indexed search. Select Do not use index when performing a search. Comparison Support for: Indexed search Nonindexed search More information Binary files in search results Common words, such as for and if, included in the search term Yes No File types include Adobe PDF (.pdf), Microsoft Excel (.xls,.xlsx), Microsoft Word (.doc,.docx), Open Document Format (.odf), and Rich Text Format (.rtf). Only in a phrase Yes Common words, such as 'for', 'if', 'in', and 'or' are not indexed. Searching for the finds results in a non-indexed search, but not in an indexed search. Searching for the executable may find results in both types of searches. Punctuation-only search term Only when using wildcards Yes Punctuation is not indexed. Searching for '&&' does not return any results in an indexed search unless you use wildcards. 222

239 Text search examples Support for: Indexed search Nonindexed search More information Relevance value to indicate how closely results match the search term Matching text beyond the first 100,000 lines in a file or first 1,000 characters in a line Yes Yes. File is included in results with a relevance value, but specific line numbers are not in results. No No When searching text files, only the first 100,000 lines in each file and 1,000 characters in each line are searched. These limits help prevent Surround SCM from becoming unresponsive when searching large files. Common words The following common words are not indexed in Surround SCM. a, an, and, are, as, at be, but, by for if, in, into, is, it no, not of, on, or such that, the, their, then, there, these, they, this, to was, will, with Text search examples The following examples can help you understand how to use wildcards and regular expressions to perform more flexible searches for text in files. See Searching for text in files, page 219. Note: These examples only apply to searching for text in files in the Find in Files window. Additional wildcards and regular expressions may be supported when adding restrictions for advanced file searches or filters. 223

240 Text search examples Wildcards You can use wildcard characters to replace characters in search phrases. Wildcards are helpful if you are searching for terms with spelling variations or text that may include other characters, such as dashes. They are also helpful for finding partial word matches. For example, searching for 'run' does not find files that contain 'running' or 'homerun', but a wildcard search using '*run*' will find 'running' and 'homerun'. To substitute for: Use: Example Zero or more characters, excluding spaces One character, excluding spaces Asterisk (*) Question mark (?) 'gr*n' returns files that contain words such as 'green' and 'grain', but does not return phrases such as 'greater than'. 'p?int' returns files that contain words such as 'print', 'point', and 'paint'. Regular expressions You can use the following regular expression syntax and symbols to search for text in file contents. Regular expression searches only support individual terms. To search for a phrase, perform a search with or without wildcards. To match: Use: Example Any single character. ab. matches ab followed by any character, such as 'abc' or 'ab_' Zero or one occurrence of the previous character One or more occurrences of the previous character Zero or more occurrences of the previous character Separate two or more alternatives to perform an OR search A specified number of occurrences of the previous character Any single character included in a set of characters? colou?r matches 'color' or 'colour' + ba+ matches b followed by any number of occurrences or a, such as 'ba', 'baa', or 'baaa' * a.* matches a followed by any number of characters, such as 'ab', 'abb', 'aab', or 'aabb' (gray grey) matches 'gray' or 'grey' {...} ba{3} matches 'baaa baa{3,} matches b followed by three or more occurrences of a, such as 'baaa', 'baaaa', or 'baaaaa' [...] [tw]alk matches 'talk' or 'walk' Group several items as a single unit (...) (file ) matches 'file1', 'file2', 'file3', or 'file4' Interpret special characters as exact literals \ file\.txt matches occurrences of 'file.txt' 224

241 Configuring filters Configuring filters Filters allow you to sort the source file list to view specific files. You can create public filters that other users can use or private filters that cannot be used by other users. The Filter list in the Source Tree window displays all public filters and any private filters that you create. For example, a development team lead may create a private filter to view all files in the Awaiting Review workflow state so they can be assigned for code review. Or, the team lead may create a public filter that allows team members to view the files that are assigned to them based on the Assigned custom field. Surround SCM includes the following pre-defined filters: All Files Displays all files in the selected repository Checked Out Files Displays all checked out files in the selected repository Files Checked Out By Me Displays all files in the selected repository checked out by the current user Files That Are Not Current Displays all files in the selected repository that are not in a Current status You can search for files based on a variety of criteria, such as filename, version number, file type, or last check in date. 1. Choose Tools > Filters. The Filters dialog box opens. The Summary field displays the restrictions for a selected filter. 2. Click Add to add a filter. See Adding filters, page Select a filter and click Edit to change it. See Editing filters, page Select a filter and click Duplicate to duplicate it. See Duplicating filters, page Select a filter and click Top, Move Up, Move Down, or Bottom to change the display order. 6. Select a filter and click Delete to delete it. See Deleting filters, page 228. Adding filters Filters allow you to quickly find files in the source file list based on specific criteria. For example, you can create a filter to find files in a specific workflow state. The Filter list in the Source Tree window displays all filters you have access to. 225

242 Adding filters Note: You can also create filters in the Advanced Find dialog box. See Searching for files, page Choose Tools > Filters. The Filters dialog box opens. 2. Click Add. The Add Filter dialog box opens. 3. Enter a descriptive Filter name. 4. Select a Public/private filter option. Public filters are shared with all users. Private filters are not shared. You may only be able to create private filters depending on your security permissions. 5. Select a Restriction to set the criteria files must meet to pass the filter. The Restriction dialog box opens. The options change based on the selected restriction. 6. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the Restrictions list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 226

243 Applying filters to the source file list 8. Add any additional restrictions. 9. Click OK. The filter is added. See Applying filters to the source file list, page 227 for information about using filters. Applying filters to the source file list You can filter the source file list to display specific files. 1. Select a filter from the Filter list. Files that meet the filter criteria are displayed. The filter remains applied even if you select another mainline branch or repository. Note: Select List recursively to recursively display all files in the selected repository and subrepositories that meet the selected filter criteria. 2. Select All Files from the list to display all files. Editing filters Edit a filter to change the name, if it is public or private, or the restrictions. 1. Choose Tools > Filters. The Filters dialog box opens. 2. Select a filter and click Edit. The Edit Filter dialog box opens. 3. Make any changes. To change a restriction value, double-click the value in the Restrictions list. 4. Click OK to save the changes. Duplicating filters If you add filters that are similar, you can save time by duplicating and editing an existing filter. 1. Choose Tools > Filters. The Filters dialog box opens. 2. Select a filter and click Duplicate. The Duplicate Filter dialog box opens. 3. Enter a Filter name and modify the filter options. 227

244 Deleting filters 4. Click OK to save the changes. Deleting filters You can delete filters that are no longer needed. 1. Choose Tools > Filters. The Filters dialog box opens. 2. Select a filter and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The filter is deleted. Browsing to files and repositories Surround SCM addresses make it easy to browse to specific files or repositories. You can enter an address or copy and paste an address to browse to repositories and files. Tip: You can also enter web addresses to open web pages in your default browser. 1. Choose File > Go To Location. The Go To Location dialog box opens. The address for the Surround SCM Server you are connected to is displayed. 2. Enter the Address for the repository or file you want to browse to. To select a repository sscm://serveraddress:port//branch//repository/subrepository To select a file sscm://serveraddress:port//branch//repository/subrepository/file Tip: To browse to a specific file version, append?ver=<number> to the address. For example, sscm://dev.wysicorp.com:4900//wysidev//wysiwrite/code/main.cpp?ver=3 opens the History dialog box with version 3 of the main.cpp file selected. Click View File to view the selected version. 3. Click OK. The repository or file is selected. You may want to bookmark the file or repository to quickly access it in the future. See Bookmarking files, repositories, and branches, page 229. Note: Use the Address toolbar to view the address for the selected repository or file. Choose View > Toolbars > Address to open the toolbar. 228

245 Bookmarking files, repositories, and branches Bookmarking files, repositories, and branches You can bookmark files, repositories, and branches you frequently use to quickly access them from the Bookmarks menu. The first nine bookmarks in the list are automatically assigned keyboard shortcuts. You can rearrange bookmarks to change the order they are displayed in the Bookmarks menu and the assigned keyboard shortcuts. See Managing bookmarks, page Select the file, repository, or branch to bookmark and choose Bookmarks > Add Bookmark. The Add Bookmark dialog box opens with the bookmark address set in the read-only Address field. 2. Enter a bookmark Name and Description. If you are bookmarking a branch, the branch name is used by default. If you are bookmarking a file or repository, the file or repository name prepended with the branch name is used by default. For example, WysiCorpDevelopment::Code or WysiWrite 2.0.x::main.cpp. 3. If you are bookmarking a repository or file, select a Navigation option to indicate the branch to access when using the bookmark. Always go to <BranchName> branch always navigates to the branch displayed in the Address field. For example, if the bookmark contains the WysiCorp branch, Surround SCM always navigates to the WysiCorp branch when using the bookmark. Do not switch branches navigates to the repository or file in the branch selected in the Source Tree window. If this option is selected, the branch name is removed from the Address field. For example, if the bookmark contains the WysiCorp branch and the WysiCorp 1.x branch is selected when you use the bookmark, Surround SCM navigates to the repository or file in the WysiCorp 1.x branch. Note: Bookmarks with the Do not switch branches option selected are not available in Surround SCM Web. 4. Click OK. The bookmark is added. To use the bookmark, select it in the Bookmarks menu. Note: If a bookmarked file, repository, or branch is moved or renamed, or the server address changes, the bookmark may no longer work and an error is displayed when you access it. You can delete the old bookmark and then create a new one. See Managing bookmarks, page

246 Managing bookmarks Managing bookmarks You can rename bookmarks and rearrange them to change the order they are displayed in the Bookmarks menu and the assigned keyboard shortcut. 1. Choose Bookmarks > Manage Bookmarks. The Manage Bookmarks dialog box opens. 2. Select a bookmark and click Edit to rename it or change the description. Note: You cannot change the Navigation option, which indicates if the bookmarked repository or file opens on a specific branch. To change navigation, delete the old bookmark and then create a new one. 3. Select a bookmark and click Top, Move Up, Move Down, and Bottom to change the order and keyboard shortcuts. Only the first nine bookmarks are assigned keyboard shortcuts. 4. Select a bookmark and click Delete to delete it. 5. Click Close when you finish. 230

247 Creating and Running Reports Reports provide an easy way to access, analyze, and share information about files, branches, and repositories and the users who perform actions on them. You can create a variety of reports that focus on the data you need. You can share reports with other users or keep them private. Before you create or run reports, you may want to get familiar with the different types and content. See Report types, page 231. To create and run most reports, choose Tools > Reports. See Creating reports, page 233 and Running reports, page 249. Other reports, such as branch and file differences reports, are available in other locations in Surround SCM. You can also add and run reports from external reporting services. See Adding external reports to Surround SCM, page 247. Report types Surround SCM includes the following reports. Report type Displays: More information Branch differences Branch maintenance Changelist Code review Code review coverage File differences File differences between two related branches. List or tree structure of all branches and their attributes (e.g., frozen, active, etc.). Use these reports to document branch configuration at a specific point in time. Information about file actions associated with pending or committed changelists. Historical information about a code review and files in it. Use these reports to review unaddressed comments, review your code review process, or save process information for audits. Information about file versions in code reviews and if the files are approved or still in review. Use these reports to determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. Differences between two or more versions of a text file. Use these reports to document code changes or generate code patch files. Running branch differences reports, page 177 Managing branch attributes, page 357 Working with pending changelists, page 125 and Working with committed changelists, page 130 Running code review reports, page 68 Creating code review coverage reports, page 234 Running file differences reports, page

248 Configuring reports Report type Displays: More information History Labeled file List Security group Trend Workflow progress Historical information about actions performed on files, including details about who, what, where, and when for each action. Use these reports to determine what changed recently or to find changes made by a specific team member that may need a code review. Files and versions that a label is applied to. Use these reports to view labeled files that correspond to a milestone, such as a test or release. Current information about files, organized in columns. Optionally group by value or display data in a chart. Use these reports to find files currently checked out, files in a specific workflow state, or files owned by you. Information about access granted or restricted for each security group. Use these reports to quickly determine which groups have access to specific actions. Actions performed over time or by user. Use these reports to determine the activity level of a project. Information about the state of files as they move through a workflow. Creating history reports, page 237 Running labeled files reports, page 150 Creating list reports, page 239 Creating security group reports, page 242 Creating trend reports, page 244 Creating workflow progress reports, page 245 Reports from external reporting services, such as SQL Server Reporting Services or Crystal Reports, can also be added to Surround SCM. External reporting gives you access to more data in the Surround SCM databases, provides more flexibility and control of the report content and layout, and offers more output format options. Ask your Surround SCM administrator for information. See Adding external reports to Surround SCM, page 247. Note: You can also save and print the source file list for reporting purposes. See Saving the source file list, page 250 and Printing the source file list, page 251. Configuring reports The following information only applies to code review coverage, history, list, security group, trend, and workflow progress reports. Labeled files reports can be generated from the Reports dialog box, but the steps are slightly different. See Running labeled files reports, page 150. Other reports are also available in Surround SCM: branch differences, branch maintenance, changelist, code review, and file differences. See Report types, page Choose Tools > Reports. The Reports dialog box opens. 232

249 Creating reports 2. Click Add to create a report. See Creating reports, page Select a report and click Edit to change it. See Editing reports, page Select a report and click Duplicate to duplicate it. See Duplicating reports, page Click Quick Report to create and run a report without saving it. See Running quick reports, page Select a report and click Run to generate it. See Running reports, page Select a report and click Delete to delete it. See Deleting reports, page Click Close when you finish. Creating reports Surround SCM includes built-in reports for analyzing file information and activity. You can create reports that contain the exact data you need. The following information explains how to create these reports: Code review coverage History List Security group Trend Workflow progress See Report types, page 231 for information about other available reports. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select a report type and click OK. See Report types, page

250 Creating code review coverage reports The Add Report dialog box opens. 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The restriction options depend on the selected report type. See Adding restrictions, page Click the Output tab to select the output format, stylesheet to use, and additional report content options. The available options depend on the report type. 8. Click OK. The report is added. See Running reports, page 249 for information about running reports. Creating code review coverage reports Code review coverage reports include information about file versions in code reviews and if the file reviews are complete or still in progress. Use these reports to determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. Code review information is displayed in the following columns, which are included in the report by default. Column Reviewed Versions Unreviewed Versions Code Reviews Contains: Version numbers of a file that are in a code review with an Approved status. A code review is approved only if all individual file reviews in it are complete. Version numbers of a file that are not in an Approved review. List of code reviews a file is included in and the version numbers, sorted oldest to newest. If a version is in a review that is not Approved, the review status is also indicated. For example, 'CodeReviewA (1, 3-5) - Needs Attention ' indicates that versions 1, 3, 4, and 5 of the file are included in the CodeReviewA review, which has a Needs Attention status. Tip: When working with code reviews, you can also run reports that provide historical information about a review and the files in it. Use these reports to review unaddressed comments, review your code review process, or save process information for audits. See Running code review reports, page Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select Code Review Coverage and click OK. The Add Report dialog box opens. 234

251 Creating code review coverage reports 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the restriction list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 9. Add any additional restrictions. 10. Click the Output tab. 235

252 Creating code review coverage reports 11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. 12. Select a report Stylesheet. Cascading Style Sheets (CSS) are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets for code review coverage reports are stored in the StyleSheets\CodeReviewCoverage directory in the Surround SCM application directory on the Surround SCM Server. 13. Select the sorting and order options. Primary sort column and Order sorts the first column of report results. Secondary sort column and Order sorts the second column of report results (optional). 14. Select Only include information for current file version to only include information about the current versions of files. If this option is selected, Surround SCM checks if the current version of a file, which is the version displayed in the source files list, is included in the code review. If this version is in the review and meets the restriction criteria, information about the file is included in the report. If the current version is not in the review, no information about the file is included in the report. If this option is not selected, information about all versions of files in the review that meet the restriction criteria is included. 15. Select Do not include files with all versions in approved reviews to exclude files that meet the restriction criteria and have all versions in code reviews with an Approved status. If Only include information for current file version is also selected, files with the current version in an Approved review are excluded. Selecting this option is helpful to show unreviewed files and help you determine files that need review before you release your product. 16. Select the Field Options to specify the columns to include in the report. 236

253 Creating history reports Select the column to add in the Available columns list and click to move it to the Selected columns list. To remove a column, select it in the Selected columns list and click. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 17. Click OK. The report is added. See Running reports, page 249 for information about running reports. Creating history reports History reports include historical information about actions performed on files, including details about who, what, where, and when for each action. Use these reports to determine what changed recently or to find changes made by a specific team member that may need a code review. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select History and click OK. The Add Report dialog box opens. 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 237

254 Creating history reports 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the restriction list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 9. Add any additional restrictions. 10. Click the Output tab. 11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. Note: If a report is in HTML format, a pie chart can be included in it. See Charting report data, page Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the Surround SCM Server. 13. Select a report style. Summary style report includes an overview of file details. 238

255 Creating list reports Hide repositories without selected actions excludes repositories with files that do not meet the report criteria. Include difference information includes file version differences. Click Diff Options to specify differences to display. See Running file differences reports, page 43. Table style report includes file information in a table format. Primary sort column and Order sorts the first column of report results. Select Group by primary sort column to organize results into groups that can be collapsed and expanded in the report. If you want to include a pie chart in the report, you must select this option. See Charting report data, page 247. Secondary sort column and Order sorts the second column of report results (optional). Select the Group by secondary sort column option to organize results into groups that can be collapsed and expanded. 14. Select the Field Options to specify the columns to include in the report. Select the column to add in the Available columns list and click to move it to the Selected columns list. To remove a column, select it in the Selected columns list and click. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 15. Click OK. The report is added. See Running reports, page 249 for information about running reports. Creating list reports List reports include current information about files, organized in columns. You can optionally group by value or display data in a chart. Use these reports to find files currently checked out, files in a specific workflow state, or files owned by you. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select List and click OK. The Add Report dialog box opens. 239

256 Creating list reports 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the restriction list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 9. Add any additional restrictions. 10. Click the Output tab. 240

257 Creating list reports 11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. Note: If a report is in HTML format, a pie chart can be included in it. See Charting report data, page Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the Surround SCM Server. 13. Select the sorting and order options. Primary sort column and Order sorts the first column of report results. Select Group by primary sort column to organize results into groups that can be collapsed and expanded in the report. If you want to include a pie chart in the report, you must select this option. See Charting report data, page 247. Secondary sort column and Order sorts the second column of report results (optional). Select the Group by secondary sort column option to organize results into groups that can be collapsed and expanded. 14. Select the Field Options to specify the columns to include in the report. Select the column to add in the Available columns list and click to move it to the Selected columns list. To remove a column, select it in the Selected columns list and click. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 15. Click OK. 241

258 Creating security group reports The report is added. See Running reports, page 249 for information about running reports. Creating security group reports Security group reports include information about access granted or restricted for each security group. Use these reports to quickly determine which groups have access to specific actions. See Security Commands, page 431 for information about the available security options. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select Security Group and click OK. The Add Report dialog box opens. 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. Select the security group name restriction to include only selected security groups. If you do not select this restriction, the report includes all security groups. The Report Restriction dialog box opens. 242

259 Creating security group reports 7. Select a security group name option. Is in list or is not in list indicates if the group name is included in the list of selected groups. All security groups includes all groups in the report. Selected security groups only includes the selected groups in the report. 8. Click OK. The restriction is added to the report. 9. Click the Output tab. 10. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. 11. Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the Surround SCM Server. 12. Select Include Repository Security and Branch Security tabs to include repository and branch security commands in the report. 13. Select a report style. Comparison style report displays security groups and commands side-by-side in the same table. 243

260 Creating trend reports Tip: You can flag commands that you want to review later. Double-click a command in the report to add a flag. Double-click a flagged command to change the flag to a green checkmark, which indicates the setting was reviewed. Detail style report displays commands for each security group in separate tables. 14. Click OK. The report is added. See Running reports, page 249 for information about running reports. Creating trend reports Trend reports include information about actions performed over time or by user. Use these reports to determine the activity level of a project. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select Trend and click OK. The Add Report dialog box opens. 4. Enter a Report name. 5. Select a Public/private report option. 244

261 Creating workflow progress reports Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the restriction list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 9. Add any additional restrictions. 10. Click the Output tab. 11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. 12. Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the Surround SCM Server. 13. Select an option to Group actions by. You can group actions by user, day, month, or week. 14. Select One event type per user per file to only include one instance of an event type per user and file. 15. Click OK. The report is added. See Running reports, page 249 for information about running reports. Creating workflow progress reports Workflow progress reports include information about the state of files as they move through a workflow. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select Workflow Progress and click OK. The Add Report dialog box opens. 245

262 Creating workflow progress reports 4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page Click OK. The restriction is added. The values are displayed in the restriction list and the Summary field. Note: To change a value, double-click it in the Restrictions list. 9. Add any additional restrictions. 10. Click the Output tab. 246

263 Charting report data 11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. 12. Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the Surround SCM Server. 13. Select a Start Date, End Date, and time Interval for the files to include in the report. 14. Select Hide unused states to exclude states that are not applied to files. 15. Select Hide <no state> to exclude the <no state> column. 16. Click OK. The report is added. See Running reports, page 249 for information about running reports. Charting report data Pie charts can be included in history and list reports for a visual representation of the report data. See Creating history reports, page 237 and Creating list reports, page 239. The following options must be set in the report configuration: The output format must be HTML. The data must be grouped by the primary sort column. To change the data in the chart, change the primary sort column value. When the report runs, the chart is included at the bottom of the report. Click Show Labels to display labels that contain the item name, count, and percentage for each piece in the chart. You can also use the chart legend to match the report data with the pieces in the chart. Click an item in the legend to highlight that piece of the chart and display a label with the item name and count. Click Hide Legend to hide the legend. Adding external reports to Surround SCM Adding external reports to Surround SCM gives you the ability to open an external report viewer from Surround SCM to view reports stored in reporting services, such as SQL Server Reporting Services or Crystal Reports. 247

264 Editing reports An administrative user or another user with high-level security permissions is responsible for configuring external reporting services and security before you can add external reports. See the External Reporting wiki for information. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select the reporting service as the report type and click OK. The Select External Reports dialog box opens with a list of available reports. 4. Select the report to add. To select more than one report, Ctrl+click each report. Note: Click Create to create a report in the external reporting service. You can only create reports if an external reporting client plug-in that supports report editing is installed. Ask your Surround SCM administrator for help. 5. Click Add. The report is added. See Running reports, page 249 for information about running reports. Note: By default, external reports are private. You can edit the report name, sharing settings, and output format after the report is added to Surround SCM. See Editing reports, page 248. Editing reports Edit a report to change the name, if it is public or private, the restrictions that control the content included, or display options. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select the report and click Edit. The Edit Report dialog box opens. 3. Make any changes. Note: If you are editing an external report, you can only change the report name, public/private sharing, and the output format fields in Surround SCM. Other field information is stored in the external reporting service. Click Edit to edit the report content in the reporting service. You can only edit reports if a client plug-in that supports report editing is installed. Ask your Surround SCM administrator for help. 4. Click OK to save the changes. Duplicating reports If you add reports with the same basic information, you can save time by duplicating an existing report and then editing the new one. 248

265 Deleting reports 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Duplicate. The report is duplicated. 3. Modify the new report and save the changes. See Editing reports, page 248. Deleting reports You can delete a report if it is no longer needed. If you delete a shared report, users with access to it can no longer view it. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The report is deleted. Note: If you delete an external report, the report is only deleted from Surround SCM and not the external reporting service. Running reports You can run reports to analyze Surround SCM data. You can run private reports you created and reports that are shared with you. You may also be able to create reports to analyze specific data you need. See Creating reports, page 233 Tip: By default, reports open in a report viewer. You can set a user option to view HTML reports in a web browser instead. See Setting general user options, page Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Run. The report opens. 3. Click Save As to save the report or Print to print it. These options are only available in the internal report viewer. If an HTML report opens in a browser, you can save, export, or print the report from the browser. 4. Click Close when you finish. Running quick reports You can run a quick report when you do not want to save the report for future use. 249

266 Saving the source file list Tip: By default, reports open in a report viewer. You can set a user option to view HTML reports in a web browser instead. See Setting general user options, page Choose Tools > Reports. The Reports dialog box opens. 2. Click Quick Report. The Select Report Type dialog box opens. 3. Select a report type and click OK. The Quick Report dialog box opens. 4. Create the report. See Creating reports, page Click Run. The report opens. 6. Click Save As to save the report or Print to print it. These options are only available in the internal report viewer. If an HTML report opens in a browser, you can save, export, or print the report from the browser. 7. Click Close when you finish. Saving the source file list You can save the source file list and use the output with third-party applications for reporting and other purposes. For example, you may want to save a list of all checked out files. 1. Select a repository. 2. Optionally select a filter from the Filter list to only include specific files in the saved list. 3. Choose File > Save File List As. The Save File List dialog box opens. The Selected columns list includes the columns currently displayed in the source file list. 4. Select the column to add in the Available columns list and click to move it to the Selected columns list. 250

267 Printing the source file list To remove a column, select it in the Selected columns list and click. 5. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 6. Select an Output format. You can save the file list in HTML, tab-delimited, or comma-delimited format. 7. Click Save As. The Save File List As dialog box opens. 8. Select the file location, enter a filename, and select the file type. 9. Click Save. The list is saved. Printing the source file list You can print the source file list, which can be helpful for reporting purposes. For example, you can print a list of all checked out files. 1. Select a repository. 2. Optionally select a filter from the Filter list to include specific files in the printed list. 3. Choose File > Print File List. The Print File List dialog box opens. The Selected columns list includes the columns that are currently displayed in the source file list. 4. Select the column to add in the Available columns list and click to move it to the Selected columns list. To remove a column, select it in the Selected columns list and click. 5. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 6. Click Print to print the list. 251

268

269 Integrating with TestTrack You can integrate Surround SCM with TestTrack to provide a complete change management solution by tracking what changed and why. Files can be attached to issues, requirements, and test cases and accessed from Surround SCM or TestTrack. For example, an issue is created in TestTrack and assigned to Jane to fix. Jane checks out the source file and fixes the bug. When she checks in the file, she clicks Attach to TestTrack and selects the TestTrack project to view her assigned issues. She then selects the appropriate issue and attaches the file to it. TestTrack users with security access to the Source Code tab can work with the file Jane attached. Configuring TestTrack connections TestTrack projects are stored on servers, which you need to provide access to. Each connection is mapped to a single project on the TestTrack Server. Note: The Surround SCM administrator or another high-level user must enable TestTrack integration before you can configure connections. See Enabling TestTrack integration, page Choose Tools > TestTrack Integration > Connections. The TestTrack Connections dialog box opens. 2. Click Add to create a connection. See Adding TestTrack connections, page Select a connection and click Edit to change it. See Editing TestTrack connections, page Select a connection and click Top, Move Up, Move Down, or Bottom to reorder the list. 5. Select a connection and click Delete to delete it. See Deleting TestTrack connections, page 254. Adding TestTrack connections To access TestTrack issues, requirements, and test cases, you need to add a connection to the TestTrack project. 1. Choose Tools > TestTrack Integration > Connections. The TestTrack Connections dialog box opens. 2. Click Add. 253

270 Editing TestTrack connections The Add Connection dialog box opens. 3. Enter a Connection name to help users identify the project. 4. Enter the Server address and Port. The default TestTrack port number is 99 on Windows and 1566 on Unix platforms. Note: If you received a server settings file from your TestTrack administrator, import it instead of manually entering the information. Click Import, select the XML file and, click Open. The Server address, Server port, and Public key fingerprint fields are automatically populated. The public key provides additional security required to connect to the TestTrack Server. Contact your TestTrack for additional help. 5. Click Get Projects to retrieve a list of all projects from the TestTrack Server. 6. Select a Project. 7. Click OK. The connection is added. Tip: You can set integration options that restrict users to a use a connection associated with a specific repository. See Setting TestTrack integration options for repositories, page 402. Editing TestTrack connections You can change the server address, port number, and project. 1. Choose Tools > TestTrack Integration > Connections. 2. Select the connection and click Edit. The Edit Connection dialog box opens. 3. Make any changes and click OK. Deleting TestTrack connections You can delete any TestTrack connections you no longer use. 1. Choose Tools > TestTrack Integration > Connections. 2. Select the connection and click Delete. You are prompted to confirm the deletion. 3. Click Yes. 254

271 Entering TestTrack login information The connection is deleted. Entering TestTrack login information You need to enter your TestTrack login information before you can attach files to issues, requirements, or test cases. 1. Choose Tools > TestTrack Integration > User Settings. The TestTrack User Settings dialog box opens. 2. Select Use Surround SCM username and password if your TestTrack and Surround SCM login information is the same. 3. Select Use the following and enter your TestTrack username and password if your login information is different from Surround SCM. 4. Click OK. You can now attach Surround SCM source files to TestTrack items. Attaching source files to TestTrack items You can attach source files to TestTrack issues, requirements, and test cases. The file information is attached to the TestTrack item, making it easy to work with the file from Surround SCM or TestTrack. You can also attach source files to TestTrack items when you add files, check in files, promote or rebase files and branches, or view file history. If the files you want to attach are included in a changelist, you can attach the changelist to TestTrack items from the Changelists dialog box. See Managing changelists, page 124. Note: You must use TestTrack or later to attach files to requirements and test cases. 1. Select the files or repository and choose Activities > Attach to TestTrack. If you want to select the files to attach by label, choose Tools > Labels, select the label, and click Attach. Ctrl+click the files you want to attach in the Select Files to Attach dialog box and click Attach. The TestTrack Browser dialog box opens. 255

272 Attaching source files to TestTrack items 2. Select the TestTrack Connection for the project you want to access. Click Configure to create or change a connection. See Configuring TestTrack connections, page Click the tab for the item type you want to attach the files or repository to. The items list is populated with your assigned items. Select a filter from the Filtered By list to display specific items. Note: You can only attach files to items you have access to in TestTrack. 4. Select the items you want to attach the files to. To select multiple items, Ctrl+click each item. A read-only description is displayed when you select an item. Click View to view the issue details. See Viewing TestTrack items, page 257. Note: If you are attaching to issues, click Edit to edit the issue details or click Add to create an issue. See Editing TestTrack issues, page 259 and Adding TestTrack issues, page 258. These options are not currently available for requirements and test cases. 5. Click Attach to attach the files to the selected items. Note: If a selected item is being edited in TestTrack, you are prompted to resolve the item lock. The Attach to TestTrack dialog box opens. Items you added are displayed in the Pending Attachments list. If you attach an item by mistake, select it and click Remove. 256

273 Viewing TestTrack items 6. If you are attaching files to issues, click Fix to mark the selected issue as fixed. See Fixing external issues, page 270. Entering TestTrack events is not currently available for requirements and test cases. 7. Click OK to attach the files to the selected items. The files are attached. Issues that you selected to fix are marked as fixed. Users can access Surround SCM files on the item's Source Code tab in the TestTrack Client. Keep in mind the tab name can be changed and may have a different name. Viewing TestTrack items After files are attached to TestTrack items, you can view the item details from Surround SCM. 1. Select the file. 257

274 Adding TestTrack issues You can search for files attached to items. See Finding files attached to TestTrack items, page Choose Activities > History. The History dialog box opens. 3. Select the file version attached to the item you want to view. 4. Click View Attached. The read-only View Item dialog box opens. Adding TestTrack issues You can create new issues to attach source files to from Surround SCM. Note: You must use TestTrack 2011 or later to add issues to TestTrack from Surround SCM. 1. When you are attaching files to TestTrack, click Add on the Issues tab. The Add Issue dialog box opens with the Detail tab selected. 2. Enter the issue information. Refer to the TestTrack help for more information. 3. Click Add when you finish entering the issue information. The issue is added to the TestTrack project and listed in the issues list. 258

275 Editing TestTrack issues Editing TestTrack issues You can edit issues when you are attaching source files from Surround SCM. Note: You must use TestTrack 2011 or later to edit issues. 1. When you are attaching files to TestTrack, select an issue and click Edit on the Issues tab. The Edit Issue dialog box opens. 2. Make any changes. 3. Click OK to save the changes in the TestTrack project. Fixing TestTrack issues You can optionally mark issues as fixed when you attach source files. Note: Issues that require electronic signatures cannot be fixed from Surround SCM. 1. Select the files or repository and choose Activities > Attach to TestTrack. The TestTrack Browser dialog box opens. 2. Select a TestTrack Connection for the project you want to access. The issues list is populated with your assigned issues. Select a filter from the Filtered By list to display specific issues. 3. Select the issues you want to attach the files to. To select multiple issues, Ctrl+click each issue. A read-only description is displayed when you select an issue. Tip: Select an issue and click View to view detailed issue information. See Viewing TestTrack items, page Click Attach to attach the files to the selected issues. The Attach to TestTrack dialog box opens. Issues you selected are displayed in the Pending Attachments list. If you attach an issue by mistake, select it and click Remove. 5. Select the issues you want to fix and click Fix. The Fix dialog box opens. 259

276 Finding files attached to TestTrack items 6. Enter the fix information. 7. Click OK. The file is attached to the issue and the issue is marked as fixed. Finding files attached to TestTrack items 1. Choose Edit > Advanced Find Files. The Advanced Find dialog box opens. 2. Select the issue number, test case number, or requirement number restriction. The Restriction dialog box opens. 3. Select a TestTrack Connection. 4. Enter or select search criteria. 5. Click OK. The restriction is added. The restriction values are displayed in the Restrictions list and the Summary field. Note: To change the restriction value, double-click the value in the Restrictions list. 6. Repeat steps 2-5 to add additional restrictions. 7. Select Search recursively to search the selected repository and any subrepositories. 8. Click Find to search for the files. Files that meet the criteria are displayed. The Find files results filter is applied. 260

277 Analyzing issue risk in files Analyzing issue risk in files You can analyze risk to predict potential problems in source files attached to issues and identify files that may need attention. For example, you may want to analyze risk to identify high risk files that have priority for code review or that need an owner or workflow state change. Risk scores are calculated based on the number of issues files are attached to during a specified time period. Files with higher risk scores compared to related files are more likely to have unresolved problems. Reviewing files with higher scores can help you address problems and prevent issues from making it into builds. See Performing Code Reviews, page 51. Keep the following in mind: To analyze risk, Surround SCM must be integrated with TestTrack or a supported third-party issue tracking tool. See Integrating with TestTrack, page 253 and Integrating with issue tracking tools, page 268. A file's risk score increases each time it is attached to a different issue. If it is attached to the same issue multiple times, only the most recent attach event is considered in the score. Recent attach events contribute more to risk scores than older events. As time passes, attach events contribute less to a file's score. 1. Choose Tools > Analyze Risk. The Analyze Risk window opens. 2. Click Browse and select the branch and repository to analyze. 261

278 Analyzing issue risk in files 3. Select the Analysis settings. Select a TestTrack or external issue tracking tool connection. Risk scores are calculated for files attached to issues in the selected connection. Select All Connections to calculate scores for issues in all connections. Optionally select an Issue filter to limit the issues included in the analysis based on the filter criteria. Filters can only be applied if one issue tracking connection is selected and if filtering is available in the issue tracking tool. Select a duration to Analyze events over. You can analyze risk based on attach events over the last three months, last six months, last year, or all time. Note: If you change the analysis settings, previously calculated risk scores are cleared. You must reanalyze files to calculate risk scores using the updated settings. 4. Select Search expanded history to include attach events from other branches. For example, you can include attach events performed when files were promoted, rebased, or added from another branch. 5. Click Analyze. The risk score is calculated for all files in the selected repository and branch that meet the selected criteria. Files with higher scores compared to other files may need to be reviewed. Tip: Sort the risk score column in descending order to rank the files from highest to lowest risk. 6. Optionally select a filter from the Filter list to limit the files displayed. 7. Select List recursively to display files in subrepositories. 8. Select a file and click a button to perform an action. Button Action View the selected file. See Viewing files in Surround SCM, page 17. View the history of the selected file. See Viewing file history, page 76. View properties for the selected file. See Viewing general file information, page 80. Change the workflow state of the selected files. See Changing workflow states, page 33. Change multiple custom field values for the selected files. See Changing multiple custom fields, page 32. Perform a code review for the selected file. See Reviewing files, page 64. Add the selected files to a code review. See Adding files to code reviews, page 55. View code reviews for the selected file. See Viewing code reviews files are included in, page

279 Selecting TestTrack items Selecting TestTrack items You can search for a TestTrack issue, test case, or requirement to display attached files from when selecting related files to add to code reviews or search for a TestTrack issue to use when duplicating or tracking changes across branches. 1. Select a TestTrack item filter when selecting files to add to a code review or duplicating or tracking changes and click Select. The TestTrack Browser dialog box opens. 2. Select a filter from the Filtered by list to display specific items. The available filters depend on the action you are performing and the filters available in the TestTrack project. 3. Select an item to view the summary and description. You can also click View to view additional item information. 4. Select an item and click Select to use it. 263

280

281 Integrating with Third-Party Applications Surround SCM can be integrated with a variety of third-party IDEs, build tools, issue tracking tools, and other applications, making it easy to work with source control files from the application of your choice. For example, developers can quickly check in and check out files directly from Visual Studio while project managers can access files from Microsoft Office without using the Surround SCM Client. The following resources can help you integrate Surround SCM with third-party applications: Surround SCM Third-Party Integrations lists supported integrations. The Surround SCM Integrations knowledgebase provides integration installation instructions, setup information, and troubleshooting help. Surround SCM integrates with many Windows IDEs and applications that support the Microsoft Source Code Control Interface (SCCI). See Integrating with IDEs and applications that support SCCI, page 267 for information about using Surround SCM as your default source control provider. Surround SCM's issue tracking API provides a dynamic library for creating custom server plug-ins for integration with third-party issue tracking tools. See Integrating with issue tracking tools, page 268 for information about the API and working with issues in an external issue tracking tool in the Surround SCM Client. Surround SCM Custom Client Menus provides information about creating and deploying plug-ins used for adding custom menus or menu items for third-party applications to the Surround SCM GUI Client. Surround SCM integrates with applications that use Content Management Interoperability Services (CMIS) to support source control integration using the Surround SCM CMIS Server. See Integrating with CMIS, page 273. Setting integration options You can set Surround SCM as the default source control provider for supported third-party applications. You must also enable plug-ins that were installed with the Surround SCM Client before using them. Note: The Integrations category is not available on Linux. 1. Choose Tools > User Options then select the Integration category. 265

282 Setting plug-in directories 2. Select Make Surround SCM my default SCCI provider sets Surround SCM as the default source control provider for IDEs that supports the SCCI interface. (Windows only) 3. Select Enable Microsoft Office plug-in to add a Surround SCM menu to Microsoft Office applications. (Windows only) This option makes it easy to access version-controlled Microsoft Word, Excel, PowerPoint, Access, and Project documents. Note: After enabling this option, you must restart any open Microsoft Office applications. 4. Select Enable Windows Explorer plug-in to add a Surround SCM shortcut menu and status icons to Windows Explorer. See Using the Windows Explorer plug-in, page Select Enable Finder plug-in to add a Surround SCM shortcut menu and display status icons to Mac Finder. See Using the Mac Finder plug-in, page Select Enable sscm:// protocol to associate sscm:// addresses with Surround SCM in applications. (Windows only) This option allows you to click hyperlinks in applications, such as an application, to automatically open Surround SCM and select a repository or file. Surround SCM hyperlinks may be included in notifications or provided by other users. See Browsing to files and repositories, page 228. Note: If you use Surround SCM on Mac or Linux, you need to manually configure applications to associate sscm:// addresses with Surround SCM. Refer to the application documentation for information. 7. Click OK to save the changes. Setting plug-in directories You can use plug-ins to add custom menus or menu items for third-party applications to the Surround SCM Client. Surround SCM loads application plug-ins stored in the plugins folder in the Surround SCM application directory by default. You can also add additional plug-in directories for Surround SCM to check. See Surround SCM Custom Client Menus for information about creating plug-ins. 266

283 Integrating with IDEs and applications that support SCCI Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Plug-ins category. 2. Click Add. The Browse for Folder dialog box opens. 3. Select the plug-in directory and click OK. 4. Click OK to save the changes. The changes do not take effect until after the Surround SCM Client is restarted. Plug-in status information is displayed in the User Options dialog box after the client is restarted. Note: If plug-ins cannot load successfully, errors are written to the SCMPluginErrorLog file in the plugins folder in the Surround SCM application directory. Integrating with IDEs and applications that support SCCI Surround SCM conforms to the Microsoft Source Code Control Interface (SCCI) standard and can be integrated with many Windows IDEs and applications. See Surround SCM Third-Party Integrations for a list of supported integrations. Other IDEs that support the SCCI standard may work with Surround SCM, but are not supported by Seapine. To use Surround SCM as the default source control provider for applications that support the SCCI interface, select the Make Surround SCM my default SCM provider option during Surround SCM installation or in user options. See Setting integration options, page 265. After the integration is enabled, you can perform Surround SCM tasks from the corresponding application. Note: Other integration options and plug-ins are available during Surround SCM installation for Windows and other supported platforms. Some integration plug-ins for Unix applications must be manually installed. See the Surround SCM Integrations knowledgebase for setup, usage, and troubleshooting information. 267

284 Integrating with issue tracking tools Integrating with issue tracking tools You can integrate Surround SCM with issue tracking tools to provide a complete change management solution by tracking what changed and why. This allows you to attach source code files from Surround SCM to issues or items managed in an external issue tracking tool. You can also view and fix issues from the Surround SCM Client. When Surround SCM is integrated with an issue tracking tool, you can analyze risk in source files to determine which files may have unresolved problems based on the issue attachment history. See Analyzing issue risk in files, page 261. A server plug-in for the issue tracking integration must be installed in the issueplugins folder in the Surround SCM application directory. See Issue Tracking API documentation in the issueplugins folder in the Surround SCM application directory for information about creating plug-ins. Note: Plug-ins for Bugzilla, JIRA, and Microsoft Team Foundation Server (TFS) can be downloaded from Seapine's Surround SCM Resources page. Entering issue tracking login information You need to enter your issue tracking login information before you can attach files to issues. 1. Choose Tools > Issue Tracking Integration > User Settings. The Issue Tracking Tool User Settings dialog box opens. 2. Enter your username and password. 3. Click OK. You can now attach Surround SCM source files to issues. Attaching source files to external issues You can attach source files to issues in the issue tracking tool you have integrated with Surround SCM. The file information is attached to the issue, making it easy to work with the file from Surround SCM or the issue tracking tool. You can also attach source files to issues when you add files, check in files, promote or rebase files and branches, or view file history. If the files you want to attach are included in a changelist, you can attach the changelist to issues from the Changelists dialog box. See Managing changelists, page Select the files or repository and choose Activities > Attach to Issue Tracking Tool. If you want to select the files to attach by label, choose Tools > Labels, select the label, and click Attach. Ctrl+click the files you want to attach in the Select Files to Attach dialog box and click Attach. 268

285 Attaching source files to external issues The Issue Browser dialog box opens. 2. Select the Connection for the project you want to connect to. The items list is populated with issues from the selected project. Select a filter from the Filtered By list to display specific items. 3. Select the issues you want to attach the files to. To select multiple items, Ctrl+click each item. A read-only description is displayed when you select an item. Click View to view the issue details. See Viewing external issues, page Click Attach to attach the files to the selected issues. The Attach to Issue dialog box opens. Items you selected are displayed in the Pending Attachments list. Click Add to select additional issues to attach to or select an issue and click Remove to remove it. 5. Click Fix to mark the selected issue as fixed. See Fixing external issues, page Click OK to attach the files to the selected issues. The files are attached. Issues that you selected to fix are marked as fixed. 269

286 Viewing external issues Viewing external issues After files are attached to issues, you can view the issue details from Surround SCM. 1. Select the file. 2. Choose Activities > History. The History dialog box opens. 3. Select the file version attached to the issue you want to view. 4. Click View Attached. The read-only View dialog box opens. Fixing external issues You can optionally mark issues as fixed when you attach source files. 1. Select the files or repository and choose Activities > Attach to Issue Tracking Tool. The Issue Browser dialog box opens. Select a filter from the Filtered By list to display specific issues. 2. Select the issues you want to attach the files to. To select multiple issues, Ctrl+click each issue. A read-only description is displayed when you select an issue. Tip: Select an issue and click View Details to view detailed issue information. See Viewing external issues, page Click Attach to attach the files to the selected issues. The Attach to Issue dialog box opens. 4. Select the issues you want to fix and click Fix. The Fix dialog box opens. 5. Enter the fix information. 6. Click OK. The file is attached to the issue and the issue is marked as fixed. Using the Windows Explorer and Mac Finder integrations Native operating system integrations let you access Surround SCM commands directly from Windows Explorer or Mac Finder. File and folder icons indicate the status of working directories and files managed by Surround SCM, making it easy to quickly identify which are new and which are out of date. Integration icon overlays The following icons indicate the status of directories and files: Icon Explanation The local file is the same as the current Surround SCM Server file. 270

287 Using the Windows Explorer plug-in Icon Explanation The local file was modified and does not match the Surround SCM Server file. A newer version was checked in and the local file is no longer current. A newer version was checked in after you modified the local file. The directory is mapped as a Surround SCM working directory. Note: Status icons are not displayed in directories with more than 1000 files. Using the Windows Explorer plug-in The Windows Explorer plug-in provides access to Surround SCM actions and displays icons to indicate the status of directories and files. You can install the plug-in when you install Surround SCM. Note: You must use single sign-on or select the Always log in with this username and password option in the login dialog box or User Options dialog box. See Setting general user options, page Right-click a file or directory in Windows Explorer and choose Surround SCM to access Surround SCM actions. 2. Choose one of the following actions. Action Use to: More information Add Add the file to Surround SCM. Adding files to Surround SCM, page 28 Check In Check in the updated file. Checking in updated files, page 24 Check Out Check out the file. Checking out files, page 21 Get Retrieve a copy of the file. Getting files, page 15 Undo Check Out Discard changes and check in the file. Undoing check out, page 23 Launch Surround SCM Open Surround SCM. If a working directory is selected, the branch and repository mapped to the directory is selected in Surround SCM. 271

288 Using the Mac Finder plug-in Action Use to: More information Show Icon Overlays Display or hide Surround SCM status icons on directories and files. Integration icon overlays, page 270 Using the Mac Finder plug-in The Mac Finder plug-in provides access to Surround SCM actions. You can install the plug-in when you install Surround SCM. You must use single sign-on or select the Always log in with this username and password option in the login dialog box or User Options dialog box. See Setting general user options, page 8. You can customize the Surround SCM actions available in the Services menu. Choose System Preferences > Keyboard & Mouse and click Keyboard Shortcuts. 1. Select a file or folder and choose Finder > Services to access Surround SCM actions. 2. Choose one of the following actions. Action Use to: More information Add Add the file to Surround SCM. Adding files to Surround SCM, page 28 Check In Check in the updated file. Checking in updated files, page 24 Check Out Check out the file. Checking out files, page 21 Get Retrieve a copy of the file. Getting files, page 15 Undo Check Out Discard changes and check in the file. Undoing check out, page 23 Launch Surround SCM Open Surround SCM. If a working directory is selected, the branch and repository mapped to the directory is selected in Surround SCM. 272

289 Integrating with CMIS Integrating with CMIS You can access files and perform Surround SCM actions in applications that use Content Management Interoperability Services (CMIS) to support source control integration, such as Adobe Drive and CMIS Workbench. The integration requires a connection to the Surround SCM CMIS Server, which hosts CMIS repositories mapped to repositories on the Surround SCM Server. See Managing the Surround SCM CMIS Server, page 423 for information about setting up the CMIS Server. Configuring the integration You must configure a connection to the Surround SCM CMIS Server in the CMIS client application before you can access Surround SCM files and actions. Ask the Surround SCM administrator for connection information. Note: To integrate with Adobe CS5 and later applications, you must use Adobe Drive 2.1 or later to connect to the Surround SCM CMIS Server. See Surround SCM Adobe Illustrator, InDesign, and Photoshop Integration for setup, usage, and troubleshooting information. Performing Surround SCM actions After connecting to the CMIS Server, you can add files, check out files, check in files, undo check outs, remove files or repositories, and view file history. Refer to the CMIS client s documentation for information about working with source control files. When you check out a file from a CMIS client, a writable copy is checked out exclusively to you on the Surround SCM Server, but a local copy is not retrieved to your working directory. CMIS clients communicate with the Surround SCM Server through the CMIS Server and to access the writable version of checked out files, you must use the same CMIS client to perform all actions on source control files. You cannot check out files checked out by other users. 273

290

291 Setting Up Surround SCM A Surround SCM administrator must perform the following tasks to configure Surround SCM before users can access files under source control. 1. After installation, make sure the Seapine License Server and Surround SCM Servers are started. See Starting the Seapine License Server, page 275 and Starting the Surround SCM Server, page Start the Surround SCM Client and log in. See Starting Surround SCM, page Create a mainline branch. You must create at least one mainline branch before users can add source files. See Creating mainline branches, page Create security groups. Security groups control the functionality a group of users has access to. You can add as many or as few security groups as you need and make the security as specific as you need. You may want to create one default security group and then create other groups based on the default settings before assigning users to groups. See Controlling Security and User Access, page Add users and then add them to security groups. You can add new users in Surround SCM or retrieve global users from the Seapine License Server. User must be in a security group to use Surround SCM. See Managing users, page Configure the Surround SCM Server. The Surround SCM Server is managed from the Surround SCM Client. You can change server settings, such as mail, logging, and database settings. See Configuring the Surround SCM Server, page Optionally configure proxy servers. If remote sites need access to Surround SCM files, you can configure proxy servers to improve file retrieval. See Using Proxy Servers, page 413. Starting the Seapine License Server An administrative user must make sure the Seapine License Server is running before the Surround SCM Server is started. Tip: If Surround SCM cannot connect to the license server, an administrative user needs to troubleshoot. See Surround SCM Cannot Connect to the License Server for information. Windows If the license server is installed as a service, it starts automatically. If the license server is installed as an application, you must start it manually. Choose Programs > Seapine Software > Seapine License Server > Seapine License Server from the Start menu. Note: If the server is installed as a service but not running or you need to restart it, see the Windows documentation for information about starting a service. 275

292 Starting the Surround SCM Server Linux Enter /usr/bin/spls start. If you need to restart the server, enter /usr/bin/spls stop and then restart the server. Starting the Surround SCM Server An administrative user must make sure the Surround SCM Server is running before users can access Surround SCM. Windows If the Surround SCM Server is installed as a service, it starts automatically. If the server is installed as an application, you must start it manually. Choose Programs > Seapine Software > Surround SCM > Surround SCM Server from the Start menu. Note: If the server is installed as a service but not running or you need to restart it, see the Windows documentation for information about starting a service. Linux Enter /usr/bin/surroundscm start. If you need to restart the server, enter /usr/bin/surroundscm stop and then restart the server. 276

293 Controlling Security and User Access Surround SCM includes extensive security options that can be configured to provide as much or as little security as needed. Most organizations only need to configure group, or server-level, security. You can also set repository and branch security. Group users by role or function before you start configuring security and adding security groups. It may be helpful to create a list of the types of users who access Surround SCM. Also consider your company s process and define roles and permissions accordingly. A strong security model allows you to be flexible in assigning access without risking data integrity. The following questions can help you get started: What types of users need access to Surround SCM? For example, project leads, programmers, and testers. What activities can users in the group perform? For example, access to promote and rebase files. Which repositories can the users in the group access? For example, restrict teams to specific repositories. How does the build process work? For example, apply read-only branch security after a software release. Note: A project team might include one or more of the following: An administrator with access to all commands. A project lead who has access to most commands but is restricted from such things as creating mainline branches, adding users, or editing server options. One or more developers with access to most file and branch commands but are restricted from most admin, user, and group commands. One or more testers who only have access to basic commands, such as getting and viewing files. A customer who is restricted to viewing one repository. Security levels Access to Surround SCM actions, such as adding files or deleting branches, is controlled by the security group that users belong to. Many organizations only need to configure this type of security. However, there may be times that you want to override the security for a specific repository or branch. In these cases, you can configure repository security or branch security. See Security examples, page 278 for additional information. Security Type Server Repository Branch Description Restricts the activities that users can perform in branches and repositories. Globally applies to all mainline branches, branches, and repositories. Controlled by security groups. See Controlling access with security groups, page 279. Restricts the activities that users can perform in a repository. Applies to a specific mainline branch, across all branches in the mainline, and to a specific repository. See Controlling access to specific repositories, page 283. Restricts the activities that users can perform in a branch. Applies to a specific mainline branch, to a specific repository, and to a specific branch. See Controlling access to specific branches, page

294 Security examples Security examples The following sample scenarios are provided to help you understand how the different security levels work. Depending on your company s needs and business processes, you may only want to set server security. If your needs are more complex, or your business process dictates restricting users to specific data, you may decide to set repository and/or branch security. WysiCorp, a fictional company, develops customized software applications for multiple customers. Many of these customers are competitors and require a high level of security and confidentiality. To ensure that all development goals are met, WysiCorp s development teams, TeamA and TeamB, are assigned to one company for the duration of a project. Other teams, such as Project Leads and QA, may be assigned to more than one company at a time. WysiCorp, the mainline branch, includes the following repositories: Client and Server. The Client repository includes two subrepositories, CompanyA and CompanyB. The CompanyA subrepository includes two baselines branches, Development and Released. Server security Members of the Project Leads security group are administrators and have access to all commands. Members of the TeamA and TeamB security groups have access to some commands, such as adding files or viewing file history. The QA security group is restricted to read-only security. Repository security WysiCorp does not want TeamA members to have access to the CompanyB subrepository or TeamB members to have access to the CompanyA subrepository. Repository security is applied to the CompanyA and CompanyB subrepositories. The TeamA security group is restricted from viewing the CompanyB subrepository. The TeamB security group is restricted from viewing the CompanyA subrepository. When viewing CompanyA repository properties, the Inherited From column changes from <server level default> to <not inherited> for the TeamB security group. This indicates the server security is overridden. 278

295 Controlling access with security groups Branch security After code is released to customers, it is important to stop development on that code. Branch security is applied to the Released branch in the CompanyA subrepository. The TeamB security group is restricted from viewing the CompanyB subrepository. In addition, all other groups only have list-only access to the Released branch. When viewing CompanyA repository properties, notice the only groups listed are Team B and <All other groups>. In addition, the Inherited From column changes from <server level default> to <not inherited>. This indicates the server security is overridden. Controlling access with security groups The Security Groups window is used to manage security groups and settings. Many users will not have access to this view. This view includes group name, description, and security permissions information. 279

296 Adding security groups Server security is set in security groups. The commands you enable or disable in a security group apply to all repositories and branches in the mainline branch. See Adding security groups, page 280. Server security commands are grouped in the following categories: General Common Surround SCM functions (e.g., Generate Reports, Edit Own Notifications) Admin Administrative commands (e.g., Edit Server Options, Void Check Out) Users User account management commands (e.g., Retrieve User, Delete User) Groups Security group management commands (e.g., Add Security Group) Files File management commands (e.g., Add File, Change File Type) Branch Branch management commands (e.g., Create Baseline Branch, Promote Branch) See Security Commands, page 431 for information about the commands in each category and what they provide access to. Note: Users do not need read/write access to the database directory on the Surround SCM Server. Only the Surround SCM Server requires read/write access to this directory. All access permissions are controlled using the Surround SCM Client and the changes are made by the server in the database. This adds an additional level of security and prevents users from making changes directly to the files using a third-party editor and bypassing version control. Adding security groups Security groups are used to create a security structure for users. Before you create security groups, it may be helpful to list the types of users you are creating and what their roles are. You can add as many or as few security groups as you need. Note: A default Admin group, which has access to all commands, is created when Surround SCM is installed. Carefully consider which users are added to this group. 1. Choose View > Security Groups. 280

297 Adding security groups The Security Groups window opens. 2. Click Add. The Add Security Group dialog box opens with the Users tab selected. 3. Enter a Name and Description. Tip: You may want to include the actions that the security group can perform in the Description field so you do not have to look at every category to determine the purpose of the group. 4. Select a user and click Add to add users to the group. To add multiple users, Ctrl+click each user. 5. Click the Server Security tab to enable or disable access to commands. Make sure you enable or disable commands for all categories. See Controlling access with security groups, page 279 for a list of commands in each category. 281

298 Viewing security groups 6. Click the Notes tab and enter any information about the security group. 7. Click OK to save the security group. Viewing security groups 1. Choose View > Security Groups. The Security Groups window opens. 2. Select the group and click View. The read-only View Security Group dialog box opens. Editing security groups You can edit security group information including permissions. 1. Choose View > Security Groups. The Security Groups window opens. 2. Select the group and click Edit. The Edit Security Group dialog box opens. 3. Click the Users tab to add users to or remove users from the security group. 4. Click the Server Security tab to modify server security. Server security, which is the default security, affects all repositories in the mainline branch. See Controlling access with security groups, page Click the Repository Security tab to modify repository security. Repository security lets you override server security for all branches in the selected repository. See Controlling access to specific repositories, page Click the Branch Security tab to modify branch security. Branch security lets you override server security for the branch. This tab is hidden unless a branch uses its own security. See Controlling access to specific branches, page Click OK to save the changes. 282

299 Duplicating security groups Duplicating security groups If you need to create a security group that is similar to an existing one, you can save time by duplicating and editing an existing group. 1. Choose View > Security Groups. 2. Select a group and click Duplicate. The duplicated security group is created using the name of the existing group with.1 appended to the name. For example, if the existing group is named Development, the duplicated group is named Development Modify the duplicated security group and save the changes. Deleting security groups When a security group is deleted, all of the corresponding historic information is also deleted. 1. Choose View > Security Groups. The Security Groups window opens. 2. Select the security group and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The security group is deleted. Controlling access to specific repositories You can enable or disable file commands at the repository level, which overrides the global security group settings. Security can be modified for any group for the selected repository. Repository security affects all branches in the selected repository. For example, if you have multiple products and development teams, you can configure repository security to restrict each development team to specific repositories. Or, you may have a large number of repositories and only a few security groups. Instead of creating additional security groups, and adding users to those groups, you can set repository level security that restricts the commands users can access. 1. Select the repository and choose Activities > Properties. The Properties dialog box opens. 2. Click the Security tab to configure repository security. The text at the top of the tab explains how the repository security affects other branches. The Group column displays the name of all security groups. The Inherited From column displays where security permissions are set. The Security column displays a summary of the group s security. 283

300 Controlling access to specific repositories 3. Click Modify to change the security. The fields are enabled. 4. Make any changes to security settings. To override permissions for a group, select it, click Override, and enable or disable commands. Click Enable All to enable all commands or click Disable All to disable all commands. To add a security group, click Add and select the group. You can select specific groups set different permissions for each group or select <All other groups> to set permissions that apply to security groups without any security overrides set on the repository. To remove a group, select it and click Remove. You can only remove a group if security is configured for <All other groups>. When a group is removed, it uses the security permissions set for this group. To revert security overrides, select a group and click Inherit. The group inherits the default security permissions set for the server. 284

301 Controlling access to specific branches 5. Select Force all child repositories to inherit these security permissions to apply security to the selected repository and all child repositories. This option applies the permissions you configured to all child repositories and removes any security overrides set in child repositories. 6. Click OK to save the changes. Controlling access to specific branches You can apply security to a branch and override the global security group settings. You can enable or disable file actions for a specific branch in a repository. The security you set only affects one branch in the selected repository. For example, you branch your code into multiple versions. When development starts in a new version, you only want the development group and projects leads to have access to the branch. You can set branch security that restricts all other groups, such as QA or technical writers, from accessing the branch. Note: If you do not have access to a branch or any repositories in it, the branch is not displayed in the Branches tree or Branch menu. If you do not have access to a parent branch but have access to a child branch, the parent branch is displayed as <restricted>. 1. Select a branch and choose Activities > Properties. The Properties dialog box opens. 2. Click the Security tab. 3. Select a Branch Security option. Use security that applies to all branches uses the server-level security settings. Use own security overrides the branch security with the selected value. Copy the security that applies to all branches uses the security applied to all branches but lets you change the permissions for the selected branch. Copy the parent branch s security is available if the parent branch uses its own security or inherits security. Start with no specific security applied uses the server defaults. Inherit parent s security uses the same security as the parent branch. 4. Click OK to save the changes. If you set the branch to use its own security, you need to enable or disable commands for the security groups that can access the branch. See Setting branch security commands, page

302 Setting branch security commands Setting branch security commands You can enable or disable security commands for individual branches configured to use their own security. See Controlling access to specific branches, page Choose View > Security Groups. The Security Groups window opens. 2. Select the group you want to set branch security permissions for and click Edit. The Edit Security Group dialog box opens. 3. Click the Branch Security tab. 4. Click Add. The Surround SCM Repository Browser opens. 5. Select the branch you want to configure security for and click OK. 6. Enable or disable the security commands for the branch. See Files security commands, page Click OK to save the changes. Managing users The Users window is used to manage Surround SCM users. Many users will not have access to this view. This view includes user, username, security group, active/inactive, and license type information. 286

303 Adding users You need to create user accounts before users can access Surround SCM. Keep in mind that users can be created in Surround SCM or in the Seapine License Server. Note: If you create users with the Seapine License Server, you need to retrieve global users. See Retrieving global users, page 289. Adding users Users can be created using the Seapine License Server or Surround SCM. Note: To retrieve global users from the Seapine License Server, see Retrieving global users, page Choose View > Users. The Users window opens. 2. Click Add. The Add User dialog box opens. 287

304 Adding users 3. Enter the First name, MI (middle initial), Last name, and Username. Note: You cannot use System as a username because it is reserved to perform trigger actions. 4. Enter or select additional information on the following tabs. Tab Info Groups License Address Notes Use to: Enter the user's phone numbers and address and create a password. Users can change their passwords when they log in. Add the user to a security group. Users can only access commands added to the security group they belong to and must be assigned to at least one security group. See Adding security groups, page 280 for information about creating security groups. Assign a license to the user. Users cannot log in if they are not assigned a license. See License types, page 288. Enter the user's address. Enter any notes about the user 5. Click OK. The user is added. License types Seapine products include floating and named licenses. Floating licenses are best for users who log in occasionally while named licenses are best for users who log in frequently. 288

305 Retrieving global users A floating license can be used by anyone on the network, up to the limit specified on the Seapine License Server. The license server tracks the number of available floating licenses. When a user logs in, the used floating license number increases by one. If more users than allowed by the floating license try to log in, they are denied access. A named license is dedicated to a specific user and allows the user to run Surround SCM from any computer on the network. Named licenses cannot be shared. Retrieving global users Global users can be retrieved from the Seapine License Server and provided access to Surround SCM. 1. Choose View > Users. The Users window opens. 2. Click Retrieve Global User. The Retrieve Global User dialog box opens. 3. Select the global users you want to add to Surround SCM and click Add. Users with valid licenses assigned to them can now access Surround SCM. Viewing users 1. Choose View > Users. The Users window opens. 2. Select the user and click View. The read-only View User dialog box opens. 3. Click OK to close the View Users dialog box. 289

306 Editing users Editing users You can edit most user information. You can only change the username if renaming usernames is enabled on the Seapine License Server. Refer to the Seapine License Server Admin help for information. Note: Information on the Info and Address tabs cannot be edited for LDAP users. You can edit this information in LDAP. 1. Choose View > Users. The Users window opens. 2. Select the user and click Edit. The Edit User dialog box opens. 3. Make any changes and click OK. Deleting users When a user is deleted, all of the corresponding historic information is also deleted. 1. Choose View > Users. The Users window opens. 2. Select the users and click Delete. You are prompted to confirm the deletion. 3. Click Yes. Viewing licenses in use You can view users who are currently using a Surround SCM license and information about the session. 1. Choose Tools > Administration > Licenses In Use. The Licenses In Use dialog box opens. 2. Click Close when you finish. 290

307 Voiding check out Voiding check out Surround SCM users with admin-level security access can void check outs. This removes the lock on a file and gives other users access to it. Changes users made to the file are not saved. 1. Choose Tools > Administration > Void Check Out. The Void Check Out dialog box opens. 2. Select a user from the Users list. The Checked out files list shows the user s checked out files. 3. Select the files and click Void Check Out. You are prompted to confirm the void. 4. Click Yes. The check outs are voided. 5. Click Close when you finish. 291

308

309 Configuring the Surround SCM Server Surround SCM is a multi-threaded client/server solution. Based on TCP/IP, the Surround SCM Server provides strong, role-based security, strict password rules, and 512-bit encrypted communications. Server options control the overall behavior of Surround SCM and apply to all users. You can set all the options when you set up the server or adjust them over time. Note: Some server options can be overridden for specific mainline branches. See Overriding server options for specific mainline branches, page 374. Options Use to: More information General (Global Server) Merge Server Database RDBMS Connections Caching Logging Servers Notifications License Server Set the local admin password, specify how often to check for new server stylesheets, enable automatic client upgrades, compress server files, and encrypt server communications. Switch from Diff3 to Guiffy for automatic file merges and configure Guiffy options. Change the server database location or convert it to a different RDBMS type. Create and modify RDBMS connections to host mainline branches. Set dynamic branch caching options to control the size of the server cache for improved performance and memory availability. Select the type of information to add to the server log and set options to send when the server log is updated. Specify protocol and connection information used to notifications from Surround SCM. Specify the return address for notifications and the server host name for file links included in s. Configure Seapine License Server connection information, the license server communications password, and global user cache refresh rate. Setting general global server options, page 294 Setting server merge options, page 300 Setting the default server database location, page 386 Adding RDBMS connections, page 389 Setting branch caching server options, page 369 Setting logging options, page 302 Setting server options, page 302 Setting notification options, page 303 Setting Seapine License Server options, page

310 Setting general global server options Options Use to: More information Update Check Check for and download software updates. Checking for new Surround SCM versions, page 307 Auto Update Check TestTrack Integration Issue Tracking Integration Specify how often to automatically check for software updates and receive about product releases. Enable TestTrack integration and edit or sync item field labels. Activate plug-ins to integrate Surround SCM with a thirdparty issue tracking tool. Setting automatic software update check options, page 305 Enabling TestTrack integration, page 401 Activating thirdparty issue tracking plug-ins, page 301 Purge Scheduling Schedule when to purge destroyed data from the database. Scheduling data purges, page 307 General (Mainline) Comments Set default check in, Unicode file, thumbnail size, and large file size options for all mainline branches. Set minimum lengths for comments entered by users when performing specific actions, such as check ins. Setting general mainline options, page 308 Setting minimum comment lengths for actions, page 312 Changelists Set default changelist usage for all mainline branches. Setting changelist server options, page 311 File Names/Extensions Specify filenames or extensions to auto-detect or ignore when adding files. Setting auto-detect and ignore file options, page 312 Setting general global server options You can set general options to change the local admin password, specify how often to look for report stylesheets, automatically upgrade clients to the current server version, and compress files stored on the Surround SCM Server. 294

311 Setting general global server options You can also enable encryption to secure client/server communication. Encryption scrambles data to prevent interception, or eavesdropping, as it passes between clients and the Surround SCM Server. You can use RSA key exchange for stronger encryption keys if your network is potentially insecure or if users log in to Surround SCM from outside of your network. See Securing communication between clients and the Surround SCM Server, page 296 for information about encryption, authentication, and key exchange methods used in Surround SCM. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens with the General category selected. 2. Enter and confirm a new password to change the local SCM admin password. A local SCM admin user is created when Surround SCM is installed. It is strongly recommended that you change the admin password to a unique password. 3. Select a Look for new server stylesheets time interval to set how often the Surround SCM Server should automatically check for new report stylesheets on the server. 4. Select Automatically upgrade Surround SCM clients to the current Surround SCM Server version to enable automatic client upgrading for clients connecting to this server. Selecting this option ensures all users are running the correct version of Surround SCM. 5. Select Compress files stored on the Surround SCM Server to compress files and use as little disk space as possible. 6. Select Encrypt communication between clients and the server to encrypt all communication between clients and the Surround SCM Server, which reduces the likelihood of eavesdropping by hackers. Encryption increases security, but may slightly affect performance. Select this option if your organization s network is secure and no client applications outside of the network communicate with the Surround SCM Server. 295

312 Securing communication between clients and the Surround SCM Server Tip: Always use encryption to keep data secure unless you are evaluating Surround SCM or troubleshooting performance issues. The OpenSSL version used by Surround SCM is displayed. Any vulnerabilities found in OpenSSL are published on the OpenSSL web site. To check if OpenSSL version displayed in Surround SCM has vulnerabilities that impact Surround SCM, check Seapine's knowledgebase or contact Seapine Support for information. 7. Select Use RSA key exchange to use strong key exchange for communication between clients and the Surround SCM Server. RSA is a public key encryption algorithm that uses separate keys for encryption and decryption. Select this option if your organization stores sensitive information in Surround SCM and users log in to client applications outside of your network using a username and password. If you use RSA, the public key must be added to all clients that access the Surround SCM Server. See Configuring RSA key exchange, page 299 for information about setting up RSA. Note: This option is only available if Encrypt communication between clients and the server is selected. 8. Click OK to save the changes. Changing key exchange options If you change key exchange options, Surround SCM client applications and the Surround SCM web and proxy servers must be updated. The following scenarios require further action after changing security settings. If you use: No encryption RSA key exchange And you change it to: RSA key exchange No encryption or basic encryption (Encrypt server communication between clients and the server is selected) You need to: Download a settings file that Surround SCM client users need to import in the server connection settings. If you use Surround SCM Web or proxy servers, import the file in the Surround SCM Registry Utility on the corresponding server computer. Remove the public key fingerprint from any clients that connect to the server. Click Remove in the server connection information in clients and in the options for servers in the Surround SCM Registry Utility. See Configuring RSA key exchange, page 299 for information about adding and removing keys in Surround SCM clients. Securing communication between clients and the Surround SCM Server Keeping your Surround SCM data secure is critical. To prevent hackers from compromising your data, encrypt communication between clients and the Surround SCM Server. 296

313 Securing communication between clients and the Surround SCM Server The following information explains how Surround SCM encrypts data, how authentication works, and how key exchange is used for different authentication methods. See Setting general global server options, page 294 for information about configuring secure client/server communication. Encryption Encryption scrambles data to prevent interception, or eavesdropping, as it passes between clients and the Surround SCM Server. Surround SCM uses the OpenSSL implementation of Advanced Encryption Standard- 256 (AES-256) to encrypt communication between clients and servers in Surround SCM and later. RC4 encryption is used for backward compatibility with earlier Surround SCM and TestTrack versions. Client/server communication is encrypted when you select Encrypt communication between clients and the server in the general global server options. See Setting general global server options, page 294. Note: Always use encryption unless you are evaluating Surround SCM or troubleshooting a performance issue. Passwords are always encrypted even if client/server communication is not. Login credentials sent from web browsers to the Surround SCM web server via HTTP are not encrypted, even if encryption is enabled on the Surround SCM Server. We strongly recommend using HTTPS to encrypt communication from the browser to the web server. HTTPS connections use a self-signed certificate by default, but you can configure the web server to use your own SSL certificate in the Surround SCM Registry Utility. See the Surround SCM Registry Utility help for information. Authentication Authentication is the process of logging in a user to Surround SCM. The following authentication methods are used in Surround SCM. Authentication method Seapine License Server LDAP How it works The username and mathematical proof that the user knows the password (not the actual password) are sent to the Surround SCM Server. The server sends different mathematical proof that it knows the password to the client. Using single sign-on Credentials proving the user's identity are sent from the LDAP server to the Surround SCM Server and verified. Not using single sign-on The username and password are sent to the Surround SCM Server. External authentication Data from the organization's authentication system is sent to the Surround SCM Server. Key exchange Key exchange is a method of exchanging secret keys over an insecure network connection without exposing them to eavesdroppers. The key exchange method used depends on the authentication method. The following key exchange methods are used in Surround SCM. 297

314 Securing communication between clients and the Surround SCM Server Key exchange method When it is used How it works To use it: Secure Remote Password (SRP) User is authenticated from the Seapine License Server and RSA key exchange is not enabled A shared secret key is generated during authentication. To compromise the secret key or impersonate the server, a hacker must know the user's password. Select Encrypt communication between clients and the server in the general global server options. Diffie- Hellman User is authenticated using LDAP or external authentication, and RSA key exchange is not enabled A mathematical process is used to generate a secret key. To compromise the secret key, a hacker must have control over an intermediate network node or impersonate the real server. Does not protect against man-in-the-middle attacks. Select Encrypt communication between clients and the server in the general global server options. RSA RSA key exchange is enabled in the Security server options The client generates a random, 256-bit secret key and encrypts it with the server's public key. The server hashes the secret key and signs the hash with its private key. The private key is only stored on the server hard drive and never leaves the server. To compromise the secret key or impersonate the server, a hacker must know the server's private key or substitute their own public key in client applications. Select Encrypt communication between clients and the server and Use RSA key exchange in the general global server options. When to use RSA key exchange SRP and Diffie-Hellman are low risk key exchange methods if your organization s network is secure and no client applications outside of the network can communicate with the Surround SCM Server. We recommend using RSA key exchange to prevent hackers from eavesdropping on communication if: Your organization stores sensitive information in Surround SCM. Your network is potentially insecure. Users log in to client applications from outside your network. Users are authenticated to Surround SCM using LDAP, single sign-on, or external authentication. Using RSA requires additional setup for users. See Configuring RSA key exchange, page

315 Configuring RSA key exchange Configuring RSA key exchange RSA is a public key encryption algorithm that uses separate keys for encryption and decryption. You may want to use RSA key exchange if your organization stores sensitive information in Surround SCM and users access the Surround SCM Server using a username and password in client applications outside of your network. If you use RSA key exchange, a public key fingerprint must be imported to all client applications that connect to the Surround SCM Server. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens with the General category selected. 2. Select Encrypt communication between clients and the server and Use RSA key exchange. A public key is generated on the Surround SCM Server. The Fingerprint field displays the public key fingerprint, which is a short version of the public key. Public and private keys are stored in the rsakeys directory in the Surround SCM application directory on the Surround SCM Server computer. Note: If you clear the Use RSA key exchange option, you are prompted that all users will need to modify their server settings. Click Yes if you no longer want to use RSA. Make sure the public key fingerprint is removed from server connection settings in Surround SCM clients and server settings in the Surround SCM Registry Utility for web and proxy servers. 3. Click Download Public Key to save an XML file that contains the Surround SCM Server address, port number, and public key fingerprint. This file must be imported to Surround SCM clients that connect to the server. Make sure the file is securely stored and distributed to users for import. If a hacker has unauthorized access to the file, changes it, and it is imported to clients, your Surround SCM installation could be hacked. Note: The server address in the XML file includes the default hostname of the Surround SCM Server computer. If users connect to the server from outside the local network, you must manually update the server address in the server settings file before providing it to users. 4. Click OK to save the changes. 5. Import the server settings file to Surround SCM clients that connect to the server. Surround SCM Client Provide the server settings file to users so they can import it when configuring a server connection. See Adding server connections, page 5. Surround SCM CLI Provide the server settings file to users so they can save it and provide the file path in the -z command when connecting to the server. See the Surround SCM CLI help for information. Surround SCM Web Import the server settings file in the web server options in the Surround SCM Registry Utility so Surround SCM Web users can log in. See the Surround SCM Registry Utility help for information. Surround SCM Proxy Server Import the server settings file in the proxy server options in the Surround SCM Registry Utility so users can connect to the server. See the Surround SCM Registry Utility help for information. 299

316 Setting server merge options Note: If you suspect the private key on the Surround SCM Server was compromised because of unauthorized server access, regenerate the public and private key pair. Click Regenerate Key Pair and click OK when you are prompted to generate the new keys. If you regenerate the keys, you must download a new server settings file and update all client applications that connect to the server. Setting server merge options By default, the Surround SCM Server uses Diff3 for merging and comparing files. You can also enable Guiffy, which is installed with Surround SCM. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Merge from the Global Server Options category. 3. Select Enable Guiffy for automatic merges to use the Guiffy diff/merge application. You must enable this option if you want to auto-merge Unicode text files. The Diff3 merge application is faster than Guiffy and uses less memory. Each application uses different algorithms for determining conflicts. You may want to use the same application on the client and server computers. 4. Enter the number of MB of memory you want Guiffy to use. The recommended setting is 128 MB. The minimum setting is 96 MB and the maximum setting is 1024 MB. Tip: This setting should not exceed 50% of the server computer s physical memory. Other applications can be negatively affected if you set the amount of memory too high. However, if this setting is too low, large text files may not be merged. 5. Select Ignore case to ignore the case of characters within lines. 300

317 Activating third-party issue tracking plug-ins This is useful if you are comparing or merging files for case-insensitive programming languages. 6. Select Ignore whitespace to ignore spaces and tabs. 7. Select Ignore blank lines to ignore inserted or deleted blank lines. This option only applies to lines that are completely empty. It does not affect lines that look empty but contain space or tab characters. 8. Enter the Tab size. This option sets the number of spaces displayed for one tab character. The default is 8 spaces. 9. To Ignore columns, enter the corresponding column numbers. You can enter two sets of columns. For example, 1-3 and To Ignore regular expressions, enter each expression on its own line. Guiffy supports standard regular expressions. Changed, inserted, or deleted lines that match any of the regular expressions are ignored during the compare or merge. 11. Click OK to save the changes. Activating third-party issue tracking plug-ins You can integrate Surround SCM with issue tracking tools, such as Microsoft Team Foundation Server (TFS) or Bugzilla. A server plug-in for the integration must be installed in the issueplugins folder in the Surround SCM application directory. See Integrating with issue tracking tools, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Issue Tracking Integration from the Global Server Options category. 3. Select an available integration and click Set Active. Note: Only one issue tracking plug-in can be active at a time. However, a single issue tracking integration can be active along with TestTrack integration. 4. Click OK to save the changes. 301

318 Setting logging options The changes do not take effect until after the Surround SCM Client is restarted. You must enter your login information for the issue tracking tool before you can attach source files to issues. See Entering issue tracking login information, page 268. Setting logging options You can set Surround SCM Server log options, such as the level of messages. The log file includes information about problems that occur during start up and while the Surround SCM Server is running. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Logging from the Global Server Options category. 3. Select a Write to server database option to indicate the types of messages written to the Surround SCM Server log file. 4. Select a Write to NT event log option to indicate the types of messages written to the server s NT log. 5. Select a Send notification option to indicate the types of server messages that generate notifications. Select No Logging if you do not want to generate notifications. 6. Select Send notification when logins fail to a specific user when a login attempt fails. 7. Enter the send to address and return address. Separate multiple addresses with a semicolon. 8. Select Write all message to SCMStartup.log to write messages to the SCMStartup.log file. The log file is generally stored in the same directory as the Surround SCM Server executable. 9. Select Log warning if the Surround SCM Server is not started as an NT service to log a warning if the server is not started as a service. 10. Click OK to save the changes. Setting server options You must enable and configure settings before notifications can be sent from Surround SCM. 1. Choose Tools > Administration > Server Options. 302

319 Setting notification options The Server Options dialog box opens. 2. Select Servers from the Global Server Options category. 3. Select Enable sending mail via Simple Mail Transport Protocol to send via SMTP. 4. Enter the SMTP information. Enter the Host used to send outgoing mail. Enter an IP address (e.g., ) or the fully qualified domain name of the mail server (e.g., mail.yourcompany.com). Select the SSL security protocol to use to encrypt communication between the mail server and the Surround SCM Server. You can use the Negotiate, SSL 3.0, STARTTLS 1.0, or TLS 1.0, 1.1, or 1.2 protocols. Select <not set> if you do not want to use a secure protocol. Enter the Port number. The default port is 465 if you select an SSL protocol and 25 if you do not. Enter the Username and Password if the SMTP host requires an authenticated login. Leave these fields empty if the host does not require authenticated login. 5. Click Test Connection to test the SMTP connection. If the test fails, check the settings and contact your system administrator for help. 6. If you are experiencing SMTP problems, select the following options to help with troubleshooting. Pause sending via SMTP stops sending via SMTP. Make sure you clear this option as soon as the problem is resolved because outgoing mail will back up in the queue. Only send one message per SMTP connection to send one message per connection. 7. Click OK to save the changes. Setting notification options You can set the return address and options used for notifications. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Notifications from the Global Server Options category. 303

320 Setting Seapine License Server options 3. Enter a notification Account name. 4. Enter a notification account address. 5. Select Always use the notification account for the return address to use the notification account. 6. Select Only use notification account if the logged in user s address is blank to use the notification account if the logged in user did not provide an address. 7. Enter a Server host name for file links to set the network address to use with file hyperlinks sent in notifications. Surround SCM uses the hostname of the Surround SCM Server computer. Make sure you use a network address that all computers can resolve, such as an IP address. You may want to use the same address that is provided to users when they set up a Surround SCM Server connection. Note: Hyperlinks do not work if notifications are sent to users with computers that cannot resolve the hostname (for example, computers in a different subnet). 8. Click OK to save the changes. Setting Seapine License Server options 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select License Server from the Global Server Options category. 304

321 Setting automatic software update check options 3. Enter the address and port number of the Seapine License Server you want Surround SCM to connect to. 4. Optionally enter a License server communications password. This password provides additional security and prevents unauthorized Surround SCM or TestTrack users from using the licenses. Note: If a communications password is set on the license server, Surround SCM must use the same password to communicate with the license server. 5. Select a Cache refresh rate. 6. Click Test Connection to test the license server connection. If the connection is not successful, check the address, port number, and password. 7. Click OK to save the changes. Setting automatic software update check options You can configure Surround SCM to check for updates or notify you about beta releases. Software is not automatically downloaded or installed. The Surround SCM Server encodes the following information and sends it to the Seapine update server, which returns update information. Unique user ID A unique ID, generated by the Surround SCM Server, that is used to identify each Surround SCM Server. It does not include any information that identifies your company or users. Surround SCM version The Surround SCM version installed on the Surround SCM Server. Operating system and version The operating system and version of the Surround SCM Server computer. Configuration settings Specifies if the following settings are configured: multiple mainlines, inactive branches, caching of branches, triggers, changelists, product update s, comments required, SMTP, custom fields, workflows, shadow folders, TestTrack integration, reports, and filters. 305

322 Setting automatic software update check options Connection timestamps The timestamps for when Surround SCM clients connect to the Surround SCM Server. This information also includes the specific type of Surround SCM client that connected to the server, the browser used if the client is Surround SCM Web, and the client operating system. Server type Specifies if the Surround SCM Server is a 32-bit or 64-bit server. Number of mainlines per RDBMS database type The number of mainline branches in each RDBMS database type. Number of external reports The number of external reports added to Surround SCM. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Auto Update Check from the Global Server Options category. 3. Automatically check for Surround SCM updates is enabled by default. After an upgrade check is performed, the corresponding information is displayed in the Update Check category. Tip: To manually check for updates, select the Update Check category and click Check for update. 4. Select any Update Check Options. Enter how often Surround SCM should check for updates. Select Send notification for product updates to be notified when product updates are available. The notification includes the available version and the release notes. If this option is selected, the release options are also enabled. Select the type of releases you want to be notified about. Select Send notification for upcoming beta releases to be notified about beta programs. Enter your information if you enabled either notification option. 5. Click OK to save the changes. 306

323 Checking for new Surround SCM versions Checking for new Surround SCM versions You can manually check for and download Surround SCM software updates. Upgrades are not installed automatically. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Update Check from the Global Server Options category. 3. Click Check for update. The Surround SCM Server and operating system version information is sent to Seapine. This information is only used to provide you with current update information. Note: If an update is available, the version number and release notes are displayed. If you want to download the update, click the link to go to Seapine s web site. 4. Click OK to close the Server Options dialog box. Scheduling data purges When Surround SCM data is destroyed, it is marked for deletion from the database. By default, a background process run by the Surround SCM Server periodically purges destroyed data. If a large amount of data needs to be purged, the process may take a long time and affect other database maintenance tasks, such as RDBMS backups. You can schedule when to purge destroyed data to ensure the process does not interfere with other tasks. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Purge Scheduling from the Global Server Options category. 307

324 Setting general mainline options 3. Select a purge scheduling option. Automatically purge destroyed data purges data automatically when the Surround SCM Server maintenance background process runs. We recommend selecting this option to ensure database space is freed up soon after data is destroyed. Schedule purge to run purges data on the specified day and time each week. Never purge destroyed data disables purges. We do not recommend selecting this option because destroyed data uses database space until purging is enabled. If data is not purged, you could run out of database space. 4. Click OK to save the changes. Setting general mainline options You can set options to control how keywords, check outs, Unicode files, thumbnails for image files, and large files are handled. Note: These options apply to all branches and users, but can be overridden for specific mainline branches. See Overriding server options for specific mainline branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select General from the Mainline Options category. 308

325 Setting general mainline options 3. Select Expand keywords to enable keyword expansion. Keywords are case-sensitive placeholders that can be inserted into text files and expanded when files are viewed or checked in. See Supported keywords, page Select Allow multiple users to check out a file to enable multiple check outs of the same text file. Allowing multiple check outs can increase productivity because users can work on the same files in parallel without waiting for files to be checked in. Changes are auto-merged when users check in files. Note: Binary files are always exclusively checked out. 5. Select Allow check in of files without check out to allow users to check in files that are not checked out. If this option is selected, when users check in a repository, all checked out files and any files in a Modified status are checked in. You may want to select this option if users previously used another source control tool that supports checking in files without check out and prefer this method. Note: We do not recommend selecting this option because it provides less control over files. 6. Select Allow workflow state changes during check in to allow users to change file states during check in. You may want to disable this option if you use triggers to set states during check in. 7. Select any Unicode File Options. These options are used when auto-merging text files. 309

326 Supported keywords Note: The international version of the Java Runtime Environment (JRE) contains character conversion classes and support for locales other than the US English locale. If you use this JRE you can enter the character encoding set you want to use. Refer to Guiffy s Help file for a list of all supported character sets. Select Auto-detect Text files as type UTF-8 Text if all files are Unicode or Unicode standards are not followed (e.g., files do not begin with a Byte Order Mark indicating they are Unicode). For example, select this option if you are adding 500 files and only a few are text files. You can then go to file properties to mark the text files. Select Use UTF-8 encoding for all Text file auto-merges to automatically use UTF-8 encoding when auto-merging text and UTF-8 files. Select a UTF-8 character encoding set. Select a UTF-16 character encoding set. 8. Enter the Thumbnail size to set the thumbnail pixel size. The default size is 128 by 128 pixels. Tip: If you change the thumbnail size, you can also compact the database to purge the existing, cached thumbnails. 9. Enter or select the maximum file size for adding or checking in Large Files. Maximum file size specifies the maximum file size limit. The default value is 2000 MB. Delta maximum file size specifies the file size limit before Surround SCM starts adding or checking in full copies of updated files instead of only differences between versions, or deltas. The default value is 100 MB. 10. Click OK to save the changes. Supported keywords Keywords are case-sensitive placeholders that can be added to text files. When viewing, getting, or checking in files, Surround SCM looks for keywords and automatically embeds the corresponding information. For example, Pat checks in a file that includes the $Author$ keyword. Surround SCM replaces the keyword with $Author: PatUser$. Note: Keywords cannot be expanded for binary files. Keyword $Archive$ $Author$ $Branch$ $Date$ $File$ Value Repository path and filename User who checked in last file revision Branch name Date and time of last check in Unqualified filename 310

327 Setting changelist server options Keyword $Header$ $JustDate$ $Log$ $Logfile$ $Modtime$ $NoKeywords$ $Revision$ $Workfile$ Value File, Revision, Author, Date Date of last check in Dates and times the modified file was checked in Repository path and filename Date and time of last modification (same value as timestamp column) Disables expansion of keywords that follow it Revision number (branch relative) Unqualified filename Setting changelist server options Changelists are used to group file transactions together. See Using Changelists, page 123. You can set options to enable or disable changelists, and to retain historical information. Note: These options apply to all branches and users, but can be overridden for specific mainline branches. See Overriding server options for specific mainline branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Changelists from the Mainline Options category. 3. Select a Changelist Usage option. 4. Clear Retain historical changelist information if you do not want to store changelist data. Historical data is discarded when a changelist is committed. 5. Click OK to save the changes. 311

328 Setting minimum comment lengths for actions Setting minimum comment lengths for actions You can set the minimum number of characters that users must enter in comment fields when performing actions. By default, comments are not required for any actions. Setting minimum comment lengths can help enforce your policy to provide comments when performing actions, which can be helpful for historical purposes. Note: These options apply to all branches and users, but can be overridden for specific mainline branches. See Overriding server options for specific mainline branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Comments from the Mainline Options category. 3. Enter the minimum number of characters required for comments for each action. Valid values are If you do not want to require comments for an action, enter Click OK to save the changes. Setting auto-detect and ignore file options You can configure Surround SCM to auto-detect or ignore files based on the filename or extension. Setting file types will automatically assign a file type to files with specified extensions when they are added to Surround SCM. Ignoring files by extension, name, or directory name will exclude files from being added to Surround SCM when users recursively add files. 312

329 Setting auto-detect and ignore file options Note: These options apply to all branches and users, but can be overridden for specific mainline branches. See Overriding server options for specific mainline branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select File Names/Extensions from the Mainline Options category. 3. Select a file type and click Edit. The Map File Extensions to File Type dialog box opens. 4. Enter the file extension. 5. Click OK. The file extension is added. Note: To remove a file extension, select the file type and click Edit. Delete the extension in the Map File Extensions to File Type dialog box. 6. Enter file extensions you want Surround SCM to ignore in the Ignore file extension field. 313

330 Configuring default user options 7. Enter the file or directory names you want Surround SCM to ignore in the Ignore file or directory name field. Tip: You can use an asterisk (*) as a wildcard for file and directory names. For example, *uninstall ignores all files or directories that end in "uninstall". Ignore file or directory name settings are case sensitive. 8. Click OK to save the changes. Configuring default user options Administrators can set default user options for Surround SCM clients that connect to the server. You may want to configure user options to help introduce new users to how you use Surround SCM in your organization or to ensure all users are using the same required settings. By default, users have full control over user options. To configure user options on the server, you need to specify how the selected user options are applied. Default user options are set as the default for new clients that connect to the server, but users can change the settings at any time. Required user options are set in all clients that connect to the server, and users cannot change the settings. Note: User options that were set as required are changed in Surround SCM clients for existing users. User options set as default for existing users are not changed in Surround SCM Clients. 1. Choose Tools > Administrations > Default User Options. The Default User Options dialog box opens. 2. Select the category you want to set default user options for. 314

331 Configuring default user options Category Use to: More information General Diff/Merge View/Edit File File Dialog Defaults Source Tree Proxy Server File Manager (Linux only) Enable external authentication, compress file transfers, specify text file format, set the file comparison option used when updating and retrieving files, and view HTML reports. The client-level general user options also include options to set a username and password to connect to the server, use single sign-on, and override the local computer name, but these cannot be set on the server. Specify applications to diff and merge files, add new diff applications, and configure Guiffy, the integrated diff/merge application. Specify applications to view and edit files from Surround SCM. Enable or disable changelists, merge and differences, local directory creation, and code review settings for file action dialog boxes. Control information displayed in the Source Tree window and actions in the branch, repository, and file list shortcut menus. Set the default proxy server and compress file transfers from servers. Specify the Linux file manager to open working directories. Setting general user options, page 8 Configuring diff application options, page 47 and Configuring merge application options, page 48 Setting viewer/editor options, page 17 Changing defaults for Surround SCM dialogs, page 94 Setting Source Tree options, page 90 Setting proxy server options, page 419 Setting the file manager on Linux, page 14 Plug-ins Specify the directories used to load custom plug-ins. Setting plug-in directories, page Select an option to specify how the user options should be applied and make any changes to the default user options. 4. Click OK to save the changes. 315

332 Configuring default user options The default user options are set in clients when they connect to the server for the first time. 316

333 Configuring Custom Fields Surround SCM automatically captures data about files, such as modification date, file type, and size. You can use custom fields to capture additional file-specific information, such as a file description. Custom fields can be displayed in the source file list and the file Properties dialog box, and can also be used with filters, reports, triggers, and notifications. Following are some examples of how custom fields can be used: Create a Do Not Modify check box field to indicate files that should not be changed. With triggers to enforce a workflow process, create a code validation or review process (e.g., create a Code Reviewed check box field), or automate a build process. See Automating Actions with Triggers, page 321. Create a Release custom field to track the release a change is assigned to. Note: See Setting custom fields, page 31 for information about setting field values. To set field values, the Set Custom Field Values command must be enabled in the Files (Default) category. See Controlling access with security groups, page Choose Tools > Administration > Custom Fields. The Custom Fields dialog box opens. Tip: Surround SCM includes the following default custom fields: Owner, Assigned, and Due Date. You can delete these custom fields if you will not use them. 2. Click Add to create a custom field. See Adding custom fields, page Select a field and click Edit to edit it. See Editing custom fields, page Select a field and click Top, Move Up, Move Down, or Bottom to change the display order in lists, menus, and dialog boxes. 5. Select a field and click Delete to delete it. See Deleting custom fields, page Select Show deleted custom fields to view deleted custom fields. Deleted custom fields are only displayed in the Custom Fields dialog box. Deleted fields can also be restored. See Restoring deleted custom fields, page

334 Adding custom fields Adding custom fields Add custom fields to capture additional file information. For example, you can add a text field used to enter a file description or a list field used to select the release file changes are related to. 1. Choose Tools > Administration > Custom Fields. The Custom Fields dialog box opens. 2. Click Add. The Add Custom Field dialog box opens. 3. Enter a Field name. 4. Enter a Field code. Field codes are used with triggers. See Automating Actions with Triggers, page Select a Field Format. Text Users can enter free-form, alphanumeric text. Integer Users can enter a numeric value without decimals. Float Users can enter a numeric value with decimals or signs, such as + or -. List Users can select a value from a list of multiple custom values. SCM User Users can select a user from a list of all users on the Surround SCM Server. Date/Time Users can enter a date/time stamp in the following format: mmddyyyy hh:mm:ss. Check Box Users can select or clear a check box. Tip: Integer and float field minimum and maximum values are enforced when a value is entered in the custom field. 6. Enter or select the Field Properties. The available properties depend on the selected field format. The default value is set on files when they are added to Surround SCM. 7. Click OK to save the custom field. Note: You can view custom field values on the Custom Fields tab in the file details pane or add custom field columns to the source file list. See Using the file details pane, page 73 and Customizing the Source Tree window, page

335 Editing custom fields Editing custom fields You can edit custom fields to change the name, field code, and other properties. Note: You cannot change the field format. Create a new custom field if you need to change the format. 1. Choose Tools > Administration > Custom Fields. The Custom Fields dialog box opens. 2. Select a custom field and click Edit. The Edit Custom Field dialog box opens. 3. Make any changes. 4. Click OK to save the changes. Deleting custom fields When a custom field is deleted, it is not permanently deleted from the Surround SCM Server. It is removed from the list of available custom fields and users can no longer select it. Note: Values set on files are not deleted from the database when custom fields are deleted. 1. Choose Tools > Administration > Custom Fields. The Edit Custom Fields dialog box opens. 2. Select Show deleted custom fields. 3. Select a custom field and click Delete. You are prompted to confirm the deletion. 4. Click Yes. The custom field is deleted. Restoring deleted custom fields You can restore deleted custom fields. 1. Choose Tools > Administration > Custom Fields. The Edit Custom Fields dialog box opens. 2. Select Show deleted custom fields. 3. Select a deleted custom field and click Restore. The custom field is restored. 319

336

337 Automating Actions with Triggers In-application programmable triggers allow you to extend Surround SCM s functionality to better fit your company s change management process. Triggers can be used to automate workflow state transitions, enforce workflow rules, send notifications, run external applications, modify custom fields, perform data validation, log information, and more. For example, use triggers to automate manual source file management tasks, such as copying files to a web server when they reach a certain branch level. When you create a trigger, you set the items the trigger applies to, the events that cause the trigger to run, and the actions to perform. Triggers can send s, run executables, prevent users from performing events, add comments to events, change file workflow states, and change custom field values. When triggers can run The following events can cause triggers to run: File is created, enters a specific workflow state, version is updated, or changes for any reason Code review file changes for any reason Code review changes to a specific status, is awaiting review (runs nightly), or changes for any reason Event is performed on a file, code review, or code review file Changelist is committed Custom field value changes Note: Surround SCM performs triggers as the System user, which is displayed as the user who performed trigger actions in the file history and reports. Pre-event triggers Pre-event triggers perform an action when a client requests that an event be performed, but before the event is complete on the Surround SCM Server. Pre-event triggers can be used to perform the following actions: Run server-side executables (scripts and compiled programs) Prevent users from performing file events Add comments or append text to comments that users enter on file events Post-event triggers Post-event triggers perform an action after an event is successfully completed on the Surround SCM Server. Post-event triggers can be used to perform the following actions: Run server-side executables (scripts and compiled programs) Send s Change custom field values Change workflow states 321

338 Trigger examples Trigger examples Triggers can be even more powerful when they are used with the Surround SCM workflow and custom fields. The following examples provide some common tasks that you can automate using triggers. Assign files for code review after they are checked in If you use the default Surround SCM workflow and the Assigned custom field, you can create a post-event trigger to run when a file version is updated. You can create trigger actions that automatically set the workflow state to Awaiting Review, set the Assigned custom field to the user who performs code reviews, and send an notification to the reviewer. Prevent users from checking out files in a specific workflow state If you use the Surround SCM workflow and have a Reviewers security group, you can prevent users who are not in the group from checking out files in the Awaiting Review state. You can create a pre-event trigger with an action to prevent check out and display a message such as "Only reviewers can check out files awaiting review". Start a build based on a custom field value change You can create a check box custom field named Start Build and create a post-event trigger to run when this field is selected. You can create trigger actions that run your build script on a server computer and clear the Start Build check box. Send files to an FTP server when a specific workflow state is selected If you use the Surround SCM default workflow, you can create a post-event trigger to run after a file s workflow state changes to Released. You can create a trigger action that runs a script that sends files to an FTP server. Configuring triggers You can configure triggers to automatically perform actions when users change files and code reviews. For example, you can add a trigger to users when a file is assigned to them or prevent users from checking out files in specific workflow states. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. The Summary field displays the files that the trigger applies to, the events that cause the trigger to run, and the actions to perform if the events occur. 322

339 Adding triggers Note: If a trigger includes more than one instance of an action, the number of instances is displayed next to the action. For example, (3). 2. Select an Action to filter the trigger list by action. You may want to select an action if the list includes a large number of triggers. 3. Click Add to create a trigger. See Adding triggers, page Select a trigger and click Edit to change it. See Editing triggers, page Select a trigger and click Duplicate to duplicate it. See Duplicating triggers, page Select a trigger and click Disable to disable it. See Disabling and enabling triggers, page 335. Tip: Select a disabled trigger and click Enable to enable it. 7. Select a trigger and click Delete to delete it. See Deleting triggers, page 335. Adding triggers You can add triggers to initiate actions based on events that users perform on files. Before you add a trigger, take the time to define the following: The event or activity that causes the trigger to fire The criteria (preconditions) the trigger will use to select the files that initiate the action The action the trigger performs 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 323

340 Adding triggers 3. Enter a Trigger Name. 4. On the Trigger When tab, select the events that cause the trigger to run. Select Perform trigger before event occurs or Perform trigger after event occurs to indicate when you want the trigger to run. Pre-event triggers are only available if the when the file version is updated, when the file is created, or on an event option is selected. Note: Some available events for the on an event option can only be used in post-event triggers, such as Remove and Duplicate Changes. Select the event that causes the trigger to run. If an event requires you to select a value, the Trigger When dialog box opens. Select a value and click OK. The value is displayed in the events list and Summary field. Double-click a value in brackets to change it. 324

341 Adding triggers 5. Click the Preconditions tab to set the condition that files must meet to run the trigger. 6. Select a precondition. The Precondition dialog box opens. You can add preconditions based on branch and repository, filename, committed changelists, workflow states, users performing file events, security groups for users performing file events, or custom field values. Note: The in branch [<all branches>] and in repository [<all repositories>] precondition is selected by default. The trigger runs for every file if you do not select additional preconditions. The Preconditions dialog box does not open if you select the is part of a changelist commit precondition. 7. Enter or select the precondition values. Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding restrictions, page

342 Adding triggers to run executables 8. Click OK. The precondition values are added. The values are displayed in the conditions list and the Summary field. 9. Repeat steps 6-8 to select any additional preconditions. To change a precondition value, double-click the value in the list. When you add more than one precondition, Surround SCM treats them as and conditions. Triggers only fire when all of the selected preconditions are met. 10. Click the Actions tab to select the actions that occur when the trigger runs. Click Add to add an action. See Adding trigger actions, page 333. Select an action and click Edit to change it. See Editing trigger actions, page 334. Select an action and click Top, Move Up, Move Down, or Bottom to change the action order. Select an action and click Delete to delete it. See Deleting trigger actions, page Select Disable trigger after it runs once if you only want the trigger to run once. 12. Click OK to add the trigger. Adding triggers to run executables Note: Pre-event triggers that run scripts can cause performance issues because the Surround SCM Server waits for the script to complete before moving to the next file. Post-event triggers should always be used to run scripts unless the trigger is used for validation. Even a 1 second pre-event script will significantly slow down the server because it takes an additional second per file that the trigger fires on. You can run scripts and compiled programs from both pre- and post-event triggers. Surround SCM accepts any command line call. Pre-event triggers can run server scripts that perform additional checks on files before the event completes. For example, you can create scripts to verify that text is included in specific files before they are checked in. Post-event triggers can run server scripts that perform additional actions after the event is successfully completed on the server. For example, you can create scripts for custom logging of SCM file activity, to synchronize two separate Surround SCM Servers, or start your build process on a server computer. If Surround SCM cannot find the script, an error is returned to the client and the action fails. In addition, if multiple triggers are associated with a file and one trigger fails, the remaining triggers do not run. The server administrator should make sure that the appropriate directory access permissions are set up for the script. 326

343 Adding triggers to prevent events Scripts that run from pre-event triggers must return a value that tells the server whether or not the event should be allowed to complete. A return value of zero means that the event can continue. A non-zero return value means that the event should be not be performed. If a non-zero value is returned, any messages output by the script or program (output to stdout) are sent back to Surround SCM with the error. This error is truncated to 1024 characters. Following are some examples of how to return a value from the trigger application: From a C program, specify the value in the return( ) statement in the main( ) routine. You can also use a parameter in the exit statement. From a Windows/DOS batch file set the ERRORLEVEL value. In Windows 2000/XP batch scripts the command exit /B # can be used. From a Windows application, you can use the CWinApp::ExitInstance( ) function. Tip: Seapine provides examples you can download to help you use executables with Surround SCM triggers. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select Run [executable] from the Action list. 6. Enter the full path to the Executable location and click OK. 7. Select Disable trigger after it runs once if you only want the trigger to run once. 8. Click OK to add the trigger. Adding triggers to prevent events You can add a trigger action that prevents users from performing file events and displays a message to inform them why they cannot perform the event. For example, you can prevent users from checking out files in specific workflow states. 1. Choose Tools > Administration > Triggers. 327

344 Adding triggers to append comments to events The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select Prevent the event with [message] from the Action list. 6. Enter the Message to display when users attempt to perform the event and click OK. Note: If the trigger prevents a promote or rebase, you can leave this field empty to skip files during the promote or rebase without displaying a message for each affected file. The skipped files are not displayed in the promote or rebase preview. 7. Select Disable trigger after it runs once if you only want the trigger to run once. 8. Click OK to add the trigger. Adding triggers to append comments to events You can add a trigger action to enter a comment or append user comments. For example, you can enter comments when files are checked in to add additional information to the file history. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select [Set Append] event s comment with [text] from the Action field. 6. Select how to add the comment. Set replaces any user comments with the text you enter in the Comment field. Append adds the Comment field text to any comments the user enters. 328

345 Adding triggers to users 7. Enter the Comment. 8. Select Disable trigger after it runs once if you only want the trigger to run once. 9. Click OK to add the trigger. Adding triggers to users You can add a trigger action to send an . For example, you can users when a file is assigned to them. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select Send an to from the Action list. 329

346 Editing templates 6. Select the users to send the to. The available options depend on the selected trigger event. Send to current user s the user who created the trigger. Send to the following users s the selected users. Send to last user to perform event s the user who last performed the selected event. Send to code review authors s all authors in the code review. Send to code review reviewers s all reviewers in the code review or only reviewers with incomplete file reviews. Send to user defined by custom fields s the specified user in the selected custom field. Send to these addresses sends an to the specified addresses. Separate multiple addresses with a semicolon. 7. Click Edit Template to modify the default template. See Editing templates, page Select Consolidate multiple file events into one to send one for all files the trigger runs on. An is sent for each file if this option is not selected. 9. Click OK. 10. Select Disable trigger after it runs once if you only want the trigger to run once. 11. Click OK to add the trigger. Editing templates Each trigger that sends and each user notification has an template that you can customize to provide information specific to the event that triggers the . You can use text and field codes to build customized s that provide information specific to the event that triggered the . Field codes, which are enclosed in percent symbols, are automatically replaced with the corresponding Surround SCM data when an is sent. See Environment Variables, page Click Edit Template when you are adding or editing a trigger or notification. See Adding trigger actions, page 333 and Adding notifications, page 83. The Edit Template dialog box opens with the Template tab selected. 330

347 Editing templates 2. Optionally customize the Subject. You can use text and field codes. 3. Optionally customize the Body. You can use text and field codes. You can enter field codes or select a code from the list and click Insert. The default template includes the %SSCM_FILELIST% field code. This code is replaced with the information on the File List or Code Review File List tab when the is sent. Tip: Use the %SSCM_FILELINK% field code to provide hyperlinks to the files. Make sure to set the server host name in server options. See Setting server options, page Select a Recipient option. 5. Select Send in HTML format to send HTML-formatted Click the File List or Code Review File List tab and make any changes to the default file list information. The information on this tab replaces the %SSCM_FILELIST% field code on the Template tab when the is sent. 7. Click OK. The template is saved with the selected trigger or notification. 331

348 Adding triggers to set workflow states Adding triggers to set workflow states You can add a trigger action to change the file workflow state to a specified state or the default state. For example, you can set the workflow state when files are checked in to track the files that require additional attention. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select Set state to [state] with comment [comment] from the Action list. 6. Select the State to set when the trigger runs. Select <Default State> to use the default state set in the workflow template. 7. Enter a Comment to include with the state change. 8. Click OK. 9. Select Disable trigger after it runs once if you only want the trigger to run once. 10. Click OK to add the trigger. Adding triggers to set custom field values You can add a trigger action to set a custom field to a specified value. For example, you can set a custom field value based on a file s workflow state. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens. 332

349 Editing triggers 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page Click the Actions tab and click Add to add an action. 5. Select Set custom field to [value] from the Action list. 6. Select the Custom field to set when the trigger runs. 7. Enter or select the Value to set the selected custom field to when the trigger runs and click OK. 8. Select Disable trigger after it runs once if you only want the trigger to run once. 9. Click OK to add the trigger. Editing triggers Edit a trigger to change the event or activity that causes it to run, the criteria used to select the files it applies to, and the action it performs. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Select a trigger and click Edit. The Edit Trigger dialog box opens. 3. Make any changes. To edit a condition on the Preconditions tab, double-click the condition. 4. Click OK to save the changes. Adding trigger actions You can add multiple actions to a trigger. For example, a trigger can set a workflow state and send an notification. 1. Click Add on the Actions tab in the Add Trigger or Edit Trigger dialog box. The Add Trigger Action dialog box opens. 333

350 Editing trigger actions 2. Select an Action. You can add the following actions for triggers that run before an event occurs: Running executables from triggers Prevent an event Set or append event comment text You can add the following actions for triggers that run after an event occurs: Run an executable Send an Set a custom field value Set a workflow state 3. Select the Parameters. The parameters change based on the selected action. 4. Click OK. The action is added to the trigger. Editing trigger actions Edit trigger actions to change the settings. For example, you can edit a send action to change the recipients or template. 1. Select an action on the Actions tab in the Add Trigger or Edit Trigger dialog box. 2. Click Edit. The Edit Trigger Action dialog box opens. 3. Make any changes. 4. Click OK to save the changes. Deleting trigger actions You can delete actions from triggers if you no longer want them to be performed when the trigger runs. Triggers must include at least one valid action to be enabled. If you delete all actions from a trigger, it is disabled. 1. Select an action on the Actions tab in the Add Trigger or Edit Trigger dialog box. 2. Click Delete. The action is deleted. 334

351 Duplicating triggers Duplicating triggers If you need to create a trigger that is similar to an existing one, save time by duplicating a trigger. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Select a trigger and click Duplicate. The trigger is duplicated and added below the selected trigger. 3. Select the new, duplicated trigger and click Edit. 4. Make any changes. 5. Click OK to save the changes. Disabling and enabling triggers If you do not want a trigger to run, you can disable it instead of deleting it. You can also enable disabled triggers. 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Select a trigger and click Disable or Enable. The trigger is disabled or enabled. Deleting triggers You can delete triggers that are no longer used. Note: You may want to disable the trigger instead of deleting it. See Disabling and enabling triggers, page Choose Tools > Administration > Triggers. 2. Select a trigger and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The trigger is deleted. 335

352

353 Configuring Workflows Surround SCM workflows can help you manage the process that files follow during their lifecycle. Workflows track the status of a file so you know if it requires action. You can also use triggers and custom fields to create workflows that can automatically assign files to users, set workflow states, and send notifications to users based on state and custom field changes. About workflows While branching provides high-level control over the change process, Surround SCM s workflow gives you much more granular control. The built-in workflow engine enables you to model your organization s change processes and ensure your team follows them every time a new file is created or change is made. Configurable workflows let you define, control, and track the state of files undergoing change. You can create triggers that automatically set file states or your team members can manually change file states after checking in changes. See Adding triggers to set workflow states, page 332 and Changing workflow states, page 33. File states can be displayed in the source file list, and are supported in filters and reports, enabling you to easily determine the overall status of files in your change process. Surround SCM supports an unlimited number of workflow definitions, allowing you to specify the appropriate process for each repository. See Setting workflows for specific repositories, page 349. Workflow example The following example illustrates how you can use a workflow with triggers and custom fields to automate the code review process. The workflow uses some of the default states defined in Surround SCM. 337

354 Workflow example Joe Jones, a developer, checks out a file and makes code changes. When he finishes, he checks in the file. A trigger changes the file s workflow state to Awaiting Review and sends an notification to Marcy Morris, the development team lead, which indicates that the file is ready for code review. After Marcy reviews the , she decides to have Rachel Rogers perform the code review. Marcy selects the file and chooses Activities > Properties. The Properties dialog box opens. Marcy clicks the Custom Fields tab, selects Rachel s name from the Assigned list, and selects a Due Date. Marcy clicks OK. A trigger sends an notification to Rachel to inform her about the assignment. After Rachel receives the , she reviews the file and finds problems in the code that Joe needs to correct. Rachel chooses Activities > Advanced > Change State. The Change State dialog box opens. Rachel selects Needs Attention from the New State list and enters comments about the changes. Rachel clicks OK. A trigger sends an notification to Marcy to inform her that the file requires additional changes. Marcy reviews Rachel s comments in the and assigns the file back to Joe so he can make the changes. Marcy right-clicks the file and chooses Properties. The Properties dialog box opens. Marcy clicks the Custom Fields tab. She selects Joe s name from the Assigned list and selects a Due Date. 338

355 About the default workflow template Marcy clicks OK. A trigger sends an notification to Joe to inform him about the assignment. Joe receives the . He chooses View > History, selects the version with Rachel s comments, and clicks Details to view her comments. Joe checks out the file, makes the code changes, and checks in the file. A trigger changes the file s workflow state to Awaiting Review and sends an notification to Marcy to inform her that the file is ready for review. After Marcy reviews the , she assigns the file to Rachel to perform another code review. A trigger sends an notification to Rachel to inform her about the assignment. Rachel receives the . She reviews the new file version and sees that Joe made all of the required changes. Rachel choose Activities > Advanced > Change State. The Change State dialog box opens. She selects Reviewed as the New State and enters comments to indicate that she approves the modified code. Rachel clicks OK. A trigger changes the Assigned custom field to <not set> and sends an notification to Marcy to inform her that the code review is complete. About the default workflow template Surround SCM includes a default workflow template, named General Workflow, that is designed for coding projects. The default workflow includes the following states: 339

356 Customizing workflows State <No State> Work in Progress Needs Attention Awaiting Review Reviewed Awaiting Release Released Destination states Work in Progress Needs Attention Awaiting Review Reviewed Awaiting Release Released <No State> Needs Attention Awaiting Review <No State> Work in Progress Awaiting Review <No State> Work in Progress Needs Attention Reviewed <No State> Work in Progress Needs Attention Awaiting Release <No State> Released <No State> Work in Progress Needs Attention Awaiting Release Customizing workflows Surround SCM s workflow provides additional control and reporting over the change process of files. Workflows are based on states, which indicate the current status of a file. For example, a file may be in an Awaiting Review state after it is checked in. After the review is complete, the state may change to Ready to Release. All files in a workflow have a State field. Users can manually change file states or you can use triggers to automatically change states when a specific file event occurs. Workflow templates define the states used in the workflow and the states that a file can move to from each state. After you create a workflow template, you can assign it to multiple repositories, which provides flexibility in managing files with different lifecycles. For example, a repository that contains source code files may require a different workflow than a repository that contains documentation files. Customizing a workflow includes the following steps: 340

357 Planning your workflow Planning your workflow, page 341 Configuring workflow states, page 341 Configuring workflow templates, page 344 Automating workflows, page 341 Setting workflows for specific repositories, page 349 Note: Workflows are optional and do not have to be used. You may also choose to use workflows for some repositories and not others. Planning your workflow Before you create a Surround SCM workflow, take the time to document and understand the process that files follow during their lifecycle. This can help you determine the status that files can be in, users who can perform work on files, information that users require, and how files move from state to state. A workflow should include a state to represent each status that a file can be in. You should also consider the users working with the files, the types of actions they perform, the actions that need to happen when files change, and the information you need to track. After you plan your workflow, you should be able to list the states that files can move to from each state. To create the workflow, first create the states and then create the workflow template. After you create the template, you can assign it to repositories and optionally configure triggers to automate the workflow. Automating workflows You can use triggers and custom fields to create an automated workflow, reducing the manual steps needed to move files through the workflow. For example, a trigger can automatically change the file state when an event occurs, such as check in, and send an notification to a team member. See Automating Actions with Triggers, page 321. You can also use custom fields with triggers. For example, a trigger can automatically change the Assigned custom field to a specific user when an event occurs and send an notification to the assigned user. See Configuring Custom Fields, page 317. Configuring workflow states States, which indicate the status of a file within its lifecycle, are used to create workflow templates. Workflow templates define the states used in a workflow and the states that a file can move to. For example, a file that requires a code review after it is checked in may be in an Awaiting Review state. See Configuring workflow templates, page Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 341

358 Adding workflow states 2. Click Add to create a new state. See Adding workflow states, page Select a state and click Edit to change it. See Editing workflow states, page Select a state and click Delete to delete it. See Deleting workflow states, page 343. Note: Select Show deleted states to display deleted states. Deleted states can be restored. See Restoring deleted workflow states, page 343. Adding workflow states Surround SCM includes the following default states: <No State>, Work in Progress, Needs Attention, Awaiting Review, Reviewed, Awaiting Release, and Released. If the default states do not match your process, you can edit the state names or add new states. States are not specific to a workflow template and can be used in any template. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Click Add. The Add State dialog box opens. 3. Enter a State name and State description. Make sure you use a descriptive name that users understand. 4. Click OK. The state is added. 342

359 Editing workflow states Tip: You can also add states when you create workflow templates. See Adding states to workflow templates, page 345. Editing workflow states Edit a workflow state to change the name or description. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Select a state and click Edit. The Edit State dialog box opens. 3. Make any changes. State changes are applied globally. If you change a state s name, all files in that state use the new state name. The old state name is saved in the file history. Note: You can also edit states when you edit workflow templates. See Editing workflow templates, page Click OK to save the changes. Deleting workflow states If you delete a state, files currently in the state remain in that state. The deleted state is not removed from the file history. Note: When a state is deleted, it is not permanently deleted and can be restored. See Restoring deleted workflow states, page Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Select a state and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The state is deleted. Restoring deleted workflow states 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Select Show deleted states. Deleted states are displayed in the list. 3. Select a deleted state and click Restore. The state is restored. 343

360 Configuring workflow templates Configuring workflow templates Workflow templates define the states used in the workflow and the transitions that control how files move from one state to another state. Surround SCM includes a default workflow template named General Workflow, which is designed for coding projects. You can use the default template out of the box or customize it. See About the default workflow template, page 339. You can also create workflow templates. Note: If you use the same state in multiple workflow templates, make sure any triggers that are configured to run based on state changes are valid for all repositories with workflows that include the state. For example, a trigger that sends when a file moves to the Awaiting Review state will the same users regardless of the workflow template. You may need to modify existing triggers or create new ones. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Click Add to add a template. See Adding workflow templates, page Select a template and click Edit to change it. See Editing workflow templates, page Select a template and click Duplicate to duplicate it. See Duplicating workflow templates, page Select the Default Workflow template to use for new repositories. You can select the workflow template to use for a repository or it can inherit the template. 7. Select a template and click Delete to delete it. See Deleting workflow templates, page 348. Adding workflow templates Workflow templates define the states used in the workflow and the transitions which control the states a file can move to from each state. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 344

361 Adding states to workflow templates 3. Click Add. The Add Workflow Template dialog box opens. All defined states are displayed. 4. Enter a Workflow Template Name and Description. 5. Click Add to add a state to the template. See Adding states to workflow templates, page Select a state and click Edit to change it. See Editing workflow states, page Select a state and click Top, Move Up, Move Down, or Bottom to change the display order. 8. Select a state and click Remove to remove it. See Removing states from workflow templates, page Select a Default State. The selected state is automatically set on files added to repositories that use the template, files added during promoting or rebasing, and files in new baseline or workspace branches. 10. Select Rollback state with file rollback to rollback the workflow state when rolling back files. By default, workflow states set on files do not change when rolling back files. The new file version has the same state as the most recent version. If this option is selected, the new version has the same state as the version rolled back to. This option applies to all repositories that use the workflow template. 11. Click Diagram Workflow to view a graphical representation of the workflow. See Diagramming workflows, page Click OK to save the changes. Tip: You can set the workflow template for a repository in the Properties dialog box. See Viewing general repository information, page 120. Adding states to workflow templates To use a state in a workflow, you need to add it to the workflow template. You can add existing states or create new states. 1. Click Add in the Add Workflow Template or Edit Workflow Template dialog box. 345

362 Removing states from workflow templates The Add State dialog box opens. 2. Select a state option. Select Add new state to add a state to the workflow template and the global list of available states. Enter the State name and State description. Select Add existing states to add an existing state to the workflow template. All states defined in Surround SCM are displayed. Select the state you want to add to the template. To select multiple states, Ctrl+click each state. 3. Click OK. The state is added. Removing states from workflow templates You may want to remove states from workflow templates if they are no longer used in the workflow. The state is only removed from the workflow template, not from other workflows. Files in repositories that use the workflow template remain in the removed state. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Select the workflow template you want to remove states from and click Edit. 4. Select a state and click Remove. If the state is not used in other workflow templates, you are prompted to mark the state as deleted. Deleted states are not permanently deleted and can be restored. See Restoring deleted workflow states, page Click Yes to remove the state and delete it or click No to remove the state without deleting it. 6. Click OK to save the changes. Editing workflow transitions Transitions define the states that a file can move to from each state. 346

363 Editing workflow templates 1. Click the Transitions tab in the Add Workflow Template or Edit Workflow Template dialog box. 2. Select the destination states for each source state. The source state is the state that a file is in. Destination states are the states a file can move to. Note: You must select at least one destination state for <No State>. 3. Click Print to print the workflow transitions. 4. Click OK to save the changes. Editing workflow templates Edit a workflow template to change the name, description, states, and transitions. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Select a workflow template and click Edit. The Edit Workflow Template dialog box opens. 4. Make any changes. You can edit workflow states when you edit workflow templates. State changes are applied globally. If you change a state s name, all files in that state use the new state name. The old state name is saved in the file history. See Editing workflow states, page Click OK to save the changes. Duplicating workflow templates If you need to create a workflow template that is similar to an existing one, save time by duplicating and editing an existing template. 347

364 Deleting workflow templates Tip: If you need to modify a workflow that is in use, you can duplicate the template and make changes to it. When you finish making changes to the duplicate template, delete the old template and rename the duplicate template using the same name as the old template. 1. Choose Tools > Administration > Workflow. The Workflow dialog box. 2. Click the Workflow tab. 3. Select a template and click Duplicate. The template is duplicated. 4. Select the duplicate template and click Edit. The Edit Workflow Template dialog box opens. 5. Make any changes. See Editing workflow templates, page Click OK to save the changes. Deleting workflow templates You may want to delete workflow templates that are no longer used. When you delete a template, users cannot change states on files in repositories that use the template. Files remain in the selected state. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Select a workflow template and click Delete. You are prompted to confirm the deletion. 4. Click Yes. The workflow template is deleted. Diagramming workflows Surround SCM's workflow diagram makes it easy to create complex workflows. With the click of a button, you can diagram a workflow to the states and transitions. This can help you evaluate the workflow to see how files move through the process and check for orphaned states or conflicts. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Select a workflow template and click Edit. The Edit Workflow dialog box opens. 4. Click Diagram Workflow. The diagram opens. The green double circle represents the default state and the blue lines indicate transitions. 348

365 Setting the default workflow 5. Click Print to print the workflow diagram. 6. Click Close to close the workflow diagram. Setting the default workflow If you want new repositories to use a workflow template, you need to select a default workflow. Note: When you create a branch, the repository uses the same workflow as the branch it is created from. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens. 2. Click the Workflow tab. 3. Select a Default Workflow. 4. Click OK to save the changes. The default workflow is applied to new repositories so users can set workflow states on files. See Changing workflow states, page 33. Setting workflows for specific repositories To use a workflow, you need to select a workflow for a repository. Each repository can use its own workflow or inherit the workflow from the parent repository. Note: The workflow only applies to the repository in the selected branch. When you create a new branch, the repository uses the same settings as the branch it is created from. All files in the new branch are set to the default workflow state. If you create a snapshot branch, the states set on files in the parent branch are copied to the new branch. 1. Select the repository and choose Activities > Properties. The Properties dialog box opens with the General tab selected. 2. Click the Workflow tab. 349

366 Setting workflows for specific repositories Select No workflow if you do not want use a workflow for the repository. Select Use parent repository workflow to use the same workflow as the parent repository. If the repository does not have a parent, select Use default workflow to use the default workflow. Select Use workflow template and select the workflow template to use for the repository. Read-only information for the selected template is displayed. 3. Click OK to save the changes. The workflow is set for the repository and users can now set workflow states on files. See Changing workflow states, page

367 Configuring Code Review Settings By default, the option to add files to code reviews is enabled when adding and checking in files to repositories. See Adding files to code reviews, page 55. You can disable or require this option for individual repositories. 1. Select a repository and choose Activities > Properties. 2. Click the Code Review tab. 3. Select Use parent repository settings to use the parent repository code review settings. 4. Select Configure repository settings to override the review settings and select an option to specify how the review option should be applied when checking in and adding files to the repository. Enabled allows users to choose to add files to reviews. Disabled prevents users from adding files to reviews. Required requires users to add files to reviews. 5. Click OK to save the changes. 351

368

369 Configuring Shadow Folders A shadow folder contains a reference copy of the current files in a repository. Files are automatically updated when changes are checked in. Use shadow folders to provide read-only access to non-surround SCM users or to provide a central location to build releases from. For example, WysiCorp wants to create a shadow folder for their existing web server directory. The existing directory, which is not empty, is at C:\Inetpub\wwwroot. First, the administrator renames wwwroot to wwwroot2 in the C:\Inetpub directory. The administrator also archives wwwroot2 in case a file was not checked in to Surround SCM. Next, a new empty directory named wwwroot is created in the C:\Inetpub directory. A shadow folder is created for wwwroot. After waiting for Surround SCM to copy the files into the new directory, the administrator manually copies any files that were not checked in from wwwroot2 to the new wwwroot directory. The files also need to be added to Surround SCM. Note: Surround SCM does not automatically create shadow folders because of security concerns. This also gives the administrator greater control over where shadow folders are created. If Surround SCM automatically created shadow folders, a hacker could fill up the hard drive with unnecessary files. A hacker could also specify the Windows system folder as the shadow folder and then check in DLLs that contain a virus. 1. Choose Tools > Administration > Shadow Folders. The Shadow Folders dialog box opens. Icons indicate the type and status of the branch associated with a shadow folder, which can help you troubleshoot any issues with updating folders. See Branch status icons, page Click Add to create a shadow folder. See Adding shadow folders, page Select a folder and click Edit to change it. See Editing shadow folders, page Select a folder and click Force Update to update it. See Refreshing shadow folder contents, page Select a folder and click Delete to delete it. See Deleting shadow folders, page 355. Adding shadow folders When shadow folders are created, Surround SCM assumes it can add, override, and delete files. You must create an empty directory before you add a shadow folder. Creating an empty directory protects against files being overwritten and security issues, such as hackers. 353

370 Adding shadow folders 1. Choose Tools > Administration > Shadow Folders. The Shadow Folders dialog box opens. 2. Click Add. The Add Shadow Folders dialog box opens. 3. Click Set to select the branch and repository. The Repository Browser dialog box opens. 4. Select the branch and repository you want to shadow and click OK. 5. Enter the Shadow Path. This is the location of the shadow folder. The path must be relative to and valid for the Surround SCM Server process that will use it. To provide increased security, you are required to manually enter the path. This ensures the shadow folder directory exists and that a user with proper authorization accesses the server computer to create it. Tip: If you are the system administrator, you can use Windows Explorer or another file management application to browse to the shadow folder location, create the shadow folder directory, then copy and paste the location into the shadow path field. 6. Select the End-Of-Line Format to use for text files. 7. Select a File timestamp option. The timestamp is set when files are retrieved. Current sets the timestamp to the current (time of retrieval) date and time. Modified sets the timestamp to the date and time that the files were last modified. Check in sets the timestamp to the date and time that the files were last checked in. 8. Select Recursive to recursively shadow all subrepositories in the selected repository. 354

371 Editing shadow folders 9. Click OK. The shadow folder is created. Editing shadow folders You can change the shadow folder end-of-line format and timestamp options. 1. Choose Tools > Administration > Shadow Folders. The Shadow Folders dialog box opens. 2. Select the folder and click Edit. 3. Make any changes. 4. Click OK to save the changes. Refreshing shadow folder contents Surround SCM is configured to update shadow folders at regular intervals. You can also manually update shadow folders. 1. Choose Tools > Administration > Shadow Folders. The Shadow Folders dialog box opens. 2. Select a folder and click Force Update. The Surround SCM files are updated in the selected shadow folder. Deleting shadow folders 1. Choose Tools > Administration > Shadow Folders. The Shadow Folders dialog box opens. 2. Select the folder and click Delete. You are prompted to confirm the deletion. 3. Click Yes. The shadow folder is deleted. 355

372

373 Maintaining Branches Surround SCM supports many branching models. Advanced branching features give you complete control over security and access, promoting, rebasing, and versioning your changes. Depending on your role and security permissions, you may be able to perform the following actions on branches. Manage attributes of all branches Update attributes for specific branches, such as hide/unhide, freeze/unfreeze, and inactivate/activate Rename branches Control access to branches and set security options for branches Change branch types Update templates to specify the repositories included and excluded in branches Index branches for optimized searching Set caching options for all branches and change cache settings for individual branches Remove branches Restore removed branches Delete branches permanently Managing branch attributes Over time, the number of branches on the Surround SCM Server will increase. It can be difficult for users to find what they need when there are a large number of branches, especially if many branches are old or rarely used. You can perform branch maintenance to view all branches in the database, freeze/unfreeze, inactivate/activate, hide/unhide, rename, and destroy branches, modify branch templates, and change the branch type and caching mode. Tip: You can also set branch attributes by choosing Branch > Branch Attributes. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. Icons indicate the branch type and status. See Branch status icons, page

374 Managing branch attributes 2. On the General tab, select a Display Mode. Tree view displays branches in a tree structure as they are displayed in the Branches tree. List view displays branches in a list. Click a column header to sort branches in the list view. 3. Select additional display options. Show hidden branches displays branches that are currently hidden. Show inactive branches displays branches that are currently inactive. Show removed branches displays removed branches. Show all private branches displays all workspace branches. Ignore branch security overrides branch security so you can view and set attributes for all branches. 4. Select a branch and click the button for the action you want to perform. Button Use to: More information Toggle Frozen Freeze or unfreeze the branch. Users can see frozen branches but cannot perform any activities that change files, such as checking files out or in. Freezing and unfreezing branches, page

375 Managing branch attributes Button Use to: More information Toggle Active Toggle Caching Toggle Hidden Change Type Edit Template Remove Destroy Make the branch active or inactive. Users cannot see or perform any actions on inactive branches. Change the branch caching mode. By default, all file and repository information for a branch is cached when the Surround SCM Server starts. If you have a large number of branches, it can take a while for the server to cache all information at startup. You can use on demand caching to cache information only when a user selects a branch. Hide or unhide the branch. Users cannot see hidden branches, but they can still perform actions on them if they choose to view hidden files. Change the branch type or owner. Modify the template used to specify the repositories included in the branch. You can also remove the template from the branch. Remove the branch. Removed branches are not deleted from the hard drive and can be restored if needed. Permanently delete a removed branch. Destroyed branches are deleted from the hard drive and cannot be restored. Inactivating and activating branches, page 365 Changing branch caching, page 368 Hiding and unhiding branches, page 364 Changing branch type, page 367 Modifying templates for existing branches, page 366 Removing branches, page 370 Deleting branches permanently, page 371 Restore Restore a removed branch. Restoring removed branches, page Click Save As to save the list or click Print to print it. 6. Click the Indexing tab to enable indexing to optimize searching for text in files. See Indexing branches for optimized searches, page Click Close when you finish. 359

376 Indexing branches for optimized searches Indexing branches for optimized searches The Surround SCM indexing server indexes branches for optimized performance and results when searching for text in files. The indexing server is installed with the Surround SCM Server and starts automatically when the Surround SCM Server starts. See Differences between indexed and non-indexed searches, page 221 for information about how indexed versus non-indexed searches work. The Surround SCM administrator can perform the following actions to manage branch indexes. Turn indexing on or off for branches. See Turning branch indexing on or off, page 361. Start the indexing server if it is not running to enable indexed searching. See Managing the indexing server, page 360. View indexing status and information. See Viewing branch index details, page 362. View the indexing server log to troubleshoot issues with corrupted indexes. See Viewing the indexing server log, page 363. Modify the indexing server startup options. See the Surround SCM Registry Utility help for information. Managing the indexing server The Surround SCM indexing server starts automatically when the Surround SCM Server starts. You may need to restart the indexing server if you make changes to the indexing registry settings or stop the server. You can also view the current server status, memory usage, index storage size, server version, and server log. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Indexing Server from the Global Server Options category. 3. Click Start to start the indexing server if it is not running. 360

377 Turning branch indexing on or off When the indexing server starts, branch indexes are available for searching. You can turn on indexing for branches and view indexing status in the Branch Maintenance dialog box. See Turning branch indexing on or off, page Click Stop to stop the server. Note: By default, the indexing server restarts automatically when the Surround SCM Server is restarted. If you do not want the indexing server to start automatically, you can use the registry utility to change the indexing server startup options. See the Surround SCM Registry Utility help for information. 5. Click Refresh to refresh the server information. 6. Click View Log to view the indexing server log and troubleshoot issues. See Viewing the indexing server log, page Click OK to save the changes. Turning branch indexing on or off You can enable indexing for active mainline and baseline branches to optimize performance and results when searching for text in files. Note: Indexing requires additional disk space to store the content. If you need to free up disk space later, you can turn indexing off for branches used less often. You can also use the registry utility to change the index storage directory to a drive with more available space. See the Surround SCM Registry Utility help for information. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Click the Indexing tab. All mainline and baseline branches are displayed. 3. Select a Display Mode. 361

378 Viewing branch index details Tree view displays branches in a tree structure as they are displayed in the Branches tree. List view displays branches in a list. Click a column header to sort branches in the list. 4. Select a Show branches with option to show branches with indexing turned on and off. 5. Select the branch and click Toggle Indexing to turn indexing on or off. Status information for the branch is updated. If you turned indexing on, click Refresh to view the indexing status. Complete (100%) indicates the branch is completely indexed. In progress indicates indexing is currently in progress. Waiting indicates the branch is waiting to be indexed after indexing for another branch is complete. Not indexed indicates the branch is marked to be indexed but has not been added to the waiting queue. Optimized searching is only available in branches with a Complete indexing status. If you turned indexing off, you are prompted to confirm the change. Click Yes to turn indexing off. The branch index is deleted and cannot be restored. If you decide to turn indexing on later, the branch will be reindexed. 6. Click Close when you finish. Tip: You can also select a branch and choose Branch > Branch Indexing > On/Off to turn indexing on or off. Viewing branch index details You can view details about indexed branches to review the indexing status, current size, health, and location of the index file. You can also view information about the average time it takes to search, when the index was last updated, and how long it took to initially index the branch. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Click the Indexing tab. 3. Select an indexed branch and click Details. The Branch Index Details dialog box opens. The read-only dialog box displays the selected branch, the branch type, and details about the index. 362

379 Viewing the indexing server log Note: If an index is corrupt, you can turn indexing off and then turn it on again to reindex the branch. See Turning branch indexing on or off, page 361. If you continue to see corrupt indexes, use the indexing server log to troubleshoot possible disk space issues. See Viewing the indexing server log, page Click Previous or Next to view the index details for the previous or next branch in the tree or list in the Branch Maintenance dialog box. 5. Click Close when you finish. Viewing the indexing server log You can use the indexing server log to troubleshoot problems, such as corrupt indexes. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Indexing Server in the Global Server Options category. 3. Click View Log. The Indexing Server Log dialog box opens. 363

380 Renaming branches 4. Review the log information. 5. Click Close when you finish. Renaming branches Note: To rename mainline branches, see Renaming mainline branches, page Select the branch and choose Branch > Rename Branch. The Rename Branch dialog box opens. 2. Enter a new name and any comments. 3. Click OK. The branch is renamed. Hiding and unhiding branches Hidden branches are not displayed in the Branch menu and Branches tree, but they are still active. You may want to hide branches to display a simplified branch structure. For example, you may want to hide snapshot branches because they are static and not frequently used. Users can enable a user option to show hidden branches. 364

381 Freezing and unfreezing branches Keep in mind that hiding a parent branch does not hide its child branches. Hidden parent branches are displayed in the Branches tree if a child branch is not hidden. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. Tip: You can also choose Branch > Branch Attributes > Hidden to hide branches. 2. Select the branch you want to hide or unhide and click Toggle Hidden. If the selected branch is unhidden, you are prompted to confirm that you want to hide it. 3. Click Close to close the Branch Maintenance dialog box. Freezing and unfreezing branches Freezing a branch prevents users from making any changes to files in the branch. When a branch is frozen, any command that can affect the code, such as adding a file or creating a repository, is disabled. Actions that do not affect the code, such as getting a file or merging to local files, are enabled. You may want to freeze a branch for administrative or maintenance purposes. For example, you need to build a release for multiple platforms. Freeze the corresponding branches to ensure the files cannot be changed during the build process. When you finish, unfreeze the branches. 1. Select the branch you want to freeze or unfreeze. 2. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. Tip: You can also choose Branch > Branch Attributes > Frozen to freeze a branch. 3. Click Toggle Frozen. If the selected branch is unfrozen, you are prompted to confirm that you want to freeze it. Inactivating and activating branches Inactivating a branch prevents users from viewing or performing any actions on the branch and its repositories and files. You may want to inactivate a branch when your team is no longer using a branch, but you want it to be displayed in the Branches tree, Branch menu, and the Branch Maintenance dialog box. For example, you may want to inactivate old baseline branches used for feature development that you do not want users to be able to access. Inactivating a parent branch does not inactive child branches, except when you inactivate a mainline branch. Inactivating a mainline branch also inactivates all child branches, repositories and subrepositories, and files, and makes the entire mainline inaccessible. Inactive branches are displayed in the Branches tree or Branch menu unless they are hidden. See Hiding and unhiding branches, page Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. Tip: You can also choose Branch > Branch Attributes > Active to inactivate a branch. 2. Select a branch to inactivate or activate and click Toggle Active. 365

382 Modifying templates for existing branches If the selected branch is active, you are prompted to confirm that you want to inactivate it. 3. Click Close to close the Branch Maintenance dialog box. Modifying templates for existing branches You can update an existing baseline or workspace branch to configure a template that specifies the repository structure for the branch. For example, if a subrepository was excluded when the branch was created, but you now need to include it, you can update the branch template to rebase the subrepository from the parent branch. You can also remove templates from branches to use the same structure as the parent repository the branch was created from. Note: Templates control the repository structure of individual branches. Changing the repositories included in the template for one branch does not affect other branches created using the same repository structure. 1. Select the branch and choose Branch > Branch Properties. The Branch Properties dialog box opens. 2. Click the Template tab and then click Modify. 3. Select a Template option. 366

383 Changing branch type To remove the template from the branch, select Do not use template. The Repositories preview is updated and displays the root repository that will be used for the branch. If multiple subrepositories were included in the template, the virtual root repository is used as the root repository for the updated branch. Continue with step 5. To change the repositories included in the branch, select Use template to define repositories in the branch. 4. If you chose to use a template, select the Repositories to include in the branch. Only repositories available in the parent branch are displayed. To exclude a subrepository from the branch, select it and click Exclude. To include an excluded subrepository, select it and click Include. To remove a repository from the current template, select it and click Remove. 5. Click OK to save the changes. The branch template is updated. If you included additional repositories or removed the template from the branch, you are prompted to rebase the branch to retrieve the repositories from the parent branch. Click Rebase to rebase the branch or Do not rebase to rebase the branch later. If you do not rebase the branch, you must manually rebase it later to update it. See Rebasing branches, page 189. If you removed or excluded repositories, you are prompted to destroy them. Click Destroy to permanently delete the repositories. All files in the repositories and historical information are destroyed and cannot be restored. Changing branch type You can change the workspace branch owner or convert workspace branches to baseline branches. For example, a developer starts working on a feature in her workspace branch but realizes it will require more time to complete than originally planned. In this case, you can change the user s workspace branch to a baseline branch so other developers can access the code or change the branch owner so another user can complete the work. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Select a workspace branch and click Change Type. The Change Branch Type dialog box opens. 367

384 Changing branch caching 3. Select a Branch Type to change the workspace branch to a baseline branch. 4. Select a New Owner to change the workspace branch owner. 5. Enter the New Branch Name. 6. Enter any Comments, such as the reason for changing the branch type. 7. Click OK to save the changes. 8. Click Close to close the Branch Maintenance dialog box. Changing branch caching Branches are cached when the Surround SCM Server starts. You can change the caching mode to reduce memory usage. Surround SCM includes the following caching modes: Always Branches are cached when the Surround SCM Server starts. Mainline branches are always cached when the server starts and cannot be changed. On Demand Branches are cached when users perform actions that access the branch, such as opening a repository. By default, baseline, workspace, and snapshot branches are cached on demand. The most recently used Cache on Demand branches are cached when the Surround SCM Server starts based on the server options. See Setting branch caching server options, page 369. Note: You cannot change the cache mode for mainline, inactive, or removed branches. Inactive and removed branches are not cached. Active mainline branches are always cached. 1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. Tip: You can also choose Branch > Branch Attributes > Cache On Demand to change the cache mode. 2. Select a branch and click Toggle Caching. You are prompted to confirm that you want to change the cache mode. 3. Click Yes. 368

385 Setting branch caching server options The cache mode is changed. 4. Click Close to close the Branch Maintenance dialog box. Setting branch caching server options You can set dynamic branch caching options to control the size of the Surround SCM Server cache, which can help reduce memory or performance issues. Mainline branches are always cached when the Surround SCM Server starts. By default, baseline, snapshot, and workspace branches are set to Cache on Demand, which means they are cached when users perform actions that access a branch. When the Surround SCM Server starts, the most recently used Cache on Demand, or dynamic, branches as of the last server shutdown are cached. If these branch types are changed to Always Cache, they are always loaded when the server starts. As additional branches are created, the cache may become too large, which can cause memory issues and slow server startup times. If this happens, you can adjust the caching server options to reduce the number of cached dynamic branches and set inactivity timeout limits for unloading inactive dynamic branches or changing inactive Always Cache branches to Cache on Demand. Note: If you are experiencing memory or performance issues, you may also want to evaluate if there are any branches set to Always Cache that you can change to Cache on Demand. See Changing branch caching, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Caching from the Global Server Options category. 3. Enter the Minimum dynamic branches to cache to indicate the minimum number of dynamic branches per mainline branch to cache during server startup and to maintain in the cache. This setting applies to each mainline branch. For example, if the server includes 10 mainline branches that each include 10 branches and the minimum branches to cache setting is 10, the cache always stores 100 branches. The default 10 branches. 4. Enter the Inactivity timeout to indicate the number of minutes to leave a dynamic branch in the cache without activity before it is unloaded. A branch is considered inactive if no read or write activities that require the branch to be loaded in the cache are performed in the specified number of minutes. Inactive dynamic branches, excluding the most recently used branches, are automatically unloaded from the cache. The default is 60 minutes. 5. Enter the Maximum dynamic branches to cache to indicate the maximum number of dynamic branches per mainline to cache. 369

386 Removing branches If this limit is exceeded, inactive dynamic branches, excluding the most recently used branches, that have not yet reached the inactivity timeout are unloaded until the minimum number of branches to cache is reached. The default is 100 branches. 6. Select Force branch to cache on demand after inactivity timeout to automatically change unused branches set to Always Cache to Cache on Demand after the specified number of days. An informational message is added to the server log if a branch is forced to Cache on Demand. The default is 120 days. 7. Click OK to save the changes. Removing branches Remove a branch if you do not want users to be able to access it. When a branch is removed, it is not deleted from the hard drive and can be restored if needed. See Restoring removed branches, page 370. If you remove a branch indexed for searching, the index is also deleted. If you restore the branch later, you must manually turn on indexing for the branch to reindex it. See Turning branch indexing on or off, page 361. Note: If you want to provide limited access to a branch, you can freeze, hide, or inactivate it instead of removing it. See Managing branch attributes, page Select the branch and choose Branch > Remove Branch. The Remove Branch dialog box opens. 2. Enter any Comments, such as the reason for removing the branch. 3. Select Permanently destroy branch to delete the branch from the hard drive. 4. Click OK. You are prompted to confirm the branch removal. 5. Click Yes. The branch is removed. Tip: You can view removed branches in the Branch Maintenance dialog box. See Managing branch attributes, page 357. Restoring removed branches You can restore removed branches to give users access to them again. 370

387 Deleting branches permanently Note: If you restore a branch that was indexed for searching before it was removed, you must manually turn on indexing for the branch to reindex it. See Turning branch indexing on or off, page Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Select a removed branch and click Restore. The Restore Branch dialog box opens. 3. Enter any Comments and click OK. The branch is restored. Deleting branches permanently Destroyed branches are permanently deleted from the hard drive and cannot be restored. Note: Only destroy branches created by mistake that do not have any changes. If changes have been made, remove the branch so it can be restored if needed. See Removing branches, page Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Select a branch and click Destroy. You are prompted to confirm that you want to destroy the selected repository. 3. Click Yes. The Destroy Branch dialog box opens. 4. Enter any Comments and click OK. The branch is destroyed and cannot be restored. 371

388

389 Managing Mainline Branches Mainline branches may require additional maintenance, such as needing to be converted, upgraded, or restored if your company switches RDBMS vendors or changes servers. Creating mainline branches A mainline branch is the highest-level branch that contains all source files, other branches, and repositories. You cannot search, branch, promote, or rebase across mainline branches. Take the time to decide on your company s use of mainline branches. Some companies may need only one mainline branch while other companies may have multiple mainline branches. 1. Choose Tools > Administration > Create Mainline Branch. The Create Mainline Branch dialog box opens. 2. Enter the Mainline name. 3. Enter any Comments, such as the purpose of the mainline branch. 4. Select the Location where you want to create the mainline branch. Each mainline branch is stored in its own database. Mainline databases are stored in an RDBMS database. The list includes RDBMS connections configured for the Surround SCM Server. Select the connection for the database you want to store the mainline branch in. See Adding RDBMS connections, page 389 if you need to add an RDBMS connection. 5. Optionally select Allow case-sensitive file and repository names to use case-sensitive names for all repositories and files in the new mainline branch. Select this option only if all users access the mainline branch using the Linux Surround SCM Client. You are prompted to confirm that you want to use case-sensitive file and repository names. Note: Enabling this option may cause problems if users access the mainline branch using the Windows or Mac Surround SCM Client. For example, Linux recognizes TEST.TXT and Test.txt as different files. Windows and Mac recognize these as the same file and do not allow the files to be saved in the same directory. When users get the files to a working directory, only one of the files can be retrieved. 373

390 Renaming mainline branches 6. Click OK. You are prompted to confirm that you want to create a mainline branch. 7. Click Yes. The mainline branch is created. See Branching, page 161. Renaming mainline branches When you rename a mainline branch, the mainline root repository and root repositories for child branches, including snapshot branches, are also renamed. Note: To rename baseline, snapshot, or workspace branches, see Renaming branches, page Select the mainline branch you want to rename and choose Tools > Administration > Rename Mainline Branch. The Rename Mainline Branch dialog box opens. 2. Enter a new name and any comments. You cannot use the same name as any active, inactive, or removed mainline branches. 3. Click OK. You are prompted to confirm the rename. 4. Click Rename Mainline. A progress indicator opens and lets you know the mainline branch is being renamed. Overriding server options for specific mainline branches You can override general, comment, changelist, and filename and extension server options for specific mainline branches. If you do not configure options for a specific mainline, the mainline options set on the Surround SCM Server are used. See Configuring the Surround SCM Server, page Select the mainline branch and choose Branch > Branch Properties. The Properties dialog box opens. 2. Click the Options tab. 374

391 Overriding server options for specific mainline branches 3. Select a category. Category Includes options for: More information General Comments Allowing checking in without check out, allowing multiple users to check out files, expanding keywords, allowing workflow state changes during check in, Unicode options for merging text files, enabling thumbnails, and setting the maximum file size for large files. Minimum character lengths for comments entered by users when performing specific actions, such as check ins. Setting general mainline options, page 308 Setting minimum comment lengths for actions, page

392 Moving repositories to different mainline branches Category Includes options for: More information Changelists Changelist usage and retaining historical changelist information. Setting changelist server options, page 311 Files Names/Extensions File type extensions and names to automatically detect and ignore when adding files. Setting autodetect and ignore file options, page Select Override for the options you want to override and make any changes. Select Inherit to use the mainline options set on the Surround SCM Server. 5. Click OK to save the changes. Moving repositories to different mainline branches To move a repository to another mainline branch, export it from the existing mainline to a new or existing mainline. The repository, subrepositories, and files are copied to the destination mainline, and include the following information: Repository history, workflow, code review settings, issue tracking integration, and removed items. File history, workflow states, custom field values, issue tracking attachment details, and share information. Keep the following in mind: Repository information about changelists, labels, code reviews, check out status, and bookmarks is not exported. File information about working directories, cloaked repositories, shadow folders, shelves, bookmarks, notifications, filters, triggers, and reports is not exported. If exporting to an existing mainline branch, the destination branch must be an active baseline branch and cannot include a repository with the same name as the source repository. All imported repositories inherit the parent repository security. You cannot export repositories from mainlines with case-sensitive filenames enabled to existing mainlines that do not allow case-sensitive filenames. If exporting to a new mainline branch, any security settings and server option overrides set on the source branch are reset to the defaults for new mainlines. See Controlling access to specific branches, page 285 and Overriding server options for specific mainline branches, page Choose Tools > Administration > Export Repository to Mainline. The Export Repository to Mainline dialog box opens. 376

393 Moving repositories to different mainline branches 2. Click Browse to select the repository to export. 3. Select an option to specify the destination mainline branch. Export repository to new mainline creates a new mainline branch. Enter a Mainline name and select the Location where you want to store the branch. The list includes all RDBMS connections configured for the Surround SCM Server. See Adding RDBMS connections, page 389 if you need to add an RDBMS connection. Export repository to existing mainline exports the repository to an existing mainline branch. Click Browse to select the branch and repository. 4. Enter any Comments, such as the reason for exporting the repository. 5. Click OK. A progress indicator opens. When the export is complete, the repository, including all files and subrepositories, are added to the destination branch. The repository now exists in the destination and source branches. To ensure users work with files in the correct location or to free up space, you can remove the repository from the source branch if it is no longer needed. See Removing repositories, page 112. Tip: Remember to inform users about new repository location. 377

394 Moving mainline branches to different databases or servers Moving mainline branches to different databases or servers By default, the Surround SCM Server database and all mainline branches are stored in one RDBMS database. You can convert mainline branches to store them in a different RDBMS database, distribute them across multiple RDBMS databases, or move them to a different Surround SCM Server. Note: When you convert the server database or mainline branches, the data is copied from the current RDBMS database to the destination database. The data is not deleted from the original database. Following are common scenarios for changing database configurations for mainline branches. Converting mainline branches stored with the server database to a new RDBMS database You may decide to switch to a different RDBMS type or host mainlines and the server database in a different RDBMS database. To do this, you need to convert the server database, which copies all the server database and mainline branches to a different RDBMS database. To copy the mainline branches and server database to the new RDBMS database: 1. Convert the server database. See Converting the server database to a different type, page Restart the Surround SCM Server. 3. Optionally delete the server database and mainline branches from the original RDBMS database. You must manually delete the server database. See Deleting mainline branches permanently, page 383. Converting mainline branches not stored with the server database to different RDBMS databases Mainline branches can be stored separately from server databases and hosted in multiple RDBMS databases. This may help alleviate performance or disk space restriction issues. To move a mainline branch to a different RDBMS database, you need to convert it. To copy a mainline branch to a different RDBMS database: 1. Inactivate the mainline branch. See Inactivating and activating branches, page Convert the mainline branch to copy it to the other database. See Copying mainline branches to different databases, page Activate the mainline branch. See Inactivating and activating branches, page Optionally destroy the mainline branch from the original RDBMS database. See Deleting mainline branches permanently, page Repeat steps 1-4 for each mainline branch you want to copy to the new RDBMS database. Converting a mainline branch to a different Surround SCM Server Some organizations use multiple Surround SCM Servers for load balancing reasons or to support geographically-dispersed teams. Only one Surround SCM Server can connect to an RDBMS database at a time. If you want to host a mainline branch on a different Surround SCM Server, copy the mainline to an empty RDBMS database that is not connected to a Surround SCM Server, remove it from the source Surround SCM Server, and then add it to the destination Surround SCM Server. 378

395 Copying mainline branches to different databases To copy a mainline branch to a different Surround SCM Server: 1. Inactivate the mainline branch you want to move. See Inactivating and activating branches, page Convert the mainline branch to move it to the different RDBMS database. See Copying mainline branches to different databases, page Remove the mainline branch from the current server. See Removing mainline branches, page Log in to the destination server. 5. Add the mainline branch to the destination server. See Restoring removed branches, page Optionally convert the mainline branch on the destination server to host it in the same RDBMS database as the server database. 7. Optionally destroy the mainline branch from the original RDBMS database. See Deleting mainline branches permanently, page 383. Copying mainline branches to different databases By default, mainline branches are stored in the same RDBMS database as the Surround SCM Server database. You can convert mainline branches to copy them to a different RDBMS database. During the conversion, data is copied to the destination database and is not deleted from the current database. Depending on the mainline database size, the conversion may take a few minutes to several hours. Note: You must inactivate the mainline branch before converting it. See Inactivating and activating branches, page Choose Tools > Administration > Convert Mainline Branch. The Mainline Destination dialog box opens. 2. Select a database Destination. The list includes RDBMS connections configured for the Surround SCM Server. Select the connection for the database you want to store the mainline branch in. See Adding RDBMS connections, page 389 if you need to add an RDBMS connection. 3. Select Ignore errors during upgrade to allow Surround SCM to continue processing regardless of any errors it may encounter. Note: Only select this option if you have already used the Surround SCM Analyze Utility and were unable to repair issues causing errors. 379

396 Removing mainline branches 4. Click OK. The conversion information is sent to the Surround SCM Server for validation. If the validation succeeds, you are prompted to start the conversion. If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an or text file and it to your DBA for help. 5. Click Yes. The Conversion Status dialog box opens. Note: If the destination database does not include any Surround SCM tables, you are prompted to create them. See Creating Surround SCM tables, page Click Close when the conversion finishes. Note: You must activate the mainline branch before users can access it. See Inactivating and activating branches, page 365. Removing mainline branches If a mainline branch is no longer used, you can remove it from the Surround SCM Server. All child branches, repositories, subrepositories, and files are also removed. 1. Select the mainline branch and choose Tools > Administration > Remove Mainline Branch. The Remove Mainline Branch dialog box opens. 2. Enter any Comments, such as the reason for removing the mainline. 3. Click OK. You are prompted to confirm the removal. 4. Click Yes. The mainline branch is removed. Restoring removed mainline branches You can restore a removed mainline branch to make it active again. 1. Choose Tools > Administration > Add Existing Mainline Branch. The Add Existing Mainline Branch dialog box opens. 380

397 Restoring RDBMS mainline branches 2. Select the Mainline Type. RDBMS allows you to restore a mainline stored in an RDBMS database. See Restoring RDBMS mainline branches, page 381. Non-RDBMS allows you to restore a mainline branch from Surround SCM 2008 or earlier that is not in RDBMS format. See Restoring non-rdbms mainline branches, page Enter or select the Location information. The fields displayed depend on the selected mainline type. 4. Click OK. The mainline branch, child branches, repositories and subrepositories, and files are restored. Restoring RDBMS mainline branches If you removed a mainline branch but did not delete the tables from the RDBMS database, you can re-add it to the Surround SCM Server. Note: If you need to restore a mainline branch created in Surround SCM 2008 or earlier, see Restoring non-rdbms mainline branches, page Choose Tools > Administration > Add Existing Mainline Branch. The Add Existing Mainline Branch dialog box opens. 2. Select RDBMS as the Mainline Type. 381

398 Restoring non-rdbms mainline branches 3. Select the Location where the mainline branch is stored. The list includes RDBMS connections configured for the Surround SCM Server. Select the database connection you want to restore the mainline branch from. 4. Select the mainline branch Name. The list includes mainline branches stored in database for the selected RDBMS connection. 5. Click OK. The mainline branch, child branches, repositories and subrepositories, and files are restored. Restoring non-rdbms mainline branches If you removed a mainline branch before upgrading to Surround SCM 2009 and later, you can re-add it to the Surround SCM Server. Mainline branches were stored in a flat file database format in Surround SCM 2008 and earlier, and must be upgraded to RDBMS format after they are restored. Note: If you want to restore a mainline branch stored in an RDBMS database, see Restoring RDBMS mainline branches, page Choose Tools > Administration > Add Existing Mainline Branch. The Add Existing Mainline Branch dialog box opens. 2. Select Non-RDBMS as the Mainline Type. 3. Enter the Mainline branch location on server. 382

399 Deleting mainline branches permanently This is the location where Surround SCM files are stored on the server computer. If the mainline database was stored in a subdirectory of the server database, you can enter the subdirectory name or the fully qualified path to the database location. 4. Click OK. The mainline branch is added to the Surround SCM Server. Note: You must upgrade the restored mainline branch before users can access it. Mainline branches that require upgrading are appended with 'non-rdbms database'. See Upgrading mainline branches, page 405. Deleting mainline branches permanently If a removed mainline branch will not be used again, you may want to delete it from the database. Destroyed mainline branches are permanently deleted from the database and cannot be restored. Note: You must remove mainline branches before they can be destroyed. See Removing mainline branches, page Choose Tools > Administration > Destroy Mainline Branch. The Destroy Mainline Branch dialog box opens. 2. Select the Location where the mainline branch is stored. The list includes RDBMS connections configured for the Surround SCM Server. Select the connection for the database that contains the mainline branch you want to destroy. 3. Select the removed mainline to destroy. The list includes removed mainline branches for the selected RDBMS connection. 4. Click Destroy. You are prompted to confirm the destroy. 5. Click OK. The mainline table entries are deleted from the database and cannot be restored. You return to the Destroy Mainline Branch dialog box. 383

400

401 Maintaining Surround SCM Databases The Surround SCM Server database and mainline branches are stored in an RDBMS database, such as PostgreSQL. You can modify the internal Surround SCM database format and data from the RDBMS database, but we do not recommend it. Your Surround SCM maintenance contract does not include support for recovering from these types of database changes. Configuration changes We recommend making configuration changes using the Surround SCM Client instead of at the database level. Making changes directly in the database requires a full understanding of the Surround SCM database format and the rules enforced at the software level. Database table changes Do not reconfigure the Surround SCM database format. Do not change database tables/column names, modify column size/attributes, or make any other structural database changes as it will result in errors running Surround SCM. Live updates Surround SCM caches data to improve performance. Do not perform live updates of Surround SCM at the database level unless the Surround SCM Server has been shut down. Adding, editing, or deleting Surround SCM data while the server is running results in errors and potential data loss. Your changes may be overwritten next time the record is modified because database changes are not immediately read into the Surround SCM cache. Surround SCM does not prevent users from opening the database in read/write mode while the Surround SCM Server is running. To perform live Surround SCM data updates, use methods available in the Surround SCM Client or CLI Client. Note: You can lock Surround SCM databases to prevent users from performing actions that write to the database, such as checking out files. See Locking databases for backups, page 392. Creating Surround SCM tables When you upgrade or convert mainline branches or the server database, the physical database and empty Surround SCM tables must be created before the data can be converted. If the tables do not exist, you are prompted to allow Surround SCM to automatically create the tables. The server loads the corresponding table creation script and sends it to the database server. See Converting the server database to a different type, page 386, Copying mainline branches to different databases, page 379, and Upgrading mainline branches, page 405. The table creation scripts are stored in a configuration text file used by the Surround SCM Server. The script for each server type is stored in the configuration file, allowing DBAs to use the script for help manually creating the tables or editing database attributes. See the Surround SCM installation help for information. 385

402 Setting the default server database location Setting the default server database location Surround SCM Server settings are stored in a database and each Surround SCM Server has its own database. You can configure the server to store its database in a different location or convert the database to a different type. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Server Database from the Global Server Options category. The current Surround SCM Server database type, name, and username are displayed. 3. Click Change to change the database location. See Changing the server database location, page Click Convert to convert the database to a different type. See Converting the server database to a different type, page Click OK to save the changes. Converting the server database to a different type You can convert the server database to Oracle, PostgreSQL, or SQL Server format. Any mainline branches stored in the same RDBMS database instance as the server database are also converted to the new instance. Keep the following in mind before you start the conversion: All users must be logged out of the Surround SCM Server. The destination database cannot be in use by another server. All of the tables in the destination database must be empty except for the serverid, ownerlck, and RDBMSOptions tables. Note: Surround SCM can automatically create the server database tables initialized with default data during the conversion or you can manually create the tables. See Creating Surround SCM tables, page Make sure you are logged in to the Surround SCM Server you want to convert. 2. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 386

403 Converting the server database to a different type 3. Select Server Database from the General Server Options category. 4. Click Convert. The Surround SCM Server Database Connection dialog box opens. 5. Select a Connection Type. 6. Enter the Connection Information. The fields displayed depend on the selected connection type. 7. Click Test to test the connection. The Test Connection dialog box opens and displays the results. If the test connection fails, you can copy and paste the text into an or text file and send it to your DBA for help. 8. Click Close to close the Test Connection dialog box. You return the Surround SCM Server Database Connection dialog box. 9. Enter the Minimum number of connections and Maximum number of connections to specify the smallest and largest number of connections that will be allowed in the database connection pool. 10. Click OK to convert the database. The conversion information is sent to the Surround SCM Server for validation. If the validation is successful, you are prompted to start the conversion. Remember that users cannot log in during the conversion process. If the validation fails, make sure the Surround SCM Server tables exist and are empty, except for the serverid, ownerlck, and RDBMSOptions tables. You should also make sure that another server is not using the database. 11. Click Yes. The conversion starts. The Conversion Status dialog box opens. 12. Click Close when the conversion finishes. You are prompted to use the converted server database. 13. Click Yes. You must stop and restart the Surround SCM Server to before users can access files. Note: You can also manually change the database the Surround SCM Server is using. See Changing the server database location, page

404 Changing the server database location Changing the server database location You can configure the Surround SCM Server to use a different database. For example, you may need to point to the server database to a new location after moving it or use a backup copy of the database if you experience problems. You should not need to frequently change the server database. 1. Make sure you are logged in to the Surround SCM Server you want to change. 2. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 3. Select Server Database from the General Server Options category. 4. Click Change. The Surround SCM Server Database Connection dialog box opens. 5. Select a Connection Type. 6. Enter the Connection Information. The fields displayed depend on the selected connection type. 7. Click Test to test the connection. The Test Connection dialog box opens and displays the results. If the test connections fails, you can copy and paste the text into an or text file and send it to your DBA for help. 8. Click Close to close the Test Connection dialog box. You return to the Surround SCM Server Database Connection dialog box. 9. Enter the Minimum number of connections and Maximum number of connections to specify the smallest and largest number of connections that will be allowed in the database connection pool. 10. Click OK to change the database location. The following information is verified: The specified connection information connects to a valid RDBMS. A Surround SCM Server application is not already configured for the selected server database. 388

405 Adding RDBMS connections The database is in the current format. If it is in an older format, you are prompted to upgrade it. Click Yes to upgrade the database. The database contains the required tables and the tables are accessible. If the database does not contain any Surround SCM tables, you are prompted to create them. See Creating Surround SCM tables, page You return to the Server Database category. Click OK to apply the changes. Note: You must stop and restart the Surround SCM Server before users can access files. Adding RDBMS connections The Surround SCM Server database and mainline databases are stored in RDBMS-based databases. The server and mainline database tables are stored in the same RDBMS database by default. If you decide to move the server database or mainlines to a different RDBMS database, you must first create an RDBMS connection. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select RDBMS Connections from the General Server Options category. 3. Click Add to add a new RDBMS connection. The Add Connection dialog box opens. 389

406 Adding RDBMS connections 4. Select a Connection Type. The fields displayed depend on the selected connection type. 5. Enter the RDBMS connection information. PostgreSQL Enter the Database Name, Host Name, Port, and Username and Password. ODBC-SQL Server Enter the Data Source Name (DSN). Only ODBC System Data Source Name types are supported. Enter the Username and Password. If you are using Windows NT authentication, leave these fields empty. The username and password of the logged in user on the Surround SCM Server computer is automatically used. Oracle Enter the Service Name of the host to connect to, Port, and Username and Password. 6. Enter the Minimum number of connections to specify the smallest number of connections to store in the database connection pool. When the Surround SCM Server starts, it automatically creates the specified number of database connections. Increasing this number can improve performance because the server does not need to create a database connection later. If you increase this number, you may need to purchase additional licenses from the database vendor. 7. Enter the Maximum number of connections to specify the largest number of connections to store in the database connection pool. The default number of connections is 999. Only change this number if you have a large number of mainline branches and are using too many connections to the backend database. 8. Click Test to validate the connection. The Test Connection dialog box opens and displays the results. If the test connection fails, you can copy and paste the text into an or text file and send it to your DBA for help. 9. Click Close to close the Test Connection dialog box. You return to the Add Connection dialog box. 10. Click OK to add the connection. 390

407 Editing RDBMS connections Editing RDBMS connections You can edit the information for an RDBMS connection. If the connection is used by active mainline branches, you can only change the number of connections. Note: You must inactivate any mainline branches stored in the RDBMS database before you edit the connection information. See Inactivating and activating branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select RDBMS Connections from the General Server Options category. 3. Select a connection and click Edit. The Edit Connection dialog box opens. Note: The RDBMS connection for the Surround SCM Server database is displayed, but you cannot edit it. See Changing the server database location, page 388 for information about changing the server database location. 4. Make any changes and click OK. Deleting RDBMS connections You cannot delete an RDBMS connection if it contains active mainline branches. You also cannot delete the server database RDBMS connection. Note: You must inactivate any mainline branches stored in the RDBMS database before you delete the connection. See Inactivating and activating branches, page Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select RDBMS Connections from the General Server Options category. 3. Select a connection and click Delete. You are prompted to confirm the deletion. 4. Click Yes. The connection is deleted. Backing up Surround SCM databases The Surround SCM Server database and mainline branch databases should be backed up regularly. See Backing Up Surround SCM 2009 and Later Databases for information about backing up PostgreSQL databases on the Surround SCM Server computer using the pgadmin tool. If you use a different RDBMS or moved the PostgreSQL database to a different computer, ask your DBA for help with backups. 391

408 Locking databases for backups Locking databases for backups Locking the database prevents users from performing actions that write to the database, such as adding and checking out files. Users can only perform read-only actions, such as getting or viewing files. This helps ensure that all data is included in the backup. Note: The database is automatically unlocked if you restart the Surround SCM Server. 1. Choose Tools > Administration > Database Lock. The Database Lock dialog box opens. 2. Click Lock Database. The database is locked. If users perform actions that require writing to the database while it is locked, a message is displayed that explains that the action cannot be performed because the database is locked. 3. After you complete the backup, unlock the database. Choose Tools > Administration > Database Lock, select the locked database, and click Unlock Database. Resolving database issues If you notice a slowdown in Surround SCM performance or if database errors are written to the server log, you can analyze databases to identify and repair issues. You can analyze databases while users are connected to the Surround SCM Server without affecting performance. When analysis is complete, you can repair any issues identified either using Surround SCM or manually. You may consider repairing databases during off-peak hours, such as in the evening or over the weekend, because users cannot perform actions that write to the affected database. Note: You do not need to analyze databases on a regular basis. You should be familiar with database maintenance before attempting to repair any issues. Selecting an analysis and repair tool You can analyze and repair databases using the Surround SCM Client, CLI, or analyze utility. Surround SCM Client Use to analyze and repair active database connections on the Surround SCM Server you are connected to. See Analyzing and repairing databases, page 394. CLI Use the analyzedb command from a command line to analyze and repair active database connections on the Surround SCM Server you are connected to. See the Surround SCM CLI help for information. Analyze utility Use to analyze RDBMS databases not in use by a Surround SCM Server and clear database server associations. You can also analyze and repair databases for active connections as you can in the Surround SCM Client or CLI. See the Surround SCM Analyze Utility help for information. Setting database analyze and repair options You can specify the types of issues to check for and repair when analyzing databases. 1. Choose Tools > Administration > Analyze/Repair Database. 392

409 Setting database analyze and repair options The Analyze Database dialog box opens. 2. Click Options. The Analyze and Repair Options dialog box opens. 3. Select Perform CHECKDB (SQL Server only) to verify the integrity of database objects in SQL Server. This option runs the SQL Server CHECKDB command when analyzing databases and returns a list of errors found. A DBA must manually repair the issues. Refer to the SQL Server help for information. 4. Select any Analyze and Repair options to check for specific repairable issues. See Repairs for common database issues, page 396 for information about the repair actions performed when these issues are found. Option Check for share corruption Check for duplicate filename conflicts Check for orphaned check outs Check for undestroyed repositories Checks for: Shares that were not removed when a repository was removed, files still marked as base share files after shares were removed, and invalid shares of share links. Duplicate filenames in the same repository. Files checked out by deleted users. Undestroyed child repositories with destroyed parent repositories or undestroyed repositories in destroyed branches. 393

410 Analyzing and repairing databases Option Check for inconsistent current versions Check for invalid tip versions Check for undestroyed merge events Check for branches with duplicate root repositories Check if VACUUM is needed Checks for: Files with inconsistent current version numbers. Files with invalid tip version numbers. Merge event records that were not destroyed when the associated file was destroyed. Corrupted branches with duplicate or invalid root repositories after a template was applied. PostgreSQL vacuum needed to remove dead table rows to free up database space and improve performance. PostgreSQL only. 5. Select Force reindex to reindex database tables. You may want to reindex tables if you notice a performance slowdown. This option only applies to PostgreSQL and SQL Server databases. If you use Oracle, ask your DBA for help checking indexes. Note: Reindexing may temporarily affect Surround SCM performance. As with any repair, you may want to consider reindexing only during off-peak hours. 6. Click OK to save the changes. Analyzing and repairing databases If issues occur in the server database or databases for active RDBMS connections, you can analyze and repair the databases to fix the issues. Note: If you need to analyze and repair issues in databases not currently in use by a Surround SCM Server, use the analyze utility. See the Surround SCM Analyze Utility help for information. You can analyze databases at any time without affecting Surround SCM performance. If the analysis indicates issues, you can repair them from Surround SCM. When repairing, Surround SCM is locked to prevent users from writing to the database, but users can still perform read-only actions. Some repairs may make branches temporarily unavailable while mainline branches are reloaded in the cache. You may consider repairing databases during off-peak hours, such as in the evening or over the weekend. Note: More advanced issues may require manual repair by your DBA. 1. Choose Tools > Administration > Analyze/Repair Database. The Analyze Database dialog box opens. 394

411 Analyzing and repairing databases 2. Select the RDBMS connection to analyze or select <all active connections> to analyze databases for all RDBMS connections with at least one active mainline branch. If all mainline branches in an RDBMS connection are inactive or removed, the connection is skipped. You can analyze these connections individually before reactivating or restoring mainline branches. 3. Click Options to configure analysis and repair options. See Setting database analyze and repair options, page Click Analyze to analyze the selected database. The analysis progress and results are displayed. You can copy and save the results for your database maintenance records or to help DBAs troubleshoot other issues. If issues are found, you should back up the database before repairing them. See Backing up Surround SCM databases, page 391. Note: To cancel an analysis or repair in progress, click Cancel Processing. 5. Click Repair to repair issues. This option is only available if repairable issues were found during an analysis. The repair results are displayed. See Repairs for common database issues, page 396 for information about how common issues are repaired. Note: If the force reindex repair option is enabled, click Repair to reindex database tables. 6. Click Close to close the dialog box when you are finished. 395

412 Repairs for common database issues Repairs for common database issues Following are common database issues that can be identified during an analysis and the actions Surround SCM performs to repair them. Database issue Files marked as shared when they are not Shared files found in removed repositories Invalid shares (share links also marked as share bases) Duplicate filenames in the same repository Orphaned check outs (files checked out by deleted users) Undestroyed child repositories with destroyed parent repositories Undestroyed repositories in destroyed branches Undestroyed merge events Inconsistent current version numbers Invalid tip version numbers Branches with duplicate root repositories Vacuum needed (PostgreSQL only) Repair Clears the share marker Removes the shares Removes the invalid shares Renames the newer file by appending '~#' to the filename (e.g., ReadMe~2.txt) Removes the check outs Destroys the child repositories Removes the repositories in incompletely destroyed branches Removes the merge events Resets current versions to correct number Removes invalid tip versions and sets the previous version number on the file Destroys duplicate or invalid root repositories and removes templates from branches to restore them to their original structure Vacuums tables requiring it 396

413 Working with the Surround SCM Server Log You can view information about problems that occur during Surround SCM Server startup and while the server is running in the server log. 1. Choose Tools > Administration > Server Log. The Server Log dialog box opens. 2. Select a Filter to filter the entries by log level. See Server log levels, page 398. Select one of the following options to further narrow the log entries displayed: and More Severe includes the filtered log entries plus more severe entries. and Less Severe includes the filtered log entries plus less severe entries. Only limits to the filtered log entries. 3. Select the entry you want to view. The details are displayed in the Selected Log Entry area. 4. Click Save As to save log entries. The Server Log Save Options dialog box opens. Select a Save option, a Format, and click OK. The following formats are available: All saves the entire log. Current Page saves the current page of log entries. Pages saves entries in the specified page range. The following date range saves entries created during the specific date range. 5. Click Print to print log entries. 397

414 Server log levels The Server Log Print Options dialog box opens. Select a Print option and click OK. The following formats are available: All to prints the entire log. Current Page prints only the current page of log entries. Pages prints entries in the specified page range. The following date range prints entries created during the specified date range. 6. Click Delete All to delete all the log entries or click Delete by Date to delete log entries created before the specified date and time. 7. Click Close when you finish. Server log levels The level of logging defines how detailed the log is. A lower level, such as Unusual Activity, provides greater detail because more types of events are logged. Level Severe Error Error Warning Unusual Activity Information Description An event is written to the log when a severe problem or critical condition occurs, such as a server failure. An event is written to the log when an error condition occurs, such as when a connection attempt to a client fails. An event is written to the log when a warning condition occurs, such as a server communication failure. An event is written to the log when unusual activity occurs, such as a user trying to log in with an incorrect username. An event is written to the log with every significant action that takes place, such as the server log starting. Note: Events for the selected level and all higher levels are logged. If you select Unusual Activity, the server logs all severe error, error, warning, and unusual activity events. 398

415 Managing Mail When Surround SCM sends , it is placed in the mail queue for processing by the server. If all mail is not sent before the Surround SCM Server is shut down, the mail queue is saved to the hard drive. The mail queue is reloaded and mail is sent the next time the server is started. The mail queue only contains unsent s. is generally sent and removed from the mail queue in less than 60 seconds. An can get stuck in the mail queue if send mail is paused, the SMTP options are not properly configured, or the SMTP host is experiencing problems. 1. Choose Tools > Administration > Mail Queue. The Mail Queue dialog box opens with a list of all unsent s. The list includes the date, the date of the last attempt to send the , the status of the , and the subject. 2. Select an to view details. The name, address, and mail type are displayed in the Recipients area. The send error is displayed in the Errors area. Resending mail You can manually resend s stuck in the mail queue if you do not want to wait for the Surround SCM Server to send the after it restarts. 1. Choose Tools > Administration > Mail Queue. The Mail Queue dialog box opens. 2. Select the you want to resend and click Reattempt. Surround SCM tries to resend the . Deleting mail You can delete s stuck in the mail queue to prevent sending them when the mail queue reloads after the Surround SCM Server is restarted. 1. Choose Tools > Administration > Mail Queue. The Mail Queue dialog box opens. 399

416 Deleting mail 2. Select the s you want to delete. 3. Click Delete. The is deleted from the mail queue. 400

417 Configuring TestTrack Integration Before users can attach source files to TestTrack items, a Surround SCM administrator must enable the integration on the Surround SCM Server. You can also set additional integration settings to customize TestTrack field labels or sync them with the field labels used in the TestTrack project. Enabling TestTrack integration You can rename issue, requirement, and test case field labels in Surround SCM after you enable the TestTrack integration. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select TestTrack Integration from the Global Server Options category. 3. Select Enable TestTrack integration to enable the integration between Surround SCM and TestTrack. 4. Select a TestTrack field and click Edit to change the field label value. Renamed field labels are only used in the Surround SCM Client. 5. Click Sync with TestTrack to synchronize the field label values with labels in a specified TestTrack project. See Syncing field labels with TestTrack, page Click Restore Default Values to replace all renamed field labels with the default values. 7. Click OK to save the changes. Syncing field labels with TestTrack If users will attach files to items in a TestTrack project that uses renamed field labels, you can sync the field labels with the TestTrack project for consistency. 401

418 Setting TestTrack integration options for repositories Syncing field labels eliminates the need to manually rename individual TestTrack field labels. However, if the field label values change in the TestTrack project, you need to sync the field labels again to see the changes in Surround SCM. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select TestTrack Integration from the General Server Options category. 3. Click Sync with TestTrack. The Sync with TestTrack Project dialog box opens. 4. Enter the TestTrack Server address and Port number. 5. Click Get Projects to load the active projects and select the Project you want to sync with from the list. 6. Click OK to save the changes. Setting TestTrack integration options for repositories You can configure TestTrack integration settings for repositories. You can restrict users to a connection associated with a specific repository or allow them select a connection. You can also enable, disable, or require attaching files to TestTrack when checking in or adding files. 1. Select a repository and choose Activities > Properties. The Properties dialog box opens. 2. Click the TestTrack Integration tab. 402

419 Setting TestTrack integration options for repositories 3. Select Configure repository settings to set TestTrack integration options for the repository. This option overrides the default parent repository settings. 4. Select a Default Connection to restrict users to a specific project. 5. Select Can override default TestTrack Connection to let users select a project. Do not select this option if you want to restrict users to a specific project. 6. Select an Attach to option for issues, test cases, and requirements. You can enable, disable, or require attaching files to TestTrack items when checking in or adding files to the repository. 7. Click OK to save the changes. 403

420

421 Upgrading Surround SCM When you upgrade the Surround SCM Server or Client, you may need to perform additional tasks to complete the update, such as upgrading mainline branches, RDBMS connections, and legacy labels. Upgrading mainline branches The Surround SCM Server automatically upgrades RDBMS mainline branches stored in the server database. You may need to manually upgrade mainline branches that are stored in different locations before they can be used. Mainline branches created in Surround SCM 2008 or earlier need to be upgraded to RDBMS format. See Upgrading non-rdbms mainline branches, page 406. Old mainline branches stored in an RDBMS database that is not the server database need to be upgraded to the current format. See Upgrading old mainline branches, page 405. Keep the following in mind: A database cannot include two mainline branches with the same name. If the destination database already includes a mainline with the same name as the mainline you are upgrading, you must select a different destination database. During the upgrade, Surround SCM attempts to match users and security groups in the mainline branch to users and groups on the Surround SCM Server. If matching names are found, Surround SCM assumes they are the same user or group. If users in the mainline do not exist on the server, they are created without assigned licenses. If security groups in the mainline do not exist on the server, they are created without any security commands enabled. Surround SCM also attempts to match TestTrack connection information. If you are upgrading a mainline branch from Surround SCM 5.x or earlier, you are prompted to automatically upgrade the branch to Surround SCM 2008 format before it is upgraded to RDBMS format. After mainline branches are upgraded, you must manually upgrade labels created in Surround SCM 2008 or earlier. See Upgrading legacy labels, page 409. Upgrading old mainline branches The Surround SCM Server automatically upgrades mainline branches stored in the server database when it starts. If you store mainline branches in other RDBMS databases, you must upgrade them to the current format. Mainline branches that require upgrading before they can be used are appended with 'old database'. 405

422 Upgrading non-rdbms mainline branches 1. Select the mainline branch you want to upgrade and choose Tools > Administration > Upgrade Mainline Branch. The Upgrade RDBMS Mainline dialog box opens. 2. Select the connection you want to upgrade. To select multiple connections, Ctrl+click each connection. 3. Click Upgrade. You are prompted to upgrade the mainline branch. 4. Click Yes. The upgrade information is sent to the Surround SCM Server for validation. If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens. If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an or text file and it to your DBA for help. 5. Click Close when the upgrade finishes. The connection is marked as Current in the Upgrade RDBMS Mainline dialog box. Upgrading non-rdbms mainline branches Mainline branches created in Surround SCM 2008 or earlier must be upgraded to RDBMS format in Surround SCM 2009 or later because the database is now stored in an RDBMS format. Mainline branches that require upgrading are appended with 'non-rdbms database'. 1. Select the mainline branch you want to upgrade and choose Tools > Administration > Upgrade Mainline Branch. 406

423 Resolving custom field and workflow issues You are prompted to upgrade the mainline branch. 2. Click Yes. The Mainline Destination dialog box opens. 3. Select the Destination database for the upgraded mainline branch. If the database you want to use is not listed, you may need to add an RDBMS connection for it. See Adding RDBMS connections, page Select Ignore errors during upgrade to allow Surround SCM to continue the upgrade regardless of any errors it may encounter. Only select this option if you have already used the Surround SCM Analyze Utility to identify any data integrity issues in the database and were unable to repair issues causing errors. 5. Click OK. The upgrade information is sent to the Surround SCM Server for validation. If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens. If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an or text file and it to your DBA for help. Note: If the destination database does not include any Surround SCM tables, you are prompted to create them. See Creating Surround SCM tables, page Click Close when the upgrade finishes. Note: The non-rdbms database is not deleted from the original location during the upgrade. You may want to manually delete the directory after verifying the branch is successfully upgraded to RDBMS format. Resolving custom field and workflow issues When you restore a mainline branch, you must manually add custom fields, workflow states, and workflow templates that do not yet exist on the Surround SCM Server before the mainline branch can load correctly. You can also delete any custom fields, workflow states, and workflow templates you do not want to use on the Surround SCM Server. 1. Choose Tools > Administration > Resolve Custom Fields/Workflow. The Resolve Custom Fields/Workflow dialog box opens with the Custom Fields tab selected. 407

424 Resolving custom field and workflow issues 2. Resolve custom field issues on the Custom Fields tab. Select a custom field and click Add to Server to add it to the Surround SCM Server. Select a custom field and click Delete to delete it. 3. Click the States tab to resolve any workflow state issues. Select a state and click Add to Server to add it to the Surround SCM Server. Select a state and click Delete to delete it. 4. Click the Workflow tab to resolve any workflow template issues. Select a template and click Add to Server to add it to the Surround SCM Server. Select a template and click Delete to delete it. 408

425 Upgrading RDBMS connections Note: A workflow template can only be added to the Surround SCM Server if all states that the workflow uses are on the server. Upgrading RDBMS connections If an existing RDBMS connection that does not contain any active mainlines was configured in Surround SCM 2009 or earlier, you must manually upgrade the RDBMS connection before it can be used as a destination for new mainline branches. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select RDBMS Connections from the General Server Options category. 3. Select the connection to upgrade. Connections that require upgrading are marked as Old in the Format column. Upgrading a connection also automatically upgrades all the mainline branches stored in the database. 4. Click Upgrade. You are prompted to upgrade the mainline branch. 5. Click Yes. The upgrade information is sent to the Surround SCM Server for validation. If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens. If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the error message into an or text file and send it to your DBA for help. 6. Click Close when the upgrade finishes. The connection is marked as Current in the Server Options dialog box. Upgrading legacy labels When you upgrade from Surround SCM 2008 and earlier, labels are not automatically applied to files and must be manually upgraded before they can be used. 409

426 Upgrading legacy labels Labels created in earlier Surround SCM versions were applied to the file version in all branches. Now, you can create labels for a mainline branch or a specific branch. Upgrading legacy labels allows you to choose the existing labels to import and the branches to apply them to. After legacy labels are upgraded, you can manage them the same way as other labels. See Using Labels, page 141. Note: The timestamp and comments from existing labels are copied to the label history during the upgrade. 1. Select the mainline branch that includes the legacy labels. 2. Choose Tools > Administration > Upgrade Legacy Labels. The Legacy Labels dialog box opens and displays the legacy labels for the selected mainline branch. 3. Select the labels you want to upgrade. To select multiple labels, Ctrl+click each label. 4. Click Upgrade. The Upgrade Legacy Labels dialog box opens. The branches the label can be applied to are displayed. 5. Enter a Label description. This field is not available if you are upgrading multiple labels. 6. Select Show snapshot branches to include snapshot branches in the branch list. 7. Select the branch to apply the label to. To select multiple branches, Ctrl+click each branch. If you select a branch that did not previously include any files with the label applied, the label is not applied to any files. 410

427 Deleting legacy labels Tip: The File count field displays the total number of files the label can be applied to. Compare this number to the File Count column for each branch to determine the branches to apply the label to. Typically, you will apply the label to the branch with the highest file count because it is a good indicator of the branch the label is intended for. You may also apply the label to other branches depending on how it is used. File count information not displayed if you are upgrading multiple labels. 8. Click OK. The label is upgraded and you return to the Legacy Labels dialog box. Note: You can also delete legacy labels. See Deleting legacy labels, page 411. Deleting legacy labels You can delete legacy labels that are no longer used. When you delete labels, the label history is also deleted. 1. Select the mainline branch that includes the legacy labels. 2. Choose Tools > Administration > Upgrade Legacy Labels. 3. Select a label and click Delete. You are prompted to confirm the deletion. This action cannot be undone. 4. Click Yes. The label is deleted. 411

428

429 Using Proxy Servers The Surround SCM proxy server is a file caching proxy that improves performance of file retrievals at remote client sites. The proxy server is usually installed on a separate computer from the master server at the remote location where the clients using the proxy reside. Proxy servers can help improve performance issues that are often experienced when source files are retrieved across distributed development environments. Proxy servers cache files requested by remote Surround SCM clients. Subsequent requests for the files are handled by the proxy server instead of the Surround SCM Server, which decreases network usage and response time. About proxy servers Proxy servers are typically installed at remote sites to support Surround SCM clients. The proxy server communicates with the master Surround SCM Server, which contains source files and file-related metadata. As files are requested, they are retrieved from the master server and cached on the proxy server. The next time a client issues a request to get the file, the proxy server checks to see if the file is available in the cache. If the file is in the cache, the proxy server returns it to the client. If the file is not in the cache, it is retrieved from the master server, added to the proxy server cache, and returned to the client. The proxy server must be installed at the local site and then added to Surround SCM before users can connect to it. See Adding proxy servers, page 416. Each Surround SCM Server can support multiple proxy servers. Each proxy server can only use one master Surround SCM Server. Performance improvements are noticeable only after files are cached. The first time files are retrieved, they are returned by the Surround SCM Server. You can specify the default users for each proxy server. If the proxy server is not available, Surround SCM clients retrieve files directly from the master server. Proxy server maintenance is minimal. Proxy servers do not require backups or extra monitoring when a cache age limit option is set. For example, your organization s Surround SCM Server is located in North America but European-based development teams need to perform a get when a new branch is created. Without a proxy server, each user gets the files from the Surround SCM Server, which impacts bandwidth, Surround SCM Server CPU usage, and productivity due to wait time. To eliminate these issues, you can install a proxy server at the local site in Europe. When one user gets a file, it is cached on the proxy server. When other users get the file, it is returned by the proxy server instead of the Surround SCM Server. 413

430 Starting the Surround SCM Proxy Server Files are cached in the SCMProxyCache directory in the directory where the Surround SCM proxy server application is installed. As files are cached, a subdirectory is created using the name of the mainline branch the files are retrieved from. Files are cached until a specified disk space limit is reached. The least recently used files are deleted from the cache so files can continue to be cached. You can also set an age limit for files before they are deleted from the cache or delete files manually. About master servers and proxy servers The proxy server is a client of the master Surround SCM Server and a server to client applications, which means it listens for transactions from Surround SCM clients (GUI clients and the CLI) and it connects to the Surround SCM master server to get files. The proxy server needs the same connection information that the Surround SCM clients use to connect to the master server. The master server also needs proxy server connection information to provide to the clients that use the proxy. The proxy server only handles get operations. Check in operations and file metadata are managed by the master Surround SCM Server to ensure that file versions and metadata information is always current. The Surround SCM Server also handles security and licensing. Before a proxy server can connect to a master Surround SCM Server, you must configure the master server to accept proxy requests. Master Surround SCM Server proxy settings are configured using a Surround SCM Client. See Configuring proxy servers, page 415. Proxy server computer options can be modified with the registry utility. See the Surround SCM Registry Utility help for information. Starting the Surround SCM Proxy Server An administrative user must make sure the Surround SCM Proxy Server is running before clients can access it. 414

431 Configuring proxy servers Windows If the proxy server is installed as a service, it starts automatically. If the server is installed as an application, you must start it manually. Choose Programs > Seapine Software > Surround SCM > Surround SCM Proxy Server from the Start menu. Note: If the server is installed as a service but not running or you need to restart it, see the Windows documentation for information about starting a service. Linux Enter /usr/bin/surroundscmproxy start. If you need to restart the server, enter /usr/bin/surroundscmproxy stop and then restart the server. Configuring proxy servers To ensure security of the master Surround SCM Server data, you must configure it to accept connections from known proxy servers before attempting to use the proxy server. The installation and configuration of the proxy server requires information about both the Surround SCM Server and proxy servers. You must set the configuration options on both computers. Note: We recommend adding a proxy server to the master Surround SCM Server before installing the proxy server. However, if the proxy server is already installed and you add a proxy server to Surround SCM, you can use the registry utility to configure the proxy server settings. The server name, password, and port number must match. See the Surround SCM Registry Utility help for information. 1. Choose Tools > Administration > Proxy Maintenance. The Proxy Server Maintenance dialog box opens. 415

432 Adding proxy servers 2. Select a proxy server to view the configuration information. 3. Click Add to add a proxy server. See Adding proxy servers, page Select a proxy server and click Edit to modify it. See Editing proxy server settings, page Select a proxy server and click Delete to delete it. See Deleting proxy servers, page 419. Adding proxy servers After you install the proxy server, you must set the connection information so the proxy server can communicate with the master Surround SCM Server. You can also set options to control how the server caches files and select proxy server users. 1. Choose Tools > Administration > Proxy Maintenance. The Proxy Server Maintenance dialog box opens. 2. Click Add. The Add Proxy Server dialog box opens. 416

433 Adding proxy servers 3. Enter a Proxy name. Enter a unique name, such as the computer location. 4. Enter and confirm a proxy server Password. You must enter a password. Note: Make sure the proxy name and password match the values in the registry utility. See the Surround SCM Registry Utility help for information. 5. Enter the Proxy address. This is the IP or host address of the computer where the proxy server application is installed. The address must be resolvable by the clients that use the proxy. 6. Enter the Proxy port. Surround SCM clients connect to the proxy server on this port via TCP/IP. The default port number is Valid values are Note: The proxy server port must be different from the master Surround SCM Server port if the servers are hosted on the same computer. 7. Enter the Refresh interval to indicate how often the proxy server connects to the master server to check for updates. The proxy server periodically connects to the master server to check the proxy server settings. The default interval is 0.5 hours. Valid values are hours. 8. Enter the Minimum file size for cache to set the minimum size of files to be cached. 417

434 Editing proxy server settings Files smaller than the specified size are not cached and are always retrieved from the master server. The default size is 10 KB. 9. Select any additional options. Maximum cache disk space sets the maximum amount of space the proxy server can use to the specified limit. If the cache exceeds the maximum disk space, the least recently used files are deleted from the cache. Age limit sets the number of days to keep retrieved files in the proxy server cache. Auto pre-cache recently requested files automatically checks for and retrieves newer file versions from the master server based on the files in the proxy server cache. Select Every day to pre-cache files every day at the specified time. Select Every refresh to pre-cache files when the proxy server refreshes, which is set in the Refresh interval field. Tip: An automatic pre-cache only evaluates the last 1,000 files in the cache. If you need to pre-cache more than 1,000 files, use a batch file to get the files to a temporary or working directory. See the Surround SCM CLI help for information about getting files. Encrypt transactions between proxy server and master server encrypts messages sent between servers. Messages and file transfers are encrypted with a 512-bit key. Encryption provides a higher level of security, but may slow performance because of the time spent encrypting and decrypting messages. Encrypt transactions between proxy server and clients encrypts messages sent between the proxy server and Surround SCM clients. Compress transactions between proxy server and master server compresses data during file transfers. Compress files if you have a slow connection to the master server. 10. Select the Default Proxy Server Users. These users automatically use the proxy server to retrieve files. To add a user, select the user in the Available users list and click Add to move the user to the Selected users list. To remove a user, select the user in the Available users list and click Remove to move the user to the Available users list. Tip: Users can change override the proxy server set by the administrator. See Setting proxy server options, page Click OK. The proxy server is added. Note: We recommend adding a proxy server to the master Surround SCM Server before installing the proxy server. If the proxy server is already installed and you add a proxy server to Surround SCM, you can use the registry utility to configure the proxy server settings. The server name, password, and port number must match. See the Surround SCM Registry Utility help for information. Editing proxy server settings You can edit proxy server settings if the server location changes or you need to modify the configuration options. 1. Choose Tools > Administration > Proxy Maintenance. 418

435 Deleting proxy servers The Proxy Server Maintenance dialog box opens. 2. Select a proxy server and click Edit. The Edit Proxy Server dialog box opens. 3. Make any changes. 4. Enter the proxy server password in the Confirm password field. You must confirm the proxy server password before you can save the changes. 5. Click OK to save the changes. The changes are sent to the proxy server based on the refresh interval value. If you want to immediately send changes to the proxy server, you must restart the proxy server on the computer where it is installed or use a remote management utility to restart it. After the proxy server restarts, it retrieves the new settings and refreshes the cache. Note: If you change the proxy server name or password, you must also update the proxy server registry settings. See the Surround SCM Registry Utility help for information. Deleting proxy servers You can delete proxy servers if they are no longer used. 1. Choose Tools > Administration > Proxy Maintenance. The Proxy Server Maintenance dialog box opens. 2. Select a proxy server and click Delete. The proxy server is deleted. Setting proxy server options You may need to set proxy server options if your organization uses proxy servers. See Using Proxy Servers, page 413. Note: Some user options may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed. 1. Choose Tools > User Options then select the Proxy Server category. 419

436 Setting proxy server options 2. Select a Proxy Server option. Use proxy server defined by administrator uses the proxy server set by the administrator. Use selected proxy server uses a specific proxy server. Select this option if the administrator has not configured a default proxy server or the proxy server is not available. Do not use proxy server disables proxy server use. 3. Select Compress file transfers from proxy server to compress files if you have a slow connection to the proxy server (e.g., you connect to the server via an ISP). Compression works best on certain types and sizes of files. This option may slow performance due to the time needed to compress and decompress files. 4. Click OK to save the changes. 420

437 Managing the Surround SCM Web Server The Surround SCM Web Server provides access to Surround SCM Web, a web-based application that allows users to view and download Surround SCM source files from a browser. To use Surround SCM Web, the Surround SCM administrator must specify HTTP and HTTPS port numbers and the Surround SCM Server connection information for the web server configuration during installation. The Surround SCM Registry Utility includes additional options to change the Surround SCM Web port numbers, use your own SSL certificate, and import the public key fingerprint if RSA key exchange is configured on the Surround SCM Server. See the Surround SCM Registry Utility help for information. Starting the Surround SCM Web Server An administrative user must make sure the Surround SCM Web Server is running before users can log in to Surround SCM Web. Windows The Surround SCM Web Server is installed as a Windows service and starts automatically. Note: If the server is not running or you need to restart it, see the Windows documentation for information about starting a service. Linux Enter /usr/bin/surroundscmweb start. If you need to restart the server, enter /usr/bin/surroundscmweb stop and then restart the server. 421

438

439 Managing the Surround SCM CMIS Server The Surround SCM Content Management Interoperability Services (CMIS) Server provides access to Surround SCM files and actions through CMIS clients, such as Adobe Drive and CMIS Workbench. CMIS repositories, which map to Surround SCM repositories, must be configured on the Surround SCM CMIS Server before users can access Surround SCM from CMIS clients. Starting the Surround SCM CMIS Server An administrative user must make sure the Surround SCM CMIS Server is running before configuring CMIS repositories. The server must also be running before users can access Surround SCM files and actions from CMIS clients, such as Adobe Drive and CMIS Workbench. Windows The Surround SCM CMIS Server is installed as a service and starts automatically. Note: If the server is not running or you need to restart it, see the Windows documentation for information about starting a service. Linux Enter /usr/bin/surroundscmcmis start. If you need to restart the server, enter /usr/bin/surroundscmcmis stop and then restart the server. Starting the Surround SCM CMIS Admin Utility An administrative user can use the Surround SCM CMIS Admin Utility to configure CMIS repositories so users can access Surround SCM files and actions from CMIS clients, such as Adobe Drive and CMIS Workbench. Windows Choose Programs > Seapine Software > Surround SCM > Surround SCM CMIS Admin Utility on the Start menu. Linux Enter /usr/bin/surroundscmcmisadmin. Configuring CMIS Server options You can manage CMIS repositories and change the server port number using the Surround SCM CMIS Admin Utility. Note: After the Surround SCM CMIS Server is configured, you must provide users with the server address before they can connect to it from CMIS clients. The default CMIS Server address is ServerName:PortNumber/atom. For example, localhost:8080/atom. 423

440 Adding CMIS repositories 1. Start the Surround SCM CMIS Admin Utility. See Starting the Surround SCM CMIS Admin Utility, page 423. The server admin utility opens. 2. Click Add to add a CMIS repository. See Adding CMIS repositories, page Select a repository and click Edit to edit it. See Editing CMIS repositories, page Select a repository and click Delete to delete it. See Deleting CMIS repositories, page Enter the Server port number. The CMIS Server communicates with CMIS clients on this port. The default number is Click OK to save the changes. If you changed the server port number, you must restart the Surround SCM CMIS Server for the change to take effect. See Starting the Surround SCM CMIS Server, page 423. If you changed CMIS repository information, the server automatically refreshes Surround SCM data every 30 minutes, but you can restart the CMIS Server for the changes to take effect immediately. Adding CMIS repositories You must add CMIS repositories to the CMIS Server before users can use CMIS clients to access files in Surround SCM. A CMIS repository includes all the files in the Surround SCM repository it maps to. You can add CMIS repositories that map to a Surround SCM repository in a specific branch or to a Surround SCM repository in all branches. Note: Adobe Drive only displays one CMIS repository when connected to the CMIS Server, even if the server contains multiple CMIS repositories. The repository that Adobe Drive users can browse is typically the repository listed first alphabetically on the server. Keep this in mind when adding CMIS repositories. 1. Click Add in the Surround SCM CMIS Admin Utility. The Add Repository dialog box opens. 424

441 Editing CMIS repositories 2. Enter a repository Name. If the CMIS repository maps to one Surround SCM repository in a specified branch, this is the only name displayed in CMIS clients. If the CMIS repository maps to a Surround SCM repository in all branches, the name and an underscore are prepended to the Surround SCM branch name to help users distinguish between different branches. For example, WysiWriteCode_WysiWrite 1.0 and WysiWriteCode_ WysiWrite Enter the Surround SCM Server Address and Port number or click Find to locate a server. 4. Select Surround SCM Repository options to specify the Surround SCM branch and repository combination to map the CMIS repository to. All branches creates a CMIS repository for each branch that includes the specified Surround SCM repository. This option provides CMIS clients access to the Surround SCM repository across branches without requiring you to add multiple CMIS repositories. Branch creates one CMIS repository for the selected Surround SCM branch and repository. This option provides CMIS clients access to only the specified Surround SCM repository. Repository path specifies the Surround SCM repository to map the CMIS repository to. Enter the repository path or click Browse to locate the repository. If you browse to the repository, you are prompted to log in to Surround SCM before selecting a repository. Recursive includes all files in the CMIS repository from the specified Surround SCM repository and all subrepositories. 5. Click OK. The CMIS Server automatically refreshes Surround SCM data every 30 minutes, but you can restart the CMIS server for the changes to take effect immediately. See Starting the Surround SCM CMIS Server, page 423. Editing CMIS repositories You can edit CMIS repositories to change the name, Surround SCM Server address or port, and mapping to the Surround SCM repository on a specific branch or all branches. 1. In the Surround SCM CMIS Admin Utility, select a repository and click Edit. 425

442 Deleting CMIS repositories 2. Make any changes. 3. Click OK to save the changes. The CMIS Server automatically refreshes data every 30 minutes, but you can restart the CMIS Server for the changes to take effect immediately. See Starting the Surround SCM CMIS Server, page 423. Deleting CMIS repositories You can delete CMIS repositories to prevent users from accessing Surround SCM files in the corresponding repository from CMIS clients. 1. In the Surround SCM CMIS Admin Utility, select a repository and click Delete. The CMIS repository is deleted. The CMIS Server automatically refreshes Surround SCM data every 30 minutes, but you can restart the CMIS server for the changes to take effect immediately. See Starting the Surround SCM CMIS Server, page 423. Troubleshooting Surround SCM CMIS Server issues If users cannot connect to the Surround SCM CMIS Server, review the Surround SCM Server log to troubleshoot the problem. See Working with the Surround SCM Server Log, page 397. Users that access the CMIS Server through Adobe Drive can also view detailed error information in the Adobe Drive log file. In Adobe Drive, click Setting. Select Error as the Log level and click Open log file. The log opens in a web browser. 426

443 Using the Surround SCM API The Surround SCM API provides developers with a dynamic library that can be used to create custom tools that leverage the Surround SCM Server. The following information provides a basic orientation to the Surround SCM API and the key concepts for using it. The API is available as a C library, a Java library, and a.net assembly (Windows only). The API documentation, which includes all available packages, classes, data structures, and examples, is installed with the API library files in your Surround SCM application directory in the following locations: C API documentation API/docs/C/index.html Java API documentation API/docs/Java/index.html.NET API documentation API/docs/DotNet/index.html Note: The APIs are not thread safe. Limit the use of any Surround SCM API to a single thread. Avoiding conflicts with the Surround SCM Client and CLI The Surround SCM API check out commands do not use working directories, which allows more flexibility when integrating with other tools. When using the API, you should not check out files to a working directory because this can cause conflicts with the Surround SCM Client and CLI. To avoid these conflicts, use separate user accounts for the API. Using the C API The C API is separated into a set of data structures and functions. You only need to include the sscamapi.h header in your code. Keep the following in mind: On Windows, include the sscmapi.dll and sscmapi.lib files in your Visual Studio project. On Mac OS X, link against the libsscmapi.dylib file. On Linux, link against the libsscmapi.so file. The C API uses UTF-8 encoding for all string parameters and return values. If you have strings in other Unicode encodings, you must convert them to UTF-8 before passing them to API functions. Examples Source code examples are included in the C API documentation for every function used to interact with the Surround SCM Server. Refer to these examples for information about specific operations. Examples are located in the API/docs/C/samples directory in the Surround SCM application directory. 427

444 Using the Java API Key concepts All calls use an SSCMContext structure as the container that holds data for the currently connected session. The pmainline and pbranch members are used by other functions to identify the mainline and branch to perform operations against. The cookie member is initially populated inside the sscm_connect function. The statuscallback function pointer is optional, but if it is set, the API uses it to return string-based status messages about long-running operations. You typically begin using the API with a call to sscm_connect, which establishes the initial SSCMContext. You then set the context to mainline and branch currently used. After all calls are complete, make a final call to sscm_disconnect to close the session. Note: Pay close attention to the sscm_free_xxxx calls (e.g., sscm_free_branch, sscm_free_file_props, etc.) to ensure memory is released correctly. Refer to the examples for each call in the API documentation to determine when memory management calls are needed. SSCMResult result code All calls also return an SSCMResult result code, which indicates the status of the last call made and defines several enumerated values. You can use the sscm_get_last_error function to return a string based on the error and code generated by the Surround SCM Server. Only the server error string for the last error is stored by the library. The call string is cleared on the next successful function call. Using the Java API The Java API is separated into a set of packages and classes. Keep the following in mind: The main class is SSCMAPI, which includes methods for all primary actions that can be performed against the Surround SCM Server. This class is located in the com.seapine.surroundscm.api package. The Surround SCM API library file must be in the application path for the solution to run. Key concepts All calls use an SSCMContext class as the container that holds data for the currently connected session. The Mainline and Branch members are used by other functions to identify the mainline and branch to perform operations against. The Cookie member is initially populated inside the connect function. You typically begin using the API with a call to SSCMAPI.Connect, which establishes the initial SSCMContext. You then set the context to the mainline and repository currently used. After all calls are complete, make a final call to SSCMAPI.Disconnect to close the session. SSCMResult class All calls also return an SSCMResult class or one of its subclasses. This result code indicates the status of the last call made and defines several enumerated values are defined. You can use the SSCMAPI.getLastError static method to return a string based on the error code and the error generated by the Surround SCM Server. Only the server error string for the last error is stored by the API. The call string is cleared on the next successful function call. 428

445 Using the.net API Using the API on Mac OS X The surroundscm-api.jar looks for the native library using the libsscmapi.jnilib filename. The native library included with the API is named in the following format: libsscmapi.x.y.z.dylib, where x, y, and z are the major, minor, and point release version numbers respectively. To use the API on Mac OS X, create a symlink called libsscmapi.jnilib that points to the native library. Using the API on Linux The surroundscm-api.jar looks for the native library using the libsscmapi.so filename. The native library included with the API is named in the following format: libsscmapi.so.x.y.z, where x, y, and z are the major, minor, and point release version numbers respectively. To use the API on Linux, create a symlink called libsscmapi.so that points to the native library. Using the.net API The.NET API is separated into a set of classes. Keep the following in mind: You need to add the sscmapi dll file as a reference to your.net project in Visual Studio before using the API. The file is in the \API\lib directory in the Surround SCM application directory. All timestamps received from the.net API are in GMT. Make sure all timestamps sent to the API are also in GMT. Key concepts All calls use an SSCMContext class as the container that holds data for the currently connected session. The SetBranch() and SetMainline() methods are used by the other functions to identify the mainline and branch to perform operations against. You typically begin using the API with a call to SSCMAPI.Connect, which establishes the initial context by taking an SSCMContext parameter as an out variable. You then set the context to the mainline and branch currently used. After all calls are complete, make a final call to SSCMAPI.Disconnect to close the session. SSCMResult class All calls also return an SSCMResult class. This result code indicates the status of the last call made and several methods are provided to view the returned error. You can use the SSCMAPI.GetLastError static method to return a string based on the error code and the error generated by the Surround SCM Server. Only the server error string for the last error is stored by the library. The call string is cleared on the next successful function call. 429

446

447 Appendix A: Security Commands Security commands limit the Surround SCM actions that users can perform. The commands you enable or disable for a security group apply to all repositories in the mainline branch. See Controlling Security and User Access, page 277 for more information about security. Commands are grouped in categories. This section provides the following information about each command: Command: The command name. Provide access to: The Surround SCM menu command or other feature that users can access if the command is enabled. For example, Activities > Add Files indicates that users can access the Add Files command from the Activities menu. More information: Other commands that must be enabled to use the command or other information to help you understand the command. Security commands enabled in the Surround SCM GUI client apply to the command line interface (CLI) and WebDAV. Keep in mind that WebDAV-enabled applications may use different functionality and terminology for Surround SCM commands. General security commands The following commands provide access to the Surround SCM clients, integrations, and commonly used features. Command Login Via GUI Client Login Via CLI Client Login Via SCC DLL Integration Login Via WebDAV Login Via Microsoft Office Integration Login Via API Provides access to: Log in using the GUI client Log in using the command line interface (CLI) Log in from SCCIcompliant applications Log in using WebDAV Log in from Microsoft Office Log in using the Surround SCM API More information Enables users to add the Surround SCM menu to Microsoft Word, Excel, PowerPoint, Access, and Project 431

448 General security commands Command Login Via CMIS Client Login Via Web Client Edit TestTrack Integration Add/Remove Files from Labels Generate Reports Edit Own Notifications View Own Committed Changelists Provides access to: Log in from CMIScompliant applications Log in using the Surround SCM Web client Tools > TestTrack Integration > Connections Activities > Advanced > Add Label Label field in the Add Files dialog box (Activities > Add Files Label field in the Check In Files dialog box (Activities > Check In) Add to Label button in the History dialog box (Activities > History) Remove button on the Files tab in the Edit Label dialog box (Tools > Labels) Tools > Reports Tools > My Notifications My Committed from the Filter changelists by list (Tools > Changelists) More information Enables users to configure connections to TestTrack Servers and projects. TestTrack connections are available to all users, but a TestTrack username and password is required to access a project. If this command is disabled, users can still generate a differences report from the History dialog box. Lets users edit their own notifications only. The Edit Triggers command must be enabled for users to add or edit notifications. 432

449 Admin security commands Command Add/Edit Private Filters Add/Edit Private Reports Add External Reports Edit Own Comments Modify Shelves Provides access to: Tools > Filters Tools > Reports Tools > Reports Edit Comments button in the file and repository History Details dialog boxes Activities > Shelve Files Buttons on the Shelves window (View > Shelves) More information Lets users manage their own filters only. Lets users manage their own reports only. Lets users only add reports from external reporting services to Surround SCM. The report is managed in the external reporting service. The Add/Edit Private Reports command must also be enabled for users to add external reports. Lets users edit their own comments only. Lets users manage their own shelves only. Admin security commands Only enable the following commands for administrator security groups. Command Provides access to: More information Edit Server Options Tools > Administration > Server Options Create Mainline Branch Tools > Administration > Default User Options Tools > Administration > Create Mainline Branch Tools > Administration > Upgrade Mainline Branch Must be enabled to migrate a database to Surround SCM from another source control provider. 433

450 Admin security commands Command Provides access to: More information Remove Mainline Branch Tools > Administration > Remove Mainline Branch Tools > Administration > Destroy Removed Mainline Rename Mainline Branch Analyze Database Tools > Administration > Rename Mainline Branch Tools > Administration > Analyze/Repair Database Analyze button on the Analyze Database dialog box (Tools > Administration > Analyze/Repair Database) Repair Database Tools > Administration > Analyze/Repair Database Repair button on the Analyze Database dialog box (Tools > Administration > Analyze/Repair Database) Void Check Out Lock Database Manage Shadow Folders Tools > Administration > Void Check Out Tools > Administration > Database Lock Tools > Administration > Shadow Folders Manage Triggers Tools > Administration > Triggers Also lets users enable notifications for all users. To allow users to only work with their own notifications, enable the Edit Own Notifications command in the General category. Manage Mail Queue Edit Other Users Pending Changelists Tools > Administration > Mail Queue Pending For User from the Filter changelists by list (Tools > Changelists) If this command is enabled, users can work with other users changelists, but some actions, such as Check In, may not be available. 434

451 Admin security commands Command Provides access to: More information View All Committed Changelists Edit Custom Fields Modify Workflow/States Override Workflow Manage Public Filters Edit Other Users Private Filters Manage Public Reports Edit Other Users Private Reports Edit Proxy Server Settings Manage Labels All Committed from the Filter changelists by list (Tools > Changelists) Tools > Administration > Custom Fields Tools > Administration > Workflow Activities > Advanced > Change State State list in the Properties dialog box (Activities > Properties) State list in the Check In Files dialog box Buttons on Filters dialog box for public filters only (Tools > Filters) Edit button on Filters dialog box for filters created by other users (Tools > Filters) Buttons on Reports dialog box for public reports only (Tools > Filters) Edit button on Reports dialog box for reports created by other users (Tools > Reports) Tools > Administration > Proxy Maintenance Tools > Administration > Labels Tools > Administration > Upgrade Legacy Labels If this command is enabled, users can set a file s workflow state to any available state. The available states are not restricted by the workflow. If this command is enabled, users can create filters that are shared with all other users and modify other public filters. If this command is enabled, users can create reports that are shared with all other users and modify other public reports. 435

452 Users security commands Command Provides access to: More information Delete Labels Delete button on the Labels dialog box (Tools > Labels) Edit Other Users' Comments Edit Other Users' Shelves Edit Other Authors' Code Reviews Delete Code Reviews Export Repository to Mainline Show Licenses In Use Delete button on the Legacy Labels dialog box (Tools > Upgrade Legacy Labels) Edit Comments button in the file and repository History Details dialog boxes Edit Shelf and Delete Shelf buttons on Shelves window for shelves owned by other users (View > Shelves) Open Review and Start Code Review buttons on Code Reviews window for code reviews users are not the author of (View > Code Reviews) Authors and Reviewers lists on Properties tab in Code Review dialog box for open code reviews users are not the author of Code reviews users are not the author of are listed on Add to Code Review dialog box (Activities > Add to Code Review) Delete button on Code Reviews window (View > Code Reviews) Tools > Administration > Export Repository to Mainline Tools > Administration > Licenses In Use If this command is enabled, users can edit comments entered by other users. If this command is enabled, users can rename, change ownership and sharing options, and delete shelves owned by other users. If this command is enabled, users can create, edit, add file versions to, and start code reviews they are not the author of. If this command is enabled, users can delete any existing code reviews. Users security commands If all commands in the Users category are disabled, users cannot access the Users window. View > Users is disabled. 436

453 Security Groups security commands Command Provides access to: More information Retrieve User View User Edit User Delete User Edit Own Integration Settings Retrieve Global Users button on the Users window (View > Users) View button on the Users window (View > Users) Edit button on the Users window (View > Users) Delete button on the Users window (View > Users) Tools > TestTrack Integration > User Settings Tools > Issue Tracking Integration > User Settings Enables users to retrieve users from the Seapine License Server and add them to Surround SCM. Enables users to specify their TestTrack or other issue tracking tool username and password. Security Groups security commands If all commands in the Security Groups category are disabled, users cannot access the Security Groups window. View > Security Groups is disabled. Command Add Security Group View Security Group Provides access to: Add button on the Security Groups window (View > Security Groups) View button on the Security Groups window (View > Security Groups) Security Group report on the Select Report Type dialog box Edit Security Group Delete Security Group Edit button on the Security Groups window (View > Security Groups) Delete button on the Security Groups window (View > Security Groups) Files security commands The Files category contains commands that are also available at the repository or branch level. See Controlling Security and User Access, page 277. Command Provides access to: More information View Repository List View the list of all repositories on the Surround SCM Server If this command is enabled on the Server Security tab, users cannot view any repositories or branches. 437

454 Files security commands Command Provides access to: More information Add File Remove File Destroy File Get File Check In/Out File Activities > Add Files Repository > Create Repository Include/Exclude button on the Template tab in the Properties dialog box for baseline branches (Branch > Branch Properties) Activities > Remove File Repository > Remove Repository Remove button on the Template tab in the Properties dialog box for baseline branches (Branch > Branch Properties) Activities > Destroy File Destroy button on the Removed Items tab in the Properties dialog box (Activities > Properties) Permanently destroy repository check box in the Remove Repository dialog box (Activities > Destroy File) Activities > Get Activities > Annotate Unshelve Files and Differences buttons on the Shelves window (View > Shelves) Activities > Check Out Activities > Check In Command must be enabled to create shares in a destination repository. Requires the Remove File command to allow users to destroy repositories. Destroyed files and repositories cannot be restored. The Permanently destroy repository check box changes to Permanently destroy repository and contents if the Force recursive remove check box is selected. Also allows users to remove repositories from branch templates when removing and permanently destroying repositories from branches that use templates. Requires the View File History command to allow users to annotate files. Also enables users to check out and check in a repository. Users can also check out and check in shared files, even if the files are shared with a repository they do not have Check In File permissions for. 438

455 Branch security commands Command Provides access to: More information Rename File Change File Type Change File Properties View File History Activities > Rename File File type list in the Properties dialog box (Activities > Properties) Expand keywords list in the Properties dialog box (Activities > Properties) Activities > History History tab in the file details pane (View > File Details Pane) Activities > Annotate Branches in the Graphical History window (Activities > Graphical History) Changing the file type changes it in all branches. Requires the Get File command to allow users to annotate files. Share Files Activities > Share Files Requires the Add Files command. Break Shares Set Custom Field Values Activities > Break Shares Change field values on Custom Fields tab in the Properties dialog box (Activities > Properties) and Custom Fields tab in the Add Files dialog box Change State Move Activities > Advanced > Bulk Custom Field Changes Activities > Advanced > Change State State list in the Properties dialog box (Activities > Properties) State list in the Check In Files dialog box Activities > Move Files Repository > Move Repository The State list in the Check In Files dialog box is only available if the Allow workflow state changes from check in option is selected in the Server Options dialog box. Branch security commands The following commands apply to all branches on the Surround SCM Server. You can override security for individual branches. See Controlling access to specific branches, page

456 Branch security commands Command Provides access to: More information Create Baseline Branch Create Workspace Branch Create Snapshot Branch View Branch History Baseline from the Branch type list (Branch > Create Branch) Workspace from the Branch type list (Branch > Create Branch) Snapshot from the Branch type list (Branch > Create Branch) History tab in the Properties dialog box (Branch > Branch Properties) Track Changes button in the Duplicate Changes and History dialog boxes (Tools > Track Changes) Delete Branch Destroy Branch Branch > Remove Branch Destroy button on the General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Permanently destroy branch check box in the Remove Branch dialog box (Branch > Remove Branch) Destroyed branches cannot be restored. 440

457 Branch security commands Command Provides access to: More information Change Branch Attributes Ignore Security in Branch Maintenance Destroy Other Users Workspace Branches Toggle Frozen, Toggle Active, Toggle Caching, and Toggle Hidden buttons on the General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Branch > Branch Attributes > Frozen Branch > Branch Attribute > Active Branch > Branch Attributes > Cache on Demand Branch > Branch Attributes > Hidden Comments field on the General tab in the Branch Properties dialog box (Branch > Branch Properties) Ignore branch security check box on the General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Destroy button on the General tab in the Branch Maintenance dialog box when another user s workspace branch is selected (Tools > Administration > Branch Maintenance) Show all private branches check box on the General tab in the Branch Maintenance dialog box Users can also freeze and unfreeze branches if the Freeze/Unfreeze Branch command is enabled. Allows users to override the security set for the selected branch and apply the available options in the Branch Maintenance dialog box. 441

458 Branch security commands Command Provides access to: More information Change Branch Type Promote Branch Rebase Branch Duplicate Changes Rollback Promote/Rebase Rename Branch Freeze/Unfreeze Branch Change Type button on the General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Branch > Promote Branch Branch > Promote File Branch > Rebase Branch Branch > Rebase Files Branch > Duplicate Changes Duplicate Changes button in the Manage Changelists dialog box (Tools > Changelists) Branch > Rollback Promote Branch > Rollback Rebase Branch > Rename Branch Toggle Freeze button on the General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Branch > Branch Attributes > Freeze Users must also have some file permissions for the repository being promoted to. The following commands must also be enabled to promote to a branch: Add File to promote an add, Check In File to promote a change, Remove File to promote a remove. Users must also have some file permissions for the repository being rebased from. The following commands must also be enabled to rebase from a branch: Add File to rebase an add, Check in File to rebase a change (also requires Get File in the parent branch), Remove File to rebase a remove. Enable this command to allow users to freeze and unfreeze branches if the Change Branch Attributes command is not enabled. 442

459 Branch security commands Command Provides access to: More information Manage Branch Indexes Toggle Indexing button on the Indexing tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance) Branch > Branch Indexing > On/Off Indexing on check box on the Index tab in the Branch Properties dialog box (Branch > Branch Properties) 443

460

461 Appendix B: Environment Variables Environment variables give scripts access to most file, repository, and code review event information. Any variable that does not apply to the event that fired the trigger is empty. Environment variables can also be used as field codes in templates. Add percent symbols (%) before and after the variable (for example, %SSCM_FILELIST%). See Editing templates, page 330. Variables marked with an asterisk (*) can only be used in scripts and on the File List or Code Review File List tab in the Edit Template dialog box. File and repository event variables Variable CF_<field code> * SSCM_BEFOREAFTER SSCM_BRANCH SSCM_BRANCHTYPE SSCM_CHANGELISTID SSCM_CHANGELISTNAME SSCM_CLIENTIP SSCM_CLIENTMACHINE SSCM_COMMENT * SSCM_DATE SSCM_ISSUENUMBER * SSCM_DESTINATIONREPOSITORY SSCM_EVENT SSCM_ EXTERNALATTACHMENTCONNECTION SSCM_EXTERNALATTACHMENTID SSCM_ EXTERNALATTACHMENTPROVIDER SSCM_FILE * SSCM_FILELINK * Definition Custom field code Indicates if trigger fired before or after the event Branch the specified file is in Type of branch the specified file is in Changelist ID number Changelist name User s IP address User s computer name File event comments Date the trigger fired TestTrack issue number the file is attached to Repository the file was moved or shared to Event that caused the trigger to fire Issue tracking tool connection name Issue ID the file is attached to Issue tracking tool name Filename File hyperlink in sscm:// format 445

462 Appendix B: Environment Variables Variable SSCM_FILELIST SSCM_FILEVERSION * SSCM_LABEL * SSCM_LOCALFILE * SSCM_MAINLINE SSCM_NUMFILES SSCM_OLDFILENAME * SSCM_PERMREMOVE * SSCM_REPOSITORY * SSCM_REQUIREMENTNUMBER * SSCM_SHAREREPOSITORY SSCM_SOURCEBRANCH SSCM_SOURCEREPOSITORY SSCM_TESTCASENUMBER * SSCM_TIME SSCM_TRIGGERDESC SSCM_USER Definition List of files for the event Post-event file version File label Full path of the local file (used with check in or add events only) Mainline branch the file is in Number of affected files Original filename; used with rename event File was permanently removed (yes/no) Full repository path for the file TestTrack requirement number the file is attached to Source repository the share was created from Source branch used for add, promote, rebase, and duplicate events Repository the file was moved from TestTrack test case number the file is attached to Time the trigger fired Trigger description User that caused the event to occur Code review event variables Variable CF_<field code> * SSCM_AUTHORLIST SSCM_AWAITINGREVIEWBY * SSCM_BEFOREAFTER SSCM_BRANCH * Definition Custom field code Code review author Reviewers who still need to review the code review file Indicates if trigger fired before or after the event Branch the specified file is in 446

463 Appendix B: Environment Variables Variable SSCM_CLIENTIP SSCM_CLIENTMACHINE SSCM_DATE SSCM_DUEDATE SSCM_EVENT SSCM_FILE * SSCM_FILELINK * SSCM_FILELIST SSCM_MAINLINE SSCM_NOTES SSCM_REPOSITORY * SSCM_REVIEWERLIST SSCM_REVIEWFILESTATUS * SSCM_REVIEWNAME SSCM_REVIEWSTATUS SSCM_TIME SSCM_TRIGGERDESC SSCM_USER SSCM_VERSIONS * Definition User s IP address User s computer name Date the trigger fired Due date for the code review Event that caused the trigger to fire Filename File hyperlink in sscm:// format List of files for the event Mainline branch the file is in Code review notes Full repository path for the file Code review reviewers Code review file status Code review name Code review status Time the trigger fired Trigger description User that caused the event to occur File versions under code review 447

464

465 Appendix C: Accessing WebDAV Directories Web-based Distributed Authoring and Versioning (WebDAV) is an extension to the HTTP protocol that supports creating and editing files in a distributed network environment. Multiple users can work with files locally or remotely using WebDAV-enabled applications and then save the files directly on a web server. WebDAV supports some of the common actions available in Surround SCM including getting files, checking files in and out, adding files, deleting files, renaming files, and creating repositories. Keep in mind that WebDAV is an open standard and the available functionality depends on the web server configuration, the client application used to access files, and how the client application works with the web server. For example, if you are using a web browser, you can get files but you cannot modify them. You can access a WebDAV directory using a web browser, Windows Explorer, Mac OS X Finder, Linux filesystem, WebDAV-specific applications, and any applications that support WebDAV, such as a Microsoft Office application, Adobe Dreamweaver, or Adobe Photoshop. Keep the following in mind: Your Surround SCM administrator must install the WebDAV CGI and configure WebDAV for use. The Seapine License Server, Surround SCM Server, and web server must all be running to access WebDAV directories. Web browser You can access a WebDAV directory the same way you access any web site. Note: Branches with a slash (/) character are not browseable through WebDAV because Surround SCM cannot tell the difference between an embedded slash and a separation character in a URL. For example, enter on an Apache web server or on a Microsoft IIS server. A page opens that displays the available alias directories that contain Surround SCM repositories and files. 1. Click an alias directory name. 2. If prompted, enter your Surround SCM username and password then click OK. A page opens that displays the available Surround SCM branches, repositories, or files. 449

466 Windows network place 3. Click the branch or repository that contains the file you want to view. 4. Click the file you want to view. The file opens. Tip: You can save a copy of the file from the web browser to a local directory, but you cannot check in any changes. Windows network place Add a network place to access a WebDAV directory in Windows. You can work with Surround SCM repositories and files the same way you work with folders and files in Windows. For example, you can add files, delete files, create folders to add new repositories. Keep in mind that these changes are made on the Surround SCM Server. Note: You can only add a Windows network place to access a WebDAV directory if the WebDAV CGI is hosted on an Apache web server. 1. Open My Network Places. 450

467 Windows network place 2. Double-click Add Network Place. The Add Network Place Wizard starts. 3. Click Next. 4. Click Choose Another Network Location. 5. Click Next. 6. Enter the WebDAV directory address. For example, enter 7. Click Next. The connection to the WebDAV directory is tested. 8. Enter a name for the new network place or use the default name. 9. Click Next. The new network place is created. 10. Click Finish. The new network place is added. 11. Open the new folder in My Network Places to access Surround SCM branches, repositories, and files. 451

468 Mac OS X Finder Tip: You can also add a network place using Internet Explorer. Select File > Open. Enter the WebDAV directory address and select Open as Web Folder. Mac OS X Finder You can connect to a WebDAV directory on Mac OS X, which allows you to work with repositories and files the same way you work with folders and files on Mac OS X. For example, you can add files, delete files, and create folders to add new repositories. Keep in mind that these changes are made on the Surround SCM Server. 1. Choose Go > Connect To Server. The Connect To Server dialog box opens. 2. Enter the WebDAV directory address. For example, enter on an Apache web server or on a Microsoft IIS server. 3. Click Connect. The WebDAV directory opens. The alias directories are displayed. 452