Surround SCM User Guide Version 2014.1 Copyrights © 2014 Seapine Software, Inc. All rights reserved. Defect Scribe, QA Wizard Pro, Resource Thief, Seapine CM, SoloBug, SoloSubmit, Surround SCM, and TestTrackare trademarksor registered trademarksof Seapine Software, Inc. in the United Statesand other countries. Borland and StarTeam are trademarksor registered trademarksof Borland, Inc. in the United Statesand other countries. Delphiand JBuilder are trademarksor registered trademarksof Embarcadero Technologies, Inc. in the United Statesand other countries. Acrobat Reader isa registered trademarkof Adobe, Inc. in the United Statesand other countries. Sun, JVM, Java, JavaScript, and allJava-based marksare trademarksor registered trademarksof Sun Microsystems, Inc. in the United Statesand other countries. UNIX isa registered trademarkin the United Statesand other countries, licensed exclusivelythrough X/Open CompanyLimited. Apple, Mac, MacOS, Macintosh, Objective-C, and Safariare registered trademarksof Apple Computer, Inc. Microsoft, Windows, WindowsNT, WindowsServer, WindowsVista, MS Windows, Active Directory, Internet Explorer, Outlook, SQL Server, VisualSourceSafe, and VisualStudio are either registered trademarksor trademarksof Microsoft Corporation in the United Statesand/or other countries. Linuxisa trademarkof LinusTorvalds. Red Hat, Red Hat Enterprise Linux, and Fedora are registered trademarksof Red Hat, Inc. in the United Statesand other countries. SUSE isa registered trademarkof NovellInc. in the United Statesand other countries. Debian isa registered trademarkof Software in the PublicInterest, Inc. Ubuntu isa registered trademarkof CanonicalLtd. IBM, ClearCase, and allother IBM brand and product namesare service marks, trademarksor registered trademarksof IBM Corporation or itssubsidiariesin the United Statesand other countries. Oracle isa registered trademarkof Oracle Corporation and/or itsaffiliates. PVCS, Serena PVCS ProfessionalSuite, and Serena PVCS Version Manager are registered trademarksof Serena Software, Inc. Allother product namesmentioned herein are the trademarksof their respective owners. Allother trademarksare the propertyof their respective owners. No part of thispublication maybe reproduced, transmitted, transcribed, stored in a retrievalsystem, or translated into anylanguage in anyform byanymeanswithout the written permission of Seapine Software, Inc. Your license agreement with Seapine Software, Inc., which isincluded with the product, specifiesthe permitted and prohibited usesof the product. Anyunauthorized duplication or use of thissoftware, in whole or in part, in print, or in anyother storage and retrievalsystem is forbidden. Information in thisdocument issubject to change without notice and doesnot represent a commitment on the part of Seapine Software, Inc. Unlessotherwise noted, allcompanies, products, street addresses, and personscontained herein are purelyfictitious. Mention of third-partycompaniesand productsisfor informationalpurposesonlyand doesnot constitute an endorsement. Seapine Software, Inc. 6960 Cintas Boulevard Mason, OH 45040 (513) 754-1655 [email protected] Contents
What's New 1 Getting Started 3 Starting Surround SCM 4 Managing server connections 4 Adding server connections 5 Editing server connections 6 Deleting server connections 6 Surround SCM interface 7 Branch menu 8 Branches tree 8 Repositories tree 8 Source file list 8 File details pane 8 Activity log 8 Pending changelists 8 Setting general user options 9 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
i 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 Setting custom fields 32 Changing multiple custom fields 33 Changing workflow states 34 Moving files 35 Renaming files 36 Removing files 36 Restoring removed files 37 Deleting files permanently 38 Comparing and Merging Files 41 Viewing file differences 41 Merging files 43 Merging unrelated files 44 Generating file differences reports 46 Viewing image file differences 47 Setting diff/merge options 49 Configuring diff application options 49 Configuring merge application options 50 Editing diff/merge application options 51 Deleting diff/merge application options 52 Configuring diff/merge application settings 52 Performing Code Reviews 55 About the code review process 55 Understanding code review status 56 Managing code reviews 57 Creating code reviews 58 Adding files to code reviews 59 Selecting code reviews 63
ii Removing files from code reviews 63 Starting code reviews 63 Opening code reviews 64 Editing code reviews 65 Reviewing files in code reviews 65 Reviewing changes between file versions 66 Reviewing files 68 Adding review comments to files 69 Editing and deleting review comments 70 Addressing code review comments 70 Viewing unaddressed review comments 71 Searching for code reviews 71 Viewing code reviews files are included in 72 Deleting code reviews 72 Viewing File Information 75 Using the file details pane 75 Viewing line-by-line file changes 76 Working with annotate results 77 Viewing file history 78 Viewing file history details 80 Viewing graphical file history 81 Viewing general file information 82 Viewing check out file information 82 Viewing shared file information 83 Viewing file custom field information 83 Setting Up Email Notifications 85 Adding email notifications 85 Editing email notifications 88 Duplicating email notifications 88 Disabling and enabling email notifications 88 Deleting email notifications 88 Customizing Surround SCM 91 Customizing the Source Tree window 91 Setting Source Tree options 92 Setting file information display options 93
iii Customizing shortcut menus 94 Customizing toolbars 95 Changing the user interface mode 96 Changing defaults for Surround SCM dialogs 97 Setting Get Files dialog defaults 97 Setting Check In Files dialog defaults 98 Setting Check Out Files dialog defaults 99 Setting Undo Check Out Files dialog defaults 100 Setting Add Files dialog defaults 100 Grouping file extensions 101 Adding file extension groups 102 Setting Shelve Files dialog defaults 103 Managing Repositories 105 Creating repositories 105 Viewing differences between repositories and working directories 106 Resolving missing moved and renamed items 109 Pushing changes to repositories 109 Renaming repositories 111 Moving repositories 112 Cloaking and uncloaking repositories 112 Viewing cloaked repositories 113 Removing repositories 114 Restoring repositories 115 Deleting repositories permanently 115 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
iv 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 Committing pending changelists 130 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 Generating 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
v 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 Branching example 163 Creating branches 165 Using branch templates 167 Including and excluding repositories for new branches 168 Selecting branch templates 169 Merging Files Between Branches 171 Deciding between promoting, rebasing, and duplicating 171 Viewing branch differences 171 Copying files across branches during check in 174 Generating branch differences reports 175 Promoting branches 178 Promote preview 180 Promote actions 182 Promoting files 183 Rolling back promoted files 186 Rebasing branches 187 Rebase preview 190 Rebase actions 191 Rebasing files 192 Rolling back rebased files 195 Duplicating selected changes across branches 196 Duplicate changes preview 198 Duplicate changes actions 199 Tracking duplicated changes 199 Viewing Branch Information 201 Viewing branch history 201 Viewing branch history details 201 Viewing general branch information 202
vi Viewing the graphical branch tree 203 Finding Files 205 Searching for files 205 Adding restrictions 207 Adding text restrictions 208 Using regular expressions 208 Adding number restrictions 210 Adding date restrictions 210 Adding multiple list selection restrictions 211 Adding condition restrictions 212 Adding event restrictions 213 Adding label restrictions 214 Adding TestTrack item number restrictions 214 Adding security group restrictions 215 Adding branch and repository restrictions 215 Adding action restrictions based on user and date 216 Searching for text in files 218 Text search examples 220 Configuring filters 222 Adding filters 222 Applying filters to the source file list 224 Editing filters 224 Duplicating filters 224 Deleting filters 225 Browsing to files and repositories 225 Bookmarking files, repositories, and branches 226 Managing bookmarks 226 Generating Reports 229 About reports 229 Configuring reports 229 Adding reports 230 Adding history reports 231 Adding list reports 234 Adding security group reports 237 Adding trend reports 239
vii Adding workflow progress reports 241 Charting report data 243 Adding external reports to Surround SCM 243 Editing reports 244 Duplicating reports 244 Deleting reports 244 Running reports 244 Running quick reports 245 Saving the source file list 245 Printing the source file list 246 Integrating with TestTrack 247 Configuring TestTrack connections 247 Adding TestTrack connections 247 Editing TestTrack connections 248 Deleting TestTrack connections 248 Entering TestTrack login information 249 Attaching source files to TestTrack items 249 Viewing TestTrack items 251 Adding TestTrack issues 252 Editing TestTrack issues 253 Fixing TestTrack issues 253 Finding files attached to TestTrack items 254 Analyzing issue risk in files 255 Selecting TestTrack items 257 Integrating with Third-Party Applications 259 Setting integration options 259 Setting Xcode integration options 260 Setting plug-in directories 261 Integrating with IDEs and applications that support SCCI 262 Integrating with issue tracking tools 262 Entering issue tracking login information 262 Attaching source files to external issues 263 Viewing external issues 264 Fixing external issues 264 Using the Windows Explorer and Mac Finder integrations 265
viii Using the Windows Explorer plug-in 265 Using the Mac Finder plug-in 266 Integrating with CMIS 267 Setting Up Surround SCM 269 Starting the Seapine License Server 269 Starting the Surround SCM Server 270 Controlling Security and User Access 271 Security levels 271 Security examples 272 Controlling access with security groups 273 Adding security groups 274 Viewing security groups 276 Editing security groups 276 Duplicating security groups 277 Deleting security groups 277 Controlling access to specific repositories 277 Controlling access to specific branches 279 Setting branch security commands 280 Managing users 280 Adding users 281 Retrieving global users 283 Viewing users 283 Editing users 284 Deleting users 284 Viewing licenses in use 284 Voiding check out 285 Configuring the Surround SCM Server 287 Setting general global server options 288 Securing communication between clients and the Surround SCM Server 290 Configuring RSA key exchange 293 Setting server merge options 294 Activating third-party issue tracking plug-ins 295 Setting logging options 296 Setting email server options 297 Setting email notification options 297
ix Setting Seapine License Server options 298 Setting automatic software update check options 299 Checking for new Surround SCM versions 301 Scheduling data purges 301 Setting general mainline options 302 Supported keywords 304 Setting changelist server options 305 Setting auto-detect and ignore file options 306 Configuring default user options 308 Configuring Custom Fields 311 Adding custom fields 312 Editing custom fields 313 Deleting custom fields 313 Restoring deleted custom fields 313 Automating Actions with Triggers 315 Trigger examples 316 Configuring triggers 316 Adding triggers 317 Adding triggers to run executables 320 Adding triggers to prevent events 321 Adding triggers to append comments to events 322 Adding triggers to email users 322 Editing email templates 323 Adding triggers to set workflow states 325 Adding triggers to set custom field values 326 Editing triggers 326 Adding trigger actions 327 Editing trigger actions 327 Deleting trigger actions 327 Duplicating triggers 328 Disabling and enabling triggers 328 Deleting triggers 328 Configuring Workflows 329 About workflows 329 Workflow example 329
x About the default workflow template 331 Customizing workflows 332 Planning your workflow 333 Automating workflows 333 Configuring workflow states 333 Adding workflow states 334 Editing workflow states 335 Deleting workflow states 335 Restoring deleted workflow states 335 Configuring workflow templates 336 Adding workflow templates 336 Adding states to workflow templates 338 Removing states from workflow templates 338 Editing workflow transitions 339 Editing workflow templates 339 Duplicating workflow templates 340 Deleting workflow templates 340 Diagramming workflows 340 Setting the default workflow 341 Setting workflows for specific repositories 342 Configuring Code Review Settings 343 Configuring Shadow Folders 345 Adding shadow folders 345 Editing shadow folders 347 Refreshing shadow folder contents 347 Deleting shadow folders 347 Maintaining Branches 349 Managing branch attributes 349 Indexing branches for optimized searches 352 Managing the indexing server 352 Turning branch indexing on or off 353 Viewing branch index details 354 Viewing the indexing server log 355 Modifying indexing server startup options 356 Renaming branches 357
xi Hiding and unhiding branches 358 Freezing and unfreezing branches 358 Inactivating and activating branches 359 Modifying templates for existing branches 359 Changing branch type 361 Changing branch caching 361 Setting branch caching server options 362 Breaking shares across branches 363 Removing branches 364 Restoring removed branches 365 Deleting branches permanently 365 Managing Mainline Branches 367 Creating mainline branches 367 Renaming mainline branches 368 Overriding server options for specific mainline branches 368 Moving repositories to different mainline branches 370 Moving mainline branches to different databases or servers 372 Copying mainline branches to different databases 373 Removing mainline branches 374 Restoring removed mainline branches 374 Restoring RDBMS mainline branches 375 Restoring non-RDBMS mainline branches 376 Deleting mainline branches permanently 377 Maintaining Surround SCM Databases 379 Creating Surround SCM tables 379 Setting the default server database location 380 Converting the server database to a different type 380 Changing the server database location 382 Adding RDBMS connections 383 Editing RDBMS connections 385 Deleting RDBMS connections 386 Backing up Surround SCM databases 386 Locking databases for backups 386 Resolving database issues 387 Setting database analyze and repair options 387
xii Analyzing and repairing databases 389 Repairs for common database issues 391 Working with the Surround SCM Server Log 393 Server log levels 394 Managing Mail 395 Resending mail 395 Deleting mail 395 Configuring TestTrack Integration 397 Enabling TestTrack integration 397 Syncing field labels with TestTrack 397 Setting TestTrack integration options for repositories 398 Upgrading Surround SCM 401 Upgrading mainline branches 401 Upgrading old mainline branches 401 Upgrading non-RDBMS mainline branches 402 Resolving custom field and workflow issues 404 Upgrading RDBMS connections 405 Upgrading legacy labels 406 Deleting legacy labels 407 Using Proxy Servers 409 About proxy servers 409 Configuring proxy servers 410 Adding proxy servers 411 Editing proxy server settings 414 Deleting proxy servers 414 Setting proxy server options 414 Modifying proxy server startup options 415 Modifying Surround SCM Server Registry Settings 419 Starting the Surround SCM Registry Utility 419 Modifying Surround SCM Server startup options 419 Managing the Surround SCM Web Server 423 Starting the Surround SCM Web Server 423 Modifying web server startup options 423
xiii Managing the Surround SCM CMIS Server 427 Starting the Surround SCM CMIS Server 427 Starting the Surround SCM CMIS Admin Utility 427 Configuring CMIS Server options 427 Adding CMIS repositories 428 Editing CMIS repositories 429 Deleting CMIS repositories 430 Troubleshooting Surround SCM CMIS Server issues 430 Using the Surround SCM API 431 Avoiding conflicts with the Surround SCM Client and CLI 431 UsingtheC API 431 Using the Java API 432 Using the .NET API 433 Appendix A: Security Commands 435 General security commands 435 Admin security commands 437 Users security commands 440 Security Groups security commands 440 Files security commands 441 Branch security commands 443 Appendix B: Environment Variables 447 Appendix C: Accessing WebDAV Directories 451 Web browser 451 Windows network place 452 Mac OS X Finder 454 Linux filesystem path 455 Glossary 457 Index 461
xiv What's New
Surround SCM 2014.1 includes the following key features. For a complete list of features, enhancements, and bug fixes, check out the release notes (www.seapine.com/scmreleasenotes.html). New Surround SCM Web application Use the new Surround SCM Web application to access source files, repositories, and branches from a web browser. You can view file contents and historical information, download files to save local copies, and use bookmarks to quickly access items. See the Surround SCM Web help for information.
Note: The Surround SCM administrator must install and configure the Surround SCM Web Server. See the Surround SCM installation help.
Security enhancements Surround SCM now uses stronger encryption to ensure safe communication between the Surround SCM Server and clients. Surround SCM administrators can enable RSA key exchange for even stronger security between the server and clients. See Securing communication between clients and the Surround SCM Server, page 290. 64-bit Surround SCM Client Use 64-bit versions of the Surround SCM Client, CLI, and API libraries. This helps you integrate 64-bit applications with the Surround SCM API and makes it easier to work with Surround SCM on 64-bit Linux distributions without installing additional 32-bit libraries. See the Surround SCM installation help for information. Bookmarking enhancements Bookmarks are now saved on the Surround SCM Server so you can access them in the Surround SCM Client and Surround SCM Web. You can also add descriptions to bookmarks to help identify them in Surround SCM Web. See Bookmarking files, repositories, and branches, page 226.
1
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 269.
1. 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 4 and Managing server connections, page 4. 2. Familiarize yourself with the Surround SCM interface. See Surround SCM interface, page 7. 3. If you are working with files that are already in Surround SCM, you may perform the following tasks:
n 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 165.
n 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.
n Get files to add local copies to a working directory or another directory. See Getting files, page 15.
n Check out files so you can modify them. See Checking out files, page 21.
n 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 41. 4. 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:
n Optionally create a workspace branch to isolate your changes from other users. See Creating branches, page 165.
n 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 105.
n Add files to Surround SCM. See Adding files to Surround SCM, page 28. 5. 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 91 and Setting general user options, page 9.
3 Starting Surround SCM
Starting Surround SCM Make sure the Seapine License Server and Surround SCM Server are running before you start Surround SCM. 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 5. 3. 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 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 5. 6. Select a server and click Edit to change the information. See Editing server connections, page 6. 7. 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 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 4900. Valid values are 1-65535.
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 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 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 trees, menus, and toolbars in 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 91.
Menu bar Provides access to Surround SCM actions.
Toolbars Provides access to 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 95.
Panes Display information as you work with files. Information is organized in the following panes and tabs: Branch menu, Branches tree, Repositories tree, source file list, file details pane, activity log, and pending changelists.
7 Branch menu
Shortcut menus Open when you right-click windows and trees, providing a quick way to perform common actions. You can customize the actions available in the Branches tree, Repositories tree, and source file list shortcut menus. See Customizing shortcut menus, page 94.
Branch menu The Branch menu contains a list of all branches you can access.
Branches tree The Branches tree displays the 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.
Repositories tree The Repositories tree displays the available repositories in a branch. When you select a branch, the tree is populated with the repositories in the branch.
Source file list The source file list displays 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. See Customizing the Source Tree window, page 91.
File details pane The file details pane displays a selected file’s properties, history, check out status, sharing information, custom fields, and a preview of local image files. It provides a convenient way to work with files and access file actions. See Using the file details pane, page 75.
Activity log The Activity Log tab displays activities as you perform actions on files, such as the file check out location.
Pending changelists The Pending Changelists tab displays pending changelists and allows you to commit changes from the Source Tree window. See Working with pending changelists, page 125.
8 Setting general user options
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.
2. Select any Server Connection options. These are the same options in the Surround SCM login dialog box, except for the file compression option.
n Always login with this username automatically logs in to the current Surround SCM Server using the specified username and password.
n 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.
n Use external authentication prompts for your credentials when logging in. Ask your Surround SCM administrator for more information.
n 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.
9 Changing your password
3. Select a Text File Format option. Select Append end-of-line if necessary to ensure text files use an end-of-line character. Surround SCM adds an end-of-line character to text files without one. 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.
n By timestamp checks the timestamp to see if the file was modified after it was retrieved.
n 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. 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
Tip: You cannot change your Surround SCM 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 new password.
10 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 12.
1. 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
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 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 12. 3. Select a working directory and click Edit to change it. See Editing working directories, page 13. 4. Select a working directory and click Delete to delete it. See Deleting working directories, page 13. 5. Click Close to close the Working Directories dialog box.
Adding working directories 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 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 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 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:
n Windows—Choose Open Containing Folder.
n Mac—Choose Reveal in Finder.
n 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 94.
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 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.
n Latest version gets the latest server version.
n Timestamp gets files based on the selected date and time.
n Label gets files based on the selected label. Click Select to search for a label. See Selecting labels, page 147.
n Latest version in state gets the latest version based on the selected workflow state.
n 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 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.
n 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.
n Replace automatically overwrites the local file with the server file or deletes the local file if it was removed from the server.
n 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.
n Current sets the timestamp to the current date and time.
n Modified sets the timestamp to the date and time that the files were last modified.
n 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 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 Explanation
Current The local file is the same as the current Surround SCM Server file.
Missing The file was not found on your computer.
Modified The local file was modified and does not match the Surround SCM Server file.
Old A newer version was checked in and the local file is no longer current.
Old, A newer version was checked in after you modified the local file. This happens if you check out Modified a file, modify it locally, and another user checks in a new version.
Working Surround SCM cannot determine the working directory location. This happens if you set the directory same working directory for two or more branches or another user sets a working directory in the conflict same location you did (for example, a shared network drive).
Unknown 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 17. 1. 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 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.
n Internal viewer/editor uses the internal viewer.
n Associated application opens the application associated with the file. (Windows/Mac only)
n Selected application opens the selected application. Click Browse to select an application. 6. Click OK to save the changes.
Editing viewer/editor settings 1. Choose Tools > User Options then select the View/Edit File category.
18 Deleting viewer/editor settings
2. Select aview/edit filesettingandclick 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 aview/edit filesettingandclick 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
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 124.
21 Creating local directories
6. Optionally expand the Advanced options area to select other check out options.
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.
n 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.
n Replace automatically overwrites the local file with the server file.
n 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.
n Current sets the timestamp to the current (time of retrieval) date and time.
n Modified sets the timestamp to the date and time the files were last modified.
n Check in sets the timestamp to the date and time the files were last checked in. 10. Click OK. The files are checked out.
n 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.
n 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.
n Create directory creates the local directory.
n Create all directories creates a local directory for each repository.
n Skip repository skips the get or check out on the repository and does not create a local directory.
22 Undoing check out
n 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 112.
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 123.
1. 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.
n Get original version replaces the local file with the original server version.
n Get latest version replaces the local file with the latest server version.
n 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.
23 Editing files in Surround SCM
The file is no longer checked out.
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 17. 1. 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 tocheck inthefileafteryousave 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 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.
n Check in as part of the following changelist adds the files to a selected changelist. Select a changelist from the list or select
n 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
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.
25 Checking in updated files
Local file options Select local file options to indicate how to handle local files after the check in.
n 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 working directory.
n Keep checked out checks in changes and keeps the files checked out.
n Leave local copy as is checks in the file and leaves the working directory copy as is.
n Remove local copy checks in the file and deletes it from the working directory.
n Make files writable leaves a read-write copy of the file in the working directory.
26 Rolling back files
Advanced options Select advanced options to change workflow states, label files, skip the merge process, and update version numbers when files are checked in.
n Change state when version updated changes the workflow state to the selected state. Select the statetoset onthefiles. Youmay alsowant toselect 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.
n Label applies the selected label to the files. Select a label from the list or select
n 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.
n 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.
6. Click Differences to view differences between the file you are checking in and the working directory copy. See Viewing file differences, page 41. 7. Click Attach to attach files to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 249 or Attaching source files to external issues, page 263. 8. Click OK. Surround SCM automatically merges changes when files are checked in. If there are conflicts, the merge application opens. See Merging files, page 43.
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.
27 Adding files to Surround SCM
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.
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.
28 Adding files to Surround SCM
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 306.
3. Click to change how files are displayed.
n List displays the filename only.
n Details displays the filename, size, and last modified date.
n 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.
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 101. 5. Select the files or folders you want to add.
n 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.
n Press Ctrl+A to select all files and folders to add.
29 Adding files to Surround SCM
n Ctrl+click each item to select multiple files or folders to add
n To add files from a folder, double-click the folder to open it and then select the files.
n 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 32. 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.
n Select Add as part of the following changelist and select a changelist. See Adding file actions to changelists, page 124.
n Select View pending changelists after add to view the pending changelist.
30 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
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. n 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. n Select Make files writable to get the files in read-write mode. n Select Check out files after add to immediately check out the files. n 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.
31 Setting custom fields
Advanced options Select advanced options to set workflow states, label files, overwrite removed server files, and detect file type when adding files.
n 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 34.
n Select Label and select a label if your organization uses labels. Select
n 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.
n 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 249 or Attaching source files to external issues, page 263. 11. 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 311 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.
32 Changing multiple custom fields
n 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. n 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 83. Keep the following in mind: n 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. n 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 165. n Promoting and rebasing does not change the custom field values set on files that already exist in the destination branch. n You can only set one custom field value for shared files. n 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 75 and Customizing the Source Tree window, page 91. 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.
33 Changing workflow states
2. Make any changes. The available options depend on the custom field type.
n To set the field to a new value, select Set to value and enter a value.
n To set the field to the default value, select Set to default value.
n To add text to the beginning of a text field value, select Append and enter the text.
n To add text to the end of a text field value, select Prepend and enter the text.
n 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.
n To keep the current field value, select
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: n Properties dialog box—See Viewing general file information, page 82. n Add Files dialog box—See Adding files to Surround SCM, page 28. n Check In Files dialog box—See Checking in updated files, page 24. n History dialog box—See Viewing file history, page 78.
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 78.
1. 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.
34 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: n You cannot move files to a repository that includes a file with the same name. n You cannot move files that are checked out or in a changelist. n Moving a shared file adds the move action to the history of the base file and all shared links without breaking the share. n 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.
35 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 124. 5. 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 124. 4. 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.
36 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 124. 5. 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.
37 Deleting files permanently
3. Select afileandclick 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 afileandclick 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.
38 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.
39
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 43. 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 76.
1. Select the file and choose Activities > Differences. The Differences dialog box opens. Read-only information is displayed in the File to Compare area.
41 Viewing file differences
2. Select a Version.
n 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.
n 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.
n Copy in working directory compares the server file with the working directory file.
n 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:
n Branched file compares the selected file to a branched version.
n Historic version compares the current version to the selected historic version.
n 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 44.
42 Merging files
5. Click Differences. The differences application opens.
Note: You can change the application Surround SCM uses to diff files. See Configuring diff application options, page 49.
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.
Note: You can specify the application Surround SCM uses to merge files. See Configuring merge application options, page 50.
1. Select the file and choose Activities > Merge. The Merge dialog box opens.
43 Merging unrelated files
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:
n Branched file merges changes with the selected branched file version.
n Historic version merges the current version with the selected historic file version.
n Unrelated files merges the current version with another file on the Surround SCM Server. See Merging unrelated files, page 44.
4. 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. 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.
44 Merging unrelated files
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. The Merge Check In dialog box opens if you checked out the file when starting the merge.
n Click Yes, check in file to check in the file.
n Click No, keep file checked out if you do not want to check in the file.
45 Generating file differences reports
Generating file differences reports File differences reports include the differences between two or more versions of a text file. 1. Select a file and choose Activities > History. The History dialog box opens.
Tip: You can also view file differences in a History report. See Adding reports, page 230.
2. Select the files to include in the report. 3. Click Differences Report. The Generate File Differences Report dialog box opens.
4. Select a Version to Include option.
n 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.
n 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.
46 Viewing image file differences
n 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 5. 5. Select any additional report Options.
n Ignore case differences in file contents excludes differences in character case.
n Ignore whitespace excludes any whitespace differences (spaces and tabs).
n Ignore changes in the amount of whitespace excludes additions or deletions to existing whitespace (spaces and tabs).
n Ignore blank lines excludes inserted or deleted blank lines.
n Include report header information includes a header with the report date, branch, repository, and file. 6. Select an Output Format option. When you view file 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.
n Enter the number of Output lines of context to display before and after each change. The default is 3 lines.
n Select Unified format to display the differences with limited context lines. This format omits redundant context lines.
n 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 is generated. 8. Click Print to print the report or click Save As to save it. 9. Click OK to close the report.
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.
47 Viewing image file 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.
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.
48 Setting diff/merge options
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.
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.
n Binary comparison uses the internal binary file comparison utility to perform a byte-to-byte comparison between two binary files.
49 Configuring merge application options
n Integrated Guiffy uses Guiffy to compare two text files. See the Guiffy help (www.guiffy.com/hthelpx.html) for more information.
n Integrated image compare uses the internal utility to compare image files.
n Microsoft Word uses Word’s compare/merge utility. (Windows only)
n 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.
50 Editing diff/merge application options
3. Select Merge from the Diff/Merge list. 4. Enter the File extensions to associate with the merge application. Separate extensions with a semicolon. 5. Select a Two-way merge with option.
n Integrated Guiffy uses Guiffy. See the Guiffy help (www.guiffy.com/hthelpx.html) for more information.
n Microsoft Word uses Word’s compare/merge utility. (Windows only)
n 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 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.
51 Deleting diff/merge application options
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.
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.
n Enter the Java runtime path or click Browse to select a directory.
n Enter the Guiffy path or click Browse to select a directory.
n Enter the amount of memory you want Guiffy to use. The default is 64 MB.
n Select the Guiffy language to use.
n Select Use Seapine default Guiffy toolbars to display only the Guiffy toolbars used in Surround SCM. 3. Select a Microsoft Office Configuration option.
52 Configuring diff/merge application settings
n Compare and Merge displays differences as tracked changes.
n Side by Side compares documents side-by-side. 4. Click OK to save the changes.
53
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 55.
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 56. The following flowchart illustrates the built-in code review workflow, which uses triggers to automatically email 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 315.
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
55 Understanding code review status
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 58. 2. 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 59.
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 255.
3. 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 email the reviewers. See Starting code reviews, page 63. 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 65. 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 68 and Reviewing changes between file versions, page 66.
5. 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 70. 6. 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.
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.
56 Managing code reviews
Status Explanation
Work Authors are adding files to a review. in Progress
Awaiting The code review is started and contains files that need review. An email about the review is Review automatically sent to reviewers.
Needs The review is complete and contains files with unaddressed comments. An email about the Attention resulting review status is automatically sent to authors.
Approved All files in the review have been reviewed and approved. An email about the resulting review status is automatically sent to authors.
Following are the statuses for files in code reviews.
Status Explanation
Awaiting The selected reviewers need to review the file. Files remain in this status until all the reviewers Review review them. The status changes when the last reviewer marks the file as completed.
Needs The file contains unaddressed comments. Attention
Approved 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, 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 343.
1. Choose View > Code Reviews. The Code Reviews window opens.
2. Select the Mainline branch that contains the reviews you want to work with. 3. Select a Filter to limit the reviews displayed.
57 Creating code reviews
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
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 59.
6. Select a review and click Open Code Review to open it. See Opening code reviews, page 64. 7. Select a review and click Start Code Review to notify reviewers that files are ready for review. See Starting code reviews, page 63. 8. Select afileorreview andclick Delete to remove the file from the review or delete the review. See Removing files from code reviews, page 63 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.
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 email if the review needs attention. 5. Select the Reviewers.
58 Adding files to code reviews
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 email 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 59.
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.
n Adding files to Surround SCM n Viewing file history
n Checking in updated files n Analyzing issue risk
n Working with changelists n Selecting related files to add to reviews
n Promoting or rebasing changes
Keep the following in mind: n 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. n 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 65. 1. 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. The Add to Code Review dialog box opens.
59 Adding files to code reviews
2. Select the Code review to add the files to.
n To create a new review, select
n 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 63. 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 63.
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 28. 1. 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.
n To add the file to a new review, select
n 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 63. 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,
60 Adding files to code reviews the differences between file versions are displayed. See Checking in updated files, page 24. 1. 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.
n To add the file to a new review, select
n 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 63. 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 124. 1. Select a changelist or file in a committed changelist in the Changelists dialog box. 2. Click Add to Code Review.
n 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 63.
n If you selected a committed changelist or file, the Add to Code Review dialog box opens. To create a new review, select
n To create a new review, select
n 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 63. 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 78. 1. 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.
n 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 63 and Creating code reviews, page 58.
61 Adding files to code reviews
n 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 69. Youcanaddthefile version to an existing review or create a new review. See Selecting code reviews, page 63 and Creating code reviews, page 58. 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 255. 1. Select afileintheAnalyzeRisk dialogbox. 2. Click abuttontoaddthefiletoareview orreview thefile.
n 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 63 and Creating code reviews, page 58.
n 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 69. You can add the file to an existing review or create a new review. See Selecting code reviews, page 63 and Creating code reviews, page 58.
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. 1. Choose View > Code Reviews. 2. Select the review to add files to and click Add Files. The Add Files to Code Review dialog box opens.
3. Select a source type in Select files and versions by list and then select a source to display files from.
n 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.
62 Selecting code reviews
n 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.
n 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 257. 4. 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 58. 3. 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. 2. Expand the review that contains the file you want to remove. 3. Select thefiletoremoveandclick Delete. You are prompted to confirm the deletion. 4. Click Yes. The file is removed from the review.
Starting code reviews After all files that need review are added to a code review, start it to notify the reviewers. An email is automatically sent to reviewers to explain that the review is ready and includes the review name, authors, notes, and due date.
63 Opening code reviews
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.
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.
n To edit the review information, open it, make any changes on the Properties tab, and click Apply. See Editing code reviews, page 65.
n 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 email 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. 2. Select a code review and click Open Code Review. The Code Review window opens.
64 Editing code reviews
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 65. 6. 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 63 and Creating code reviews, page 58.
1. 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 email is automatically sent to the added reviewers when the changes are saved.
Reviewing files in code reviews You can review the changes made between file versions or review entire files in code reviews.
65 Reviewing changes between file versions
n 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 66. n 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 68.
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 68.
1. 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.
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.
66 Reviewing changes between file versions
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 47. 6. Tofindtext inthefile, enterthetext inthesearchfieldandclick Find. 7. Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page 69. 8. 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 70. 10. 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.
n 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.
n 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 56.
67 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 59.
1. 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. Tofindtext inthefile, enterthetext inthesearchfieldandclick 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 47.
68 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 66. 6. Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page 69. 7. 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 70. 9. 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.
n 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.
n 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 56.
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.
69 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 70.
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.
n To edit a comment, choose Edit. Make any changes and click OK.
n To delete a comment, choose Delete. You are prompted to confirm the deletion.
n 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 64. 2. 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 59. 6. Repeat steps 1 and 2. 7. Select the comment you addressed and click Mark Addressed or click Address All to address all comments.
70 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.
71 Viewing code reviews files are included in
2. Select
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.
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 78 and Analyzing issue risk in files, page 255. 1. Select thefileorversionandclick . 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 64. 3. Click Close when you finish viewing 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. 2. Select a code review and click Delete.
72 Deleting code reviews
You are prompted to confirm the deletion. 3. Click Yes. The code review is deleted.
73
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 78. You can also annotate files to view line-by-line changes to files between versions. See Viewing line-by-line file changes, page 76.
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. Selectafile. 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 78. 5. 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.
75 Viewing line-by-line file changes
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. 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 41.
1. Selectafile.
Note: The only Unicode files you can annotate are UTF-8 and UTF-16.
2. Choose Activities > Annotate. The Annotate dialog box opens.
3. Select a Version to annotate.
n Latest version uses the latest server version.
n Historic version uses the selected server version.
n Timestamp uses the current server version based on the selected date and time.
n Label uses the version with the selected label. Click Select to search for a label.
n 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.
n Historic version uses the selected server version. You can also enter a version. Select All to display changes for all files, including version 1.
76 Working with annotate results
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.
n Timestamp uses the current server version based on the selected date and time.
n 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.
n 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 77.
Working with annotate results Information about annotated files is displayed in the following columns in the Annotate window.
Column Description
User User who made the last change to the line
Version Version of the file the change was included in
Event Type Event that caused the change, such as check in or promote
Change Type Type of change made to the line (add or modify)
Line # File line number
Content 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.
77 Viewing file history
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: n 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. n 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. n 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. n 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. n 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. n 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.
78 Viewing file history
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. 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 80.
View differences for the selected versions. See Viewing file differences, page 41.
Generate a report of differences between versions. See Generating file differences reports, page 46.
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 199.
Review changes made in the selected version. See Reviewing changes between file versions, page 66.
Add the selected version to a code review. See Adding files to code reviews, page 59.
79 Viewing file history details
Button Action
View code reviews for the selected version. See Viewing code reviews files are included in, page 72.
Attach the selected version to an item in TestTrack item or an external issue tracking tool. See Attaching source files to TestTrack items, page 249 or Attaching source files to external issues, page 263.
View the TestTrack item the selected version is attached to. See Viewing TestTrack items, page 251.
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 34.
Label the selected version. See Labeling files, page 146.
View labels applied to the selected version. See Viewing labels, page 144.
7. 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 afileversionandclick Details. The read-only History Details dialog box opens.
80 Viewing graphical file history
3. If thefileis attachedtoanissue, 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.
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.
81 Viewing general file information
n Click and drag the zoom slider to zoom in and out.
n Click a node to view file version details in the Details pane.
n 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 41. 4. Click Save As to save the graph or Print to print it.
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 check out file information The Check Out properties tab includes information about a checked out file. 1. Select a file and choose Activities > Properties. 2. Click the Check Out tab. This tab is only available if you selected a checked out file.
82 Viewing shared file information
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.
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 32.
83
Setting Up Email Notifications
You can create email 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 email to be sent. In some cases, you may receive multiple emails 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 emails if you create too many notifications. 1. Choose Tools > My Email Notifications. The My Email Notifications dialog box opens.
2. Select Show shared triggers where I am an email 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 email notifications, page 85. 4. Select anotificationandclick Edit to change it. See Editing email notifications, page 88. 5. Select anotificationandclick Duplicate to duplicate it. See Duplicating email notifications, page 88. 6. Select anotificationandclick Disable to disable it. See Disabling and enabling email notifications, page 88.
Tip: Select a disabled notification and click Enable to enable it.
7. Select anotificationandclick Delete to delete it. See Deleting email notifications, page 88.
Adding email notifications Add email 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 Email Notifications. The My Email Notifications dialog box opens.
85 Adding email notifications
2. Click Add. The Add My Email Notification dialog box opens.
3. Enter a Notification Name. 4. On the Trigger When tab, select the events that cause the email to be sent.
5. Click the Preconditions tab to set the condition that files must meet to send the email.
86 Adding email 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 [
7. Enter or select the precondition values. Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding restrictions, page 207. 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. Clear Enabled if you do not want the notification to be active. 11. Select Disable email notification after it runs once if you only want the email to be sent once. 12. Select Consolidate multiple file events into one email to send one email for all files the notification runs on. An email is sent for each file if this option is not selected. 13. Click Edit Email Template to modify the default template. See Editing email templates, page 323. 14. Click OK to add the notification.
87 Editing email notifications
Editing email notifications You can edit email notifications to change the event that causes the email to be sent or the condition that files must meet to send the email. 1. Choose Tools > My Email Notifications. The My Email Notifications dialog box opens. 2. Select anotificationandclick Edit. The Edit My Email Notification dialog box opens. 3. Make any changes.
n To edit a value on the Preconditions tab, double-click the value.
n Click Edit Email Template to modify the template. See Editing email templates, page 323. 4. Click OK to save the changes.
Duplicating email notifications If you need to create an email notification similar to an existing one, save time by duplicating and editing an existing notification. 1. Choose Tools > My Email Notifications. 2. Select anotificationandclick 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 email notifications If you do not want an email notification to be sent, you can disable it temporarily instead of deleting it. You can also enable disabled notifications. 1. Choose Tools > My Email Notifications. The My Email Notifications dialog box opens. 2. Select anotificationandclick Disable or Enable. The notification is disabled or enabled.
Deleting email notifications You can delete email notifications if they are no longer used. If you do not want an email notification to be sent, you can disable it temporarily instead of deleting it. See Disabling and enabling email notifications, page 88. 1. Choose Tools > My Email Notifications.
88 Deleting email notifications
The My Email Notifications dialog box opens. 2. Select anotificationandclick Delete. You are prompted to confirm the deletion. 3. Click Yes. The notification is deleted.
89
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.
91 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.
n 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.
92 Setting file information display options
n Hide snapshot branches hides snapshot branches in the Branch menu and Branches tree. Select this option if you do not work with snapshot branches.
n 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.
n 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.
n View server copy opens a read-only copy of the most recent file version on the Surround SCM Server.
n 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.
n 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.
n Share automatically shares files between two locations. See Sharing Files Between Repositories, page 117.
n Move automatically moves files to a location. See Moving files, page 35.
n 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.
93 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.
94 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
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.
n Icon/Text—Displays icons and text on toolbar buttons.
n Icon—Displays icons on toolbar buttons.
n 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.
95 Changing the user interface mode
2. To hide a toolbar, choose View > Toolbars and select the toolbar to hide.
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:
n Separator—Adds a vertical line to separate toolbar sections.
n Spacer—Adds a space between toolbar buttons.
n Flexible Spacer—Adds a space that you can resize between toolbar buttons. 3. Select a Show option to control how toolbar buttons are displayed.
n Icon/Text—Displays icons and text on toolbar buttons.
n Icon—Displays icons on toolbar buttons.
n 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.
n 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.
n 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.
96 Changing defaults for Surround SCM dialogs
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.
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.
n Perform actions as part of changelist enables the use of changelists when performing file actions. If this option is enabled,
n View pending changelists after action opens the Changelists dialog box to display all your pending changelists after performing file actions.
n 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 41 and Merging files, page 43. 4. 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.
97 Setting Check In 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 Get Files from the File Dialog Defaults category.
2. Change any default settings for the Get Files dialog box.
n Force file retrieval from server gets the server copy.
n Merge should first attempt auto-merge automatically merges file version if needed. You are only prompted to manually merge files if auto-merge fails.
n Make files writable leaves the files in the working directory in read-write mode.
n Recursive includes all child repositories in the get.
n 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.
n 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.
98 Setting Check Out Files dialog defaults
2. Change any default settings for the Check In Files dialog box.
n Update version even if no change is made always updates the file version.
n Apply comments to all uses the comment field value for each file.
n Add changes to code review adds checked in files to a code review.
n Prompt to link with TestTrack (IDE integrations only) prompts you to attach files to TestTrack items.
n Warn if checked out to a different computer prompts you to confirm the check in if files are checked out to a different computer.
n Recursive checks in files from the selected repository and all child repositories.
n 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.
99 Setting Undo Check Out Files dialog defaults
2. Change any default settings for the Check Out Files dialog box.
n Exclusive check out prevents other users from checking out the files. This option is only available if Surround SCM allows multiple check outs.
n Force file retrieval from server checks out the server copy.
n Recursive checks out files from the selected repository and all child repositories.
n Overwrite option specifies what to do if the local file and server file are different.
n 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 23.
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.
n Recursive automatically reverts the check out for the selected repository and all child repositories.
n 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.
100 Grouping file extensions
2. Change any default settings for the Add Files dialog box.
n Recursive adds files from the selected directory and all subdirectories.
n 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.
n 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.
n 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.
n 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.
101 Adding file extension groups
2. Click Add to create a group of file extensions. See Adding file extension groups, page 102. 3. 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.
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.
102 Setting Shelve Files dialog defaults
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.
n Select Recursive to shelve files from the selected repository and all child repositories.
n Select View Shelves window after shelving files to open the Shelves window after files are shelved.
n 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.
103
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: n Should a new repository be created for each product, each component, etc.? n Who can create Surround SCM repositories? n Who can access advanced Surround SCM repository actions, such as promoting? n 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.
105 Viewing differences between repositories and working directories
n Enter a Working directory path or click Browse to select a directory.
n Select Allow child repositories to inherit this working directory if you want child repositories to use the same directory.
n 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 124. 6. 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 359.
Viewing differences between repositories and working directories You can diff files in a repository to check for differences between server files and files in your working directory. You can also perform actions on files while viewing the differences.
Tip: If your working directory contains a large number of changes and you want to update Surround SCM to match the contents and structure, you can push changes to the repository to perform multiple actions at the same time. See Pushing changes to repositories, page 109.
1. Select the repository and choose Repository > Working Directory Differences. The Working Directory Differences dialog box opens.
106 Viewing differences between repositories and working directories
2. Click to switch between tree view and list view. 3. Select any options to control which files are displayed.
n Recursive displays all files in the repository and any subrepositories.
n Show changed files displays files that are modified or have a different timestamp in the working directory.
n Show identical files displays files that are the same in the repository and working directory.
n Show files excluded by file name or extension displays all files regardless of name or extension. Surround SCM may be 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 Show files not in Surround option is also selected.
n Show missing local files displays missing local files.
n Show files not in Surround displays files that have not been added to Surround SCM. If a file name or extension matches an excluded value and this option is selected, the file is displayed if the Show files excluded by file name and extension option is also selected.
n Show files in cloaked repositories displays files in cloaked repositories.
Note: 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 perform an action.
107 Viewing differences between repositories and working directories
Button Use to: More information
Differences Compare the file versions. Viewing file differences, page 41
Merge Merge the file versions. Merging files, page 43
View View the file. You can view the local or server copy of changed files.
History Viewthefilehistory. Viewing file history, page 78
Properties View the file properties. Viewing general file information, page 82
Get Get a copy of the file. Getting files, page 15
Add Add the file to Surround SCM. Adding files to Surround SCM, page 28
CheckIn Checkinfile. Checking in updated files, page 24
Shelve Shelvethefile. Shelving files, page 153
Remove Delete the file. If you select a local file or directory, you are Removing files, prompted to confirm the deletion. If you select a server file or page 36 and repository, the Remove Files or Remove Repository dialog box Removing opens. repositories, page 114
Resolve Resolve the file differences if a file or repository was moved or Resolving missing Missing renamed. Ctrl+click the old and new item and then click Resolve moved and renamed Missing. items, page 109
5. Select Save As to save the differences list or click Print to print it. 6. Click Close when you finish.
108 Resolving missing moved and renamed items
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.
n 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.
n 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.
n 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.
n 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.
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.
109 Pushing changes to repositories
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 106.
1. 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 Viewing file differences, page 41 versions.
View View the local or server copy of changed files.
History Viewthefilehistory. Viewing file history, page 78
Properties View the file properties. Viewing general file information, page 82
5. Select the files with changes you want to push to Surround SCM.
110 Renaming repositories
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 124. 8. 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 249 or Attaching source files to external issues, page 263. 9. 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 130.
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.
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 124. 4. Click OK.
111 Moving repositories
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: n You cannot move repositories that include files that are checked out or in a changelist. n 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. n 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 370.
1. Select a repository and choose Repository > Move Repository. The Move Repository dialog box opens.
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.
112 Viewing cloaked repositories
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.
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.
113 Removing repositories
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.
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 124. 6. Click OK. 7. Confirm the removal.
n 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.
n 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.
n 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.
114 Restoring repositories
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.
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.
115 Deleting repositories permanently
Note: You can also remove and destroy repositories at the same time. See Removing repositories, page 114.
1. 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.
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.
116 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 (http://blogs.seapine.com/2009/06/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 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 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, right- click a column and select the column you want to hide.
2. Select any Filter by options to narrow the displayed actions.
n 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.
n Filter by action limits the history to the selected actions performed.
n 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 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 130. 9. If filehistory is included, select afileandclick File History to view the history. See Viewing file history, page 78.
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 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 345. 1. 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
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 130. 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 305.
Creating changelists You typically create changelists when checking in updated files, but you can also create them when: n Checking out, adding, moving, renaming, or removing files n Creating, renaming, or removing repositories n Pushing changes to repositories 1. Expand the Changelist options in the action dialog box. 2. Select
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 249 or Attaching source files to external issues, page 263. 5. Click OK.
123 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 130.
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.
n Select Rename as part of the following changelist and select the changelist you want to add the action to. Select
n 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 97.
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 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. n 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. n 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 Working with pending changelists
Note: To view or work with committed changelists, see Working with committed changelists, page 130.
1. 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 View details about the changelist or file actions. Viewing changelist Details details, page 125
Commit Commit the changelist, which perform actions on all files in the Committing pending Changelist changelist at the same time. changelists, page 130
126 Renaming changelists
Button Use to: More information
Rename Rename the changelist. Renaming changelists, Changelist page 127
Remove Remove the changelist and all related file actions. Removing changelists, Changelist page 128
Set Add comments to the file or all files in the changelist. Adding comments to Comment changelist files, page 129
Attach Attach the file or changelist to an item in TestTrack or an Attaching source files external issue tracking tool. Changelists and files are attached to TestTrack items, to items when changelists are committed. The Attach button is page 249 or Attaching only available if at least one selected changelist file includes source files to external an Add or Check In action. issues, page 263
Edit Action Change the file action options. Editing changelist file Details actions, page 128
Move Move the file action to another changelist. Moving changelist Action actions, page 128
Remove Remove the file action from the changelist. Removing changelist Action file actions, page 129
Differences Compare the file to another version. Viewing changelist file differences, page 132
Merge Merge the file with another version. Merging changelist files, page 133
Add to Add the changelist to a code review. Adding files to code Code reviews, page 59 Review
4. 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. The Changelists dialog box opens. 2. Select the changelist and click Rename Changelist. The Rename Changelist dialog box opens.
127 Removing changelists
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 thefileandclick 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 thefiles andclick Move Action. The Move Actions dialog box opens.
128 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 123. 4. 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 thefileandclick 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.
129 Committing pending changelists
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. 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.
n If the transaction is successful, the changelist is removed from the pending list and added to the committed list.
n 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 131.
3. Select a changelist or file and click the button for the action you want to perform.
130 Searching for committed changelists
Button Use to: More information
View View details about the changelist or file actions. Viewing changelist details, page Details 125
Get Retrieve a copy of the file or all files in the changelist. Getting files, page 15
History Viewthefilehistory. Viewing file history, page 78
Differences View differences between the version of the Viewing file differences, page changelist file and the version the action modified. 41
ViewFile Viewthefile. Viewing files in Surround SCM, page 17
Add to Label the file or all files in the changelist. You can Labeling files, page 146 Label only label files with Add or Check In actions.
Add to Add the changes to a code review. Adding files to code reviews, Code page 59 Review
Duplicate Duplicate changes to another branch. Duplicating selected changes Changes across branches, page 196
Rollback Rollback changelist actions. Rolling back changelist actions, Changes page 135
4. 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
131 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 thefileandclick Differences. The Differences dialog box opens.
132 Merging changelist files
3. Select a Second File option.
n Copy in working directory compares the server file with the working directory file.
n 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:
n Branched file merges changes with a branched version. Select a file from the list.
n Historic version merges the current version with a specific historic version. Select the version from the list.
n Unrelated files merges the current version with any other file. Click Browse to select a file. See Merging unrelated files, page 44.
5. 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 thefileandclick Merge. The Merge dialog box opens.
133 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:
n Branched file merges changes with a branched version. Select a file from the list.
n Historic version merges the current version with a specific historic version. Select the version from the list.
n Unrelated files merges the current version with any other file. Click Browse to select a file. See Merging unrelated files, page 44.
5. 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 Rolling back changelist actions
n If you want to check in the file, enter any comments then click Yes, check in file.
n 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 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 View details about the changelist and action Viewing changelist details, page Details performed. 125
Differences Compare file versions. Viewing file differences, page 41
History Viewthefilehistory. Viewing file history, page 78
Properties View the file properties. Viewing general file information, page 82
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 Undo the changelist action. Changes
136 Rollback changelist action resolutions
Button Use to: More information
Differences Manually merge file versions. If the action you want to rollback changed Merging file contents, you may need to manually merge the files to maintain files, page changes made after the changelist was committed. 43
Rollback File Force a rollback to the previous file version. When rolling back files, any Rolling changes made after the changelist was committed are discarded. back files, page 27
Rollback All Roll back all the actions.
6. 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. n The Reason is 'Already rolled back' if an action was already rolled back. n 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 New file added, not latest version
No resolution required File removed
137 Rollback changelist action resolutions
Changelist action Status Rollback resolution Reason
Check In Rollback change --
Merge locally Auto-merge conflict
Rollback file Binary file changed, not latest version
No resolution available File removed
Create Repository Remove repository --
Remove repository Repository not empty
No resolution required Repository removed
Destroy No resolution available File destroyed
Destroy Repository No resolution available Repository destroyed
Move Move file --
Move file Repository different than moved to repository
No resolution available File removed
Move Repository Move repository --
Move repository Repository different than moved to repository
No resolution available Repository removed
Remove Restore file --
No resolution required File no longer removed
No resolution available File destroyed
Remove Repository Restore repository --
No resolution required Repository no longer removed
No resolution available Repository destroyed
138 Selecting changelists
Changelist action Status Rollback resolution Reason
Rename Rename file --
Rename file Name different than renamed to
No resolution available File removed
Rename Repository Rename repository --
Rename repository Name different than renamed to
No resolution available 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 131. 3. Select changelist or file and click View Details to view the details. See Viewing changelist details, page 125. 4. Select a changelist and click Select to use it.
139
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: n Add files n Get files n Check in files n Promote files or branches n Duplicate changes to a branch n View a committed changelist n 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 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 406.
3. Select a Filter labels by option.
n All Labels displays all labels for all branches.
n Search For File searches for labels by branch, repository, filename, and version. See Searching for labels, page 147. 4. Select any label display options.
n Show hidden labels displays hidden labels.
n Only show my labels only displays labels you created. 5. Click Add to create a label. See Creating labels, page 143. 6. 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 Editing labels, page 144 branches it is available in, or remove it from files.
Delete Delete the label. Deleting labels, page 145
Duplicate Duplicate the label. Duplicating labels, page 145
142 Creating labels
Button Use to: More information
Differences Compare two labels to determine the Viewing label differences, page 148 missing, different, or identical files between the labels.
Attach Attachlabeledfilestoanitemin Attaching source files to TestTrack items, TestTrack or an external issue tracking page 249 or Attaching source files to external tool. issues, page 263
Add to Add labeled files to a code review. Adding files to code reviews, page 59 Code Review
Toggle Hide or unhide the label. Hiding labels, page 145 Hidden
7. 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.
143 Viewing labels
n Mainline makes the label available to all branches in the selected mainline branch. The mainline branch name is read-only.
n Branch makes the label available only to the selected branch. Click Browse to select a branch. 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: n 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. n If the label is available and applied to files in a specific branch, the availability can only be changed to the mainline branch. n 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. n 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 151. 6. Click the History tab to view the label history. See Viewing label history, page 149. 7. Click OK to save the changes.
144 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 145.
1. 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 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
n Current version applies the label to the current file version on the server.
n 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 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.
n All Labels displays labels for all branches.
n Search For File allows you to search for labels by branch, repository, filename, and version. See Searching for labels, page 147. 3. Select any label display options.
n Show hidden labels displays hidden labels.
n 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 144. 6. 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 205.
1. In the Select Label dialog box, select Search For File in the Filter labels by field. The Label Search dialog box opens.
147 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 207. 4. 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 Viewing label history
5. Select any options to control which files are displayed.
n Show missing files displays files that do not have one of the labels applied.
n Show files with different versions displays files with different contents between the labels.
n Show identical files displays files with identical contents between the labels. 6. Select afileandclick Differences to compare file versions. See Viewing file differences, page 41. 7. 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 Generating labeled files reports
Generating labeled files reports Labeled file reports include a list of files and versions a label is applied to. 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 you want 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 is displayed.
150 Removing labels from files
8. Click Print to print the report or click Save As to save it. 9. Click OK to close the report.
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 149. 1. 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
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. n 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. n 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 106.
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 on the Surround SCM Server without adding or checking them in. You can only shelve files that are modified from the current server version or missing from the server.
Note: If you want to shelve files that are not under source control, shelve them from the Shelves window. See Adding files to existing shelves, page 155.
1. Select the files or repositories to shelve and choose Activities > Shelve Files. The Shelve Files dialog box opens.
153 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
n Get original version replaces the local file with the original server version and reverts the check out if files are checked out.
n Get latest version replaces the local file with the latest server version and reverts the check out if files are checked out.
n Leave local file leaves the local file as is.
n 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 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 ashelf tostorefiles inandclick 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.
n Get original version replaces the local file with the original server version and reverts the check out if files are checked out.
n Get latest version replaces the local file with the latest server version and reverts the check out if files are checked out.
155 Managing shelves
n Leave local file leaves the local file as is.
n 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.
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 manage shelves and shelved files in the Shelves window. 1. Choose View > Shelves. The Shelves window opens.
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 157. 4. Select a shelf or file and click the button for the action you want to perform.
Button Use to: More information
Shelve Add files to the shelf. Adding files to existing Files shelves, page 155
Unshelve Retrieve the file or all files in a shelf to a local or working Unshelving files, page Files directory. 159
156 Creating shelves
Button Use to: More information
ViewFile Viewthefile.
Differences Compare, accept, or reject differences between the shelved Viewing shelved file a file in another location. differences, page 158
Edit Shelf Edit the shelf to change the name, description, owner, and Editing shelves, page sharing settings, and manage the files in the shelf. 158
Delete Remove the file from the shelf or delete the shelf. Deleting shelved files and shelves, page 158
Creating shelves 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. See Shelving files, page 153.
1. 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 Editing shelves
n All users shares the shelf with all users.
n Selected users shares the shelf with only the selected users. 5. Click OK. The shelf is added. You can now add files to the shelf. 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. 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 ashelf orfileandclick 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. 2. Select ashelvedfileandclick Differences. The Differences dialog box opens. Read-only information is displayed in the First File area.
158 Unshelving files
3. Select a Second File option.
n Server version of the shelved file compares the shelved file with the file version on the server that was modified.
n Copy in working directory for branch compares the shelved file with the local file in the working directory for the selected branch.
n 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 ashelf orfileandclick Unshelve Files. If you select a shelf, all files in the shelf are retrieved. The Unshelve Files dialog box opens.
159 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 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 349 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 dissimilar. 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.
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 367.
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 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 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 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 1.0.0 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 1.0.0 branch and promoted to both the WysiCalc 1.0.x and WysiCorp Products branches.
After the product is released, the WysiCalc 1.0.0 branch is made read-only and a snapshot branch named WysiCalc 1.0.0 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 Creating branches
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: n 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.
n 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 167. 1. Select a branch and repository to create the new branch from.
165 Creating branches
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. 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.
n To copy only the selected repository and all subrepositories from the parent branch to the new branch, select
n 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 169.
n To select the specific repositories to include or exclude in the new branch, select
166 Using branch templates
n Latest version creates a branch from the latest version of each file.
n Timestamp creates a branch based on the selected last check in timestamp.
n 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 147.
n Latest version in state creates a branch from the latest version of each file in the selected workflow state.
n 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.
n 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.
n 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.
167 Including and excluding repositories for new branches
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.
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. n 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 168. n To change the repositories included in an existing branch, update the template in the branch properties. See Modifying templates for existing branches, page 359.
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 169.
1. Select
168 Selecting branch templates
2. Click Modify. The Branch Template dialog box opens and displays the parent branch repository structure.
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 359.
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.
169 Selecting branch templates
Note: If multiple branches include and exclude the same repositories, only the branch that most recently used the repository structure is displayed.
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.
170 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: n Promoting changes from a child branch up to the parent branch. See Promoting branches, page 178 and Promoting files, page 183. n Rebasing changes from a parent branch down to a child branch. See Rebasing branches, page 187 and Rebasing files, page 192. n 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 196.
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 178. 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 187. 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 196.
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.
171 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.
172 Viewing branch differences
The Differences column displays the reason for the difference.
Column Description Color contains
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 Gray template applied to it.
Note: If you do not have access to a repository in one of the branches,
6. Select any display options.
n Show identical files displays files with identical contents.
n 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,
n Show moved files displays files moved from one branch to another.
n Show changed files displays files with different contents.
n Show renamed files displays files renamed in one branch but have a different name in the other branch.
n 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. Viewing file differences, You can only diff binary files if a diff application is page 41 and Setting configured for the file extension. diff/merge options, page 49
173 Copying files across branches during check in
Button Use to: More information
Diff Report Generate a branch differences report. Generating branch differences reports, page 175
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 Viewing file history, page 78 Edit File, Check Out File, and Rollback File are not and Viewing repository available in the History dialog box because they can history, page 119 change the file version.
Properties View the file or repository properties. Viewing general file information, page 82 and Viewing general repository information, page 120
Remove Remove a missing file or repository from a branch. Removing files, page 36 and Removing repositories, page 114
Restore Restore a removed file or repository in the branch. Restoring removed files, page 37 and Restoring repositories, page 115
Rename Rename a file or repository to use the name in the other Renaming files, page 36 and branch. Renaming repositories, page 111
Promote Update a file in the ancestor branch with changes from Promoting files, page 183 the child branch.
Rebase Update a file in the child branch with changes from the Rebasing files, page 192 ancestor branch.
Merge Merge a changed file with the file in the other branch. Merging files, page 43
Copy Copy a changed file to the other branch. Copying files across branches during check in, page 174
8. 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 171. 1. Select a changed file and click Copy. The Copy Check In dialog box opens.
174 Generating 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 249 or Attaching source files to external issues, page 263. 4. Click OK. You return to the Branch Differences dialog box. The file is copied to the branch.
n 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.
n If the file does not exist in the destination branch, it is added and checked in as the current version.
n If a file’s parent repository does not exist in the destination branch, it is automatically added when the file is copied.
n 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.
Generating branch differences reports Branch differences reports include file differences between two related branches. See Viewing branch differences, page 171. 1. Select a branch or repository. 2. Choose Branch > Branch Differences. The Branch Differences dialog box opens.
175 Generating branch differences reports
3. Select the branch you want to compare Branch 1 with from the Branch 2 list. You can also click Browse to select a branch. 4. Select Recursive to display 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.
176 Generating branch differences reports
7. Select any additional report Options.
n Ignore case differences in file contents excludes differences in character case.
n Ignore whitespace excludes any whitespace differences (spaces and tabs).
n Ignore changes in the amount of whitespace excludes additions or deletions to existing whitespace (spaces and tabs).
n Ignore blank lines excludes inserted or deleted blank lines.
n 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 option. When you view the differences, you may also want to see the parts of the files near the lines that differ to help you understand what changed. These nearby parts of the files are called 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 diffs.
n Enter the number of Output lines of context to display before and after each change. The default is 3 lines.
n Select Unified format to display the differences with limited context lines. This format excludes redundant context lines.
n 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 is generated. For information about report symbols, see Generating file differences reports, page 46. 10. Click Print to print the report or click Save As to save it. 11. Click OK to close the report.
177 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.
n Latest version promotes the latest version of each file.
n Timestamp promotes changes from the specified timestamp.
178 Promoting branches
n 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.
n Latest version in state promotes changes from the latest version of each file in the selected workflow state.
n 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 180.
7. Select Label promoted files in destination to label the files in the ancestor branch. Select a label or select
179 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.
180 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 Viewing file differences, To branch file. page 41
History Viewthefilehistory. Viewing file history, page 78
Properties View the file properties.
Attach Attach the file to an item in TestTrack or an external issue Attaching source files to tracking tool. You can only attach successfully promoted TestTrack items, page files that changed the version number on the destination 249 and Attaching source branch. Files removed, renamed, or in broken shares cannot files to external issues, be attached. page 263
Add to Add the file to a code review. You can only add successfully Adding files to code Code promoted files that changed the version on the destination reviews, page 59 Review branch. Files removed, renamed, or in broken shares cannot be added to reviews.
181 Promote actions
Button Action More information
Promote Promote the file. You can view files that were promoted or Promoting files, page 183 File were not promoted, and files with conflicts. You can also perform actions to resolve conflicts and promote files.
Merge Manually merge the files. Merging files, page 43 Locally
Remove Remove the file from the parent branch. If you promote a file Removing files, page 36 Parent that was removed from the child branch, you may need to remove it from the parent branch.
Break Unshare a file. Breaking shares, page Share 118
Force Promote the file and overwrite the parent branch file. Promotion
3. Select Label promoted files in destination to label files in the ancestor branch. Select a label or select
Promote actions Following are promote actions and corresponding reasons.
182 Promoting files
Action Reason
Will promote/Promoted 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
Will not promote/Could not promote 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
User action required 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
None 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 178. 1. Select the files you want to promote and choose Branch > Promote File.
183 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.
n Latest version promotes the latest version of each file.
n Timestamp promotes changes from the specified timestamp.
n 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.
n Latest version in state promotes changes from the latest version of each file in the selected workflow state.
n 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 180.
184 Promoting files
8. Select afileandclick Attach to attach it to an item in TestTrack or an external issue tracking tool. See Attaching source files to TestTrack items, page 249 or Attaching source files to external issues, page 263. 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
185 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.
186 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 41
History Viewfilehistory. Viewing file history, page 78
Properties View file properties. Viewing general file information, page 82
Rollback Rollback the selected file.
Merge Manually merge the files. Merging files, page 43 Locally
Force Remove the file from the Remove 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 (www.seapine.com/kb/questions/1222) for information.
187 Rebasing branches
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.
2. Enter any Comments, such as the reason for rebasing the branch. 3. Select a Rebase branch based on option.
n Latest version rebases from the latest version of each file.
n Timestamp rebases from the specified timestamp.
n Label rebases from the selected label. Click Select to view label details or search for a label. See Selecting labels, page 147.
n Latest version in state rebases from the latest version of each file in the selected workflow state.
n 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 190.
188 Rebasing branches
6. Select afileandclick 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.
189 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 41
History Viewthefilehistory. Viewing file history, page 78
Properties View the file properties.
190 Rebase actions
Button Action More Information
Attach Attach the file to an item in TestTrack or an external issue Attaching source files to tracking tool. You can only attach files that were already TestTrack items, page successfully rebased and changed the version number on the 249 and Attaching destination branch. Files removed, renamed, or in broken source files to external shares cannot be attached. issues, page 263
Add to Add the file to a code review. Adding files to code Code reviews, page 59 Review
Rebase Rebase the file. Rebasing files, page File 192
Merge Manually merge the files. Merging files, page 43 Locally
Break Unshare the files. Breaking shares, page Share 118
Force Rebase the file and overwrite the child branch file. Rebase
3. Select Label rebased files in destination to label files in the parent branch. Select a label or select
Rebase actions Following are rebase actions and corresponding reasons.
191 Rebasing files
Action Reason
Will rebase/Rebased 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
Will not rebase/Could not rebase 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
User action required 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
None 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 187. 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 (www.seapine.com/kb/questions/1222) for information.
192 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.
n Latest version rebases the latest version of each file.
n Timestamp rebases changes from the specific timestamp.
n 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.
n Latest version in state rebases changes from the latest version of each file in the selected workflow state.
n 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 190.
193 Rebasing files
7. Select afileandclick 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.
194 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 41
History Viewfilehistory. Viewing file history, page 78
Properties View file properties. Viewing general file information, page 82
Rollback Rollback the selected file.
Merge Manually merge the files. Merging files, page 43 Locally
Force Remove the file from the Remove rollback list.
195 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,
n Changelist duplicates changes associated with the selected changelist. Click Select to search for a changelist or view changelist details. See Selecting changelists, page 139.
196 Duplicating selected changes across branches
n 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 257.
n Label duplicates changes associated with the selected label. Click Select to search for a label or view label details. See Selecting labels, page 147. 5. Select afileandclick 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 auto- merge 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 199 7. 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 198.
8. Select Label changed files in destination to label the files in the destination branch. Select a label or select
197 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 41
History Viewfilehistory. Viewing file history, page 78
Properties View file properties. Viewing general file information, page 82
Duplicate Duplicate file changes to the destination Duplicating selected changes across Changes branch. branches, page 196
Merge Manually merge the files. Merging files, page 43 Locally
Force Duplicate the file changes and overwrite the file Overwrite in the destination branch.
3. Select Label changed files in destination to label files in the destination branch. Select a label or select
198 Duplicate changes actions
4. Click Duplicate All to duplicate all file changes. The Duplicate Changes Status dialog box opens. You can view files with duplicate actions and reasons. See Duplicate changes actions, page 199 5. 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 Reason
Will duplicate / Duplicated New file Removed file Modified file
Will not duplicate / Could not duplicate Binary files are different Destination file does not exist Changes already applied in branch
User action required Auto-merge conflict
None 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.
199 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,
n Changelist tracks changes associated with the specified changelist. Click Select to search for a changelist or view changelist details. See Selecting changelists, page 139.
n 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 257.
n Label tracks changes associated with the specified label. Click Select to search for a label or view label details. See Selecting labels, page 147. 4. Click Save As to save the results list or click Print to print it. 5. Click Close when you finish.
200 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 201. 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 203.
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 201.
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.
201 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 349.
202 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.
203 Viewing the graphical branch tree
2. Select the Branches you want to display. Each branch is displayed as a node.
n Click and drag the zoom slider to zoom in and out.
n Click a node to view branch details in the Details pane.
n 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 171. 4. Click Save As to save the graph or Print to print it.
204 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 205. You can also search for specific phrases or text in file contents. See Searching for text in files, page 218.
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 222. 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 224.
Going directly to a file or repository You can click or copy and paste an address from a notification email to go directly to repositories and files. See Browsing to files and repositories, page 225.
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 226.
Searching for files You can search for files based on a variety of criteria, such as filename, version number, and file type. You can specify any combination of the available criteria to perform more complex searches.
Tip: You can 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.
205 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 207 for information about each restriction. 4. 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 it in the Restrictions list.
5. Repeat steps 2-4 to add 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.
206 Adding restrictions
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 224 and Adding reports, page 230.
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 Limits results to files with:
Text Text that does or does not match text or a regular expression. See Adding text restrictions, page 208.
Number Numbers that do or do not match a number or number in a range. See Adding number restrictions, page 210.
Date Dates that do or do not match a date, date range, or time period. See Adding date restrictions, page 210.
Multiple list Values that do or do not match selected values. See Adding multiple list selection selection restrictions, page 211.
Condition Attributes that do or do not match a condition. See Adding condition restrictions, page 212.
Event File events that do or do not match events. See Adding event restrictions, page 213.
Label Labels that do or do not match text or a regular expression. See Adding label restrictions, page 214.
TestTrack item TestTrack items that do or do not match a number or number in a range or list. See number Adding TestTrack item number restrictions, page 214.
Security group Events performed by users in a security group. See Adding security group restrictions, page 215.
Branch/repository Locations in a repository for a specific branch or across all branches. See Adding branch and repository restrictions, page 215.
Actions based on File actions performed by users on a date or in a date range. See Adding action user and date restrictions based on user and date, page 216.
Note: Triggers and email 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 Email Notifications, page 85 and Configuring triggers, page 316.
207 Adding text restrictions
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. 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.
n Match includes files with text that matches the specified text string.
n 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 208.
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 ? colou?r matches color or colour previous character
208 Using regular expressions
To match: Use: Example
Zero or more occurrences of the * a.* matches ‘a’ followed by any number of characters, such previous character as ab, abb, aab, or aabb
One or more occurrences of the + ba+ matches ‘b’ followed by any number of occurrences or previous character ‘a’, such as ba, baa, or baaa
A specified number of occurrences of {...} ba{3} matches baaa the previous character baa{3,} matches ‘b’ followed by three or more occurrences of ‘a’, such as baaa, baaaa, or baaaaa
Any single character included in a set [...] [abc] matches a, b, or c of characters
Any single character not included in a [^...] [^abc] matches any character except a, b, or c set of characters
Any single character in a specified [ - ] [a-z] matches any lowercase character range [0-9] matches any digit, 0-9
Any single whitespace character \s v\s matches ‘v’ followed by a whitespace character (space, tab, new line)
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 (...) (file1|2|3|4) matches file1, file2, file3, or file4
Escape special characters for literal interpretation (modify the \ file\.txt matches occurrences meaning of the following character) of file.txt
Examples n You want to send an email 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) n 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)
209 Adding number restrictions
n 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.* n 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.* n 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.
n Equal to only includes numbers equal to the specified number.
n Less than only includes numbers less than the specified number.
n Greater than only includes numbers greater than the specified number.
n 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.
210 Adding multiple list selection restrictions
2. Select is or is not to indicate if the files include the specified date or time period.
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.
n Equal to, before, after, or between includes files relative to the specified date or time period.
n A specific time period includes files from the selected period, such as last week or last year.
n 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 locked 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.
211 Adding condition restrictions
2. Select is or is not to indicate if the files include the selected users. 3. Select an option to indicate the values to include.
n If you are adding a user restriction, Current user includes files for the logged in user.
n All includes files with one or more values in the list.
n 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.
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.
212 Adding event restrictions
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.
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.
n All events includes files with one or more events in the list.
n 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 208.
n Does or does not indicates if the files include matching text.
n Match searches using the specified text string. Match regular expression searches using the specified regular expression.
n If you entered text, select Match case to match the case of the text. 5. Click OK to add the restriction.
213 Adding label restrictions
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 1.0.0 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.
n Match includes labels that match the specified text string.
n 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 208.
5. If you entered text, select Match case to match the case of the text. 6. Click OK to add the restriction.
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 100-200 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.
214 Adding security group restrictions
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.
n Equal to only includes items equal to the specified number.
n Less than only includes items less than the specified number.
n Greater than only includes items greater than the specified number.
n Between only includes items within the specified range.
n 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. 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.
215 Adding action restrictions based on user and date
2. Select a branch and repository option.
n Current branch and repository only includes files in the current branch and repository.
n 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.
216 Adding action restrictions based on user and date
2. Select any Filter by Users options.
n Is in list or is not in list indicates if the files include the selected users.
n Current user only includes actions performed by the logged in user.
n All users includes actions performed by all users.
n 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.
n Is in list or is not in list indicates if the files include the selected actions.
n 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.
n All actions includes all actions.
n Selected actions only includes the selected actions.
Note: Click Select All to select all actions or click Select None to clear any selected actions.
217 Searching for text in files
4. Select any Filter by Dates options.
n Is or is not indicates if the files include dates that match the specified date or time period.
n All dates includes files with any date.
n Equal to, before, after, or between includes files relative to the specified date or time period.
n A specific time period includes files from the selected period, such as last week or last year.
n 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 locate and open files you may 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. n You can search using text phrases, with or without wildcards, or regular expressions. If you enter a phrase, the exact phrase is searched for.
n 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.
n If you enter only one search term, only files that contain the exact term are returned. For example, if you enter 'WysiCorp', files that contain 'WysiCorp.h' or 'WysiCorporation' are not returned. You can use wildcards for more flexible searching. n Only current file versions are searched. Historical file versions are not included in searches. n 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. n 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 352. 1. Choose Edit > Find in Files. The Find in Files window opens.
218 Searching for text in files
2. In the Search area, enter or select the Search Criteria.
n 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.
n 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 220 for examples using wildcards and regular expressions.
n Recursive searches for the specified text in all files in the selected repository and all subrepositories.
n 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.
n 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 specify file extensions to include or exclude when searching or limit the number of search results displayed.
n 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.
219 Text search examples
n 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 101.
n 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 searched an indexed branched, 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.
n 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.
n 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.
n 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.
n 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.
n To open a file, select it and click Open.
n Togotothefileinthesource files list, select it andclick Go To File.
n 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.
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 218.
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.
220 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.
To substitute for: Use: Example
Zero or more Asterisk Entering 'gr*n' returns files that contain words such as 'green' and characters, excluding (*) 'grain', but does not return phrases such as 'greater than'. spaces
One character, Question Entering 'p?int' returns files that contain words such as 'print', 'point', excluding spaces mark (?) 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 basic 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 ? colou?r matches 'color' or 'colour' previous character
One or more occurrences of the + ba+ matches ‘b’ followed by any number of occurrences or previous character ‘a’, such as 'ba', 'baa', or 'baaa'
Zero or more occurrences of the * a.* matches ‘a’ followed by any number of characters, such previous character as 'ab', 'abb', 'aab', or 'aabb'
Separate two or more alternatives to | (gray|grey) matches 'gray' or 'grey' perform an OR search
A specified number of occurrences {...} ba{3} matches 'baaa of the previous character baa{3,} matches ‘b’ followed by three or more occurrences of ‘a’, such as 'baaa', 'baaaa', or 'baaaaa'
Any single character included in a [...] [tw]alk matches 'talk' or'walk' set of characters
Group several items as a single unit (...) (file1|2|3|4) matches 'file1', 'file2', 'file3', or 'file4'
Interpret special characters as exact \ file\.txt matches occurrences of 'file.txt' literals
221 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: n All Files—Displays all files in the selected repository n Checked Out Files—Displays all checked out files in the selected repository n Files Checked Out By Me—Displays all files in the selected repository checked out by the current user n 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 222. 3. Select afilterandclick Edit to change it. See Editing filters, page 224. 4. Select afilterandclick Duplicate to duplicate it. See Duplicating filters, page 224. 5. Select afilterandclick Top, Move Up, Move Down, or Bottom to change the display order. 6. Select afilterandclick Delete to delete it. See Deleting filters, page 225.
Adding filters Filters allow you to quickly find files based on selected criteria. For example, you can create a filter to find files in a specific workflow state.
222 Adding filters
Note: You can also create filters in the Advanced Find dialog box. See Searching for files, page 205.
1. 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 cannot be 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. See Adding restrictions, page 207 for information about restrictions. 6. Enter or select the restriction values. 7. Click OK.
223 Applying filters to the source file list
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.
8. Repeat steps 5-7 to add additional restrictions. 9. Click OK. The filter is created.
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 1. Choose Tools > Filters. The Filters dialog box opens. 2. Select afilterandclick 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.
224 Deleting filters
The Filters dialog box opens. 2. Select afilterandclick Duplicate. The Duplicate Filter dialog box opens. 3. Enter a Filter name and modify the filter options. 4. Click OK to save the changes.
Deleting filters 1. Choose Tools > Filters. The Filters dialog box opens. 2. Select afilterandclick 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.
n To select a repository—sscm://ServerAddress:Port//Branch//Repository/SubRepository
n To select a file—sscm://ServerAddress:Port//Branch//Repository/SubRepository/File
Tip: To browse to a specific file version, append ?ver=
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 226.
225 Bookmarking files, repositories, and branches
Note: Use the Address toolbar to view the address for the selected repository or file. Choose View > Toolbars > Address to open the toolbar.
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 226. 1. Select the file, repository, or branch you want 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. Click OK. The bookmark is added to the Bookmarks menu.
Note: If a bookmarked file, repository, or branch is moved or renamed, or the server address changes, the bookmark no longer works. You need to delete the old bookmark and then create a new one. See Managing bookmarks, page 226.
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.
226 Managing bookmarks
2. Select a bookmark and click Edit to rename it or change the description. 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.
227
Generating Reports
Surround SCM includes a large amount of information about the files, branches, and repositories and the users who perform actions. Reports provide an easy way to access, analyze, and share this information. You can build reports that focus on the data you need. You can also share reports with other users or keep them private.
About reports Surround SCM includes the following reports: n History reports include information about files, actions, and users who performed the actions. n List reports include current information about files in columns. n Security group reports include information about commands assigned to security groups. n Trend reports include actions over time. n Workflow progress reports include information about the state of files as they move through a workflow. n Labeled file reports include the files and versions that a label is applied to. n File differences reports include differences between two or more file versions. n Branch differences reports include differences between two branches. You can also view reports from external reporting services, such as SQL Server Reporting Services or Crystal Reports, in 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 additional information about external reporting. See Adding external reports to Surround SCM, page 243.
Note: You can also save and print the source file list. See Saving the source file list, page 245 and Printing the source file list, page 246.
Configuring reports The following information only applies to history, list, security group, trend, and workflow progress reports. File differences reports and branch differences reports are not managed in the Reports dialog box. See Generating file differences reports, page 46 and Generating branch differences reports, page 175. Labeled files reports can be generated from the Reports dialog box, but the steps are slightly different. See Generating labeled files reports, page 150. 1. Choose Tools > Reports. The Reports dialog box opens.
229 Adding reports
2. Click Add to create a report. See Adding reports, page 230. 3. Select a report and click Edit to change it. See Editing reports, page 244. 4. Select a report and click Duplicate to duplicate it. See Duplicating reports, page 244. 5. Click Quick Report to create and run a report without saving it. See Running quick reports, page 245. 6. Select a report and click Run to generate it. See Running reports, page 244. 7. Select a report and click Delete to delete it. See Deleting reports, page 244. 8. Click Close to close the Reports dialog box.
Adding 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 About reports, page 229. 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 a Restriction to set the criteria for the report content. The restriction options depend on the selected report type. See Adding restrictions, page 207. 7. Click the Output tab to select the output format, the stylesheet to use, and options for additional information to include in the report. The available options depend on the selected report type. 8. Click OK.
230 Adding history reports
The report is added. See Running reports, page 244 for information about running reports.
Adding history reports History reports include historical information about files, actions, and the users who performed the actions. 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. 6. Select a Restriction to set 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. You can add restrictions based on branch and repository, users who performed actions within a date range, filename, version number, last modified date, last check in date, file size, locked by user, workflow state, or custom field values.
231 Adding history reports
7. Enter or select the restriction values. See Adding restrictions, page 207. 8. 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. Repeat steps 6-8 to add additional restrictions. 10. Click the Output tab.
232 Adding history reports
11. Select an Output format. Reports can be generated in HTML, space-delimited columns, or tab-delimited columns.
Tip: If a history report is generated in HTML, a pie chart is included in the report. See Charting report data, page 243.
12. Select a report Stylesheet. Stylesheets are templates you can use to quickly generate formatted reports. Cascading Style Sheets (CSS) files are installed with Surround SCM for each report type to help you create reports with predefined layout and design options. You can customize an existing CSS stylesheet or create your own and add it to Surround SCM. Stylesheets are generally located in the StyleSheets folder in the Surround SCM application directory. 13. Select a report style. Summary style report generates a report that includes an overview of file details.
n Hide repositories without selected actions excludes repositories with files that do not meet the report criteria.
n Include difference information includes file version differences. Click Diff Options to specify differences to display. See Generating file differences reports, page 46. Table style report generates a report with file information displayed in a table format.
n 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 when the report is generated. If you want to include a pie chart with the report, you must select this option. See Charting report data, page 243.
233 Adding list reports
n 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 when the report is generated. 14. Select the Field Options to specify the columns to include in the report. Select the column you want to add in the Available columns list and click the right arrow to move it to the Selected columns list. To remove a column, select the column in the Selected columns list and click the left arrow to move it to the Available columns list. 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 244 for information about running reports.
Adding list reports List reports include current information about files in columns. 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.
234 Adding 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. Select a Restriction to set 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. You can add restrictions based on branch and repository, users who performed actions within a date range, filename, version number, last modified date, last check in date, file size, locked by user, workflow state, or custom field values.
7. Enter or select the restriction values. See Adding restrictions, page 207. 8. 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. Repeat steps 6-8 to add additional restrictions. 10. Click the Output tab.
235 Adding list reports
11. Select an Output format. Reports can be generated in HTML, space-delimited columns, or tab-delimited columns.
Tip: If a list report is generated in HTML, a pie chart is included in the report. See Charting report data, page 243.
12. Select a report Stylesheet. Stylesheets are templates you can use to quickly generate formatted reports. Cascading Style Sheets (CSS) files are installed with Surround SCM for each report type to help you create reports with predefined layout and design options. You can customize an existing CSS stylesheet or create your own and add it to Surround SCM. Stylesheets are generally located in the StyleSheets folder in the Surround SCM application directory. 13. Select the sorting and order options.
n 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 when the report is generated. If you want to include a pie chart with the report, you must select this option. See Charting report data, page 243.
n 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 when the report is generated. 14. Select the Field Options to specify the columns to include in the report.
236 Adding security group reports
Select the column you want to add in the Available columns list and click the right arrow to move it to the Selected columns list. To remove a column, select the column in the Selected columns list and click the left arrow to move it to the Available columns list. 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 244 for information about running reports.
Adding security group reports Security group reports include information about commands assigned to security groups. See Security Commands, page 435. 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 if you want 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.
237 Adding security group reports
7. Select a security group name option.
n Is in list or is not in list indicates if the security group name is included in the list of selected security groups.
n All security groups includes all security groups in the report.
n Selected security groups only includes the selected security 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 generated in HTML, space-delimited columns, or tab-delimited columns. 11. Select a report Stylesheet. Stylesheets are templates you can use to quickly generate formatted reports. Cascading Style Sheets (CSS) files are installed with Surround SCM for each report type to help you create reports with predefined layout and design options. You can customize an existing CSS stylesheet or create your own and add it to Surround SCM. Stylesheets are generally located in the StyleSheets folder in the Surround SCM application directory. 12. Select Include Repository Security and Branch Security tabs to include repository and branch security commands in the report. 13. Select a report style.
238 Adding trend reports
n Comparison style report displays the security groups and commands side-by-side in the same table.
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.
n Detail style report displays the commands for each security group in separate tables. 14. Click OK. The report is added. See Running reports, page 244 for information about running reports.
Adding trend reports Trend reports include information about actions over time. 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.
239 Adding trend reports
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 a Restriction to set 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. You can add restrictions based on branch and repository, users who performed actions within a date range, filename, version number, last modified date, last check in date, file size, locked by user, workflow state, or custom field values.
7. Enter or select the restriction values. See Adding restrictions, page 207. 8. 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. Repeat steps 6-8 to add additional restrictions. 10. Click the Output tab.
11. Select an option to Group actions by. You can group actions by user, day, month, or week. 12. Select One event type per user per file to only include one event type per file.
240 Adding workflow progress reports
13. Click OK. The report is added. See Running reports, page 244 for information about running reports.
Adding 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.
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 a Restriction to set the criteria that files must meet to be included in the report.
241 Adding workflow progress reports
The Report Restriction dialog box opens. The options change based on the selected restriction. You can add restrictions based on branch and repository, users who performed actions within a date range, filename, version number, last modified date, last check in date, file size, locked by user, workflow state, or custom field values.
7. Enter or select the restriction values. See Adding restrictions, page 207. 8. 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. Repeat steps 6-8 to add additional restrictions. 10. Click the Output tab.
11. Select a Start Date, End Date, and time Interval for the files to include in the report. 12. Select Hide unused states to exclude states that are not applied to files. 13. Select Hide
242 Charting report data
14. Click OK. The report is added. See Running reports, page 244 for information about running reports.
Charting report data You can view data in a pie chart when running history and list reports. The following options must be set: n The output format must be set to HTML. n The report data must be grouped by the primary sort column. To change the data displayed in the chart, change the primary sort column value. When the report runs, the chart is displayed at the bottom of the report. You can include labels to display the item name, count, and percentage for each piece of the pie chart. Click Show Labels to display labels. You can also use the chart legend to match the report data with the pieces of the pie chart. Click an item in the chart legend to highlight that piece of the pie chart and display a label that includes the item name and data count. The chart legend is displayed by default. Click Hide Legend to hide the chart 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.
Note: The Surround SCM administrator must configure external reporting services and security permissions before you can add external reports. See the External Reporting wiki (http://labs.seapine.com/reporting.php) for information about configuring external reports.
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 external report you want 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 information.
5. Click Add. The report is added and displayed in the Reports dialog box.
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 244.
243 Editing reports
Editing reports 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 and click OK. If you are editing an external report, you can only change the Report name, Public/private report sharing, and the Output format fields. The other field information is stored in the reporting service.
Note: Click Edit to edit the report content in the external reporting service. You can only edit reports if a client plug-in that supports report editing is installed. Ask your Surround SCM administrator for information.
Duplicating reports If you add reports with the same basic information, you can save time by duplicating and editing an existing report. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Duplicate. The report is duplicated. 3. Modify the duplicated report and save the changes.
Deleting reports 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Delete. The report is deleted.
Running reports After you create a report, you can quickly run it. You can also print and save reports. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Select a report and click Run. The report is generated. 3. Click Print to print the report or click Save As to save it.
244 Running quick reports
Running quick reports You can create and run a quick report when you do not want to save the report for future use. 1. 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 with the Restrictions tab selected. 4. Create the report. See Adding reports, page 230. 5. Click Run. The report is generated. 6. Click Print to print the report or click Save As to save it.
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. 1. Select a repository. 2. Optionally select a filter from the Filter list if you only want to include specific files in the saved list. For example, to save a list of all checked out files, select Checked Out Files from the Filter list before you save the 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.
245 Printing the source file list
4. Select the column you want to add in the Available columns list and click the right arrow to move it to the Selected columns list. To remove a column, select the column in the Selected columns list and click the left arrow to move it to the Available columns list. 5. Select a column in the Available 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 file list is saved.
Printing the source file list You can print the source file list, which can be helpful for reporting purposes. 1. Select a repository. 2. Optionally select a filter from the Filter list if you want to include specific files in the printed list. See Applying filters to the source file list, page 224. 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 you want to add in the Available columns list and click the right arrow to move it to the Selected columns list. To remove a column, select the column in the Selected columns list and click the left arrow to move it to the Available columns list. 5. Select a column in the Available columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 6. Click Print to print the file list.
246 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 397.
1. Choose Tools > TestTrack Integration > Connections. The TestTrack Connections dialog box opens.
2. Click Add to create a connection. See Adding TestTrack connections, page 247. 3. Select a connection and click Edit to change it. See Editing TestTrack connections, page 248. 4. 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 248.
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.
247 Editing TestTrack connections
2. Click Add. 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 398.
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 1. Choose Tools > TestTrack Integration > Connections. 2. Select the connection and click Delete. You are prompted to confirm the deletion.
248 Entering TestTrack login information
3. Click Yes. 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 2010.1 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.
249 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 247. 3. 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 251.
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 253 and Adding TestTrack issues, page 252. 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.
250 Viewing TestTrack items
6. If youareattachingfiles toissues, click Fix to mark the selected issue as fixed. See Fixing external issues, page 264. 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.
251 Adding TestTrack issues
1. Select the file. You can search for files attached to items. See Finding files attached to TestTrack items, page 254. 2. Choose Activities > History. The History dialog box opens. 3. Select thefileversionattachedtotheitem youwant toview. 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.
252 Editing TestTrack issues
The issue is added to the TestTrack project and listed in the issues list.
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 251.
4. 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 theissues youwant tofix andclick Fix. The Fix dialog box opens.
253 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.
254 Analyzing issue risk in files
Files that meet the criteria are displayed. The Find files results filter is applied.
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 55. Keep the following in mind: n To analyze risk, Surround SCM must be integrated with TestTrack or a supported third-party issue tracking tool. See Integrating with TestTrack, page 247 and Integrating with issue tracking tools, page 262. n 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. n 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.
255 Analyzing issue risk in files
2. Click Browse and select the branch and repository to analyze. 3. Select the Analysis settings.
n 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.
n 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.
n 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 78.
View properties for the selected file. See Viewing general file information, page 82.
Change the workflow state of the selected files. See Changing workflow states, page 34.
Change multiple custom field values for the selected files. See Changing multiple custom fields, page 33.
Perform a code review for the selected file. See Reviewing files, page 68.
Add the selected files to a code review. See Adding files to code reviews, page 59.
View code reviews for the selected file. See Viewing code reviews files are included in, page 72.
256 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.
257
Integrating with Third-Party Applications
Surround SCM can be integrated with a variety of third-party IDEs, build and issue tracking tools, and applications, making it easy for you to work with source controlled 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 are available to help you integrate Surround SCM with third-party applications: n Surround SCM Third-Party Integrations (www.seapine.com/kb/questions/1504) lists the supported integrations. n The Integrations knowledgebase category (www.seapine.com/kb/categories/Surround+SCM/Integrations) provides integration installation instructions, setup information, and troubleshooting help. n 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 262 for information about using Surround SCM as your default source control provider. n 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 262 for information about the API and working with issues in an external issue tracking tool in the Surround SCM Client. n Surround SCM Custom Client Menus (http://blogs.seapine.com/2009/11/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. n 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 267.
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.
259 Setting Xcode integration options
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 265. 5. 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 266. 6. 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 email application, to automatically open Surround SCM and select a repository or file. Surround SCM hyperlinks may be included in email notifications or provided by other users. See Browsing to files and repositories, page 225.
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 Xcode integration options You can set options for committing changelists and specify file types Surround SCM should ignore when integrating with Xcode on Mac OS X.
260 Setting plug-in directories
Note: See Xcode 3 Integration (www.seapine.com/kb/questions/1595) and Xcode 4 Integration (www.seapine.com/kb/questions/1650) for information about configuring, using, and troubleshooting the integration.
1. Choose Tools > User Options then select the Xcode Integration category. 2. Select Display the TestTrack Browser dialog before all changelist commit operations to always open the TestTrack Browser to attach files to TestTrack items before committing changes. 3. Enter any file extensions in the Ignored Files field to exclude files when committing changelists. Use a semicolon to separate file extensions. 4. 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 (http://blogs.seapine.com/2009/11/surround-scm-custom-client- menus) for information about creating plug-ins.
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.
261 Integrating with IDEs and applications that support SCCI
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 (www.seapine.com/kb/questions/1504) 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 259. 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 Integrations knowledgebase category (www.seapine.com/kb/categories/Surround+SCM/Integrations) for setup, usage, and troubleshooting information.
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 255. 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 web page (www.seapine.com/scmresources).
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.
262 Attaching source files to external issues
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 124. 1. 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. The Issue Browser dialog box opens.
2. Select the Connection for the project you want to connect to.
263 Viewing external issues
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 264. 4. 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 264. 6. Click OK to attach the files to the selected issues. The files are attached. Issues that you selected to fix are marked as fixed.
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 thefileversionattachedtotheissueyouwant toview. 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.
264 Using the Windows Explorer and Mac Finder integrations
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 264.
3. Click Attach to attach the files to the selected issues. The Attach to Issue dialog box opens. 4. Select theissues youwant tofix andclick 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.
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 9.
265 Using the Mac Finder plug-in
1. 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 or directory 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 Open Surround SCM. If a working directory is selected, the SCM branch and repository mapped to the directory is selected in Surround SCM.
Show Icon Display or hide Surround SCM status icons on directories and Integration icon Overlays files. overlays, page 265
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. n 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 9. n 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.
266 Integrating with CMIS
Action Use to: More information
Add Add the file or directory 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 Open Surround SCM. If a working directory is selected, the SCM branch and repository mapped to the directory is selected in Surround SCM.
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 427 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 (www.seapine.com/kb/questions/1637) 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.
267 Integrating with CMIS
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.
268 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 269 and Starting the Surround SCM Server, page 270. 2. Start the Surround SCM Client and log in. See Starting Surround SCM, page 4. 3. Create a mainline branch. You must create at least one mainline branch before users can add source files. See Creating mainline branches, page 367. 4. 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 271. 5. 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 280. 6. 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 287. 7. 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 409.
Starting the Seapine License Server The Seapine License Server must be running before the Surround SCM Server is started. n Windows—If you chose to run the license server as a service, it starts automatically. If you chose to run the license server as an application, you have to start it yourself. Choose Programs > Seapine Software > Seapine License Server > Seapine License Server from the Start menu. n Mac—Click Seapine License Server in the System Preferences. If you want to set the server to start automatically, click the lock button and select Start Seapine License Server when this computer starts up. n Linux—Enter /usr/bin/spls start
269 Starting the Surround SCM Server
Starting the Surround SCM Server n Windows—If you chose to run the Surround SCM Server as a service, it starts automatically. If you chose to run the server as an application, you have to start it yourself. Choose Programs > Seapine Software > Surround SCM > Surround SCM Server from the Start menu. n Mac—Click Surround SCM in the System Preferences. If you want to set the server to start automatically, click the lock button and select Start Surround SCM Server when this computer starts up. n Linux—Enter /usr/bin/surroundscm start
270 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: n What types of users need access to Surround SCM? For example, project leads, programmers, and testers. n What activities can users in the group perform? For example, access to promote and rebase files. n Which repositories can the users in the group access? For example, restrict teams to specific repositories. n 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 272 for additional information.
Security Description Type
Server 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 273.
Repository 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 277.
Branch 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 279.
271 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
272 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
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. Security group commands are accessed from the command buttons or the shortcut menu. This view includes group name, description, and security permissions information.
273 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 274. Server security commands are grouped in the following categories: n General—Common Surround SCM functions (e.g., Generate Reports, Edit Own Email Notifications) n Admin—Administrative commands (e.g., Edit Server Options, Void Check Out) n Users—User account management commands (e.g., Retrieve User, Delete User) n Groups—Security group management commands (e.g., Add Security Group) n Files—File management commands (e.g., Add File, Change File Type) n Branch—Branch management commands (e.g., Create Baseline Branch, Promote Branch) See Security Commands, page 435 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.
274 Adding security groups
1. Choose View > 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 273 for a list of commands in each category.
275 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 273. 5. 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 277. 6. 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 279.
276 Duplicating security groups
7. Click OK to save the changes.
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.1. 3. 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.
n The Group column displays the name of all security groups.
n The Inherited From column displays where security permissions are set.
n The Security column displays a summary of the group’s security.
277 Controlling access to specific repositories
3. Click Modify to change the security. The fields are enabled.
4. Make any changes to security settings.
n 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.
n To add a security group, click Add and select the group. You can select specific groups set different permissions for each group or select
n To remove a group, select it and click Remove. You can only remove a group if security is configured for
n To revert security overrides, select a group and click Inherit. The group inherits the default security permissions set for the server.
278 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
1. Select a branch and choose Activities > Properties. The Properties dialog box opens. 2. Click the Security tab.
3. Select a Branch Security option.
n Use security that applies to all branches uses the server-level security settings.
n 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.
n 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 280.
279 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 279. 1. 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 441. 7. 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.
280 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 283.
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 283.
1. Choose View > Users. The Users window opens. 2. Click Add. The Add User dialog box opens.
281 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 Use to:
Info Enter the user's phone numbers and email address and create a password. Users can change their passwords when they log in.
Groups 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 274 for information about creating security groups.
License Assign a license to the user. Users cannot log in if they are not assigned a license. See License types, page 282.
Address Enter the user's address.
Notes 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.
282 Retrieving global users
n 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. n 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.
283 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.
284 Voiding check out
Voiding check out Surround SCM users with admin-level security access can void check outs. This breaks the file lock and gives other users access to the file. 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 is populated with the user’s checked out files. 3. Select thefiles andclick Void Check Out. You are prompted to confirm that you want to void check outs. 4. Click Yes. The check out operation is voided.
285
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 368.
Options Use to: More information
General (Global Set the local admin password, specify how often to check Setting general Server) for new server stylesheets, enable automatic client global server upgrades, compress server files, and encrypt server options, page 288 communications.
Merge Switch from Diff3 to Guiffy for automatic file merges and Setting server configure Guiffy options. merge options, page 294
Server Database Change the server database location or convert it to a Setting the default different RDBMS type. server database location, page 380
RDBMS Connections Create and modify RDBMS connections to host mainline Adding RDBMS branches. connections, page 383
Caching Set dynamic branch caching options to control the size of Setting branch the server cache for improved performance and memory caching server availability. options, page 362
Logging Select the type of information to add to the server log and set Setting logging options to send email when the server log is updated. options, page 296
Email Servers Specify protocol and connection information used to email Setting email notifications from Surround SCM. server options, page 297
Email Notifications Specify the return address for email notifications and the Setting email server host name for file links included in emails. notification options, page 297
License Server Configure Seapine License Server connection information, Setting Seapine the license server communications password, and global License Server user cache refresh rate. options, page 298
287 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 301
Auto Update Check Specify how often to automatically check for software Setting automatic updates and receive email about product releases. software update check options, page 299
TestTrack Integration Enable TestTrack integration and edit or sync item field Enabling labels. TestTrack integration, page 397
Issue Tracking Activate plug-ins to integrate Surround SCM with a third- Activating third- Integration party issue tracking tool. party issue tracking plug-ins, page 295
Purge Scheduling Schedule when to purge destroyed data from the database. Scheduling data purges, page 301
General (Mainline) Set default check in, Unicode file, thumbnail size, and large Setting general file size options for all mainline branches. mainline options, page 302
Changelists Set default changelist usage for all mainline branches. Setting changelist server options, page 305
File Specify filenames or extensions to auto-detect or ignore Setting auto-detect Names/Extensions when adding files. and ignore file options, page 306
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. 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 290 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.
288 Setting general global server options
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 in the server database. 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.
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 (www.openssl.org). To check if OpenSSL version displayed in Surround SCM has vulnerabilities that impact Surround SCM, check Seapine's knowledgebase (www.seapine.com/kb) or contact Seapine Support for information.
289 Securing communication between clients and the Surround SCM Server
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 293 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 And you change it to: You need to: use:
No RSA key exchange Download a settings file that Surround SCM client users need encryption 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.
RSA key No encryption or basic Remove the public key fingerprint from any clients that connect exchange encryption (Encrypt server to the server. Click Remove in the server connection communication between information in clients and in the options for servers in the clients and the server is Surround SCM Registry Utility. selected)
See Configuring RSA key exchange, page 293 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. 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 288 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 2014.1 and later. RC4 encryption is used for backward compatibility with earlier Surround SCM and TestTrack versions.
290 Securing communication between clients and the Surround SCM Server
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 288.
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 Modifying web server startup options, page 423 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 How it works method
Seapine The username and mathematical proof that the user knows the password (not the actual License Server password) are sent to the Surround SCM Server. The server sends different mathematical proof that it knows the password to the client.
LDAP 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 Data from the organization's authentication system is sent to the Surround SCM Server. authentication
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.
291 Securing communication between clients and the Surround SCM Server
Key When it is How it works To use it: exchange used method
Secure User is A shared secret key is generated during authentication. Select Encrypt Remote authenticated To compromise the secret key or impersonate the communication Password from the server, a hacker must know the user's password. between clients (SRP) Seapine and the server License in the general Server and global server RSA key options. exchange is not enabled
Diffie- User is A mathematical process is used to generate a secret Select Encrypt Hellman authenticated key. To compromise the secret key, a hacker must have communication using LDAP or control over an intermediate network node or between clients external impersonate the real server. Does not protect against and the server authentication, man-in-the-middle attacks. in the general and RSA key global server exchange is options. not enabled
RSA RSA key The client generates a random, 256-bit secret key and Select Encrypt exchange is encrypts it with the server's public key. The server communication enabled in the hashes the secret key and signs the hash with its private between clients Security key. The private key is only stored on the server hard and the server server options drive and never leaves the server. To compromise the and Use RSA secret key or impersonate the server, a hacker must key exchange in know the server's private key or substitute their own the general public key in client applications. 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: n Your organization stores sensitive information in Surround SCM. n Your network is potentially insecure. n Users log in to client applications from outside your network. n 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 293.
292 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.
n 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.
n 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.
n 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 Modifying web server startup options, page 423.
n 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 Modifying proxy server startup options, page 415.
293 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.
294 Activating third-party issue tracking plug-ins
5. Select Ignore case to ignore the case of characters within lines. 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 7-8. 10. 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 262. 1. 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.
295 Setting logging options
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. 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 262.
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 email notification option to indicate the types of server messages that generate email notifications. Select No Logging if you do not want to generate email notifications. 6. Select Send email notification when logins fail to email a specific user when a login attempt fails. 7. Enter the Email send to address and Email 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.
296 Setting email server options
Setting email server options You can select the mail protocol used with email sent from Surround SCM. 1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Email Servers from the Global Server Options category.
3. Select Enable sending mail via Simple Mail Transport Protocol to send email via SMTP.
n Enter the SMTP Host used to send outgoing mail. Enter an IP address (e.g., 123.34.5.26) or the fully qualified domain name of the mail server (e.g., mail.yourcompany.com).
n Select the SSL security protocol to use to encrypt communication between the mail server and the Surround SCM Server. You can use the SSL 3.0, TLS 1.0, Negotiate, or STARTTLS 1.0 protocols. Select
n Enter the Port number used by the SMTP host. The default SMTP port number is 25 if no security protocol is set and 465 for all other protocols.
n Enter the Username and Password.
n Click Test Connection to test the SMTP connection. 4. Select Pause sending via SMTP only if you are experiencing mail problems and want to troubleshoot the cause. Email is not sent if this option is enabled. 5. Select Only send one message per SMTP connection to send one message per connection. 6. Click OK to save the changes.
Setting email notification options You can set the return address and options used for email notifications. 1. Choose Tools > Administration > Server Options.
297 Setting Seapine License Server options
The Server Options dialog box opens. 2. Select Email Notifications from the Global Server Options category.
3. Enter a notification Account name. 4. Enter a notification account Email address. 5. Select Always use the notification email account for the return address to use the notification email account. 6. Select Only use notification account if the logged in user’s email address is blank to use the notification email account if the logged in user did not provide an email address. 7. Enter a Server host name for file email links to set the network address to use with file hyperlinks sent in email 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.
298 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. n 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. n Surround SCM version—The Surround SCM version installed on the Surround SCM Server. n Operating system and version—The operating system and version of the Surround SCM Server computer. n Configuration settings—Specifies if the following settings are configured: multiple mainlines, inactive branches, caching of branches, triggers, changelists, product update emails, comments required, SMTP, custom fields, workflows, shadow folders, TestTrack integration, reports, and filters.
299 Setting automatic software update check options
n 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. n Server type—Specifies if the Surround SCM Server is a 32-bit or 64-bit server. n Number of mainlines per RDBMS database type—The number of mainline branches in each RDBMS database type. n 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.
n Enter how often Surround SCM should check for updates.
n Select Send email notification for product updates to be notified when product updates are available. The notification email 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.
n Select Send email notification for upcoming beta releases to be notified about beta programs.
n Enter your email information if you enabled either notification option. 5. Click OK to save the changes.
300 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.
301 Setting general mainline options
3. Select a purge scheduling option.
n 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.
n Schedule purge to run purges data on the specified day and time each week.
n 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
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 368.
1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select General from the Mainline Options category.
302 Setting general mainline options
3. 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 software configuration management tool that supports checking in files without check out and prefer this method for working with files.
Note: We do not recommend selecting this option because it provides less control over files.
4. 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. 5. 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 304.
Note: Binary files are always exclusively checked out.
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. Enter the Minimum comment length for actions to require users to enter comments for all actions with comment fields, such as check in or rebase.
303 Supported keywords
This setting does not apply to check outs or workflow state changes. 8. Enter the Minimum comment length for state changes to require users to enter comments for workflow state changes. 9. Select any Unicode File Options. Unicode file options are used when auto-merging text files.
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.
n 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.
n 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.
n Select a UTF-8 character encoding set.
n Select a UTF-16 character encoding set. 10. 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.
11. Enter or select the maximum file size for adding or checking in Large Files.
n Maximum file size specifies the maximum file size limit. The default value is 2000 MB.
n 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. 12. 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.
304 Setting changelist server options
Keyword Value
$Archive$ Repository path and filename
$Author$ User who checked in last file revision
$Branch$ Branch name
$Date$ Date and time of last check in
$File$ Unqualified filename
$Header$ File, Revision, Author, Date
$JustDate$ Date of last check in
$Log$ Dates and times the modified file was checked in
$Logfile$ Repository path and filename
$Modtime$ Date and time of last modification (same value as timestamp column)
$NoKeywords$ Disables expansion of keywords that follow it
$Revision$ Revision number (branch relative)
$Workfile$ Unqualified filename
Setting changelist server options Changelists are used to group file transactions together. See Using Changelists, page 123.
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 368.
1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Changelists from the Mainline Options category.
305 Setting auto-detect and ignore file options
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.
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.
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 368.
1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select File Names/Extensions from the Mainline Options category.
306 Setting auto-detect and ignore file options
3. Select afiletypeandclick 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. 7. Enter the file or directory names you want Surround SCM to ignore in the Ignore file or directory name field.
307 Configuring default user options
Note: 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.
308 Configuring default user options
Category Use to: More information
General Enable external authentication, compress file transfers, specify text Setting general file format, set the file comparison option used when updating and user options, retrieving files, and view HTML reports. The client-level general user page 9 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
Diff/Merge Specify applications used to diff and merge files, add new diff Configuring diff applications, and configure Guiffy, the integrated diff/merge application application. options, page 49 and Configuring merge application options, page 50
View/Edit Specify applications used to view and edit files from Surround SCM. Setting File viewer/editor options, page 17
File Dialog Enable or disable changelists, merge and differences, local directory Changing Defaults creation, and code review settings for file action dialog boxes. defaults for Surround SCM dialogs, page 97
Source Control information displayed in the Source Tree window and the Setting Source Tree default items to include in the branch, repository, and file list shortcut Tree options, menus. page 92
Proxy Set the default proxy server and compress file transfers from proxy Setting proxy Server servers. server options, page 414
File Specify the Linux file manager used to open working directories.. Setting the file Manager manager on (Linux Linux, page 14 only)
Plug-ins Specify the directories used to load custom plug-ins. Setting plug-in directories, page 261
3. 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.
309 Configuring default user options
The default user options are set in clients when they connect to the server for the first time.
310 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: n Create a Do Not Modify check box field to indicate files that should not be changed. n 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 315. n Create a Release custom field to track the release a change is assigned to.
Note: See Setting custom fields, page 32 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 273.
1. 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 312. 3. Select afieldandclick Edit toedit it. See Editing custom fields, page 313. 4. Select afieldandclick Top, Move Up, Move Down, or Bottom to change the display order in lists, menus, and dialog boxes. 5. Select afieldandclick Delete to delete it. See Deleting custom fields, page 313. 6. 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 313.
311 Adding custom fields
Adding custom fields 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 315. 5. Select a Field Format.
n Text—Users can enter free-form, alphanumeric text.
n Integer—Users can enter a numeric value without decimals.
n Float—Users can enter a numeric value with decimals or signs, such as + or -.
n List—Users can select a value from a list of multiple custom values.
n SCM User—Users can select a user from a list of all users on the Surround SCM Server.
n Date/Time—Users can enter a date/time stamp in the following format: mmddyyyy hh:mm:ss.
n 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 75 and Customizing the Source Tree window, page 91.
312 Editing custom fields
Editing custom fields 1. Choose Tools > Administration > Custom Fields. The Custom Fields dialog box opens. 2. Select acustom fieldandclick Edit. The Edit Custom Field dialog box opens. 3. Make any changes. You cannot change the field format. Create a new custom field if you need to change the format. 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 acustom fieldandclick 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.
313
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 email 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 emails, 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: n File is created, enters a specific workflow state, version is updated, or changes for any reason n Code review file changes for any reason n Code review changes to a specific status, is awaiting review (runs nightly), or changes for any reason n Event is performed on a file, code review, or code review file n Changelist is committed n 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: n Run server-side executables (scripts and compiled programs) n Prevent users from performing file events n 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: n Run server-side executables (scripts and compiled programs) n Send emails n Change custom field values n Change workflow states
315 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. n 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 email notification to the reviewer. n 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". n 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. n 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 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.
Note: If a trigger includes more than one instance of an action, the number of instances is displayed next to the action. For example, Email (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.
316 Adding triggers
3. Click Add to create a trigger. See Adding triggers, page 317. 4. Select a trigger and click Edit to change it. See Editing triggers, page 326. 5. Select a trigger and click Duplicate to duplicate it. See Duplicating triggers, page 328. 6. Select a trigger and click Disable to disable it. See Disabling and enabling triggers, page 328.
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 328.
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: n The event or activity that causes the trigger to fire n The criteria (preconditions) the trigger will use to select the files that initiate the action n The action the trigger performs 1. Choose Tools > Administration > Triggers. The Triggers dialog box opens. 2. Click Add. The Add Trigger dialog box opens.
3. Enter a Trigger Name.
317 Adding triggers
4. On the Trigger When tab, select the events that cause the trigger to run.
n 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.
n 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.
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.
318 Adding triggers
Note: The in branch [
7. Enter or select the precondition values. Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding restrictions, page 207. 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.
n Click Add to add an action. See Adding trigger actions, page 327.
n Select an action and click Edit to change it. See Editing trigger actions, page 327.
n Select an action and click Top, Move Up, Move Down, or Bottom to change the action order.
n Select an action and click Delete to delete it. See Deleting trigger actions, page 327.
11. Select Disable trigger after it runs once if you only want the trigger to run once. 12. Click OK to add the trigger.
319 Adding triggers to run executables
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. n 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. n 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. 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: n 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. n From a Windows/DOS batch file set the ERRORLEVEL value. In Windows 2000/XP batch scripts the command “exit /B #” can be used. n From a Windows application, you can use the CWinApp::ExitInstance( ) function. 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 317. 4. 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.
320 Adding triggers to prevent events
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. 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 317. 4. 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.
321 Adding triggers to append comments to events
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 317. 4. 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.
n Set replaces any user comments with the text you enter in the Comment field.
n Append adds the Comment field text to any comments the user enters. 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 email users You can add a trigger action to send an email. For example, you can email 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.
322 Editing email templates
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page 317. 4. Click the Actions tab and click Add to add an action. 5. Select Send an email to from the Action list.
6. Select the users to send the email to. The available options depend on the selected trigger event.
n Send to current user emails the user who created the trigger.
n Send to the following users emails the selected users.
n Send to last user to perform event emails the user who last performed the selected event.
n Send to code review authors emails all authors in the code review.
n Send to code review reviewers emails all reviewers in the code review or only reviewers with incomplete file reviews.
n Send to user defined by custom fields emails the specified user in the selected custom field.
n Send to these email addresses sends an email to the specified email addresses. Separate multiple addresses with a semicolon. 7. Click Edit Email Template to modify the default template. See Editing email templates, page 323. 8. Select Consolidate multiple file events into one email to send one email for all files the trigger runs on. An email 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 email templates Each trigger that sends email and each user notification has an email template that you can customize to provide information specific to the event that triggers the email.
323 Editing email templates
You can use text and field codes to build customized emails that provide information specific to the event that triggered the email. Field codes, which are enclosed in percent symbols, are automatically replaced with the corresponding Surround SCM data when an email is sent. See Environment Variables, page 447. 1. Click Edit Email Template when you are adding or editing a trigger or notification. See Adding trigger actions, page 327 and Adding email notifications, page 85. The Edit Email Template dialog box opens with the Email Template tab selected.
2. Optionally customize the email Subject. You can use text and field codes. 3. Optionally customize the email 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 email 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 email server options, page 297.
4. Select a Recipient option. 5. Select Send email in HTML format to send HTML-formatted email. 6. 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 Email Template tab when the email is sent.
324 Adding triggers to set workflow states
7. Click OK. The template is saved with the selected trigger or notification.
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 317. 4. 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
325 Adding triggers to set custom field values
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. 3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers, page 317. 4. 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 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.
326 Adding trigger actions
Adding trigger actions You can add multiple actions to a trigger. For example, a trigger can set a workflow state and send an email notification. 1. Click Add on the Actions tab in the Add Trigger or Edit Trigger dialog box. The Add Trigger Action dialog box opens.
2. Select an Action. You can add the following actions for triggers that run before an event occurs:
n Running executables from triggers
n Prevent an event
n Set or append event comment text You can add the following actions for triggers that run after an event occurs:
n Run an executable
n Send an email
n Set a custom field value
n 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 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 and click OK.
Deleting trigger actions 1. Select an action on the Actions tab in the Add Trigger or Edit Trigger dialog box.
327 Duplicating triggers
2. Click Delete. The action is deleted.
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 328.
1. 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.
328 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 email 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 325 and Changing workflow states, page 34. 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 342.
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.
329 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 email notification to Marcy Morris, the development team lead, which indicates that the file is ready for code review. After Marcy reviews the email, 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 email notification to Rachel to inform her about the assignment. After Rachel receives the email, 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 email notification to Marcy to inform her that the file requires additional changes. Marcy reviews Rachel’s comments in the email 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.
330 About the default workflow template
Marcy clicks OK. A trigger sends an email notification to Joe to inform him about the assignment. Joe receives the email. 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 email notification to Marcy to inform her that the file is ready for review. After Marcy reviews the email, she assigns the file to Rachel to perform another code review. A trigger sends an email notification to Rachel to inform her about the assignment. Rachel receives the email. 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
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:
331 Customizing workflows
State Destination states
Work in Progress
Needs Attention
AwaitingReview
Reviewed
AwaitingRelease
Released
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:
332 Planning your workflow
n Planning your workflow, page 333 n Configuring workflow states, page 333 n Configuring workflow templates, page 336 n Automating workflows, page 333 n Setting workflows for specific repositories, page 342
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 email notification to a team member. See Automating Actions with Triggers, page 315. 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 email notification to the assigned user. See Configuring Custom Fields, page 311.
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 336. 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected.
333 Adding workflow states
2. Click Add to create a new state. See Adding workflow states, page 334. 3. Select astateandclick Edit to change it. See Editing workflow states, page 335. 4. Select astateandclick Delete to delete it. See Deleting workflow states, page 335.
Note: Select Show deleted states to display deleted states. Deleted states can be restored. See Restoring deleted workflow states, page 335.
Adding workflow states Surround SCM includes the following default states:
3. Enter a State name and State description. Make sure you use a descriptive name that users understand. 4. Click OK.
334 Editing workflow states
The state is added.
Tip: You can also add states when you create workflow templates. See Adding states to workflow templates, page 338.
Editing workflow states 1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Select astateandclick 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 339.
4. 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 335.
1. Choose Tools > Administration > Workflow. The Workflow dialog box opens with the States tab selected. 2. Select astateandclick 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.
335 Configuring workflow templates
The state is restored.
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 331. 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 email when a file moves to the Awaiting Review state will email 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 336. 4. Select a template and click Edit to change it. See Editing workflow templates, page 339. 5. Select a template and click Duplicate to duplicate it. See Duplicating workflow templates, page 340. 6. 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 340.
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.
336 Adding workflow templates
2. Click the Workflow tab. 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 338. 6. Select astateandclick Edit to change it. See Editing workflow states, page 335. 7. Select astateandclick Top, Move Up, Move Down, or Bottom to change the display order. 8. Select astateandclick Remove to remove it. See Removing states from workflow templates, page 338. 9. 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 340. 12. 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.
337 Adding states to workflow templates
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. The Add State dialog box opens.
2. Select a state option.
n 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.
n 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 astateandclick Remove.
338 Editing workflow transitions
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 335. 5. 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. 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
3. Click Print to print the workflow transitions. 4. Click OK to save the changes.
Editing workflow templates 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.
339 Duplicating workflow templates
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 335. 5. 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.
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 339. 6. 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.
340 Setting the default 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.
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 34.
341 Setting workflows for specific repositories
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.
n Select No workflow if you do not want use a workflow for the repository.
n 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.
n 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 34.
342 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 59. 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.
n Enabled allows users to choose to add files to reviews.
n Disabled prevents users from adding files to reviews.
n Required requires users to add files to reviews. 5. Click OK to save the changes.
343
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. n 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. n Next, a new empty directory named wwwroot is created in the C:\Inetpub directory. A shadow folder is created for wwwroot. n 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.
2. Click Add to create a shadow folder. See Adding shadow folders, page 345. 3. Select a folder and click Edit to change it. See Editing shadow folders, page 347. 4. Select a folder and click Force Update to update it. See Refreshing shadow folder contents, page 347. 5. Select a folder and click Delete to delete it. See Deleting shadow folders, page 347.
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. 1. Choose Tools > Administration > Shadow Folders.
345 Adding 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.
n Current sets the timestamp to the current (time of retrieval) date and time.
n Modified sets the timestamp to the date and time that the files were last modified.
n 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.
346 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.
347
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. n Manage attributes of all branches n Update attributes for specific branches, such as hide/unhide, freeze/unfreeze, and inactivate/activate n Rename branches n Control access to branches and set security options for branches n Change branch types n Update templates to specify the repositories included and excluded in branches n Index branches for optimized searching n Set caching options for all branches and change cache settings for individual branches n Remove branches n Restore removed branches n 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.
349 Managing branch attributes
2. On the General tab, select a Display Mode.
n Tree view displays branches in a tree structure as they are displayed in the Branches tree.
n List view displays branches in a list. Click a column header to sort branches in the list view. 3. Select additional display options.
n Show hidden branches displays branches that are currently hidden.
n Show inactive branches displays branches that are currently inactive.
n Show removed branches displays removed branches.
n Show all private branches displays all workspace branches.
n 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 Freeze or unfreeze the branch. Users can see frozen branches but cannot Freezing and Frozen perform any activities that change files, such as checking files out or in. unfreezing branches, page 358
350 Managing branch attributes
Button Use to: More information
Toggle Make the branch active or inactive. Users cannot see or perform any Inactivating Active actions on inactive branches. and activating branches, page 359
Toggle Change the branch caching mode. By default, all file and repository Changing Caching information for a branch is cached when the Surround SCM Server starts. branch If you have a large number of branches, it can take a while for the server to caching, cache all information at startup. You can use on demand caching to cache page 361 information only when a user selects a branch.
Toggle Hide or unhide the branch. Users cannot see hidden branches, but they Hiding and Hidden can still perform actions on them if they choose to view hidden files. unhiding branches, page 358
Change Change the branch type or owner. Changing Type branch type, page 361
Edit Modify the template used to specify the repositories included in the branch. Modifying Template You can also remove the template from the branch. templates for existing branches, page 359
Remove Remove the branch. Removed branches are not deleted from the hard Removing drive and can be restored if needed. branches, page 364
Destroy Permanently delete a removed branch. Destroyed branches are deleted Deleting from the hard drive and cannot be restored. branches permanently, page 365
Restore Restore a removed branch. Restoring removed branches, page 365
5. Click Save As tosavethelist orclick 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 352. 7. Click Close when you finish.
351 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.
Differences between indexed and non-indexed searches Following are differences in searching for text in indexed versus non-indexed branches. n Searching indexed branches returns more accurate results more quickly. Searching non-indexed branches looks for text in every file line-by-line, which takes longer. n Binary files, such as Microsoft Word (.doc, .docx), Microsoft Excel (.xls, .xlsx), Adobe PDF (.pdf), Open Document Format (.odf), and Rich Text Format (.rtf) files, are parsed in indexed branches and included in search results. Searching non-indexed branches only includes text files. n Results for searches in indexed branches include a relevance value to indicate how closely the results match the search criteria. The Relevance column is not displayed in search results for non-indexed branches. n Common words such as 'the' and 'a' are not indexed. If only these words are used when searching an indexed branch, no results are returned. When searching non-indexed branches, these words can be used as the entire search phrase. For example, searching for 'the' does not return results from an indexed branch, but it can return results from a non-indexed branch. Searching for 'the executable' may return results from indexed and non-indexed branches.
Common administrative tasks for branch indexing The Surround SCM administrator can perform the following actions to manage branch indexes. n Turn indexing on or off for branches. See Turning branch indexing on or off, page 353. n Start the indexing server if it is not running to enable indexed searching. See Managing the indexing server, page 352. n View indexing status and information. See Viewing branch index details, page 354. n View the indexing server log to troubleshoot issues with corrupted indexes. See Viewing the indexing server log, page 355. n Modify the indexing server startup options. See Modifying indexing server startup options, page 356.
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.
352 Turning branch indexing on or off
3. Click Start to start the indexing server if it is not running. 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 353. 4. 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 Modifying indexing server startup options, page 356.
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 355. 7. 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 Modifying indexing server startup options, page 356.
1. Choose Tools > Administration > Branch Maintenance. The Branch Maintenance dialog box opens. 2. Click the Indexing tab. All mainline and baseline branches are displayed.
353 Viewing branch index details
3. Select a Display Mode.
n Tree view displays branches in a tree structure as they are displayed in the Branches tree.
n 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.
n 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.
n 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.
354 Viewing the indexing server log
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.
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 353. 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 355.
4. 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.
355 Modifying indexing server startup options
4. Review the log information. 5. Click Close when you finish.
Modifying indexing server startup options If you do not want the indexing server to start automatically, you can modify the startup information in the registry utility. You can also change the indexing server port, directories where indexed content and the indexing server log are stored, and other options. 1. Start the Surround SCM Registry Utility. See Starting the Surround SCM Registry Utility, page 419. 2. Click Indexing Options. You can also choose Edit > Indexing Options. The Surround SCM Indexing Server Options dialog box opens.
3. Make any changes to the server information.
356 Renaming branches
Field Description
Indexing Port number the indexing server uses to communicate with Surround SCM. The server port default port is 4902.
Start indexing Automatically starts the indexing server when the Surround SCM Server starts. Clear server this option if you do not want the indexing server to start automatically. If you clear when Surround this option, you must manually start the indexing server to make existing branch SCM Server indexes available for searching and index new branches. See Managing the indexing starts server, page 352.
Index storage Directory where indexed content is stored. The default directory is the directory IndexingServer/Storage directory in the Surround SCM application directory. Click to select a different directory.
Log directory Directory where the indexing server log file is stored. The default directory is the IndexingServer directory in the Surround SCM application directory. Click to select a different directory.
Java runtime Directory where the Java Runtime Environment (JRE) used by the indexing server is path located. This path is automatically set during installation. Click to select a different directory.
Java Parameters that specify if the JRE runs as a server or service and the minimum and parameters maximum heap size. The default parameters set the JRE to run as a server, the minimum heap size to 128 MB, and the maximum heap size to 1024 MB.
4. Click Validate Options to validate the information. If validation fails, check the following:
n Make sure the Java runtime path is correct.
n Make sure the index storage and log directories are correct and that they exist. 5. Click OK to save the changes.
Note: You must restart the indexing server for the changes to take effect. See Managing the indexing server, page 352.
Renaming branches
Note: To rename mainline branches, see Renaming mainline branches, page 368.
1. Select the branch and choose Branch > Rename Branch. The Rename Branch dialog box opens.
357 Hiding and unhiding branches
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. 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.
358 Inactivating and activating branches
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 358. 1. 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. 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.
359 Modifying templates for existing branches
3. Select a Template option.
n 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.
n 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.
n To exclude a subrepository from the branch, select it and click Exclude. To include an excluded subrepository, select it and click Include.
n 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.
n 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
360 Changing branch type
manually rebase it later to update it. See Rebasing branches, page 187.
n 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.
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:
361 Setting branch caching server options
n Always—Branches are cached when the Surround SCM Server starts. Mainline branches are always cached when the server starts and cannot be changed. n 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 362.
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. 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 361.
1. Choose Tools > Administration > Server Options. The Server Options dialog box opens. 2. Select Caching from the Global Server Options category.
362 Breaking shares across branches
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. 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.
Breaking shares across branches In Surround SCM’s branching schema, breaking a file share only affects the file at the branch level. The file remains shared in other branches until the break is promoted or rebased. Breaking a shared link across all branches allows you to maintain files independently. All historical information is duplicated in the shared repository when the share is broken.
Tip: This command is provided for users who track releases with labels instead of using Surround SCM’s branching capabilities.
1. Select the file you want to break the internal share for. This command affects all branches including snapshot, workspace, and removed branches. 2. Choose Tools > Administration > Break Share All Branches. The Break Share All Branches dialog box opens.
363 Removing branches
3. Enter any Comments, such as the reason for breaking the shares. 4. Click OK. The internal share is broken.
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 365. 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 353.
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 349.
1. 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.
364 Restoring removed branches
Tip: You can view removed branches in the Branch Maintenance dialog box. See Managing branch attributes, page 349.
Restoring removed branches You can restore removed branches to give users access to them again.
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 353.
1. 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 364.
1. 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.
365
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 383 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.
367 Renaming mainline branches
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.
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 357.
1. 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, 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 287. 1. Select the mainline branch and choose Branch > Branch Properties.
368 Overriding server options for specific mainline branches
The Properties dialog box opens. 2. Click the Options tab.
3. Select a category.
n General—Includes options for allowing checking in without check out, allowing multiple users to check out files, expanding keywords, allowing workflow state changes during check in, setting minimum comment lengths, Unicode options for merging text files, enabling thumbnails, and setting the maximum file size for large files. See Setting general mainline options, page 302.
n Changelists—Includes options for changelist usage and retaining historical changelist information. See Setting changelist server options, page 305.
n Files Names/Extensions—Includes options to set file type extensions and names to automatically detect and ignore when adding files. See Setting auto-detect and ignore file options, page 306. 4. 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.
369 Moving repositories to different mainline branches
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: n Repository history, workflow, code review settings, issue tracking integration, and removed items. n File history, workflow states, custom field values, issue tracking attachment details, and share information. Keep the following in mind: n 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, email notifications, filters, triggers, and reports is not exported. n 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. n You cannot export repositories from mainlines with case-sensitive filenames enabled to existing mainlines that do not allow case-sensitive filenames. n 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 279 and Overriding server options for specific mainline branches, page 368. 1. Choose Tools > Administration > Export Repository to Mainline. The Export Repository to Mainline dialog box opens.
370 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.
n 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 383 if you need to add an RDBMS connection.
n 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 114.
Tip: Remember to inform users about new repository location.
371 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 380. 2. 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 377.
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 359. 2. Convert the mainline branch to copy it to the other database. See Copying mainline branches to different databases, page 373. 3. Activate the mainline branch. See Inactivating and activating branches, page 359. 4. Optionally destroy the mainline branch from the original RDBMS database. See Deleting mainline branches permanently, page 377. 5. 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. To copy a mainline branch to a different Surround SCM Server:
372 Copying mainline branches to different databases
1. Inactivate the mainline branch you want to move. See Inactivating and activating branches, page 359. 2. Convert the mainline branch to move it to the different RDBMS database. See Copying mainline branches to different databases, page 373. 3. Remove the mainline branch from the current server. See Removing mainline branches, page 374. 4. Log in to the destination server. 5. Add the mainline branch to the destination server. See Restoring removed branches, page 365. 6. 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 377.
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 359.
1. 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 383 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.
4. Click OK.
373 Removing mainline branches
The conversion information is sent to the Surround SCM Server for validation.
n If the validation succeeds, you are prompted to start the conversion.
n If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an email or text file and email 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 379.
6. Click Close when the conversion finishes.
Note: You must activate the mainline branch before users can access it. See Inactivating and activating branches, page 359.
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.
374 Restoring RDBMS mainline branches
2. Select the Mainline Type.
n RDBMS allows you to restore a mainline stored in an RDBMS database. See Restoring RDBMS mainline branches, page 375.
n 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 376. 3. 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 376.
1. Choose Tools > Administration > Add Existing Mainline Branch. The Add Existing Mainline Branch dialog box opens. 2. Select RDBMS as the Mainline Type.
375 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 375.
1. 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.
376 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 401.
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 374.
1. 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.
377
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 386.
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 380, Copying mainline branches to different databases, page 373, and Upgrading mainline branches, page 401. 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.
379 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 382. 4. Click Convert to convert the database to a different type. See Converting the server database to a different type, page 380. 5. 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: n All users must be logged out of the Surround SCM Server. n The destination database cannot be in use by another server. n 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 379.
1. 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.
380 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 email 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.
n If the validation is successful, you are prompted to start the conversion. Remember that users cannot log in during the conversion process.
n 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.
381 Changing the server database location
Note: You can also manually change the database the Surround SCM Server is using. See Changing the server database location, page 382.
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 email 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:
382 Adding RDBMS connections
n The specified connection information connects to a valid RDBMS.
n A Surround SCM Server application is not already configured for the selected server database.
n 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.
n 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 379. 11. 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.
383 Adding RDBMS connections
4. Select a Connection Type. The fields displayed depend on the selected connection type. 5. Optionally enter the PostgreSQL Connection Information.
n Enter a Database Name to connect to.
n Enter the Host Name.
n Enter the Port number.
n Enter the database Username and Password.
n Enter the Minimum number of connections to specify the smallest number of connections that will be stored 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 will not need to create a database connection later. If you increase this number, you may need to purchase additional licenses from the database vendor.
n The Maximum number of connections specifies the largest number of connections that will be allowed in the database connection pool. The default number of connections is 999. You should only change this number if you have a large number of mainlines and are using too many backend database connections. 6. Optionally enter the ODBC Connection Information.
n Enter a Data Source Name. Only ODBC System Data Source Name types are supported.
n Enter the connection Username and Password. If you are using Windows NT authentication, the username and password of the user who logged in to the computer running the Surround SCM Server application is used automatically.
n Enter the Minimum number of connections to specify the smallest number of connections that will be stored 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 will not need to create a database connection later. If you increase this number, you may need to purchase additional licenses from the database vendor.
384 Editing RDBMS connections
n The Maximum number of connections specifies the largest number of connections that will be allowed in the database connection pool. The default number of connections is 999. You should only change this number if you have a large number of mainlines and are running out of backend database connections. 7. Optionally enter the Oracle Connection Information.
n Enter the Service Name to indicate the database instance to connect to.
n Enter the Host Name.
n Enter the Port number.
n Enter the database Username and Password.
n Enter the Minimum number of connections to specify the smallest number of connections that will be stored 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 will not need to create a database connection later. If you increase this number, you may need to purchase additional licenses from the database vendor.
n The Maximum number of connections specifies the largest number of connections that will be allowed in the database connection pool. The default number of connections is 999. You should only change this number if you have a large number of mainlines and are using too many backend database connections. 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 email 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.
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 359.
1. 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.
385 Deleting RDBMS connections
Note: The RDBMS connection for the Surround SCM Server database is displayed, but you cannot edit it. See Changing the server database location, page 382 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 359.
1. 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 (www.seapine.com/kb/questions/1528) 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.
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.
386 Resolving database issues
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. n 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 389. n 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 Guide for information. n 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. The Analyze Database dialog box opens. 2. Click Options. The Analyze and Repair Options dialog box opens.
387 Setting database analyze and repair options
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 391 for information about the repair actions performed when these issues are found.
Option Checks for:
Check for share Shares that were not removed when a repository was removed, files still marked corruption as base share files after shares were removed, and invalid shares of share links.
Check for Duplicate filenames in the same repository. duplicate filename conflicts
Check for Files checked out by deleted users. orphaned check outs
Check for Undestroyed child repositories with destroyed parent repositories or undestroyed undestroyed repositories in destroyed branches. repositories
Check for Files with inconsistent current version numbers. inconsistent current versions
388 Analyzing and repairing databases
Option Checks for:
Check for invalid Files with invalid tip version numbers. tip versions
Check for Merge event records that were not destroyed when the associated file was undestroyed destroyed. merge events
Check if PostgreSQL vacuum needed to remove dead table rows to free up database VACUUM is space and improve performance. PostgreSQL only. needed
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.
389 Analyzing and repairing databases
2. Select the RDBMS connection to analyze or select
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 391 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.
390 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 Repair
Files marked as shared when they are not Clears the share marker
Shared files found in removed repositories Removes the shares
Invalid shares (share links also marked as Removes the invalid shares share bases)
Duplicate filenames in the same repository Renames the newer file by appending '~#' to the filename (e.g., ReadMe~2.txt)
Orphaned check outs (files checked out by Removes the check outs deleted users)
Undestroyed child repositories with destroyed Destroys the child repositories parent repositories
Undestroyed repositories in destroyed Removes the repositories in incompletely destroyed branches branches
Undestroyed merge events Removes the merge events
Inconsistent current version numbers Resets current versions to correct number
Invalid tip version numbers Removes invalid tip versions and sets the previous version number on the file
Vacuum needed (PostgreSQL only) Vacuums tables requiring it
391
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 394. Select one of the following options to further narrow the log entries displayed:
n and More Severe includes the filtered log entries plus more severe entries.
n and Less Severe includes the filtered log entries plus less severe entries.
n 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:
n All saves the entire log.
n Current Page saves the current page of log entries.
n Pages saves entries in the specified page range.
n The following date range saves entries created during the specific date range.
393 Server log levels
5. Click Print to print log entries. The Server Log Print Options dialog box opens. Select a Print option and click OK. The following formats are available:
n All to prints the entire log.
n Current Page prints only the current page of log entries.
n Pages prints entries in the specified page range.
n 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 Description
Severe Error An event is written to the log when a severe problem or critical condition occurs, such as a server failure.
Error An event is written to the log when an error condition occurs, such as when a connection attempt to a client fails.
Warning An event is written to the log when a warning condition occurs, such as a server communication failure.
Unusual An event is written to the log when unusual activity occurs, such as a user trying to log in Activity with an incorrect username.
Information 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.
394 Managing Mail
When Surround SCM sends email, 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 emails. Email is generally sent and removed from the mail queue in less than 60 seconds. An email 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 emails. The list includes the email date, the date of the last attempt to send the email, the status of the email, and the email subject.
2. Select an email to view details. The name, email address, and mail type are displayed in the Recipients area. The send error is displayed in the Errors area.
Resending mail 1. Choose Tools > Administration > Mail Queue. The Mail Queue dialog box opens. 2. Select the email you want to resend and click Reattempt. Surround SCM tries to resend the email.
Deleting mail 1. Choose Tools > Administration > Mail Queue. The Mail Queue dialog box opens. 2. Select the emails you want to delete. 3. Click Delete.
395 Deleting mail
The email is deleted from the mail queue.
396 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 397. 6. 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.
397 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.
398 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.
399
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. n Mainline branches created in Surround SCM 2008 or earlier need to be upgraded to RDBMS format. See Upgrading non-RDBMS mainline branches, page 402. n 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 401. Keep the following in mind: n 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. n 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. n 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. n After mainline branches are upgraded, you must manually upgrade labels created in Surround SCM 2008 or earlier. See Upgrading legacy labels, page 406.
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'.
401 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.
n If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens.
n If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an email or text file and email 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'.
402 Upgrading non-RDBMS mainline branches
1. Select the mainline branch you want to upgrade and choose Tools > Administration > Upgrade Mainline Branch. 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 383. 4. 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.
n If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens.
n If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the text into an email or text file and email 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 379.
6. 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.
403 Resolving custom field and workflow issues
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.
2. Resolve custom field issues on the Custom Fields tab.
n Select a custom field and click Add to Server to add it to the Surround SCM Server.
n Select a custom field and click Delete to delete it. 3. Click the States tab to resolve any workflow state issues.
n Select a state and click Add to Server to add it to the Surround SCM Server.
n Select a state and click Delete to delete it.
4. Click the Workflow tab to resolve any workflow template issues.
404 Upgrading RDBMS connections
n Select a template and click Add to Server to add it to the Surround SCM Server.
n Select a template and click Delete to delete it.
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.
n If the validation succeeds, the upgrade starts and the Upgrade Status dialog box opens.
n If the validation fails, the Test Connection dialog box opens with error information. You can copy and paste the error message into an email 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.
405 Upgrading legacy labels
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. 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.
406 Deleting legacy labels
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.
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 407.
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.
407
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 thecache. If thefileis inthecache, theproxy serverreturns it totheclient. If thefileis not inthecache, it is retrieved from the master server, added to the proxy server cache, and returned to the client. n 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 411. n Each Surround SCM Server can support multiple proxy servers. Each proxy server can only use one master Surround SCM Server. n Performance improvements are noticeable only after files are cached. The first time files are retrieved, they are returned by the Surround SCM Server. n You can specify the default users for each proxy server. n If the proxy server is not available, Surround SCM clients retrieve files directly from the master server. n 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.
409 Configuring proxy servers
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. n Master Surround SCM Server proxy settings are configured using a Surround SCM Client. See Configuring proxy servers, page 410. n Proxy server computer options can be modified with the registry utility. See Modifying proxy server startup options, page 415.
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.
410 Adding proxy servers
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 Modifying proxy server startup options, page 415.
1. Choose Tools > Administration > Proxy Maintenance. The Proxy Server Maintenance dialog box opens.
2. Select a proxy server to view the configuration information. 3. Click Add to add a proxy server. See Adding proxy servers, page 411. 4. Select a proxy server and click Edit to modify it. See Editing proxy server settings, page 414. 5. Select a proxy server and click Delete to delete it. See Deleting proxy servers, page 414.
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.
411 Adding proxy servers
The Add Proxy Server dialog box opens.
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 Modifying proxy server startup options, page 415.
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 4901. Valid values are 1-65535.
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.
412 Adding proxy servers
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 0.25-24 hours. 8. Enter the Minimum file size for cache to set the minimum size of files to be cached. 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.
n 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.
n Age limit sets the number of days to keep retrieved files in the proxy server cache.
n 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.
n 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.
n Encrypt transactions between proxy server and clients encrypts messages sent between the proxy server and Surround SCM clients.
n 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.
n To add a user, select the user in the Available users list and click Add to move the user to the Selected users list.
n 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 414.
11. 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 Modifying proxy server startup options, page 415.
413 Editing proxy server settings
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. 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. See Modifying proxy server startup options, page 415.
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 409.
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.
414 Modifying proxy server startup options
2. Select a Proxy Server option.
n Use proxy server defined by administrator uses the proxy server set by the administrator.
n 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.
n 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.
Modifying proxy server startup options If you add a proxy server or install the proxy server on a local computer, you may need to update the proxy server options. Keep in mind that these settings apply to the proxy server application. If you need to change the master Surround SCM server settings, see Editing proxy server settings, page 414. 1. Start the Surround SCM Registry Utility. See Starting the Surround SCM Registry Utility, page 419. 2. Click Proxy Options. You can also choose Edit > Proxy Options. The Surround SCM Proxy Server Options dialog box opens.
415 Modifying proxy server startup options
3. Make any changes to the server information.
Field Description
Proxy Surround SCM proxy server name. name
Proxy Proxy server connection password. This password must match the master Surround connection SCM server value. See Adding proxy servers, page 411. password
Password Proxy connection password confirmation. confirm
Master Master server address the proxy server connects to. If RSA key exchange is enabled on server the Surround SCM Server, download the server settings file and then import it instead of address manually entering the server address and port. See Configuring RSA key exchange, page 293. Click Import, select the XML file and, click Open. The Server address, Server port, and Public key fingerprint fields are automatically populated.
Master Master server port number. The default port is 4900. Valid values are 1-65535. server port
Public key Read-only public key fingerprint that provides additional security required to connect to fingerprint the Surround SCM Server. Automatically populated when you import a server settings file.
416 Modifying proxy server startup options
Field Description
Application Directory where the proxy server application is stored. Click to select a directory. directory
Log Directory where the proxy server writes the SCMProxyStartup.log file, which contains directory any error messages that occur when the proxy server application starts. The default directory is the Surround SCM application directory. Click to select a different directory.
Proxy Directory where cached files are stored on the proxy server. The default directory is the cache SCMProxyCache directory in the proxy server application directory. Click to select a directory different directory. To avoid retrieving previously cached files after changing the cache location, move the contents of the SCMProxyCache directory to the new directory.
4. Click Validate Options to validate the information. If validation fails, check the following:
n Make sure the master server is running.
n Make sure you entered the correct master server address and port number.
n In the Surround SCM Client, make sure the proxy server is listed in the Proxy Server Maintenance dialog box and the proxy name and password match the values in the registry utility. See Editing proxy server settings, page 414. 5. Click OK to save the changes.
Note: You must restart the proxy server for changes to take effect.
417
Modifying Surround SCM Server Registry Settings
Installing the Surround SCM Server, Surround SCM Web Server, and Surround SCM Proxy Server applications writes several values to the system registry. These values are read from the registry every time these servers and the Surround SCM Web Server start. You can use the registry utility to modify these values instead of reinstalling the server applications. The registry utility writes to the local registry and only works on the local computer that hosts the servers. The servers read the registry settings during initialization. If you change any of the registry options, you must stop and restart the servers. See Modifying Surround SCM Server startup options, page 419, Modifying indexing server startup options, page 356, Modifying proxy server startup options, page 415, and Modifying web server startup options, page 423.
Note: To use the Surround SCM Registry Utility, you must be logged into the server computer and have full administrative privileges.
Starting the Surround SCM Registry Utility n Windows—On the Start menu, choose Programs > Seapine Software > Surround SCM > Surround SCM Registry Utility. n Mac—Double-click the Surround SCM Registry Utility icon in the Applications/Surround SCM folder. n Linux—Enter /var/lib/SurroundSCM/scmregistryutil
Modifying Surround SCM Server startup options You can modify the startup information used by the Surround SCM Server without reinstalling the server application. For example, you can change the server port if another application uses the default port or change the directories where temporary files, the server log, or cached files are stored. 1. Start the Surround SCM Registry Utility. See Starting the Surround SCM Registry Utility, page 419. 2. Click Server Options. You can also choose Edit > Server Options. The Surround SCM Server Options dialog box opens.
419 Modifying Surround SCM Server startup options
3. Make any changes to the server information.
Field Description
Server port Surround SCM Server port number. The server communicates with Surround SCM clients on this port. The default number is 4900. Valid values are 1-65535.
Reattempt How long the Surround SCM Server should attempt connecting to an RDBMS server connection before initializing the server database. The server attempts to connect to RDBMS to RDBMS servers for 1 minute by default. Valid values are 0 - 10 minutes. There is a 20 second server delay between each attempt. If you stop the server while it is connecting to an RDBMS server, it stops after the 20 second delay ends. You cannot log in to Surround SCM while the server is connecting to an RDBMS server.
Application Directory where Surround SCM applications, documentation, and help files are located. directory Click to select a directory.
420 Modifying Surround SCM Server startup options
Field Description
Log Directory where the Surround SCM Server writes the SCMStartup.log file, which directory contains any error messages that may occur when the server starts. The default directory is the Surround SCM application directory. Click to select a different directory.
Guiffy path Directory where Guiffy, the integrated diff/merge application, is located. This path is automatically set during installation. Click to select a different directory.
Java Directory where the Java Runtime Environment (JRE) used by Guiffy is located. This runtime path is automatically set during installation. Click to select a different directory. path
Application Directory where temporary files are stored. This directory is used during file transfers, temporary report generation, and other actions. The default directory is the SCMTempFiles directory files in the Surround SCM application directory. Click to select a different directory. directory
Application Directory where the Surround SCM Server large files retrieved from the database, which working reduces the load on the database and improves performance. The default directory is the cache SCMWorkingCache directory in the Surround SCM application directory. Click to directory select a different directory.
Working How much disk space the working cache can use. No working cache limit does not Cache limit the size of the working cache. Limit working cache disk usage limits the working cache to the specified number of megabytes. The default is 10 MB. Disable working cache disables the working cache.
4. Click Download Public Key File to save an XML file that contains the Surround SCM Server address, port number, and public key fingerprint. This option is only available if RSA keys are detected in the Surround SCM application directory. 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. 5. Click Validate Options to check the information. If the validation fails, check the directory paths and the server port number. 6. Click OK to save the changes.
Note: You must restart the Surround SCM Server for changes to take effect. See Starting the Surround SCM Server, page 270.
421
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 Modifying web server startup options, page 423.
Starting the Surround SCM Web Server The Surround SCM Web Server must be running before users can log in to Surround SCM Web. n Windows—The Surround SCM Web Server is installed as a Windows service and starts automatically. If it is not running or you need to restart the server, refer to the Windows documentation for information about starting a service. n Unix—Enter /usr/bin/surroundscmweb start. If you need to restart the server, enter /usr/bin/surroundscmweb stop and then restart the server.
Modifying web server startup options Surround SCM Web supports HTTP and HTTPS. By default, HTTPS connections use a self-signed certificate and the default Java KeyStore and TrustStore to secure communication between browsers and the Surround SCM Web Server. If you used the Java keytool utility to generate KeyStore and TrustStore files for your own SSL certificate, you can use these files instead of the default files. You can also change the HTTP or HTTPS port number, set the directory where temporary Surround SCM Web files are stored, and modify the Surround SCM Server connection information if you want web users to access a different server. If you use RSA key exchange, you can import the server settings file to add the required key to the Surround SCM Web configuration. 1. Start the Surround SCM Registry Utility. See Starting the Surround SCM Registry Utility, page 419. 2. Click Web Options. You can also choose Edit > Web Options. The Surround SCM Web Server options dialog box opens.
423 Modifying web server startup options
3. Make any changes to the server information.
Field Description
HTTP port Surround SCM Web HTTP port number. The default port is 8090. Valid values are 1- 65535.
HTTPS Surround SCM Web HTTPS port number. The default port is 8443. Valid values are 1- port 65535.
KeyStore Path to the Java KeyStore file that contains the identity certificate for Surround SCM file path Web. Click to select the file. If not set, HTTPS connections use the default self-signed certificate, which is stored in the ssl directory in the web application directory.
KeyStore Password used to create the specified KeyStore file. password
TrustStore Path to the Java TrustStore file that contains trusted certificate authorities. Click to file path select the file. If not set, the web server uses the default Java TrustStore.
TrustStore Password used to create the specified TrustStore file. password
424 Modifying web server startup options
Field Description
Web Directory where temporary Surround SCM Web files are stored. The default directory is application the sscmweb/tempAppDir directory in the Surround SCM application directory. Click directory to select a different directory.
Surround Surround SCM Server address the web server connects to. If you RSA key exchange is SCM enabled on the Surround SCM Server, download the server settings file and then import it Server instead of manually entering the server address and port. See Configuring RSA key address exchange, page 293. Click Import, select the XML file and, click Open. The Server address, Server port, and Public key fingerprint fields are automatically populated.
Surround Surround SCM Server port number. The default post is 4900. Valid values are 1-65535. SCM Server port
Public key Read-only public key fingerprint that provides additional security required to connect to fingerprint the Surround SCM Server. Automatically populated when you import a server settings file.
4. Click Validate Options to validate the information. If validation fails, check the following:
n Make sure the Surround SCM Server is running.
n If you use your own KeyStore and TrustStore files, make sure the file paths and passwords are correct.
n If you use RSA key exchange and a key mismatch error is returned, download the public key and reimport the server settings file. See Configuring RSA key exchange, page 293. 5. Click OK to save the changes.
Note: You must restart the Surround SCM Web Server for changes to take effect. See Starting the Surround SCM Web Server, page 423.
425
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 n Windows—The Surround SCM CMIS Server is installed as a Windows service and starts automatically. If it is not running or you need to restart the server, refer to Windows documentation for information about starting a service. n Mac—Click Surround SCM CMIS Server in the System Preferences. n Linux—Enter /usr/bin/surroundscmcmis start
Starting the Surround SCM CMIS Admin Utility n Windows—Choose Programs > Seapine Software > Surround SCM > Surround SCM CMIS Admin Utility on the Start menu. n Mac—Double-click the Surround SCM CMIS Admin Utility icon in the Applications/Surround SCM/CMIS folder. n 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.
1. Start the Surround SCM CMIS Admin Utility. See Starting the Surround SCM CMIS Admin Utility, page 427. The server admin utility opens.
427 Adding CMIS repositories
2. Click Add to add a CMIS repository. See Adding CMIS repositories, page 428. 3. Select a repository and click Edit toedit it. See Editing CMIS repositories, page 429. 4. Select a repository and click Delete to delete it. See Deleting CMIS repositories, page 430. 5. Enter the Server port number. The CMIS Server communicates with CMIS clients on this port. The default number is 8080. 6. 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 427. 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.
428 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 2.0. 3. 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.
n 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.
n 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.
n 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.
n 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 427.
Editing CMIS repositories 1. In the Surround SCM CMIS Admin Utility, select a repository and click Edit. 2. Make any changes.
429 Deleting CMIS repositories
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 427.
Deleting CMIS repositories 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 427.
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 393. 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.
430 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: n C API documentation—API/docs/C/index.html n Java API documentation—API/docs/Java/index.html n .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: n On Windows, include the sscmapi.dll and sscmapi.lib files in your Visual Studio project. n On Mac OS X, link against the libsscmapi.dylib file. n On Linux, link against the libsscmapi.so file. n 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.
431 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: n 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. n 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.
432 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: n 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. n 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.
433
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 271 for more information about security. Commands are grouped in categories. This section provides the following information about each command: n Command: The command name. n 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. n More information: Other commands that must be enabled to use the command or other information to help you understand the command. n 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 Provides access to: More information
Login Via Log in using the GUI GUI Client client
Login Via Log in using the CLI Client command line interface (CLI)
Login Via Log in from SCCI- SCC DLL compliant applications Integration
Login Via Log in using WebDAV WebDAV
Login Via Log in from Microsoft Enables users to add the Surround SCM menu to Microsoft Word, Microsoft Office Excel, PowerPoint, Access, and Project Office Integration
Login Via Log in using the API Surround SCM API
Login Via Log in from CMIS- CMIS Client compliant applications
435 General security commands
Command Provides access to: More information
Login Via Log in using the Web Client Surround SCM Web client
Edit Tools > TestTrack Enables users to configure connections to TestTrack Servers and TestTrack Integration > projects. TestTrack connections are available to all users, but a Integration Connections TestTrack username and password is required to access a project.
Add/Remove Activities > Advanced Files from > Add Label Labels 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)
Generate Tools > Reports If this command is disabled, users can still generate a differences Reports report from the History dialog box.
Edit Own Tools > My Email Lets users edit their own email notifications only. The Edit Triggers Email Notifications command must be enabled for users to add or edit email notifications. Notifications
View Own My Committed from Committed the Filter changelists Changelists by list (Tools > Changelists)
Add/Edit Tools > Filters Lets users manage their own filters only. Private Filters
Add/Edit Tools > Reports Lets users manage their own reports only. Private Reports
Add External Tools > Reports Lets users only add reports from external reporting services to Reports 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.
436 Admin security commands
Command Provides access to: More information
Edit Own Edit Comments button Lets users edit their own comments only. Comments in the file and repository History Details dialog boxes
Modify Activities > Shelve Lets users manage their own shelves only. Shelves Files
Buttons on the Shelves window (View > Shelves)
Admin security commands Only enable the following commands for administrator security groups.
Command Provides access to: More information
Edit Server Tools > Administration > Server Options Options
Tools > Administration > Default User Options
Create Mainline Tools > Administration > Create Must be enabled to migrate a database to Surround Branch Mainline Branch SCM from another source code control provider.
Tools > Administration > Upgrade Mainline Branch
Remove Tools > Administration > Remove Mainline Mainline Branch Branch Tools > Administration > Destroy Removed Mainline
Rename Tools > Administration > Rename Mainline Mainline Branch Branch
Analyze Tools > Administration > Database Analyze/Repair Database
Analyze button on the Analyze Database dialog box (Tools > Administration > Analyze/Repair Database)
437 Admin security commands
Command Provides access to: More information
Repair Tools > Administration Database > Analyze/Repair Database
Repair button on the Analyze Database dialog box (Tools > Administration > Analyze/Repair Database)
Void Check Out Tools > Administration > Void Check Out
Lock Database Tools > Administration > Database Lock
Manage Tools > Administration > Shadow Shadow Folders Folders
Manage Tools > Administration > Triggers Also lets users enable email notifications for all Triggers users. To allow users to only work with their own email notifications, enable the Edit Own Email Notifications command in the General category.
Manage Mail Tools > Administration > Mail Queue Queue
Edit Other Pending For User from the Filter If this command is enabled, users can work with Users’ Pending changelists by list (Tools > other users’ changelists, but some actions, such as Changelists Changelists) Check In, may not be available.
View All All Committed from the Filter Committed changelists by list (Tools > Changelists Changelists)
Break Share Tools > Administration > Break Share Across All All Branches Branches
Edit Custom Tools > Administration > Custom Fields Fields
Modify Tools > Administration > Workflow Workflow/States
Override Activities > Advanced > Change State If this command is enabled, users can set a file’s Workflow workflow state to any available state. The available State list in the Properties dialog box states are not restricted by the workflow. (Activities > Properties)
State list in the Check In Files dialog box
438 Admin security commands
Command Provides access to: More information
Manage Public Buttons on Filters dialog box for public If this command is enabled, users can create filters Filters filters only (Tools > Filters) that are shared with all other users and modify other public filters.
Edit Other Edit button on Filters dialog box for Users Private filters created by other users (Tools > Filters Filters)
Manage Public Buttons on Reports dialog box for If this command is enabled, users can create reports Reports public reports only (Tools > Filters) that are shared with all other users and modify other public reports.
Edit Other Edit button on Reports dialog box for Users Private reports created by other users (Tools Reports > Reports)
Edit Proxy Tools > Administration > Proxy Server Settings Maintenance
Manage Labels Tools > Administration > Labels
Tools > Administration > Upgrade Legacy Labels
Delete Labels Delete button on the Labelsdialog box (Tools > Labels)
Delete button on the Legacy Labels dialog box (Tools > Upgrade Legacy Labels)
Edit Other Edit Comments button in the file and If this command is enabled, users can edit Users' repository History Details dialog comments entered by other users. Comments boxes
Edit Other Edit Shelf and Delete Shelf buttons on If this command is enabled, users can rename, Users' Shelves Shelves window for shelves owned by change ownership and sharing options, and delete other users (View > Shelves) shelves owned by other users.
Edit Other Open Review and Start Code Review If this command is enabled, users can create, edit, Authors' Code buttons on Code Reviews window for add file versions to, and start code reviews they are Reviews code reviews users are not the author not the author of. 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)
439 Users security commands
Command Provides access to: More information
Delete Code Delete button on Code Reviews If this command is enabled, users can delete any Reviews window (View > Code Reviews) existing code reviews.
Export Tools > Administration > Export Repository to Repository to Mainline Mainline
Show Licenses Tools > Administration > Licenses In In Use Use
Users security commands If all commands in the Users category are disabled, users cannot access the Users window. View > Users is disabled.
Command Provides access to: More information
Retrieve User Retrieve Global Users button on the Enables users to retrieve users from the Seapine Users window (View > Users) License Server and add them to Surround SCM.
View User View button on the Users window (View > Users)
Edit User Edit button on the Users window (View > Users)
Delete User Delete button on the Users window (View > Users)
Edit Own Tools > TestTrack Integration > User Enables users to specify their TestTrack or other issue Integration Settings tracking tool username and password. Settings Tools > Issue Tracking Integration > User Settings
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 Provides access to:
Add Security Group Add button on the Security Groups window (View > Security Groups)
View Security Group View button on the Security Groups window (View > Security Groups)
Security Group report on the Select Report Type dialog box
Edit Security Group Edit button on the Security Groups window (View > Security Groups)
Delete Security Group Delete button on the Security Groups window (View > Security Groups)
440 Files security commands
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 271.
Command Provides access to: More information
View View the list of all repositories on the If this command is enabled on the Server Security Repository Surround SCM Server tab, users cannot view any repositories or List branches.
Add File Activities > Add Files Command must be enabled to create shares in a destination repository. Repository > Create Repository
Include/Exclude button on the Template tab in the Properties dialog box for baseline branches (Branch > Branch Properties)
Remove Activities > Remove File File Repository > Remove Repository
Remove button on the Template tab in the Properties dialog box for baseline branches (Branch > Branch Properties)
Destroy Activities > Destroy File Requires the Remove File command to allow File users to destroy repositories. Destroy button on the Removed Items tab in the Properties dialog box (Activities > Destroyed files and repositories cannot be Properties) restored.
Permanently destroy repository check box in The Permanently destroy repository check box the Remove Repository dialog box changes to Permanently destroy repository and (Activities > Destroy File) 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.
Get File Activities > Get Requires the View File History command to allow users to annotate files. Activities > Annotate
Unshelve Files and Differences buttons on the Shelves window (View > Shelves)
441 Files security commands
Command Provides access to: More information
Check Activities > Check Out Also enables users to check out and check in a In/Out File repository. Activities > Check In 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.
Rename Activities > Rename File File
Change File type list in the Properties dialog box Changing the file type changes it in all branches. File Type (Activities > Properties)
Change Expand keywords list in the Properties File dialog box (Activities > Properties) Properties
View File Activities > History Requires the Get File command to allow users to History annotate files. History tab in the file details pane (View > File Details Pane)
Activities > Annotate
Branches in the Graphical History window (Activities > Graphical History)
Share Activities > Share Files Requires the Add Files command. Files
Break Activities > Break Shares Shares
Set Change field values on Custom Fields tab in Custom the Properties dialog box (Activities > Field Properties) and Custom Fields tab in the Values Add Files dialog box
Activities > Advanced > Bulk Custom Field Changes
Change Activities > Advanced > Change State The State listin the Check In Files dialog box is State only available if the Allow workflow state changes State list in the Properties dialog box from check in option is selected in the Server (Activities > Properties) Options dialog box.
State list in the Check In Files dialog box
Move Activities > Move Files
Repository > Move Repository
442 Branch security commands
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 279.
Command Provides access to: More information
Create Baseline Baseline from the Branch type list Branch (Branch > Create Branch)
Create Workspace from the Branch type Workspace list (Branch > Create Branch) Branch
Create Snapshot Snapshot from the Branch type Branch list (Branch > Create Branch)
View Branch History tab in the Properties History dialog box (Branch > Branch Properties)
Track Changes button in the Duplicate Changes and History dialog boxes (Tools > Track Changes)
Delete Branch Branch > Remove Branch
Destroy Branch Destroy button on the General tab Destroyed branches cannot be restored. in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance)
Permanently destroy branch check box in the Remove Branch dialog box (Branch > Remove Branch)
443 Branch security commands
Command Provides access to: More information
Change Branch Toggle Frozen, Toggle Active, Users can also freeze and unfreeze branches if the Attributes Toggle Caching, and Toggle Freeze/Unfreeze Branch command is enabled. 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 Security Ignore branch security check box Allows users to override the security set for the selected in Branch on the General tab in the Branch branch and apply the available options in the Branch Maintenance Maintenance dialog box (Tools > Maintenance dialog box. Administration > Branch Maintenance)
Destroy Other Destroy button on the General tab Users’ in the Branch Maintenance dialog Workspace box when another user’s Branches workspace branch is selected (Tools > Administration > Branch Maintenance)
Show all private branches check box on the General tab in the Branch Maintenance dialog box
Change Branch Change Type button on the Type General tab in the Branch Maintenance dialog box (Tools > Administration > Branch Maintenance)
Promote Branch Branch > Promote Branch Users must also have some file permissions for the repository being promoted to. The following commands Branch > Promote File 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.
444 Branch security commands
Command Provides access to: More information
Rebase Branch Branch > Rebase Branch Users must also have some file permissions for the repository being rebased from. The following Branch > Rebase Files 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.
Duplicate Branch > Duplicate Changes Changes Duplicate Changes button in the Manage Changelists dialog box (Tools > Changelists)
Rollback Branch > Rollback Promote Promote/Rebase Branch > Rollback Rebase
Rename Branch Branch > Rename Branch
Freeze/Unfreeze Toggle Freeze button on the Enable this command to allow users to freeze and Branch General tab in the Branch unfreeze branches if the Change Branch Attributes Maintenance dialog box (Tools > command is not enabled. Administration > Branch Maintenance)
Branch > Branch Attributes > Freeze
Manage Branch Toggle Indexing button on the Indexes 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)
445
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 email templates. Add percent symbols (%) before and after the variable (for example, %SSCM_FILELIST%). See Editing email templates, page 323. 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 Email Template dialog box.
File and repository event variables Variable Definition
CF_
SSCM_BEFOREAFTER Indicates if trigger fired before or after the event
SSCM_BRANCH Branch the specified file is in
SSCM_BRANCHTYPE Type of branch the specified file is in
SSCM_CHANGELISTID Changelist ID number
SSCM_CHANGELISTNAME Changelist name
SSCM_CLIENTIP User’s IP address
SSCM_CLIENTMACHINE User’s computer name
SSCM_COMMENT * File event comments
SSCM_DATE Date the trigger fired
SSCM_ISSUENUMBER * TestTrack issue number the file is attached to
SSCM_DESTINATIONREPOSITORY Repository the file was moved or shared to
SSCM_EVENT Event that caused the trigger to fire
SSCM_ Issue tracking tool connection name EXTERNALATTACHMENTCONNECTION
SSCM_EXTERNALATTACHMENTID IssueIDthefileisattachedto
SSCM_ Issue tracking tool name EXTERNALATTACHMENTPROVIDER
SSCM_FILE * Filename
SSCM_FILELINK * File hyperlink in sscm:// format
447 Appendix B: Environment Variables
Variable Definition
SSCM_FILELIST List of files for the event
SSCM_FILEVERSION * Post-event file version
SSCM_LABEL * File label
SSCM_LOCALFILE * Full path of the local file (used with check in or add events only)
SSCM_MAINLINE Mainline branch the file is in
SSCM_NUMFILES Number of affected files
SSCM_OLDFILENAME * Original filename; used with rename event
SSCM_PERMREMOVE * File was permanently removed (yes/no)
SSCM_REPOSITORY * Full repository path for the file
SSCM_REQUIREMENTNUMBER * TestTrack requirement number the file is attached to
SSCM_SHAREREPOSITORY Source repository the share was created from
SSCM_SOURCEBRANCH Source branch used for add, promote, rebase, and duplicate events
SSCM_SOURCEREPOSITORY Repository the file was moved from
SSCM_TESTCASENUMBER * TestTrack test case number the file is attached to
SSCM_TIME Time the trigger fired
SSCM_TRIGGERDESC Trigger description
SSCM_USER User that caused the event to occur
Code review event variables Variable Definition
CF_
SSCM_AUTHORLIST Code review author
SSCM_AWAITINGREVIEWBY * Reviewers who still need to review the code review file
SSCM_BEFOREAFTER Indicates if trigger fired before or after the event
SSCM_BRANCH * Branch the specified file is in
SSCM_CLIENTIP User’s IP address
448 Appendix B: Environment Variables
Variable Definition
SSCM_CLIENTMACHINE User’s computer name
SSCM_DATE Date the trigger fired
SSCM_DUEDATE Due date for the code review
SSCM_EVENT Event that caused the trigger to fire
SSCM_FILE * Filename
SSCM_FILELINK * File hyperlink in sscm:// format
SSCM_FILELIST List of files for the event
SSCM_MAINLINE Mainline branch the file is in
SSCM_NOTES Code review notes
SSCM_REPOSITORY * Full repository path for the file
SSCM_REVIEWERLIST Code review reviewers
SSCM_REVIEWFILESTATUS * Codereview filestatus
SSCM_REVIEWNAME Code review name
SSCM_REVIEWSTATUS Code review status
SSCM_TIME Time the trigger fired
SSCM_TRIGGERDESC Trigger description
SSCM_USER User that caused the event to occur
SSCM_VERSIONS * File versions under code review
449
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: n Your Surround SCM administrator must install the WebDAV CGI and configure WebDAV for use. n 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 http://127.0.0.1/cgi-bin/sscmdav.cgi on an Apache web server or http://127.0.0.1/scripts/sscmdav.cgi 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.
451 Windows network place
3. Click the branch or repository that contains the file you want to view.
4. Click thefileyouwant toview. 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.
452 Windows network place
1. Open My Network Places. 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 http://127.0.0.1/cgi-bin/sscmdav.cgi.
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.
453 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 http://127.0.0.1/cgi-bin/sscmdav.cgi on an Apache web server or http://127.0.0.1/scripts/sscmdav.cgi on a Microsoft IIS server. 3. Click Connect. The WebDAV directory opens. The alias directories are displayed.
454 Linux filesystem path
4. Open an alias directory to access Surround SCM branches, repositories, or files.
Linux filesystem path You can mount a WebDAV directory as a Linux filesystem path.
Note: The Linux filesystem davfs driver is required to mount a WebDAV directory in Linux. You can download the driver from http://dav.sourceforge.net.
1. Enter mount.davfs
2. Change (cd) to the alias directory to access Surround SCM branches, repositories, or files.
455
Glossary
Ancestor branch The branch that a baseline, snapshot, or workspace branch is created from.
Annotate The process of comparing text files to determine new or changed lines between versions.
Atomic transaction A transaction that either completely succeeds or completely fails.
Baseline branch A public branch that all users can generally access. Changes made to the baseline branch affect everyone who accesses that branch.
Branch A separate line of development that uses an existing repository and the files in that repository as a starting point. When a repository is branched, the files in both branches are initially identical. As file contents change, the branched files become dissimilar.
Branch security File commands that are enabled or disabled for a specific branch in a repository. Branch security overrides server security.
Branch template Defines the repositories to include or exclude in a branch.
Changelist Files and actions that are grouped together and treated as one unit. Changelists allow for atomic transactions—if one action in a changelist fails, the entire operation is cancelled and changes are not made.
Check in Add source file changes to the archive on the Surround SCM Server. Checking in a file removes the lock on the file, makes changes available to other users, and increments the version number by one.
Check out Lock a file on the Surround SCM Server for editing. File changes are saved locally and are not available to other users until you check in the file.
CLI Command line interface. Offers access to Surround SCM features. Frequently used with scripts to automate processes, such as nightly builds.
Cloak Mark a repository to skip it when you recursively get, check in, check out, or undo check out files.
Code review A container in Surround SCM used to group related files and changes that need review and exchange feedback without affecting file contents.
457 Glossary
Common ancestor Originating file used to compare one or two sets of changes. Used to perform 2-way and 3-way merges when promoting and rebasing files.
Diff Compare file versions to find the differences.
Exclusive check out Exclusively lock a file on the Surround SCM Server for editing, preventing other users from checking out files or a repository.
Freeze Prevent users from making changes to files in a branch. When a branch is frozen, any command that can affect source files is disabled.
Get Retrieve the current version of files from the Surround SCM Server and copy them to a local directory.
Guiffy An integrated diff/merge utility.
Keywords Case-sensitive placeholders that can be inserted in text files and expanded when files are checked in.
Label Used to mark a specific version of a file or repository.
Mainline branch The highest-level branch that contains all source files, labels, other branches, and repositories. Commonly referred to as the mainline.
Merge Combine changes between file versions.
Post-event trigger Trigger that performs an action after a file event is successfully completed on the Surround SCM Server.
Pre-event trigger Trigger that performs an action when a client requests that a file event be performed, but before the event is complete on the Surround SCM Server.
Promote Update an ancestor branch with changes made in a selected branch, repository, or file.
Proxy server A server that caches files retrieved from the Surround SCM Server and handles subsequent file requests.
Rebase Update a selected branch, repository, or file with changes made in an ancestor branch.
Recursive Apply a command to a repository and all of its files and subrepositories.
458 Glossary
Repository A collection of files and subrepositories that help you organize source code and other files managed with Surround SCM.
Repository security File commands that are enabled or disabled for a specific repository. Repository security overrides server security.
Rollback Revert to a previous file version without affecting file history and version numbers.
SCM Software configuration management, which is the task of tracking and controlling changes in software.
Seapine License Server A client/server application that concurrently manages users and licenses.
Server security File commands that are enabled or disabled for all repositories in a mainline branch.
Shadow folder A folder that contains a copy of the current files in a branch. Files in a shadow folder are automatically updated when changes are checked in.
Share Create a link in one repository to a file in another repository within the same branch.
Shelf A container on the Surround SCM Server where you can temporarily store files.
Snapshot branch A static branch of a baseline or workspace branch that generally corresponds to a project milestone. Most commands are disabled in snapshot branches.
State The current status of a file within its lifecycle. States are used in workflows.
Timestamp The recorded date and time when an event occurs.
Trigger An event-driven procedure that automatically initiates actions based on file events that users perform.
Workflow Defines the path that files follow during their lifecycle.
Workflow template Defines the states used in a workflow and the states that a file can move to from each state.
Working directory A local directory where files are stored.
459 Glossary
Workspace branch A private branch that other users cannot access. Workspace branches isolate work and changes from other users.
460 Index: Activity Log – Branches
Index Analyzing issue risk in files 255 Annotating files 76 A results 77 API 431 Activity Log 8 .NET 433 Adding avoiding conflicts 431 actions to changelists 124 C 431 changelists 123 Java 432 CMIS repositories 428 Attaching files custom fields 312 external issues 263 email notifications 85 TestTrack items 249 existing mainline branches 374 Authentication methods 291 non-RDBMS format 376 RDBMS format 375 B external reports 243 Backups files 28 databases 386 files to code reviews 59 locking databases 386 filters 222 Base file 117 licenses 4 Baseline branches 161 plug-in directories 261 Blame See Annotating files proxy servers 411 Bookmarks RDBMS connections 383 adding 226 reports 230 changing keyboard shortcuts 226 repositories 105 deleting 226 security groups 274 editing 226 server connections 5 Branch menu 8 shadow folders 345 Branch templates 167 TestTrack connections 247 applying to existing branches 359 TestTrack issues 252 creating 168 trigger actions 327 modifying 359 triggers 317 removing from branches 359 users 281 selecting for new branches 169 workflow states 334 Branches workflow templates 336 activating 359 working directories 12 adding existing mainlines 374 Address toolbar 226 applying templates to existing branches 359 Advanced find files 205 baseline 161 Analyze and repair options 387 bookmarking 226 Analyzing databases 387, 389 caching 361
461 Index: Branches tree – Checking for new versions
changing type 361 viewing index details 354 controlling access 279-280 when to branch 162 creating 165 workspace 162 creating mainline 367 Branches tree 8 creating templates 168 Break shares deleting permanently 365 files 118 differences 171 files across branches 363 differences report 175 Bulk custom field changes 33 example 163 C freezing 358 Caching hiding 358 branches 361 history 201 proxy server 410 inactivating 359 server options 362 including and excluding repositories 168 Changelists indexing 352 adding comments to files 129 mainline 161 adding file actions 124 managing attributes 349 committed 130 modifying templates 359 committing 130 promoting 178 creating 123 properties 202 editing file actions 128 rebasing 187 file differences 132 removing 364 managing 124 removing mainlines 374 merging files 133 removing templates 359 moving actions 128 renaming 357 pending 125 restoring 365 printing 127, 131 restoring mainlines 374 removing 128 rolling back promoted files 186 removing file actions 129 rolling back rebased files 195 renaming 127 selecting templates 169 rolling back 135 shortcut menu 94 saving 127, 131 snapshot 162 searching for committed 131 templates 167 selecting 139 turning indexing on or off 353 server options 305 unfreezing 358 viewing details 125 unhiding 358 Changing server database location 382 upgrading mainlines 401 Charting report data 243 viewing 203 Checking for new versions 301
462 Index: Checking in files – Databases
Checking in files 24 starting 63 copying files 174 status 56 entering comments 25 viewing included files 72 merged files 44 viewing unaddressed comments 71 Checking out files 21 Columns undoing 23 changing contents 91 voiding 285 changing width 91 Client-side plug-ins 259 sorting 92 Cloaking repositories 112 Comments CMIS Admin Utility editing for file actions 81, 120 starting 427 Committing changelists 130 CMIS repositories Converting adding 428 mainline branches to different databases 373 deleting 430 server database to a different type 380 editing 429 Copied files CMIS Server checking in 174 configuring 427 Creating port number 428 branches 165 server address 427 changelists 123 starting 427 labels 143 troubleshooting 430 mainline branches 367 Code reviews 55 repositories 105 adding comments 69 shelves 157 adding files 59 Custom fields addressing comments 70 adding 312 configuring settings for repositories 343 changing multiple 33 creating 58 configuring 311 deleting 72 deleting 313 deleting comments 70 editing 313 editing 65 resolving issues 404 editing comments 70 restoring 313 finding 71 setting 32 managing 57 viewing file information 83 moving comments 70 Custom toolbar 96 opening 64 D removing files 63 Databases reviewing files 65 analyzing and repairing 387, 389 selecting 63 backing up 386
463 Index: Default file dialog options – Duplicating changes
creating tables 379 trigger actions 327 locking 386 triggers 328 maintaining 379 users 284 repairing 391 viewer/editor settings 19 scheduling data purges 301 workflow states 335 setting analyze and repair options 387 workflow templates 340 Default file dialog options 97 working directories 13 Add Files 100 Destroying Check In Files 98 branches 365 Check Out Files 99 files 38 Get Files 97 removed mainline branches 377 Shelve Files 103 repositories 115 Undo Check Out Files 100 Diagramming workflows 340 Default server database 380 Diff applications Default user options 308 configuring 49 Deleting deleting settings 52 branches 365 editing settings 51 CMIS repositories 430 Diff/merge application settings 52 custom fields 313 Diffing diff/merge applications 52 branch differences report 175 email notifications 88 branches 171 files 38 changelist files 132 filters 225 file differences report 46 labels 145 files 41 legacy labels 407 image files 47 mail 395 labels 148 mainline branches 377 shelved files 158 proxy servers 414 working directories 106 RDBMS connections 386 Downloading RSA keys 293, 421 reports 244 Duplicating repositories 115 email notifications 88 security groups 277 filters 224 server connections 6 labels 145 shadow folders 347 reports 244 shelved files 158 security groups 277 shelves 158 triggers 328 Surround SCM Server log entries 394 workflow templates 340 TestTrack connections 248 Duplicating changes 171, 196 actions 199
464 Index: Editing – Filename search
preview 198 setting up 85 tracking changes 199 Email server options 297 E Email templates editing 323 Editing field codes 447 changelist file actions 128 Encryption 290 CMIS repositories 429 enabling 289 code reviews 65 Environment variables 447 custom fields 313 Executables diff/merge applications 51 running from triggers 320 email notifications 88 Expanding keywords 303 email templates 323 Exporting files 24 repositories to different mainlines 370 filters 224 External reports labels 144 adding 243 proxy server settings 414 RDBMS connections 385 F reports 244 Favorites security groups 276 see Bookmarks 226 server connections 6 Field codes 447 shadow folders 347 File details pane 8,75 shelves 158 File dialog defaults 97 TestTrack connections 248 Add Files 100 TestTrack issues 253 Check In Files 98 trigger actions 327 Check Out Files 99 triggers 326 Get Files 97 users 284 Shelve Files 103 view/edit file settings 18 Undo Check Out Files 100 workflow states 335 File extension user options 101 workflow templates 339 File information working directories 13 check out 82 Email notifications custom fields 83 adding 85 general 82 deleting 88 shared files 83 disabling 88 File manager user options 14 duplicating 88 File names/extensions server options 306 editing 88 File status 17 enabling 88 Filename search 205 setting server options 297
465 Index: Files – History
Files viewing 17 adding 28 viewing application 17 bookmarking 226 viewing in working directory 14 breaking shares 118 viewing line-by-line file changes 76 breaking shares across branches 363 voiding check out 285 checking in 24 Filters checking out 21 adding 222 deleting from shelves 158 applying to source file list 224 deleting permanently 38 configuring 222 destroying 38 deleting 225 differences 41 duplicating 224 editing 24 editing 224 editing application 17 Finding See Searching finding 205 Fixing getting 15 external issues 264 history 78 TestTrack issues 253 image differences 47 Font labeling 146 changing viewer/editor 19 merging 43 Freezing branches 358 merging unrelated 44 G moving 35 Getting files 15 opening local copies 19 Global users promoting 183 retrieving 283 rebasing 192 Go To Location 225 removing 36 Graphical Branch Tree 203 removing labels 151 Graphical History 81 renaming 36 H restoring 37 retrieving from shelves 159 Hiding rolling back 27 branches 358 searching for text in contents 218 labels 145 sharing 117 toolbars 95 shelving 153 History shortcut menu 94 branch 201 undoing check out 23 branch details 201 unsharing 118 file 78, 81 unsharing across branches 363 file details 80 unshelving 159 labels 149 reports 231
466 Index: HTTPS – Labels
repositories 119 Repositories tree 8 HTTPS 291, 423 source file list 8 I Internal viewer/editor changing text settings 19 IDE integrations 259 deleting settings 19 user options 259 editing settings 18 Image file differences 47 Internal viewer/editor options 17 Inactivating branches 359 Issue tracking integration Indexing activating 295 turning on or off for branches 353 attaching source files 263 viewing details for branches 354 fixing issues 264 Indexing branches 352 user settings 262 changing index storage location 356 viewing issues 264 Indexing server Issues checking status 352 adding TestTrack issues 252 setting startup options 356 attaching source files 249, 263 starting 352 editing TestTrack issues 253 stopping 352 finding attached files 254 viewing log 355 fixing external issues 264 viewing server log 352 fixing TestTrack 253 Integrations Adobe CS5 and later 267 K client-side plug-ins 259 Key exchange 291 CMIS clients 267 changing 290 installing plug-ins 262 RSA 292 installing third-party 259 Keywords issue tracking 295 expanding 303 Mac Finder 266 supported 304 setting Xcode options 260 L supported integrations 259 Labeled file reports 150 third-party 259 Labels user options 259 applying to files 146 Windows Explorer 265 configuring 141 Interface 7 creating 143 Activity Log 8 deleting 145 Branch menu 8 deleting legacy 407 Branches tree 8 duplicating 145 file details pane 8 editing 144 Pending Changelists 8 hiding 145
467 Index: Legacy labels – Plug-ins
removing from files 151 restoring 374 renaming 144 non-RDBMS format 376 searching 147 RDBMS format 375 selecting 147 upgrading 401 unhiding 145 upgrading non-RDBMS 402 upgrading 406 upgrading old 401 viewing 144 Master proxy servers 410 viewing differences 148 Merge applications Legacy labels configuring 50 deleting 407 deleting settings 52 upgrading 406 editing settings 51 Licenses Merging adding 4 changelist files 133 viewing in use 284 checking in files 44 List reports files 43 adding 234 server options 294 Local directories unrelated files 44 creating 22 Moving Local SCM admin login 4 files 35 Locking databases 386 repositories 112 M repositories to different mainlines 370
Mac Finder plug-in 266 O Mail queue Open Containing Folder 14 deleting mail 395 Opening managing 395 local files 19 resending mail 395 toolbars 95 Mainline branches 161 working directories 14 adding existing 374 Oracle database connections 385 non-RDBMS format 376 P RDBMS format 375 Passwords copying to different databases 373 changing 10 creating 367 Pending changelists deleting permanently 377 viewing 8 exporting repositories 370 Pending Changelists tab 126 moving to different databases or servers 372 Plug-ins overriding options 368 client-side 259 removing 374 Mac Finder 266 renaming 368 user options 261
468 Index: Pop-up file details – Renaming
Windows Explorer 265 Purging data 301 Pop-up file details 93 Pushing changes to repositories 109 Post-event triggers 315 Q PostgreSQL database connections 384 Quick reports 245 Pre-event triggers 315 R Previewing duplicate changes 198 RDBMS connections promoted branches 180 adding 383 rebased branches 190 deleting 386 Printing editing 385 branch differences 177 upgrading 405 file differences 47 Reactivating branches 359 labeled files report 151 Rebasing 171 repository differences 108 actions 191 source file list 246 branches 187 Surround SCM Server log 394 preview 190 workflow diagrams 341 files 192 workflow transitions 339 Refreshing Source Tree window 92 Promoting 171 Regenerating RSA key pairs 294 actions 182 Registry utility 419 branches 178 indexing options 356 preview 180 proxy server options 415 files 183 starting 419 Properties Surround SCM Server options 419 branch 202 web server options 423 check out file 82 Regular expressions 208 custom fields 83 Removing general file 82 branches 364 repository 120 changelist file actions 129 shared files 83 changelists 128 Proxy servers 409 files 36 adding 411 files from code reviews 63 cache directory 410 labels from files 151 configuring 410 mainline branches 374 deleting 414 repositories 114 editing settings 414 states from workflow templates 338 modifying startup options 415 Renaming user options 414 branches 357 changelists 127
469 Index: Repairing databases – Restrictions
files 36 removing 114 labels 144 renaming 111 mainline branches 368 restoring 115 repositories 111 setting workflows 342 TestTrack field labels 397 shortcut menu 94 Repairing databases 387, 389 viewing cloaked 113 common issues 391 viewing shadow folders 121 Reports Repositories tree 8 adding 230 Requirements adding external reports 243 attaching source files 249 adding history reports 231 finding attached files 254 adding list reports 234 viewing 251 adding security group reports 237 Resending mail 395 adding trend reports 239 Resolving custom field and workflow issues 404 adding workflow progress reports 241 Restoring branch differences 175 deleted custom fields 313 charting report data 243 files 37 configuring 229 mainline branches deleting 244 non-RDBMS format 376 duplicating 244 RDBMS format 375 editing 244 removed branches 365 file differences 46 removed mainline branches 374 running 244 repositories 115 running quick 245 workflow states 335 types 229 Restrictions Repositories adding 207 bookmarking 226 branch and repository 215 cloaking and uncloaking 112 condition 212 controlling access 277 date 210 creating 105 event 213 deleting permanently 115 filter by action 216 diffing 106 label 214 resolving missing items 109 multiple list selection 211 exporting to mainlines 370 number 210 history 119 regular expressions 208 moving 112 security group 215 properties 120 TestTrack items 214 pushing changes 109 text 208 wildcard search 208
470 Index: Retrieving global users – Server log
Retrieving global users 283 commands 435 Reveal in Finder 14 controlling access to specific branches 277, 279 Reviewing examples 272 changes between versions 66 levels 271 file contents 68 overriding branch security 280 Risk score 255 server 273 Rolling back Security commands changelist actions 135 admin 437 resolutions 137 branch 443 files 27 files 441 promoted files 186 general 435 rebased files 195 security groups 440 RSA key exchange 293 users 440 downloading key pair 293, 421 Security groups regenerating keys 294 adding 274 S deleting 277 Saving duplicating 277 branch differences 177 editing 276 file differences 47 reports 237 labeled files report 151 Security Groups window 273 repository differences 108 viewing 276 source file list 245 Server connections Surround SCM Server log 393 adding 5 SCCI plug-in installation 262 connecting to different server 5 Seapine License Server deleting 6 options 298 editing 6 starting 269 finding servers 5 Searching Server database committed changelists 131 changing location 382 file content 218 converting database type 380 regular expression examples 220 setting default location 380 wildcard examples 220 Server log files 205 indexing server 355 files attached to TestTrack items 254 Surround SCM Server labels 147 deleting entries 394 Surround SCM Servers 5 log levels 394 Security printing 394 client/server communication 290 saving 393
471 Index: Server options – States
setting options 296 shelving files 153 viewing 393 unshelving files 159 Server options Shortcut menus branch caching 362 customizing 94 changelists 305 Snapshot branches 162 email notifications 297 Sorting columns 92 file names and extensions 306 Source file list 8 general global options 288 Source Tree window 7 general mainline options 302 Activity Log 8 issue tracking integration 295 Branch menu 8 local SCM admin password 289 Branches tree 8 merge 294 customizing 91 RDBMS connections 383 displaying panes 92 RSA key exchange 293 file details pane 8 Seapine License Server 298 file status 17 send mail 297 hiding panes 92 server database 380 Pending Changelists 8 software update check 299 printing source file list 246 manual check 301 refreshing automatically 92 TestTrack integration 397 Repositories tree 8 Server security 273-274 saving source file list 245 Shadow folders source file list 8 adding 345 user options 92 configuring 345 SQL Server database connections 384 deleting 347 sscm addresses 225 editing 347 Starting updating 347 CMIS Admin Utility 427 viewing for repository 121 CMIS Server 427 Share link 117 indexing server 352 Sharing files 117 registry utility 419 Shelves Seapine License Server 269 adding new files 155 Surround SCM 4 creating 157 Surround SCM Server 270 deleting 158 Surround SCM Web Server 423 diffing files 158 States editing 158 adding 334 managing 156 adding to workflow templates 338 Shelves window 156 configuring 333 deleting 335
472 Index: Status – Trigger actions
editing 335 Test cases restoring 335 attaching source files 249 setting 34 finding attached files 254 Status 17 viewing 251 Surround SCM interface 7 TestTrack integration Surround SCM Server adding connections 247 adding connections 5 adding issues 252 connecting to different 5 attaching source files 249 deleting connections 6 configuring connections 247 editing connections 6 deleting connections 248 finding on network 5 editing connections 248 modifying startup options 419 editing field labels 397 setting up connections 4 enabling 397 starting 270 finding attached files 254 Surround SCM Web fixing issues 253 starting server 423 options 398 Syncing renaming field labels 397 moved items 109 selecting items 257 renamed items 109 syncing field labels 397 repositories and working directories 106 user settings 249 TestTrack field labels 397 viewing items 251 System user 315 Text search examples 220 T Third-party integrations 259 user options 259 Tables Thumbnail file details 93 creating database 379 Toolbars Templates changing the custom toolbar 96 adding workflow 336 customizing 95 adding workflow states 338 display options 95 deleting workflow 340 displaying 95 diagramming workflow 340 hiding 95 duplicating workflow 340 Tracking changes 199 editing email 323 Transitions editing workflow 339 editing 339 editing workflow transitions 339 Trend reports removing states from workflow 338 adding 239 setting default workflow 341 Trigger actions workflow 336 append event comment text 322 prevent an event 321
473 Index: Triggers – Viewer/editor
send email 322 RDBMS connections 405 set a custom field value 326 User interface mode set event comment text 322 changing 96 set workflow state 325 User options Triggers Add/Find In Files extensions 101-102 adding 317 diff/merge 49 adding actions 327 file dialog defaults 97 configuring 316 Add Files 100 deleting 328 Check In Files 98 deleting actions 327 Check Out Files 99 disabling 328 Get Files 97 duplicating 328 Shelve Files 103 editing 326 Undo Check Out Files 100 editing actions 327 file manager 14 enabling 328 general 9 environment variables 447 integration 259 examples 316 plug-ins 261 post-event 315 pop-up file details 93 pre-event 315 proxy server 414 running executables 320 setting default 308 U source tree 92 thumbnail file details 93 Uncloaking repositories 112 view/edit file 17 Undoing check out 23 Xcode integration 260 Unfreezing branches 358 Users Unhiding adding 281 branches 358 deleting 284 labels 145 editing 284 Unlocking databases 386 retrieving global 283 Unsharing viewing 283 files 118 viewing current license usage 284 files across branches 363 Users window 280 Unshelving files 159 Update check options 299 V Upgrading Viewer/editor legacy labels 406 changing text settings 19 mainline branches 401 deleting settings 19 non-RDBMS 402 editing settings 18 old 401
474 Index: Viewing – Workspace branches
Viewing Workflow progress reports branch differences 171 adding 241 branch history 201 Workflows branch index details 354 automating 333 branch properties 202 customizing 332 changelist details 125 editing transitions 339 check out file information 82 planning 333 cloaked repositories 113 printing transitions 339 custom field file information 83 resolving issues 404 file history 78 setting default 341 file history details 80 states files 17 adding 334 general file information 82 changing 34 graphical branch structure 203 configuring 333 graphical file history 81 deleting 335 issues 264 editing 335 label differences 148 restoring 335 label history 149 templates labels 144 adding 336 repository history 119 adding states 338 repository shadow folders 121 configuring 336 security groups 276 default 331 shared file information 83 deleting 340 TestTrack items 251 diagramming 340 users 283 duplicating 340 working directory differences 106 editing 339 Voiding check out 285 removing states 338 W setting for repositories 342 Working directories Web server adding 12 HTTPS 423 deleting 13 modifying startup options 423 diffing 106 WebDAV editing 13 accessing directories 451 editor 12 Linux access 455 opening 14 Mac OS X access 454 setting 11 web browser access 451 Workspace branches 162 Windows network place access 452 Windows Explorer plug-in 265 X
475 Index: Xcode integration options – Xcode integration options
Xcode integration options 260
476