Surround SCM
User Guide
Version 2016
Copyrights
© 2016 Seapine Software, Inc. All rights reserved.
Defect Scribe, QA Wizard Pro, Resource Thief, Seapine CM, SoloBug, SoloSubmit, Surround SCM, and TestTrack are trademarks or
registered trademarks of Seapine Software, Inc. in the United States and other countries.
Borland and StarTeam are trademarks or registered trademarks of Borland, Inc. in the United States and other countries.
Delphi and JBuilder are trademarks or registered trademarks of Embarcadero Technologies, Inc. in the United States and other
countries.
Acrobat Reader is a registered trademark of Adobe, Inc. in the United States and other countries.
Sun, JVM, Java, JavaScript, and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United
States and other countries.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.
Apple, Mac, Mac OS, Macintosh, Objective-C, and Safari are registered trademarks of Apple Computer, Inc.
Microsoft, Windows, Windows NT, Windows Server, Windows Vista, MS Windows, Active Directory, Internet Explorer, Outlook, SQL
Server, Visual SourceSafe, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United
States and/or other countries.
Linux is a trademark of Linus Torvalds.
Red Hat, Red Hat Enterprise Linux, and Fedora are registered trademarks of Red Hat, Inc. in the United States and other countries.
SUSE is a registered trademark of Novell Inc. in the United States and other countries.
Debian is a registered trademark of Software in the Public Interest, Inc.
Ubuntu is a registered trademark of Canonical Ltd.
IBM, ClearCase, and all other IBM brand and product names are service marks, trademarks or registered trademarks of IBM
Corporation or its subsidiaries in the United States and other countries.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
PVCS, Serena PVCS Professional Suite, and Serena PVCS Version Manager are registered trademarks of Serena Software, Inc.
All other product names mentioned herein are the trademarks of their respective owners. All other trademarks are the property of their
respective owners.
No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in
any form by any means without the written permission of Seapine Software, Inc.
Your license agreement with Seapine Software, Inc., which is included with the product, specifies the permitted and prohibited uses of
the product. Any unauthorized duplication or use of this software, in whole or in part, in print, or in any other storage and retrieval system
is forbidden.
Information in this document is subject to change without notice and does not represent a commitment on the part of Seapine Software,
Inc. Unless otherwise noted, all companies, products, street addresses, and persons contained herein are purely fictitious. Mention of
third-party companies and products is for informational purposes only and does not constitute an endorsement.
Seapine Software, Inc.
6960 Cintas Boulevard
Mason, OH 45040
(513) 754-1655
documentation@seapine.com
Contents
What's New
Getting Started
1
3
Starting Surround SCM
3
Managing server connections
4
Adding server connections
5
Editing server connections
6
Deleting server connections
6
Surround SCM interface
7
Setting general user options
8
Changing your password
Managing Working Directories
10
11
Setting working directories for repositories
11
Configuring working directories
12
Adding working directories
12
Editing working directories
13
Deleting working directories
14
Opening working directories
Setting the file manager on Linux
Getting and Viewing Files
14
14
15
Getting files
15
Understanding file status
17
Viewing files in Surround SCM
17
Setting file viewer and editor options
18
Setting the application for viewing and editing specific file types
18
Editing and deleting file viewer and editor settings
20
Changing file viewer and editor text display options
20
Opening local files from Surround SCM
Modifying Files
Checking out files
Creating local directories
21
23
23
25
Undoing check out
25
Editing files in Surround SCM
26
Checking in updated files
26
Rolling back files
29
Adding files to Surround SCM
30
i
Setting custom fields
Changing multiple custom fields
Changing workflow states
Entering electronic signatures
35
36
37
Moving files
37
Renaming files
38
Removing files
39
Restoring removed files
40
Deleting files permanently
40
Comparing and Merging Files
43
Viewing file differences
43
Merging files
45
Merging unrelated files
46
Running file differences reports
48
Viewing image file differences
50
Setting diff/merge options
51
Adding diff/merge applications
51
Editing diff/merge applications
53
Deleting diff/merge applications
54
Configuring diff/merge application settings
54
Performing Code Reviews
ii
34
57
About the code review process
57
Understanding code review status
59
Managing code reviews
60
Creating code reviews
61
Adding files to code reviews
62
Selecting code reviews
65
Removing files from code reviews
66
Starting code reviews
66
Opening code reviews
67
Editing code reviews
68
Reviewing files in code reviews
68
Reviewing changes between file versions
69
Reviewing files
70
Adding review comments to files
72
Editing and deleting review comments
73
Addressing code review comments
73
Viewing unaddressed review comments
73
Searching for code reviews
74
Running code review reports
75
Viewing code reviews files are included in
78
Deleting code reviews
79
Viewing File Information
81
Using the file details pane
81
Viewing line-by-line file changes
82
Working with annotate results
83
Viewing file history
84
Viewing file history details
86
Viewing graphical file history
87
Viewing file properties
88
Setting Up Email Notifications
91
Adding email notifications
91
Editing email notifications
94
Duplicating email notifications
94
Disabling and enabling email notifications
94
Deleting email notifications
94
Customizing Surround SCM
97
Customizing the Source Tree window
Setting Source Tree options
98
99
Setting file information display options
100
Customizing shortcut menus
101
Customizing toolbars
102
Changing the user interface mode
103
Changing defaults for Surround SCM dialogs
103
Setting Get Files dialog defaults
104
Setting Check In Files dialog defaults
105
Setting Check Out Files dialog defaults
106
Setting Undo Check Out Files dialog defaults
106
Setting Add Files dialog defaults
107
Grouping file extensions to find related file types
108
iii
Setting Shelve Files dialog defaults
Managing Repositories
111
Creating repositories
111
Viewing differences between repositories and working directories
112
Resolving missing moved and renamed items
115
Pushing changes to repositories
116
Renaming repositories
117
Moving repositories
118
Cloaking and uncloaking repositories
119
Viewing cloaked repositories
Removing repositories
120
120
Restoring repositories
121
Deleting repositories permanently
122
Sharing Files Between Repositories
125
Breaking shares
Viewing Repository Information
126
127
Viewing repository history
127
Viewing general repository information
128
Viewing repository shadow folders
129
Using Changelists
Creating changelists
Adding file actions to changelists
Managing changelists
Viewing changelist details
Working with pending changelists
131
131
132
132
133
133
Renaming changelists
135
Removing changelists
136
Editing changelist file actions
136
Moving changelist actions
136
Removing changelist file actions
137
Adding comments to changelist files
137
Committing pending changelists
137
Working with committed changelists
138
Searching for committed changelists
Rolling back changelist actions
iv
109
139
140
Rollback changelist action resolutions
Selecting changelists
Using Labels
142
144
145
Configuring labels
145
Creating labels
147
Viewing labels
148
Editing labels
148
Duplicating labels
149
Hiding labels
149
Deleting labels
149
Labeling files
150
Selecting labels
151
Searching for labels
151
Viewing label differences
152
Viewing label history
153
Running labeled files reports
154
Removing labels from files
155
Using Shelves
157
Shelving files
157
Adding files to existing shelves
159
Managing shelves
160
Creating shelves
161
Editing shelves
162
Deleting shelved files and shelves
162
Viewing shelved file differences
162
Unshelving files
163
Branching
About branches
165
165
When to branch
166
Branching example
167
Branch status icons
169
Creating branches
170
Using branch templates
172
Including and excluding repositories for new branches
173
Selecting branch templates
174
v
Merging Files Between Branches
Deciding between promoting, rebasing, and duplicating
177
Viewing branch differences
177
Copying files across branches during check in
180
Running branch differences reports
181
Promoting branches
184
Promote preview
186
Promote actions
188
Promoting files
189
Rolling back promoted files
192
Rebasing branches
193
Rebase preview
196
Rebase actions
197
Rebasing files
198
Rolling back rebased files
201
Duplicating selected changes across branches
202
Duplicate changes actions
205
Tracking duplicated changes
205
Viewing Branch Information
207
Viewing branch history
207
Viewing branch history details
207
Viewing general branch information
208
Viewing the graphical branch tree
209
Finding Files
Searching for files
Adding restrictions
Adding text restrictions
Using regular expressions
vi
177
211
211
213
214
214
Adding number restrictions
216
Adding date restrictions
217
Adding list value restrictions
217
Adding condition restrictions
218
Adding event restrictions
219
Adding label restrictions
220
Adding TestTrack item number restrictions
221
Adding external issue tracking attachment restrictions
221
Adding branch and repository restrictions
222
Adding action restrictions based on user and date
223
Searching for text in files
225
Differences between indexed and non-indexed searches
227
Text search examples
229
Configuring filters
231
Adding filters
231
Applying filters to the source file list
233
Editing filters
233
Duplicating filters
233
Deleting filters
234
Browsing to files and repositories
234
Bookmarking files, repositories, and branches
235
Managing bookmarks
Creating and Running Reports
236
237
Report types
237
Configuring reports
238
Creating reports
239
Creating audit trail reports
240
Creating code review coverage reports
244
Creating history reports
247
Creating list reports
249
Creating security group reports
252
Creating trend reports
254
Creating workflow progress reports
255
Charting report data
257
Adding external reports to Surround SCM
257
Editing reports
258
Duplicating reports
258
Deleting reports
259
Running reports
259
Running quick reports
259
Adding shortcuts to run reports from the Source Tree window
260
Changing report menu item names and icons
262
vii
Saving the source file list
262
Printing the source file list
263
Integrating with TestTrack
265
Configuring TestTrack connections
265
Adding TestTrack connections
265
Editing TestTrack connections
266
Deleting TestTrack connections
266
Entering TestTrack login information
267
Attaching source files to TestTrack items
267
Viewing TestTrack items
269
Adding TestTrack issues
270
Editing TestTrack issues
271
Fixing TestTrack issues
271
Finding files attached to TestTrack items
272
Analyzing issue risk in files
273
Selecting TestTrack items
275
Integrating with Third-Party Applications
Setting integration options
277
Setting plug-in options
278
Integrating with IDEs and applications that support SCCI
279
Integrating with issue tracking tools
280
Entering issue tracking login information
280
Attaching source files to external issues
281
Viewing external issues
282
Fixing external issues
282
Using the Windows Explorer and Mac Finder integrations
283
Using the Windows Explorer plug-in
283
Using the Mac Finder plug-in
284
Integrating with CMIS
Setting Up Surround SCM
285
287
Starting the Seapine License Server
287
Starting the Surround SCM Server
288
Controlling Security and User Access
viii
277
289
Security levels
289
Security examples
290
Controlling access with security groups
291
Adding security groups
292
Viewing security groups
294
Editing security groups
294
Duplicating security groups
295
Deleting security groups
295
Controlling access to specific repositories
295
Controlling access to specific branches
297
Setting branch security commands
298
Managing users
298
Adding users
299
Retrieving global users
301
Viewing users
302
Editing users
302
Deleting users
302
Viewing licenses in use
302
Voiding check out
303
Configuring the Surround SCM Server
Setting general global server options
305
307
Securing communication between clients and the Surround SCM Server
309
Configuring RSA key exchange
311
Setting server merge options
312
Activating third-party issue tracking plug-ins
314
Setting logging options
314
Setting email server options
315
Setting email notification options
316
Setting Seapine License Server options
317
Setting automatic software update check options
318
Checking for new Surround SCM versions
320
Scheduling data purges
320
Setting general mainline options
321
Supported keywords
323
Setting changelist server options
324
Setting minimum comment lengths for actions
325
Setting auto-detect and ignore file options
325
ix
Setting compliance options
327
Configuring default user options
328
Configuring Custom Fields
331
Adding custom fields
332
Editing custom fields
333
Deleting custom fields
333
Restoring deleted custom fields
333
Automating Actions with Triggers
Trigger examples
336
Configuring triggers
336
Adding triggers
337
Adding triggers to run executables
340
Adding triggers to prevent events
341
Adding triggers to append comments to events
342
Adding triggers to email users
343
Editing email templates
344
Adding triggers to set workflow states
346
Adding triggers to set custom field values
346
Editing triggers
347
Adding trigger actions
347
Editing trigger actions
348
Deleting trigger actions
348
Duplicating triggers
349
Disabling and enabling triggers
349
Deleting triggers
349
Configuring Workflows
About workflows
x
335
351
351
Workflow example
351
About the default workflow template
353
Customizing workflows
354
Planning your workflow
355
Automating workflows
355
Configuring workflow states
355
Adding workflow states
356
Editing workflow states
357
Deleting workflow states
357
Restoring deleted workflow states
358
Configuring workflow templates
358
Adding workflow templates
359
Adding states to workflow templates
360
Removing states from workflow templates
361
Editing workflow transitions
361
Editing workflow templates
362
Duplicating workflow templates
362
Deleting workflow templates
362
Diagramming workflows
363
Setting the default workflow
363
Setting workflows for specific repositories
364
Configuring Code Review Settings
Configuring Shadow Folders
365
367
Adding shadow folders
367
Editing shadow folders
369
Refreshing shadow folder contents
369
Deleting shadow folders
369
Maintaining Branches
371
Managing branch attributes
371
Indexing branches for optimized searches
374
Managing the indexing server
374
Turning branch indexing on or off
375
Viewing branch index details
376
Viewing the indexing server log
377
Renaming branches
378
Hiding and unhiding branches
378
Freezing and unfreezing branches
379
Inactivating and activating branches
379
Modifying templates for existing branches
380
Changing branch type
381
Changing branch caching
382
Setting branch caching server options
383
Removing branches
384
xi
Restoring removed branches
384
Deleting branches permanently
385
Managing Mainline Branches
387
Creating mainline branches
387
Renaming mainline branches
388
Overriding server options for specific mainline branches
388
Moving repositories to different mainline branches
390
Moving mainline branches to different databases or servers
392
Copying mainline branches to different databases
393
Removing mainline branches
394
Restoring removed mainline branches
394
Restoring RDBMS mainline branches
395
Restoring non-RDBMS mainline branches
396
Deleting mainline branches permanently
397
Maintaining Surround SCM Databases
399
Creating Surround SCM tables
399
Setting the default server database location
400
Converting the server database to a different type
400
Changing the server database location
402
Adding RDBMS connections
403
Editing RDBMS connections
405
Deleting RDBMS connections
405
Backing up Surround SCM databases
405
Locking databases for backups
406
Resolving database issues
406
Setting database analyze and repair options
406
Analyzing and repairing databases
408
Repairs for common database issues
410
Working with the Surround SCM Server Log
Server log levels
Managing Mail
xii
411
412
413
Resending mail
413
Deleting mail
413
Managing Auditable Processes
Configuring TestTrack Integration
415
417
Enabling TestTrack integration
417
Syncing field labels with TestTrack
418
Setting TestTrack integration options for repositories
418
Upgrading Surround SCM
Upgrading mainline branches
421
421
Upgrading old mainline branches
421
Upgrading non-RDBMS mainline branches
422
Resolving custom field and workflow issues
423
Upgrading RDBMS connections
425
Upgrading legacy labels
425
Deleting legacy labels
427
Using Proxy Servers
429
About proxy servers
429
Starting the Surround SCM Proxy Server
430
Configuring proxy servers
431
Adding proxy servers
432
Editing proxy server settings
434
Deleting proxy servers
435
Setting proxy server options
435
Managing the Surround SCM Web Server
Starting the Surround SCM Web Server
Managing the Surround SCM CMIS Server
437
437
439
Starting the Surround SCM CMIS Server
439
Starting the Surround SCM CMIS Admin Utility
439
Configuring CMIS Server options
439
Adding CMIS repositories
440
Editing CMIS repositories
441
Deleting CMIS repositories
442
Troubleshooting Surround SCM CMIS Server issues
Using the Surround SCM API
442
443
Avoiding conflicts with the Surround SCM Client and CLI
443
Using the C API
443
Using the Java API
444
xiii
Using the .NET API
Appendix A: Security Commands
447
General security commands
447
Admin security commands
449
Users security commands
452
Security Groups security commands
453
Files security commands
453
Branch security commands
455
Appendix B: Environment Variables
Appendix C: Accessing WebDAV Directories
461
465
Web browser
465
Windows network place
466
Mac OS X Finder
468
Linux filesystem path
469
Glossary
Index
xiv
445
471
475
What's New
Surround SCM 2016 includes the following key features. For a complete list of features, enhancements, and
bug fixes, check out the release notes.
Capture electronic signatures and run audit trail reports for compliance
purposes
To meet industry compliance regulations, such as Title 21 CFR Part 11 requirements, you can now capture
electronic signatures to track who signed off on files and when. Signature information is stored in the Surround
SCM database.
Administrative users can enable electronic signatures for workflow states. See Adding workflow states, page
356. Electronic signature settings, such as signature components and the certification message to include
with signatures, can be configured. See Setting compliance options, page 327.
When files are ready to be signed off on, users change the state and enter their electronic signature. See
Entering electronic signatures, page 37. During an audit, you can run audit trail reports to review and validate
signature records. See Creating audit trail reports, page 240.
Reset files to default workflow states when versions change
Administrative users can now configure workflow states to automatically reset to the default state when file
versions change. This helps ensure files are not in an incorrect state after they are updated and automatically
restarts the workflow. See Adding workflow states, page 356.
Run reports from the Source Tree window
You can now quickly run reports on files from the Source Tree window.
n
Run quick reports for one-time use from the Tools > Quick Reports menu instead of the Reports dialog
box. See Running quick reports, page 259.
n
Run saved reports on files in a specific repository from the shortcut menu. Right-click a repository and
select the report to run. Before you can do this, you need to create a plug-in for the report and then add the
report to the repository shortcut menu. See Adding shortcuts to run reports from the Source Tree window,
page 260.
View syntax highlighting in the built-in text file viewer and editor
Use syntax highlighting to display specific text in different styles and colors in the built-in file viewer and
editor. This makes file contents easier to read when you view and edit files, perform code reviews, and search
for text in files. See Changing file viewer and editor text display options, page 20.
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 287.
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 3 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 170.
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 23.
n
Check in files to share changes with other users. See Checking in updated files, page 26. 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 43.
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 170.
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
111.
n
Add files to Surround SCM. See Adding files to Surround SCM, page 30.
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 97 and Setting general user options, page 8.
Starting Surround SCM
Make sure the Seapine License Server and Surround SCM Server are running before you start Surround SCM.
3
Managing server connections
If this is your first time using Surround SCM and you have not set up any users, you can log in as the default
administrative user. The username is Administrator and there is no password.
Note: If you try to log in to Surround SCM and the Seapine License Server is not running or is not found,
you are prompted to log in using the local SCM admin password. This allows you to log in and verify the
Seapine License Server settings.
1. Windows—Choose Programs > Seapine Software > Surround SCM > Surround SCM Client.
Mac—Double-click the Surround SCM Client icon in the Applications/Surround SCM folder.
Linux—Enter /usr/bin/scmgui
The login dialog box opens.
2. Select the Server 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 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
You can delete any server connections you no longer use.
1. Choose File > Connect to Server to open the Surround SCM login dialog box.
2. Click Setup.
The Setup Server Connections dialog box opens.
3. Select the server and click Delete.
6
Surround SCM interface
You are prompted to confirm the deletion.
4. Click Yes.
The server is deleted.
Surround SCM interface
The Source Tree window displays the branches, repositories, and source files in Surround SCM. The actions
available in this window depending on the function you are performing and your security permissions.
You may want to take some time to familiarize yourself with the Source Tree window before working with
files. You can customize this window as you become more comfortable working in it. See Customizing the
Source Tree window, page 98.
#
Area
Use to:
Menu bar
Access all Surround SCM actions.
Toolbars
Access the most commonly used Surround SCM actions. To display or hide a
toolbar, choose View > Toolbars and the toolbar name. You can also add buttons to
the custom toolbar to include actions you frequently perform. See Customizing
toolbars, page 102.
Branch
menu
Switch between branches. Only branches you can access are displayed in the menu.
7
Setting general user options
#
Area
Use to:
Branches
tree
View available branches in a tree hierarchy. Many users hide the Branches tree and
use the Branch menu to access branches. To hide the Branches tree, choose View
and clear the Branch Tree option. Icons indicate branch type and status. See
Branch status icons, page 169.
Repositories
tree
View available repositories in a branch.
Source file
list
View all source files in a selected repository. You can customize the columns to
display the information you need. You can also filter the list to display specific files
and search for files by name. See Customizing the Source Tree window, page 98.
Shortcut
menus
Quickly perform common actions. Shortcut menus open when you right-click
windows and trees. You can customize the actions available in the Branches tree,
Repositories tree, and source file list shortcut menus. See Customizing shortcut
menus, page 101.
File details
pane
View the selected file’s properties, history, check out status, sharing information,
custom fields, and a preview of local image files. See Using the file details pane,
page 81.
Activity Log
tab
View information about the actions you perform on files, such as the file check out
location.
Pending
Changelists
tab
View pending changelists and commit changes. You can right-click a changelist or
file to perform an action on it. See Working with pending changelists, page 133.
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: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
1. Choose Tools > User Options then select the General category.
8
Setting general user options
2. Select any Server Connection options.
These are the same options in the Surround SCM login dialog box, except for the file compression option.
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.
3. Select a Text File Format option.
Select Append end-of-line if necessary to ensure text files end with an end-of-line character.
4. Select a File comparison option. Surround SCM compares files before updating the file status or
retrieving files from the server when a get or check out is performed.
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.
9
Changing your password
Select this option if you always want Surround SCM to use a specific computer name instead of the
operating system value. When Surround SCM starts, it caches the computer name from the operating
system. In some cases, the operating system may return the computer name inconsistently between
sessions, which can cause working directory issues or prompt you that files were checked out to a
different computer during check in.
For example, this may occur if you use a dual boot system and each boot configuration has the same
computer name, but the operating systems have a different directory structure.
7. Click OK to save the changes.
Changing your password
You may be able to change your Surround SCM password. You cannot change your password if it is centrally
managed by LDAP. Ask your Surround SCM administrator for help.
1. Choose Tools > Change Password.
The Change Password dialog box opens.
2. Enter the current password.
3. Enter and confirm the new password.
4. Click OK to save the changes.
10
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. You can then modify the local
copy in the working directory. Surround SCM compares the local file with the server file to determine the
status of the local copy, which can help you track which modified files need to be checked in.
By default, repositories inherit their working directories from the parent repository. The repository structure in
Surround SCM usually mirrors the directory structure where the files were created from. You can set the
working directory for the topmost repository and allow all subrepositories to inherit it from the parent.
You can perform the following tasks to configure and access working directories.
n
Set working directories for repositories to specify where to create local copies of checked out files.
n
Edit or delete existing working directories and configure new working directories for all computers you
access Surround SCM from.
n
Open working directories from Surround SCM to quickly find local copies of 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 to set the working directory for.
2. Choose Repository > Set Working Directory.
The Set Working Directory dialog box opens.
3. Enter a Working directory path or click Browse to select a directory.
4. Select Allow child repositories to inherit this working directory if you want child repositories to use
the same directory.
The working directory is set automatically when subrepositories are added.
5. Select Inherit working directory from parent to use the parent repository’s working directory.
The working directory is set as <parent’s path> \ <repository name>.
6. Select Get files to working directory to retrieve a copy of the files to the working directory.
11
Configuring working directories
Files in subrepositories are also copied to local directories if the Allow child repositories to inherit this
working directory option is selected. If the local directories do not exist, you are prompted to create
them. See Creating local directories, page 25.
7. Click OK to set the working directory.
Note: You are prompted to resolve conflicts if you reuse a working directory. Click Remove to
remove the existing setting and switch the working directory to the new repository. Click Don't
Remove to keep the existing setting and then select a directory not used for other repositories.
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 14.
5. Click Close to close the Working Directories dialog box.
Adding working directories
Add working directories to specify the local or network directories to map repositories to. When you check out
files, writable copies are added to the corresponding working directory.
1. Choose Tools > Working Directories.
The Working Directories dialog box opens.
2. Click Add.
The Surround SCM Repository Browser opens.
12
Editing working directories
3. Select a branch and repository and click OK.
The Add Working Directory dialog box opens.
4. Enter a Working directory path or click Browse to select a directory.
Note: Working directory conflicts occur if you reuse a working directory. To resolve a conflict, create
a new local directory or select a directory that is not used for other repositories.
5. Select Allow child repositories to inherit this working directory if you want child repositories to use
the same directory.
The working directory is automatically set when subrepositories are added.
6. Click OK.
The working directory is set.
Editing working directories
Edit a working directory to change the local or network directory to save writable file copies in and the child
repositories inherit settings.
1. Choose Tools > Working Directories.
The Working Directories dialog box opens.
2. Select a working directory and click Edit.
The Edit Working Directory dialog box opens.
3. Make any changes.
4. Click OK to save the changes.
13
Deleting working directories
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.
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 101.
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: User options apply only to the current user account logged in to the computer. 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
Surround SCM files are stored on the Surround SCM Server, which is a central location for all users to access
and back up source code and other files. You can get files from Surround SCM to retrieve a local copy to your
computer without affecting the copy on the server. You can also view text, binary, and image files directly in
Surround SCM or another application that you choose.
Depending on your role and security permissions, you can perform the following tasks to get and view files.
n
Get files to retrieve a local copy to a specified directory on your computer.
n
Review file status information to determine if local files are out of sync with Surround SCM.
n
View files in Surround SCM.
n
Open local copies of files in working directories to quickly locate files on your computer.
n
Select applications for viewing and editing files and configure settings for specific file types.
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 in Surround SCM. 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 for updates.
1. Select the files or repository and choose Activities > Get.
The Get Files dialog box opens.
2. Select the Location 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. Expand and select any additional check out options.
Get based on
Select options for retrieving files based on version, timestamp, label, or workflow state.
15
Getting files
n
Latest version gets the latest 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 151.
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.
Advanced options
Select advanced options to get writable files, force file retrieval from the server, enable auto-merges,
specify a file overwrite option, and set the timestamp on local files retrieved from the server.
16
n
Make files writable gets the files in read-write mode.
n
Force file retrieval from server gets the current version of the file from Surround SCM. Surround
SCM checks the local copy to determine if the file is current. Select this option to retrieve a new copy
of the file from Surround SCM even if the local copy is current.
n
Merge should first attempt auto-merge to enable auto-merges. You are only prompted to manually
merge files if auto-merge fails.
n
Overwrite option specifies what to do if the local file and server file are different, or how to handle
modified files in the working directory that were removed from the server. Prompt prompts you to
replace the file, skip the file, or merge the server and local files. If you merge the files, the get
operation finishes after the files are reviewed and merged. If you get a repository to the working
directory, this option prompts you to delete or skip the file. Replace automatically overwrites the local
file with the server file or deletes the local file if it was removed from the server. Skip skips the file.
n
File timestamp sets the timestamp on the local files when they are retrieved from Surround SCM.
Current sets the timestamp to the current date and time. Modified sets the timestamp to the date
and time the files were last modified. Check in sets the timestamp to the date and time the files were
last checked in.
Understanding file status
5. Click OK to get the files.
The files are copied to the specified directory.
Tip: If the local directory does not exist, you are prompted to create it. See Creating local directories,
page 25.
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,
Modified
A newer version was checked in after you modified the local file. This happens if you check out
a file, modify it locally, and another user checks in a new version.
Working
directory
conflict
Surround SCM cannot determine the working directory location. This happens if you set the
same working directory for two or more branches or another user sets a working directory in the
same location you did (for example, a shared network drive).
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 file viewer and editor options,
page 18.
1. Select the file.
17
Setting file viewer and editor options
2. Choose Activities > View File.
A read-only copy of the file opens in the selected viewer or application.
Setting file viewer and editor options
You can select the applications to use for viewing and editing files. You can also edit default settings for text,
binary, and image files, configure settings for specific file types, and change how text is displayed in the builtin viewer and editor.
Note: User options apply only to the current user account logged in to the computer. 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.
2. Click Add to add settings for specific file types. See Setting the application for viewing and editing
specific file types, page 18.
3. Select a setting and click Edit to change it. See Editing and deleting file viewer and editor settings, page
20.
4. Select a setting and click Delete to delete it. See Editing and deleting file viewer and editor settings, page
20.
5. Select any syntax highlighting, font, and tab width options to change how text is displayed in the built-in
file viewer and editor. See Changing file viewer and editor text display options, page 20.
6. Click OK to save the changes.
Setting the application for viewing and editing specific file
types
You can specify the application to use when viewing and editing specific file types. View and edit settings
associate file extensions with the built-in Surround SCM file viewer and editor, the application associated with
the file extensions in the operating system, or an application you prefer to work in.
18
Setting the application for viewing and editing specific file types
If you do not set a viewer or editor for a file type, the application selected in the default setting ('All other files')
is used. Following are the default viewer and editor settings for each file type.
File
type
Default viewer setting
Default editor setting
Binary
files
Application associated with the file type in the
operating system
Application associated with the file type in the
operating system
Image
files
Built-in Surround SCM file viewer
Application associated with the file type in the
operating system
Text
files
Built-in Surround SCM file viewer
Built-in Surround SCM file editor
Note: User options apply only to the current user account logged in to the computer. 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.
2. Click Add.
The View/Edit Settings dialog box opens.
3. Enter the File extensions to associate with the application. Separate multiple extensions with a
semicolon.
4. Select View or Edit from the View/Edit list to specify the action the settings apply to.
5. Select how to open the files.
n
Internal viewer/editor opens files in the built-in Surround SCM viewer or editor.
n
Associated application opens files in the application associated with them in the operating system.
(Windows/Mac only)
n
Selected application opens files in the selected application. Click Browse to select an application.
6. Click OK to save the changes.
Tip: Make sure you add both view and edit settings for an application. For example, if you add view
settings to use Notepad for .txt and .css files, also add an edit setting for Notepad with the same file
extensions. This ensures you use the same application to view and edit files of the same type.
19
Editing and deleting file viewer and editor settings
Editing and deleting file viewer and editor settings
You can edit file viewer and editor settings to change the default application used to open specific file types.
You can also delete viewer and editor settings you no longer need.
Note: User options apply only to the current user account logged in to the computer. 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.
2. Edit or delete the setting.
n
To edit a setting, select it and click Edit. Make any changes and click OK.
n
To delete a setting, select it and click Delete. Click Yes to confirm the deletion. You cannot delete the
default 'All other files' settings.
3. Click OK to save the changes.
Changing file viewer and editor text display options
The built-in Surround SCM viewer and editor opens when you view or edit files, perform code reviews, and
search for text in files. You can change the viewer and editor settings to use syntax highlighting, specify the
default font and size, and set a specific number of spaces to use for tabs.
To change the default application for viewing or editing specific file types, see Setting file viewer and editor
options, page 18.
1. Choose Tools > User Options then select the View/Edit File category.
2. Select Use syntax highlighting to display specific text in different styles and colors.
20
Opening local files from Surround SCM
Surround SCM supports syntax highlighting in ASP, C, C#, C++, CSS, HTML, Java, Javascript, OBJC,
OBJC++, Perl, PHP, Python, Ruby, and XML files. Syntax styles are automatically applied based on the
file type.
Note: Surround SCM uses KDE Advanced Text Editor (Kate) style highlight definition files, which
are installed in the syntaxhighlighting directory in the Surround SCM application directory. If
highlighting errors occur for a supported file type, review the errors.log file in this directory to
troubleshoot. You can also create and install custom Kate highlight definition files for other file types,
but Seapine does not support these files.
3. Select Only use for files smaller than and enter the maximum file size to control when syntax
highlighting is applied.
Large files take longer to open in code reviews when syntax highlighting is used. Set a limit to
automatically disable highlighting in large files to improve performance. The default value is 1024 KB.
4. To set the default font options, click Choose Font, select any options, and click OK.
5. Enter or select the number of spaces to set as the Tab width.
You can enter a value between 1 and 99. The default value is 8 spaces.
6. 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.
21
Modifying Files
Depending on your role and security permissions, you can typically perform the following tasks to modify
Surround SCM files.
1. Check out files to make changes to them. If you decide not to edit or save changes in a checked out file,
undo the check out.
2. Edit files from the working directory or directly in Surround SCM to update the contents.
3. When you finish updating files, check them in to back up your work and share the changes with other
users.
4. If you create new files as you work, add them to Surround SCM to make them available to other users.
You may also be able to perform the following tasks to modify files.
n
Roll back files to revert to a previous version.
n
Set custom fields to provide additional file information that your organization wants to track. You can also
perform bulk custom field changes to set custom fields for multiple files at the same time.
n
Change the state of files to move them through the configured workflow.
n
Move files to other repositories on the same branch.
n
Rename files to update filenames without affecting historical file information.
n
Remove files that are no longer needed. You can also restore files removed by mistake or destroy files to
permanently delete them.
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.
23
Checking out files
3. Select Exclusive check out to prevent other users from checking out the files or repository. This option
is only available if multiple check outs are allowed.
4. Select Recursive to check out all files from the selected repository and all subrepositories.
5. Expand and select any additional check out options.
Changelist options
Select changelist options to check 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 132.
Advanced options
Select advanced options to force file retrieval from the server, specify a file overwrite option, and set the
timestamp on local files retrieved from the server.
n
Force file retrieval from server checks 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.
n
Overwrite option specifies what to do if the local file and server file are different or how to handle
modified files in the working directory that were removed from the server. Prompt prompts you to
replace the file, skip the file, or merge the server and local files. If you merge the files, the check out
operation finishes after the files are reviewed and merged. Replace automatically overwrites the local
file with the server file. Skip skips the file.
Note: If you skip retrieval of a writable file that is old (out of sync with the server), you will lose
any changes in the old file when you check it in.
n
File timestamp sets the timestamp on local files when they are retrieved from the server. Current
sets the timestamp to the date and time the file is retrieved. Modified sets the timestamp to the date
and time the files were last modified. Check in sets the timestamp to the date and time the files were
last checked in.
6. Click OK.
24
Creating local directories
The files are checked out.
n
If the local and server files are different and you chose to merge them, 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
25.
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.
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 119.
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.
1. Select the files or repository and choose Activities > Undo Check Out.
The Undo Check Out Files dialog box opens.
25
Editing files in Surround SCM
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.
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 file viewer and editor options, page 18.
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 to check in the file after you save it. Click Save to save the file without
checking it in.
Checking in updated files
Check in updates files with changes, removes the lock on the files, makes changes available to other users,
and increments the version number by one.
Check in files whenever you are able to successfully build with the changes and your changes do not break
other areas of the code. If you use multi-user check outs, it may be necessary to merge files frequently.
Checking in regularly reduces the complexity of these merges, making it easier to resolve conflicts. Checking
in often also allows other users to access changes.
1. Select the files or repository and choose Activities > Check In.
The Check In Files dialog box opens.
26
Checking in updated files
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.
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 132.
n
Check in as part of the following changelist adds the files to a selected changelist. Select a
changelist from the list or select <New changelist> to create a new changelist.
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 <New code review> to create a new code review. See Creating code
reviews, page 61. Click Select to view code review details and determine which review to add the files
to. See Selecting code reviews, page 65.
27
Checking in updated files
Note: If you are checking in files as part of a changelist, the files are added to the code review after
the changelist is committed.
Local file options
Select local file options to indicate how to handle local files after the check in.
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.
Advanced options
Select advanced options to change workflow states, label files, skip the merge process, and update
version numbers when files are checked in.
28
n
Change state when version updated changes the workflow state to the selected state. Select the
state to set on the files. You may also want to select the Update version even if no change is
made option. If you do not select this option, the check out operation is canceled for files that were
not modified. Attach actions are not performed, check in triggers do not run, and the file state does not
change. If you are checking in the file as part of a changelist, the state changes after the changelist is
committed.
n
Label applies the selected label to the files. Select a label from the list or select <New label> to
create a label. See Creating labels, page 147. Click Select to view label details or search for a label.
See Selecting labels, page 151. Optionally select Update label with selected version to remove
the label from earlier versions when applying it to the new version. If you are checking in the file as
part of a changelist, the file is labeled after the changelist is committed.
Rolling back files
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 43.
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 267 or Attaching source files to external issues, page 281.
8. Click OK to check in the files.
Surround SCM automatically merges changes when files are checked in. If there are conflicts, the merge
application opens. See Merging files, page 45.
Note: If you changed the workflow state for the files, you may be prompted to enter an electronic
signature and reason. See Entering electronic signatures, page 37. You cannot set a state that
requires an electronic signature on files if a merge is required. If you need to change the state, clear
Change state when version updated, check in and merge the files to resolve conflicts, and then
manually change the state. See Changing workflow states, page 36.
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 version. For example, the
current version is 5 and you roll back to version 3. After the rollback, the new version is 6. Version 3 and
version 6 have the same contents.
When you roll back a shared file, all the shared files are affected. If you only want to change the file in the
specified repository, break the share then roll back the file.
Tip: If multiple files were updated when a changelist was committed, you can rollback the changelist
action to revert all the files at the same time. See Rolling back changelist actions, page 140.
1. Select the file and choose Activities > History.
The History dialog box opens.
2. Select the file version to roll back to and click Rollback File.
The Rollback File dialog box opens.
29
Adding files to Surround SCM
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 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.
30
Adding files to Surround SCM
2. Select a drive or directory from the Look in list and then browse to the directory to add files from.
Tip: You can prevent adding files with specific names and extensions. See Setting auto-detect and
ignore file options, page 325.
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 to find related file
types, page 108.
5. Select the files or folders 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.
31
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 34.
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 132.
n
Select View pending changelists after add to view the pending changelist.
Code review options
Select code review options to add the files to a code review.
Select Add new version to code review and select a code review. Select <New code review> to
create a new code review. See Creating code reviews, page 61. Click Select to view code review details
and determine which review to add the files to.
32
Adding files to Surround SCM
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.
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 36.
n
Select Label and select a label if your organization uses labels. Select <New label> to create a label.
See Creating labels, page 147. Click Select to view label details or search for a label. See Selecting
labels, page 151. Optionally select Update label with selected version to remove the label from
earlier file versions when applying it to the new version.
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.
33
Setting custom fields
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 267 or Attaching source files to external issues, page 281.
11. Click OK to add the files to Surround SCM.
Note: If you set a workflow state on the files, you may be prompted to enter an electronic signature
and reason. See Entering electronic signatures, page 37.
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 331 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.
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 30.
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 properties, page 88.
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 170.
n
Promoting and rebasing does not change the custom field values set on files that already exist in the
destination branch.
34
Changing multiple custom fields
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 81 and Customizing the Source Tree window,
page 98. 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 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.
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 to search for. Enter the replacement
text in the With field.
n
To keep the current field value, select <Do not change>.
3. Select Set custom fields recursively to change the field values on all files in the selected repository and
all subrepositories.
4. Click OK.
The field values are changed.
35
Changing workflow states
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 file properties, page 88.
n
Add Files dialog box—See Adding files to Surround SCM, page 30.
n
Check In Files dialog box—See Checking in updated files, page 26.
n
History dialog box—See Viewing file history, page 84.
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 84.
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.
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 Change state recursively to apply the state change to all files in the selected repository and all
subrepositories.
5. Click OK to change the state.
Note: You may be prompted to enter an electronic signature and change reason. See Entering
electronic signatures, page 37.
36
Entering electronic signatures
Entering electronic signatures
Depending on the workflow, you may be required to enter an electronic signature for compliance purposes
when changing the workflow state on files. Signature information, including when files entered a specific
workflow state, is stored in the Surround SCM database.
1. The Signature Required dialog box opens after performing an action that changes a file's workflow state.
2. Enter your signature.
A signature may require a username, password, and reason for signing off on the file.
3. Click Sign.
The signature is saved.
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.
37
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 132.
5. Click OK.
The files are moved.
Renaming files
You can rename files if the current filename is incorrect. Filenames must be unique. They cannot match an
existing or removed file in the same repository.
1. Select a file and choose Activities > Rename File.
The Rename File dialog box opens.
38
Removing files
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 132.
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.
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.
39
Restoring removed files
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 132.
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
You can restore files removed from a repository if they were not destroyed. All historical file information is also
restored with the file.
1. Select the repository that contains the file 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.
3. Select a file and click History to view the file history. Click Properties to view the file properties.
4. Select the files to restore and 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 to destroy and choose Activities > Properties.
40
Deleting files permanently
The Properties dialog box opens.
2. Click the Removed Items tab. This tab includes a list of all removed files and repositories.
3. Select a file and click History to view the file history. Click Properties to view the file properties.
4. Select the files to destroy and then click Destroy.
The Destroy Files/Repositories dialog box opens.
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.
41
Comparing and Merging Files
Before you check in file changes, you may need to review differences between the file in your working
directory and the current version in Surround SCM. Diffing and merging files is crucial if you use non-exclusive
check outs and other users make changes to the same files you are working with. This helps ensure all the
correct changes are added to the file in Surround SCM.
Note: Diff3 and Guiffy are the default diff/merge applications integrated with Surround SCM. You can
configure different applications to diff and merge specific file types. See Setting diff/merge options, page
51.
You can perform the following tasks to compare and merge files.
n
View file differences to compare the local file to a file version in Surround SCM and accept or reject
differences between them.
n
View image file differences to compare a local image file to a version in Surround SCM.
n
Merge files to manually resolve issues when Surround SCM cannot automatically merge file versions.
n
Run file differences reports to view the differences between two or more versions of a text file.
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
45.
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 82.
1. Select the file and choose Activities > Differences.
The Differences dialog box opens. Read-only information is displayed in the File to Compare area.
43
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:
44
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 46.
Merging files
5. Click Differences.
The differences application opens.
Note: You can change the application Surround SCM uses to diff files. See Adding diff/merge
applications, page 51.
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 Setting diff/merge options,
page 51.
1. Select the file and choose Activities > Merge.
The Merge dialog box opens.
2. Select Copy on server to merge changes with the latest version in Surround SCM.
45
Merging unrelated files
3. Click Advanced to select a different 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 in Surround SCM. See Merging unrelated
files, page 46.
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.
n
To check in the file, enter any comments and then click Yes, check in file.
n
To keep the file checked out, click No, keep file checked out.
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.
46
Merging unrelated files
For example, changes are made to the XYZ.txt file in the Branch B/Common Files repository. Similar changes
must also be made to the ABC.txt file in the Branch A/Code/Common Files repository. Merge the files to
share the changes.
1. Select the file and choose Activities > Merge.
The Merge dialog box opens.
2. Click Advanced.
The Second File area expands with additional options.
3. Select Unrelated files.
4. Click Browse to select the file to merge from.
The Surround SCM Repository/File Browser opens.
5. Select a branch, repository, and file, and then click OK.
You return to the Merge dialog box.
6. Click Merge.
If the file to merge into is checked out, the merge application opens. If the file is not checked out, the
Check Out Files dialog box opens.
Note: If Surround SCM identifies a common ancestor for the selected files, a 3-way merge is
performed. Otherwise, the 2-way diff application is used.
The files are merged and the merge application closes.
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.
47
Running file differences reports
Running file differences reports
File differences reports include the differences between two or more versions of a text file. You can run these
reports when viewing file history. See Viewing file history, page 84.
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 Creating history reports, page 247.
2. Select the files to include in the report.
3. Click
.
The Generate File Differences Report dialog box opens.
4. Select a Version to Include option.
48
Running file differences reports
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.
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.
When you view differences, you may also want to see the parts of the files near the lines that differ to help
you understand what changed. This is the context.
If you are distributing new versions of files in the form of diff output, use one of the output formats that
show context so users can easily apply the differences.
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.
7. Click OK.
The report opens.
8. Click Save As to save the report or Print to print it.
9. Click OK when you finish.
Symbol meanings
The following symbols indicate differences in a differences report.
49
Viewing image file differences
Symbol
Meaning
!
A line that is part of a group of lines that changed between the two versions (context format
only)
+
Inserted line
-
Deleted line
Viewing image file differences
You can diff image files to view differences between file versions.
1. Select the file and choose Activities > Differences.
The Differences dialog box opens.
2. Select a Second File option or click Advanced to select a branched file, historic file version, or unrelated
file.
3. Click Differences.
The Image Comparison viewer opens.
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
50
Setting diff/merge options
Button
Use to:
View combined differences, which is the result of subtracting the pixel values of one
image from the other
View the high contrast result of subtracting the pixel values of one image from the
other. This view can help you identify subtle color differences.
Display the images at actual size
Zoom in
Zoom out
5. Click Close when you finish.
Setting diff/merge options
You can select the applications or utilities to use to diff and merge files. You can also change the default
diff/merge application settings and configure settings for specific file types.
Note: User options apply only to the current user account logged in to the computer. 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 to add a diff/merge application for specific file types. See Adding diff/merge applications, page
51.
3. Select a diff/merge setting and click Edit to change the configuration. See Editing diff/merge applications,
page 53.
4. Select a diff/merge setting for a specific file type and click Delete to delete the configuration. See
Deleting diff/merge applications, page 54.
5. Click OK to save the changes.
Adding diff/merge applications
You can add a diff/merge application to use to compare or merge specific file types.
51
Adding diff/merge applications
Note: User options apply only to the current user account logged in to the computer. 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. Enter the File extensions to associate with the application. Separate extensions with a semicolon.
4. Select Diff or Merge from the Diff/Merge list to specify the application type to add.
5. Enter or select any diff/merge options. The available options depend on the type of application you are
configuring.
Diff application options
Select a Compare with option to specify the utility or application to use to diff files with the specified file
extensions.
n
Binary comparison uses the internal binary file comparison utility to perform a byte-to-byte
comparison between two binary files.
n
Integrated Guiffy uses Guiffy to compare two text files. See the Guiffy help 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 control applications.
52
Editing diff/merge applications
Merge application options
Select a Two-way merge with option to specify the utility or application to use to merge two versions of
files with the specified file extension.
n
Integrated Guiffy uses Guiffy. See the Guiffy help 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 to work correctly.
Refer to the merge application documentation for information about the command line
requirements for integrating with source control applications.
You can also select a Three-way merge with option to specify the utility or application to use to perform
three-way merges. Three-way merges compare two updated versions against a common ancestor
version to merge file contents.
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.
6. Click OK to save the changes.
Editing diff/merge applications
You can edit diff/merge application options to change the diff or merge application to use when working with
specific file types or files with specific extensions.
Note: User options apply only to the current user account logged in to the computer. 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. Select a diff/merge setting and click Edit.
53
Deleting diff/merge applications
The Diff/Merge Settings dialog box opens.
3. Make any changes.
4. Click OK to save the changes.
Deleting diff/merge applications
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: User options apply only to the current user account logged in to the computer. 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. <Default> indicates that Guiffy will select the language.
n
Select Use Seapine default Guiffy toolbars to display only the Guiffy toolbars used in Surround
SCM.
3. Select a Microsoft Office Configuration option.
54
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.
55
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 57.
Depending on your role and security permissions, you can use the following options to work with and perform
code reviews.
n
Use the Code Reviews window to view the code reviews you have a role in. You can also create new code
reviews, open reviews, search for reviews, edit reviews, start reviews, run review reports, and delete
reviews from this window.
n
Add files that need to be reviewed to a code review. You can also remove files from reviews if they were
added by mistake.
n
View code reviews files are included in to make sure files needing review are in the appropriate review.
n
Review files in code reviews to provide feedback.
n
Mark review comments as addressed after making the changes and view unaddressed comments to track
what still needs attention.
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 59.
The following flowchart illustrates the built-in code review workflow, which uses triggers to automatically
email users when reviews are started and completed.
57
About the code review process
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 335.
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
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 61.
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 62.
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 273.
3. Start the review
58
Understanding code review status
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 66. 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 68. 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 70 and Reviewing changes between file versions, page 69.
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 73.
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.
Tip: Reports can help you analyze code review data. Code review reports include historical information
about a code review and files in it. Use these reports to review unaddressed comments, review your code
review process, or save process information for audits. See Running code review reports, page 75. Code
review coverage reports include information about file versions in code reviews and if the files reviews are
complete or still in progress. Use these reports to determine if you are ready to release your product,
measure coverage of your code review process, or demonstrate quality control during an audit. See
Creating code review coverage reports, page 244.
Understanding code review status
The status of a code review is displayed in the Code Review window Status column. Individual review file
status is also displayed. Information in this column can help you determine where files are in the review
process.
Following are the code review statuses.
Status
Explanation
Work
in Progress
Authors are adding files to a review.
Awaiting
Review
The code review is started and contains files that need review. An email about the review is
automatically sent to reviewers.
Needs
Attention
The review is complete and contains files with unaddressed comments. An email about the
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.
59
Managing code reviews
Following are the statuses for files in code reviews.
Status
Explanation
Awaiting
Review
The selected reviewers need to review the file. Files remain in this status until all the reviewers
review them. The status changes when the last reviewer marks the file as completed.
Needs
Attention
The file contains unaddressed comments.
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, report on reviews,
and delete reviews from the Code Reviews window.
Note: Administrators can configure code review settings for individual repositories to require or prevent
users from adding files to reviews when adding or check in files to Surround SCM. See Configuring Code
Review Settings, page 365.
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.
You can view reviews requiring your action, unapproved reviews you are an author for, unapproved
reviews you are a reviewer for, all unapproved reviews, or all approved reviews. All reviews on the
mainline branch that match the criteria are displayed. To search for a review, select <Advanced find>.
See Searching for code reviews, page 74.
4. Click Create Review to add a new review. See Creating code reviews, page 61.
5. Click Add Files to select files by changelist, label, or TestTrack item to add to the review. See Selecting
related files to add to code reviews, page 65.
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 62.
60
Creating code reviews
6. Select a review and click Open Code Review to open it. See Opening code reviews, page 67.
7. Select a review and click Start Code Review to notify reviewers that files are ready for review. See
Starting code reviews, page 66.
8. To report on reviews, select a Report on Code Reviews option and click Report On. See Running code
review reports, page 75.
9. Select a file or review and click Delete to remove the file from the review or delete the review. See
Removing files from code reviews, page 66 and Deleting code reviews, page 79.
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.
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 62.
61
Adding files to code reviews
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
Checking in updated files
n
Working with changelists
n
Promoting or rebasing
changes
n
Viewing file history
n
Analyzing issue risk
n
Selecting related files to
add to reviews
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 68.
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.
2. Select the Code review to add the files to.
n
62
To create a new review, select <New code review> and enter the review details. See Creating code
reviews, page 61.
Adding files to code reviews
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 65. 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 66.
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 30.
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 <New code review>. The Create Code Review dialog box
opens when you add the file. See Creating code reviews, page 61.
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 65.
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,
the differences between file versions are displayed. See Checking in updated files, page 26.
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 <New code review>. The Create Code Review dialog box
opens when you check in the file. See Creating code reviews, page 61.
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 65.
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 132.
1. Select a changelist or file in a committed changelist in the Changelists dialog box.
2. Click Add to Code Review.
63
Adding files to code reviews
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 65.
n
If you selected a committed changelist or file, the Add to Code Review dialog box opens. To create a
new review, select <New code review> and enter the review details. See Creating code reviews,
page 61. To add the files to an existing review, select the review from the list or click Select to view
review details and determine which review to add the files to. See Selecting code reviews, page 65.
Promoting or rebasing changes
You can add files to code reviews after promoting or rebasing changes between branches. When the files are
opened in a review, the differences between file versions are displayed. See Merging Files Between
Branches, page 177.
1. Select a file in the Promote Status or Rebase Status dialog box and click Add to Review.
The Add to Code Review dialog box opens.
2. Select the Code review to add the files to.
n
To create a new review, select <New code review> and enter the review details. See Creating code
reviews, page 61.
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 65.
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 84.
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 65 and Creating code reviews, page 61.
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 72. You can add the file
version to an existing review or create a new review. See Selecting code reviews, page 65 and
Creating code reviews, page 61.
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 273.
1. Select a file in the Analyze Risk dialog box.
2. Click a button to add the file to a review or review the file.
n
64
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 65 and Creating code reviews, page 61.
Selecting code reviews
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 72. You can add the file to an existing review or
create a new review. See Selecting code reviews, page 65 and Creating code reviews, page 61.
Tip: You can also drag files to code reviews from the Analyze Risk dialog box to quickly add the
current version to a review.
Selecting related files to add to code reviews
You can select related files to add to code reviews by changelist, label, or TestTrack issue, test case, or
requirement. When the files are opened in a review, the differences between file versions are displayed.
3. Choose View > Code Reviews.
The Code Reviews window opens.
4. Select the review to add files to and click Add Files.
The Add Files to Code Review dialog box opens.
5. Select a source type in Select files and versions by list and then select a source to display files from.
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 144.
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 151.
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 275.
6. 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.
65
Removing files from code reviews
2. Click Create Review to create a new review. See Creating code reviews, page 61.
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.
The Code Reviews window opens.
2. Expand the review that contains the file to remove.
3. Select the file to remove and click Delete.
You are prompted to confirm the deletion.
4. Click Yes.
The file is removed from the review.
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.
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.
66
Opening code reviews
Note: If the review has unaddressed comments and is in a Needs Attention state, you are prompted
to confirm starting the review. This can help you identify if the review contains comments you
addressed, but forgot to mark as addressed before restarting the review.
3. Enter or select a Due date.
4. Select the Reviewers.
5. Optionally make any changes to the review Notes, such as requests for the reviewers.
6. Click Start Review.
The review status changes to Awaiting Review and the reviewers are notified about the review.
You can edit started reviews to change the name, notes, authors, or reviewers. You can also revert
reviews before any files are reviewed to change the due date.
n
To edit the review information, open it, make any changes on the Properties tab, and click Apply. See
Editing code reviews, page 68.
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.
The Code Reviews window opens.
2. Select a code review and click Open Code Review.
The Code Review window opens.
3. Optionally select a filter to display the files 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.
67
Editing code reviews
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 68.
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 66 and Creating code reviews, page 61.
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.
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 69.
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 70.
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.
68
Reviewing changes between file versions
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 70.
1. Open the code review and double-click the file to review.
Differences between file versions open in a new tab in the Code Review window.
Note: Large files take longer to open in code reviews if syntax highlighting is used. You can set a
maximum file size limit in the user options to disable highlighting in large files to improve
performance. See Changing file viewer and editor text display options, page 20.
2. Click Previous Change and Next Change to go to the previous or next change.
3. To compare different versions, select a Version from the list to display in each area.
Versions not included in the review are displayed in gray. If you are reviewing updates after a review was
restarted, versions less than or equal to the last version you reviewed are displayed in italics.
4. Click a view button to display the differences side by side, top over bottom, or combined. You can also
view the file without the differences highlighted.
69
Reviewing files
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 50.
6. To find text in the file, enter the text in the search field and click Find.
7. Select content you have feedback about and click Add Comment to add a comment. See Adding review
comments to files, page 72.
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 73.
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 59.
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.
70
Reviewing 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 62.
1. Open the code review and double-click the file to review.
The file opens in a new tab in the Code Review window. Depending on how the file was added to the
review, differences between file versions may be displayed by default. Click to view the entire file
without highlighted differences.
Note: Large files take longer to open in code reviews if syntax highlighting is used. You can set a
maximum file size limit in the user options to disable highlighting in large files to improve
performance. See Changing file viewer and editor text display options, page 20.
2. To find text in the file, enter the text in the search field and click Find.
3. To view another version of the file, select the Version from the list.
Versions not included in the review are displayed in gray. If you are reviewing a file after a review was
restarted, the last version you reviewed and earlier versions are displayed in italics.
4. If you are reviewing an image file, click a button to change how differences are displayed or enter a
percentage to change the magnification. See Viewing image file differences, page 50.
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 69.
6. Select content you have feedback about and click Add Comment to add a comment. See Adding review
comments to files, page 72.
7. Click Previous Comment and Next Comment to go to the previous or next comment.
71
Adding review comments to files
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 73.
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 59.
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 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.
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.
72
Editing and deleting review comments
Note: If you need to make changes to a comment, you can edit, move, or delete it. See Editing and
deleting review comments, page 73.
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 67.
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 62.
6. Repeat steps 1 and 2.
7. Select the comment you addressed and click Mark Addressed or click Address All to address all
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.
73
Searching for code reviews
For example, if a file was added to a code review from a baseline branch and then promoted to the mainline
branch, users retrieving the file from the mainline can view the unaddressed review comments to see what
changes other users still need to make to the file.
1. Select the file in the Source Tree window and choose Activities > Code Review > View Unaddressed
Comments.
The View Unaddressed Comments window opens.
2. Make sure the corresponding Version is selected to view the content the comment applies to. The
version the comment was added to and the line number is displayed next to the comment. You can only
view the current version and versions that include unaddressed comments.
3. Close the window when you finish.
Searching for code reviews
You can search for code reviews based on status, author, reviewer, and files awaiting review by user.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select <Advanced find> in the Filter list.
The Advanced Find dialog box opens.
74
Running code review reports
3. Select the criteria that reviews must meet to pass the filter.
The Restriction dialog box opens. The options change based on the selected restriction.
4. Select the restriction value.
5. Click OK.
6. Repeat steps 3-5 to add additional restrictions.
7. Click Find.
Reviews that meet the criteria are displayed and the Find results filter is applied.
Running code review reports
When working with code reviews, you can run reports to view historical information about a code review and
files in it. Use these reports to see unaddressed comments, review your code review process, or save
process information for audits.
You can run the following types of code review reports:
n
Summary reports include a list of code reviews and the files in them.
n
Detail reports include more detailed information about each code review, the files in it, and comments
added to the files.
Tip: Code review coverage reports are also available. Use these reports to see file versions in code
reviews and if the individual file reviews are complete or still in progress. This report can you help you
determine if you are ready to release your product, measure coverage of your code review process, or
demonstrate quality control during an audit. See Creating code review coverage reports, page 244.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select the Mainline branch that includes the files and code reviews.
3. Select a Report on Code Reviews option.
n
All code reviews includes all reviews in the report.
n
Selected code reviews only includes specific reviews. Select the code reviews to include. To limit
the reviews displayed, select a Filter. To search for a review, select <Advanced find>. See
Searching for code reviews, page 74.
75
Running code review reports
Tip: All files in a selected code review are included in detail style reports. To only include specific
files, select the files to include in the review.
4. Click Report On.
The Code Review Report dialog box opens.
5. Select an Output format. Reports can be formatted in HTML or plain text format.
6. If the selected output format is HTML, select a Stylesheet to format the report.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Code review report
stylesheets are stored in the StyleSheets/CodeReview directory in the Surround SCM application
directory on the Surround SCM Server.
7. Select a report type. See Examples, page 77.
n
76
Summary style report includes general information about the review, including the name, status, due
date, authors, reviewers, and notes.
Running code review reports
n
Detail style report includes detailed information about the review and files in it. Select any of the
following options for these reports.
n
Include unaddressed comments includes all unaddressed comments for a file.
n
Include addressed comments includes all addressed comments for a file.
n
Include commented file contents with # lines of context includes the specified number of
context lines from the file before and after a comment. Including context lines can help you
understand more about the code a comment applies to. Context lines are only included for
comments in text files and not binary files.
8. Select a Sort comments by option to indicate the order to display review comments in the report.
n
Location in file organizes comments in the same order they are in the file.
n
Timestamp organizes comments based on date and time, from oldest to newest.
9. Click Run.
The report opens.
10. Click Save As to save the report or Print to print it.
These options are only available in the internal report viewer. If an HTML report opens in a browser, you
can save, export, or print the report from the browser.
11. Click Close when you finish.
Examples
Summary style report
The following example is a summary style code review report in HTML format.
Detail style report
The following example is a detail style code review report in HTML format. It includes unaddressed comments
only, commented file contents with two lines of context, and sorts comments by the location in the file.
77
Viewing code reviews files are included in
Viewing code reviews files are included in
You can view the code reviews that files are included in when viewing file history and analyzing risk of files
attached to issues. See Viewing file history, page 84 and Analyzing issue risk in files, page 273.
1. Select the file or version and click
.
The View Code Reviews dialog box opens. Only code reviews that include the selected file or version are
displayed.
2. If you are viewing a review from a risk analysis, select a review and click Open Code Review to open it.
See Opening code reviews, page 67.
3. Click Close when you finish.
78
Deleting code reviews
Deleting code reviews
You can delete code reviews that are no longer used. For example, you may need to delete a review created
by mistake or delete approved reviews that are no longer needed to free up server space.
Note: We do not recommend deleting code reviews because all review history is also deleted. Before
deleting a review, make sure users do not need access to it.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select a code review and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
The code review is deleted.
79
Viewing File Information
Surround SCM stores historical file information you can use to review the actions performed on files, where
files are checked out to, if files are shared between repositories, and custom field settings.
Depending on your role and security permissions, you can perform the following tasks to view more
information about a file.
n
Use the file details pane to view file properties, history, check out status, sharing information, and custom
fields directly in the Source Tree window. You can also view a preview of local image files.
n
View line-by-line annotations to trace the history of content changes between file versions.
n
View file history to review all actions performed on a file and work with historical versions.
n
View a graphical representation of file history to see a timeline of file history, including actions that caused
the version number to change and information about the branches that include the file.
n
View file properties to see more information about a file, such as the working directory, when it was last
modified and checked in, who checked it out and when, repositories that share it, and custom fields. You
may also be able to modify some file attributes and custom field values.
Using the file details pane
The file details pane provides a convenient way to work with files and access file commands. It displays file
properties, history, check out status, sharing information, custom fields, and a local preview of image files.
1. In the Source Tree window, choose View > File Details Pane.
The file details pane opens.
2. Select a file.
Information about the file is displayed.
3. Click the Properties tab to view file information, such as branch, filename, size, and workflow state.
81
Viewing line-by-line file changes
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 84.
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.
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 43.
1. Select a file.
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.
82
Working with annotate results
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.
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 151.
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 83.
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
83
Viewing file history
Consecutive lines with the same version number are grouped, indicated by different background colors. All
lines in a group share the column information displayed in the first row of the block. Only the Content column
information is different.
Note: If Surround SCM cannot annotate a line, a dash (-) is displayed and the line is grayed out. Deleted
lines are not annotated.
You can perform the following actions in the Annotate window:
n
To add or remove a column, right-click a column and select the column from the list. To move a column,
drag it to the new location.
n
To select all rows that contain the same value, click a value in the User, Version, Timestamp, or Event
Type column. 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
To open a pop-up window that includes all information and comments entered when an event was
performed, mouse over a line. This can help you see information in columns hidden in the Annotate
window.
n
To annotate a version that was promoted or rebased, click the link in the Event Type column.
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.
84
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 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 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
More information
View history details for the selected
version
Viewing file history details, page 86
View differences for the selected versions
Viewing file differences, page 43
Generate a report of differences between
versions
Running file differences reports, page 48
Retrieve a copy of the selected version
Getting files, page 15
Check out the selected version
Checking out files, page 23
View the selected version
Viewing files in Surround SCM, page 17
Edit the file
Editing files in Surround SCM, page 26
Revert to a previous file version
Rolling back files, page 29
View branches that contain changes made
in the selected version
Tracking duplicated changes, page 205
Review changes made in the selected
version
Reviewing changes between file versions,
page 69
Add the selected version to a code review
Adding files to code reviews, page 62
85
Viewing file history details
Button
Action
More information
View code reviews for the selected
version
Viewing code reviews files are included in,
page 78
Attach the selected version to an item in
TestTrack item or an external issue
tracking tool
Attaching source files to TestTrack items, page
267 and Attaching source files to external
issues, page 281
View the TestTrack item the selected
version is attached to
Viewing TestTrack items, page 269
View the committed changelist. Only
enabled if the action was performed as
part of a changelist.
Working with committed changelists, page 138
Set the workflow state for the file
Changing workflow states, page 36
Label the selected version
Labeling files, page 150
View labels applied to the selected version
Viewing labels, page 148
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 a file version and click Details.
The read-only History Details dialog box opens.
86
Viewing graphical file history
3. If the file is attached to an issue, click View to view the issue.
4. Click Edit Comments to modify the comments entered for the file action and click OK to save the
changes.
Note: Depending on your security permissions, you may only be able to edit comments you entered.
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.
87
Viewing file properties
2. Select the Branches to display. The branches that include the file version are selected by default.
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 43.
4. Click Save As to save the graph or Print to print it.
Viewing file properties
View the properties of a file to see more information about it, such as the working directory, when it was last
modified and checked in, who checked it out and when, repositories that share it, and custom fields. You may
also be able to modify some file attributes and custom field values depending on your security permissions.
1. Select a file and choose Activities > Properties.
The Properties dialog box opens.
88
Viewing file properties
2. Click a tab to view file information.
General
The General tab includes information about the file size, type, version number, current workflow state,
working directory, when it was last modified and checked in, and if keyword expansion is enabled. You
may be able to set or change the keyword expansion setting, file type, and workflow state.
Check Out
The Check Out tab includes information about who checked out the file and when. Only enabled if a
checked out file is selected. See Checking out files, page 23.
Sharing
The Sharing tab includes information about where the file is shared from and shared to. Only enabled if a
shared file is selected. See Sharing Files Between Repositories, page 125.
89
Viewing file properties
Custom Fields
The Custom Fields tab includes additional file information that your organization wants to track, such as
the user assigned to work on a file, a file description, or the user who owns the file. You may be able to
set or change the field values. See Setting custom fields, page 34.
3. Click OK when you finish.
90
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 91.
4. Select a notification and click Edit to change it. See Editing email notifications, page 94.
5. Select a notification and click Duplicate to duplicate it. See Duplicating email notifications, page 94.
6. Select a notification and click Disable to disable it. See Disabling and enabling email notifications, page
94.
Tip: Select a disabled notification and click Enable to enable it.
7. Select a notification and click Delete to delete it. See Deleting email notifications, page 94.
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.
2. Click Add.
91
Adding email notifications
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.
92
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 [<all branches>] and in repository [<all repositories>] precondition is selected by
default. An email is sent for every file if you do not select additional preconditions. The Precondition
dialog box does not open if you select the 'is part of a changelist commit' precondition.
7. Enter or select the precondition values.
Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding
restrictions, page 213.
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 344.
14. Click OK to add the notification.
93
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 a notification and click 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 344.
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 a notification and click Duplicate.
The notification is duplicated and added below the selected notification.
3. Select the new notification and click Edit.
4. Make any changes.
5. Click OK to save the changes.
Disabling and enabling 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 a notification and click 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
94.
1. Choose Tools > My Email Notifications.
The My Email Notifications dialog box opens.
2. Select a notification and click Delete.
94
Deleting email notifications
You are prompted to confirm the deletion.
3. Click Yes.
The notification is deleted.
95
Customizing Surround SCM
You can customize Surround SCM to help you work more efficiently. You can customize the interface to
display information most important to you, configure options to control how Surround SCM works, and create
email notifications to stay informed about changes.
Interface
You can perform the following tasks to customize the Surround SCM interface and get quick access to
information and actions you use most frequently.
n
Customize the Source Tree window to add, rearrange, and remove columns, sort columns to organize
displayed files, and hide or show panes.
n
Customize toolbars to add or remove buttons for commonly used actions and change how buttons are
displayed.
n
Changing the user interface mode, page 103 to display windows in a single parent window or as individual
windows.
n
Configure default settings for Surround SCM dialog boxes to set the options that are enabled or disabled
by default in file action dialog boxes, such as Get Files, Add Files, Check Out Files, Check In Files, and
more.
n
Customize shortcut menus to add, rearrange, or remove actions.
User options
You can perform the following tasks to set your preferences for using Surround SCM.
Note: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
n
Configure general user options to specify how to connect to the server, set the text file end-of-line format,
change the option for comparing files before updating their status, view HTML reports in an external
browser, and more.
n
Set Source Tree options to control information displayed in the Source Tree window and the default
double-click and drag-and-drop actions. You can also specify information displayed when you mouse over
a file.
n
Select applications for diffing and merging files and configure settings for specific file types.
n
Select applications for viewing and editing files and configure settings for specific file types.
n
Set Surround SCM as the default source control provider for third-party applications and enable integration
plug-ins.
n
Configure the Linux file manager used to open working directories from Surround SCM.
n
Set proxy server options to specify which server to use if your organization uses proxy servers for remote
clients.
n
Add directories and check status for plug-ins used for custom menus and menu items.
97
Customizing the Source Tree window
Email notifications
You can set up email notifications to be notified when files change. This helps you stay informed about the
changes you are most interested in.
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.
98
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.
or
is displayed next to the secondary
2. Shift+click a column heading to perform a secondary sort.
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 to display or hide.
Setting Source Tree options
You can set options to control the information displayed in the Source Tree window.
Note: User options apply only to the current user account logged in to the computer. 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.
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.
99
Setting file information display options
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 file
viewer and editor options, page 18 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 125.
n
Move automatically moves files to a location. See Moving files, page 37.
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: User options apply only to the current user account logged in to the computer. 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.
100
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 items in the branch, repository, and file list shortcut menus to include the actions you
perform most frequently.
You can also create plug-ins to add custom shortcut menu items.
n
To add a menu item that runs a report from the Source Tree window, create a plug-in for the report in
Surround SCM. See Adding shortcuts to run reports from the Source Tree window, page 260.
n
To add a menu item that provides access to third-party application functionality in Surround SCM, create
and install a custom client plug-in. See Surround SCM Custom Client Menus.
Note: User options apply only to the current user account logged in to the computer. 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.
101
Customizing toolbars
2. Select the item to add in the Available menu items list and click
items list.
to move it to the Current menu
To remove an item, select it in the Current menu items list and click
menu items list.
to move it to the Available
3. Select an item in the Current menu items list and click Top, Move Up, Move Down, or Bottom to
change the display order. You can also move the <separator> to divide the menu.
4. Click OK to save the changes.
Note: Click Reset to reset the shortcut menu items.
Customizing toolbars
The default toolbar, which is named Custom, includes buttons for the most commonly used actions. You can
add or remove buttons to the toolbar and change how buttons are displayed. You can also display or hide other
built-in toolbars, such as the Activities or Bookmarks toolbar.
Customizing toolbar options
You can change how toolbar buttons are displayed.
1. Choose View > Toolbars and select a display option.
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.
2. To hide a toolbar, choose View > Toolbars and select the toolbar to hide.
102
Changing the user interface mode
Note: On Mac OS X, only the default toolbar is available. To display it, choose View > Show Toolbar. To
hide it, choose View > Hide Toolbar.
Changing the custom toolbar
You can add buttons to the custom toolbar to access actions you frequently use.
1. Choose View > Toolbars > Customize Toolbar (Windows and Linux) or View > Customize Toolbar
(Mac OS X).
The Customize Toolbar dialog box opens. All available buttons and the default custom toolbar are
displayed.
Note: On Mac OS X, the toolbar button used to open the Properties dialog box is named Info.
2. Select an item and drag it to the custom toolbar.
You can also add the following items to the toolbar to group items:
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.
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.
103
Setting Get Files dialog defaults
Note: User options apply only to the current user account logged in to the computer. 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 131.
n
Perform actions as part of changelist enables the use of changelists when performing file actions.
If this option is enabled, <New changelist> is automatically selected in file action dialog boxes unless
the option to remember last selected changelist is also enabled.
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 43 and Merging files, page 45.
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.
Note: User options apply only to the current user account logged in to the computer. 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.
104
Setting Check In Files dialog defaults
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 26.
Note: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
1. Choose Tools > User Options then select Check In Files from the File Dialog Defaults category.
2. Change any default settings for the Check In Files dialog box.
105
Setting Check Out Files dialog defaults
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
23.
Note: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
1. Choose Tools > User Options then select Check Out Files from the File Dialog Defaults category.
2. Change any default settings for the Check Out Files dialog box.
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 25.
106
Setting Add Files dialog defaults
Note: User options apply only to the current user account logged in to the computer. 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 30.
Note: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
1. Choose Tools > User Options then select Add Files from the File Dialog Defaults category.
2. Change any default settings for the Add Files dialog box.
107
Grouping file extensions to find related file types
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 to find related file types
You can group file extensions to organize related file types 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 files to add to Surround
SCM or specify file types when searching for text in files.
Note: User options apply only to the current user account logged in to the computer. 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.
108
Setting Shelve Files dialog defaults
2. Click Add to create a group of file extensions.
The File Extension Settings dialog box opens.
3. Enter a Description of the group you are adding.
4. Enter the File extensions to include in the group. Separate multiple extensions with a semicolon.
5. Click OK to add the group.
6. Select a group and click Edit to change the group name or extensions included in it.
7. Select a group and click Top, Move Up, Move Down, or Bottom to change the display order.
8. Select a group and click Delete to delete it.
9. Click OK to save the changes.
Setting Shelve Files dialog defaults
Note: User options apply only to the current user account logged in to the computer. 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.
109
Setting Shelve Files dialog defaults
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.
110
Managing Repositories
Repositories group related files and subrepositories on branches. You can manually create repositories in
Surround SCM and then add files to them, or you can let Surround SCM create the repository structure as you
add new files. How and when you set up repositories depends on how your organization manages files.
Depending on your role and security permissions, you can perform the following tasks to set up and work with
repositories.
n
Create repositories to store files in.
n
Diff repositories and working directories to view differences between files in Surround SCM and local files.
n
Cloak repositories to skip them when recursively getting, checking out, and checking in files.
n
Push changes to repositories to update Surround SCM with multiple changes at the same time.
n
View a repository's properties to learn more about it.
You may also be able to perform the following tasks to manage repositories.
n
Control access to specific repositories
n
Move repositories to different locations
n
Rename repositories
n
Remove repositories that are no longer used
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.
111
Viewing differences between repositories and working directories
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.
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 132.
6. Click OK.
After creating a repository, you need to add source files to it. See Adding files to Surround SCM, page 30.
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 380.
Viewing differences between repositories and working
directories
You can diff a repository to see differences between Surround SCM and your working directory. You can also
perform actions on files and repositories while viewing the differences.
Tip: If your working directory contains many changes and you want to update Surround SCM to match it,
you can push changes to the repository to perform multiple actions at the same time. See Pushing
changes to repositories, page 116.
112
Viewing differences between repositories and working directories
1. Select the repository and choose Repository > Working Directory Differences.
The Working Directory Differences dialog box opens.
2. Click
to switch between tree view and list view.
3. Select Recursive to show all files in the repository and any subrepositories.
4. Select any Files to show options to control which files and repositories are included in the list.
n
Different contents shows files in the working directory that are different from the repository.
n
Different timestamps shows files in the working directory with a different timestamp than the
repository. The file contents are the same.
n
Identical shows files that are the same in the working directory and repository.
n
Missing locally shows files and subrepositories in the repository that are missing from the working
directory.
n
Missing from Surround SCM shows files and repositories in the working directory that have not
been added to Surround SCM. If a filename or extension matches an excluded value and this option is
selected, the file is shown if the Excluded by filename or extension option is also selected.
113
Viewing differences between repositories and working directories
n
Excluded by filename or extension shows all files regardless of name or extension even if Surround
SCM is configured to ignore some filenames and extensions when adding files. If a local file name or
extension matches an excluded value and this option is selected, the file is displayed if the Missing
from Surround SCM option is also selected.
n
In cloaked repositories includes files in cloaked repositories.
Note: Click Expand All to expand all repositories with differences. Click Collapse All to collapse
all expanded repositories.
5. Select a file or repository and click a button to perform an action.
114
Button
Use to:
More information
Differences
Compare the current file version in Surround SCM with the copy
in the working directory or another version to see the differences
between them.
Viewing file
differences, page 43
Merge
Merge the file in the working directory with the file in Surround
SCM.
Merging files, page
45
View
View the file. You can view the local or Surround SCM file.
History
View the file or repository history.
Viewing file history,
page 84 and Viewing
repository history,
page 127
Properties
View the file or repository information.
Viewing file
properties, page 88
and Viewing general
repository
information, page 128
Get
Retrieve a copy of the file or repository to the working directory.
Getting files, page 15
Add
Add the file or repository to Surround SCM.
Adding files to
Surround SCM, page
30
Check In
Check in the file to Surround SCM.
Checking in updated
files, page 26
Shelve
Shelve the file or repository in Surround SCM.
Shelving files, page
157
Remove
Delete the missing file or directory from the working directory. If
you select a local file or directory, you are prompted to confirm
the deletion. If you select a server file or repository, the Remove
Files or Remove Repository dialog box opens.
Removing files, page
39 and Removing
repositories, page
120
Resolving missing moved and renamed items
Button
Use to:
More information
Resolve
Missing
Resolve file differences if a file or repository was moved or
renamed. Ctrl+click the old and new item and then click
Resolve Missing.
Resolving missing
moved and renamed
items, page 115
6. Click Save As to save the differences list or click Print to print it.
7. Click Close when you finish.
Resolving missing moved and renamed items
Moved and renamed files and repositories are treated as unique items. When diffing working directories,
Surround SCM displays local and server copies of the same item as missing. For example, if a file was moved
from one working directory to another, the server copy is displayed as missing locally and the local copy is
displayed as missing on server. If you have move and rename security permissions, you can perform one
action to resolve differences between moved and renamed items, and maintain historical information for both
items.
Note: You can only resolve one difference. If an item was moved and renamed, you must manually
resolve the separate actions.
Resolving moved item differences
1. In the Working Directory Differences dialog box, Ctrl+click the original and moved items.
2. Click Resolve Missing.
3. Click Move Local to move the local copy to a different directory or click Move Server to move the server
copy to a different repository.
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.
115
Pushing changes to repositories
Pushing changes to repositories
You can push changes to repositories to update Surround SCM to match your working directory. For example,
if you use third-party source libraries that are frequently modified when new versions are available, you can
push changes to simultaneously move, create, and add files and repositories in Surround SCM.
Note: Pushing changes is a one-way update and does not affect working directory contents. 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 112.
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.
116
Button
Use to:
More information
Differences
Compare, accept, or reject
differences between file versions.
Viewing file differences, page 43
Renaming repositories
Button
Use to:
More information
View
View the local or server copy of
changed files.
Viewing files in Surround SCM, page 17 and
Opening local files from Surround SCM, page 21
History
View the file history.
Viewing file history, page 84
Properties
View the file properties.
Viewing file properties, page 88
5. Select the files with changes you want to push to Surround SCM.
All files and repositories with changes are automatically selected. The corresponding actions, such as
remove, add, and check in, are performed to push the changes to the repository. Clear any items you do
not want to include.
6. Enter any Comments, such as the reason for pushing changes to the repository.
7. Expand the Changelist options to select options for pushing changes as part of a changelist. See
Adding file actions to changelists, page 132.
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 267 or Attaching source files to
external issues, page 281.
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 137.
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.
117
Moving repositories
2. Enter a New Name and any Comments.
3. Expand the Changelist options to select options for renaming the repository as part of a changelist. See
Adding file actions to changelists, page 132.
4. Click OK.
The repository is renamed.
Moving repositories
You can move a repository to a different parent repository in the same branch. Keep the following in mind:
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 390.
1. Select a repository and choose Repository > Move Repository.
The Move Repository dialog box opens.
118
Cloaking and uncloaking repositories
2. Select a Destination Repository to move the repository to.
3. Enter any Comments, such as the reason for moving the repository.
4. Click OK.
The repository is moved.
Cloaking and uncloaking repositories
You can cloak repositories to skip them when you recursively get, check in, check out, or undo check out. All
subrepositories are also cloaked. For example, the Project A repository contains Code, Testing, and
Documentation subrepositories. You do not use any files in the Testing repository, but you frequently
recursively get the Project A repository. You can cloak the Testing repository to skip it when you get the
Project A repository.
Note: Cloaked repositories are specific to the computer they are cloaked on and the logged in user. Files
in cloaked repositories are not displayed when recursively viewing files in the source file list or working
directory differences.
1. Select a repository and choose Repository > Cloak Repository.
The repository is cloaked.
119
Viewing cloaked repositories
2. To uncloak a repository, select it and choose Repository > Uncloak Repository. The uncloaked
repository is included next time you recursively get, check in, check out, or undo check out.
Viewing cloaked repositories
You can view a list of all cloaked repositories.
1. Choose Tools > Cloaked Repositories.
The Cloaked Repositories dialog box opens.
2. To uncloak a repository, select the repository and click Uncloak.
You are prompted to confirm the uncloak.
3. Click Yes.
The repository is uncloaked.
4. Click Close to close the Cloaked Repositories dialog box.
Removing repositories
Remove a repository if it is no longer needed, but you want to keep it in case you need to use it again later.
When a repository is removed, its contents are not permanently deleted and can be restored.
1. Select the repository and choose Repository > Remove Repository.
The Remove Repository dialog box opens.
120
Restoring repositories
2. Enter any Comments, such as the reason for removing the repository.
3. Select Force recursive remove to remove the repository and all files and subrepositories.
4. Select Permanently destroy repository to delete the repository from the hard drive.
If you select Force recursive remove, this option changes to Permanently destroy repository and
contents.
5. Expand the Changelist options to select options for removing the repository as part of a changelist. See
Adding file actions to changelists, page 132.
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.
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 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 to restore.
121
Deleting repositories permanently
Tip: Click History to view repository history. Click Properties to view repository properties.
5. Click Restore.
The Restore Files/Repositories dialog box opens.
6. Enter any Comments, such as the reason for restoring the repository.
7. Select Recursive restore to recursively restore all subrepositories and files.
8. Click OK.
The repository is restored.
Deleting repositories permanently
When a repository is removed, it remains in the Surround SCM database unless it is destroyed. You may want
to destroy repositories that are no longer needed to free up space in the database. Destroyed repositories are
permanently deleted from Surround SCM and cannot be restored.
Note: You can also remove and destroy repositories at the same time. See Removing repositories, page
120.
1. Select the repository that contains the subrepository 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 to destroy and click Destroy.
The Destroy Files/Repositories dialog box opens.
122
Deleting repositories permanently
5. Enter any Comments, such as the reason for destroying the repository.
6. Click OK.
You are prompted to confirm the deletion.
7. Click Yes.
The repository is destroyed and cannot be restored.
123
Sharing Files Between Repositories
When you share a file, one copy of the file exists in multiple repositories. The file used to create the share is
the base file and the copies created in other repositories are share links. When the base file is updated, all
repositories reflect the updates simultaneously. Actions performed on the share links are applied to the base
file.
When a file is shared, the file history, filename, custom field values, and workflow state are maintained. Only
the file location is different. If a file or repository is shared in a branch, any subsequent branches maintain the
defined shared files.
Sharing is a useful feature with many applications. For example, if a EULA file is identical across several
projects, the EULA text file or Word document can be shared in each project repository. If an update is made
to the EULA file then those updates are automatically included in the next release of any of the projects that
contain the shared document.
Tip: Surround SCM Shares Explained provides more information about sharing.
1. Select the file or repository to share and choose Activities > Share Files.
The Share Files dialog box opens.
2. Select the repository 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.
125
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 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.
126
Viewing Repository Information
Surround SCM stores historical information about each repository that you can use to review the actions
performed on it, details about when it was created, the number of files and subrepositories in it, the associated
working directory, and the shadow folders used.
Depending on your role and security permissions, you can perform the following tasks to view more
information about a repository.
n
View repository history to review all actions performed on a repository and the files and subrepositories in
it.
n
View general repository information to see the working directories mapped to a repository and the number
of files and subrepositories it includes.
n
View shadow folder information to see all shadow folders associated with a repository.
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 to add. Click and drag the column to change its location. To hide a column, right-click a
column and select the column to hide.
2. Select any Filter by options to narrow the displayed actions.
127
Viewing general repository information
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.
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 138.
9. If file history is included, select a file and click File History to view the history. See Viewing file history,
page 84.
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.
128
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 367.
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.
129
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 131. 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 132.
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 137.
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 140.
Note: The Surround SCM administrator or another high-level user sets access to changelists. See Setting
changelist server options, page 324.
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 <New Changelist> from the <file action> as part of the following changelist list.
The Name Changelist dialog box opens when you perform the action.
3. Enter a New changelist name.
4. Click Attach to attach the changelist to items in TestTrack or an external issue tracking tool. See
Attaching source files to TestTrack items, page 267 or Attaching source files to external issues, page
281.
5. Click OK.
131
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 137.
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 to add the action to.
Select <New changelist> to create a changelist.
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
103.
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.
132
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 133.
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 138.
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.
133
Working with pending changelists
Note: To view or work with committed changelists, see Working with committed changelists, page 138.
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 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.
134
Button
Use to:
More information
View
Details
View details about the changelist or file actions.
Viewing changelist
details, page 133
Commit
Changelist
Commit the changelist, which perform actions on all files in
the changelist at the same time.
Committing pending
changelists, page 137
Renaming changelists
Button
Use to:
More information
Rename
Changelist
Rename the changelist.
Renaming changelists,
page 135
Remove
Changelist
Remove the changelist and all related file actions.
Removing changelists,
page 136
Set
Comment
Add comments to the file or all files in the changelist.
Adding comments to
changelist files, page
137
Attach
Attach the file or changelist to an item in TestTrack or an
external issue tracking tool. Changelists and files are attached
to items when changelists are committed. The Attach button
is only available if at least one selected changelist file includes
an Add or Check In action.
Attaching source files
to TestTrack items,
page 267 or Attaching
source files to external
issues, page 281
Edit Action
Details
Change the file action options.
Editing changelist file
actions, page 136
Move
Action
Move the file action to another changelist.
Moving changelist
actions, page 136
Remove
Action
Remove the file action from the changelist.
Removing changelist
file actions, page 137
Differences
Compare the file to another version.
Viewing file
differences, page 43
Edit File
Edit the file.
Editing files in
Surround SCM, page
26
Merge
Merge the file with another version.
Merging files, page 45
Add to
Code
Review
Add the changelist to a code review.
Adding files to code
reviews, page 62
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.
135
Removing changelists
2. Select the changelist and click Rename Changelist.
The Rename Changelist dialog box opens.
3. Enter a new name and click OK.
The changelist is renamed.
Removing changelists
You can remove pending changelists and all actions associated with them. Removing a changelist does not
delete any files, it only deletes the pending file actions.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the changelist and click Remove Changelist.
You are prompted to confirm the removal.
Note: If the changelist includes pending check ins, you are prompted to undo the check out after
removing the changelist. Click Remove and Undo Check Out to undo the check out after the
changelist is removed or Remove Only to remove the changelist and keep the files checked out.
3. Click Yes.
The changelist and all of the actions associated with the pending changelist are removed.
Editing changelist file actions
You can edit changelist file action options. If files have the same action type, you can edit details for multiple
files at the same time.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the file and click Edit Action Details.
The corresponding file action dialog box opens. For example, the Check In dialog box opens if you select
a file with a Check In action.
3. Make any changes.
4. Click OK to save the changes.
Moving changelist actions
You can move actions from one changelist to another.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the files and click Move Action.
The Move Actions dialog box opens.
136
Removing changelist file actions
3. Select the Destination changelist to move the files to.
You can also create a new changelist. See Creating changelists, page 131.
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 the file and click Remove Action.
You are prompted to confirm the removal.
Note: If you are removing check in actions, you are prompted to undo the check out on files. Click
Remove and Undo Check Out to undo the check out after the action is removed or Remove Only
to remove the action and keep the files checked out.
3. Click Yes.
The actions are removed.
Adding comments to changelist files
You can add comments to files in a changelist.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the files or changelist and click Set Comment. If you select a changelist, the comment is added to
all the files in the changelist.
The Set Comments dialog box opens.
3. Enter the comments.
4. Click OK.
The comments are added to the selected files.
Committing pending changelists
Changelist actions are not performed until you commit the changelist. When you commit a changelist, all files
in the changelist are submitted to the server at the same time.
137
Working with committed changelists
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the changelists and click Commit Changelist.
Note: If any changelist actions set or change workflow states on files, you may be prompted to enter
an electronic signature and reason. See Entering electronic signatures, page 37.
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 139.
3. Select a changelist or file and click the button for the action to perform.
138
Searching for committed changelists
Button
Use to:
More information
View
Details
View details about the changelist or file actions.
Viewing changelist details,
page 133
Get
Retrieve a copy of the file or all files in the changelist.
Getting files, page 15
History
View the file history.
Viewing file history, page 84
Differences
View differences between the version of the
changelist file and the version the action modified.
Viewing file differences, page
43
View File
View the file.
Viewing files in Surround SCM,
page 17
Add to
Label
Label the file or all files in the changelist. You can
only label files with Add or Check In actions.
Labeling files, page 150
Add to
Code
Review
Add the changes to a code review.
Adding files to code reviews,
page 62
Duplicate
Changes
Duplicate changes to another branch.
Duplicating selected changes
across branches, page 202
Rollback
Changes
Rollback changelist actions.
Rolling back changelist actions,
page 140
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 <Search> in the Filter changelists by list to specify additional filter criteria.
The Changelist Search dialog box opens.
139
Rolling back changelist actions
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.
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 142 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.
140
Rolling back changelist actions
3. Select a file or repository and click a button review the information. Review the information closely if
changes were made after the changelist was committed to determine how rolling back actions may affect
files.
Button
Use to:
More information
View
Details
View details about the changelist and action
performed.
Viewing changelist details, page
133
Differences
Compare file versions.
Viewing file differences, page 43
History
View the file history.
Viewing file history, page 84
Properties
View the file properties.
Viewing file properties, page 88
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:
Rollback
Changes
Undo the changelist action.
More
information
141
Rollback changelist action resolutions
Button
Use to:
More
information
Merge
Locally
Manually merge file versions. If the action to rollback changed file
contents, you may need to manually merge the files to maintain
changes made after the changelist was committed.
Merging
files, page
45
Rollback File
Force a rollback to the previous file version. When rolling back files, any
changes made after the changelist was committed are discarded.
Rolling back
files, page
29
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
Add
142
Status
Rollback resolution
Reason
Remove file
--
Remove file
New file added, not latest version
No resolution required
File removed
Rollback changelist action resolutions
Changelist action
Rollback resolution
Reason
Rollback change
--
Merge locally
Auto-merge conflict
Rollback file
Binary file changed, not latest version
No resolution available
File removed
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
Repository different than moved to repository
No resolution available
Repository removed
Restore file
--
No resolution required
File no longer removed
No resolution available
File destroyed
Restore repository
--
No resolution required
Repository no longer removed
No resolution available
Repository destroyed
Check In
Create Repository
Move Repository
Remove
Remove Repository
Status
143
Selecting changelists
Changelist action
Rename
Rename Repository
Status
Rollback resolution
Reason
Rename file
--
Rename file
Name different than renamed to
No resolution available
File removed
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 139.
3. Select changelist or file and click View Details to view the details. See Viewing changelist details, page
133.
4. Select a changelist and click Select to use it.
144
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.
145
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 425.
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 151.
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 147.
6. Select a label and click the button for the action to perform.
146
Button
Use to:
More information
View
View the label details.
Viewing labels, page 148
Edit
Edit the label to rename it, change the
branches it is available in, or remove it
from files.
Editing labels, page 148
Delete
Delete the label.
Deleting labels, page 149
Duplicate
Duplicate the label.
Duplicating labels, page 149
Differences
Compare two labels to determine the
missing, different, or identical files
between the labels.
Viewing label differences, page 152
Creating labels
Button
Use to:
More information
Attach
Attach labeled files to an item in
TestTrack or an external issue tracking
tool.
Attaching source files to TestTrack items,
page 267 or Attaching source files to external
issues, page 281
Add to
Code
Review
Add labeled files to a code review.
Adding files to code reviews, page 62
Toggle
Hidden
Hide or unhide the label.
Hiding labels, page 149
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.
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.
147
Viewing labels
6. Select Hidden to hide the label. Users cannot apply hidden labels to files or repositories.
7. Click OK to save the changes.
Viewing labels
You can view labels to see the files the label is applied to and the label history.
1. Select the mainline branch that includes the label.
2. Choose Tools > Labels. The Labels dialog box opens.
3. Select a label and click View.
The read-only View Label dialog box opens.
4. Click the Files tab to view the files that the label is applied to.
5. Click the History tab to view the label history.
Editing labels
You can edit a label to rename it, change the branches it is available in, or remove it from files. You can
change the branches that a label is available in based on the following rules:
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 155.
6. Click the History tab to view the label history. See Viewing label history, page 153.
7. Click OK to save the changes.
148
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 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: 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 149.
1. Select the mainline branch that includes the label 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.
149
Labeling files
Labeling files
You can apply labels to files to group them with related versions in a branch. For example, you can label a set
of files that are all affected by the same issue fix.
You can label the current file version on the Surround SCM Server or the version in your working directory. A
label can only be applied to one version of a file.
Note: You can also label files in committed changelists, in file history, and when you add, check in, or
promote files.
1. Select the files or repository and choose Activities > Advanced > Add Label.
The Add to Label dialog box opens.
2. Select a Label.
Select <New Label> to create a label. See Creating labels, page 147. Click Select to view label details or
search for a label. See Selecting labels, page 151.
3. Enter any Comments, such as the purpose of the label.
4. Select the File Version to apply the label to.
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 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.
The label is applied to the files.
150
Selecting labels
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 151.
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 147.
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 148.
6. Select a label and click Select to use it.
Searching for labels
If you do not know the name of the label 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 211.
1. In the Select Label dialog box, select Search For File in the Filter labels by field.
The Label Search dialog box opens.
151
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 213.
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 to compare.
4. Click Differences.
The Label Differences dialog box opens.
152
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 a file and click Differences to compare file versions. See Viewing file differences, page 43.
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.
153
Running labeled files reports
Running labeled files reports
Labeled file reports include a list of files and versions a label is applied to. Use these reports to view labeled
files that correspond to a milestone, such as a test or release.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Labeled Files Report.
The Generate Labeled Files Report dialog box opens.
3. Click Set to select a different branch and repository.
4. Select the Label to report on.
5. Select Recursive to include all subrepositories.
6. Select Hide repositories that do not contain files to exclude empty repositories.
7. Click OK.
The report opens.
154
Removing labels from files
8. Click Save As to save the report or Print to print it.
9. Click OK when you finish.
Removing labels from files
When you remove a label from a file, the file is longer grouped with related files. The file label history is
maintained with the label. See Viewing label history, page 153.
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.
155
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
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 157.
n
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 159.
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 112.
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 163.
Shelving files
Shelve files to store them in Surround SCM without adding or checking them in. You can only shelve files that
are modified from the current version or missing from Surround SCM.
Note: Use the Shelves window to shelve files that are not under source control. See Adding files to
existing shelves, page 159.
1. Select the files or repositories to shelve and choose Activities > Shelve Files.
The Shelve Files dialog box opens.
157
Shelving files
2. Select a Shelf to store the files in. The list includes shelves you own and shelves shared with you by
other users.
Select <New shelf> to create a shelf. See Creating shelves, page 161.
3. Expand the Local file options to select options for handling local files.
n
Get original version replaces the local file with the original Surround SCM version and reverts the
check out if files are checked out.
n
Get latest version replaces the local file with the latest Surround SCM 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.
158
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 163.
Adding files to existing shelves
You can add modified and new files in your working directory to existing shelves.
Tip: You can also drag files from your working directory or the Source Tree window to a shelf in the
Shelves window.
1. Choose View > Shelves.
The Shelves window opens.
2. Select a shelf to store files in and click Shelve Files.
The Add to Shelf dialog box opens.
3. Select the files to shelve.
4. Expand the Local file options to select options for handling local files.
n
Get original version replaces the local file with the original Surround SCM version and reverts the
check out if files are checked out.
n
Get latest version replaces the local file with the latest Surround SCM 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.
5. Select Recursive to shelve all new and modified files in the selected directory and all subdirectories.
159
Managing shelves
Note: Recursively adding files to a shelf ignores directories that do not have a matching repository on
the branch. Only modified and new files are added.
6. Click OK.
The files are added to the shelf.
Note: After a file is shelved, only other files from the same branch can be added to the shelf. However,
you can unshelve files across branches. For example, you may add new files to a shared shelf from the
working directory for a workspace branch. Other users can unshelve those files to the working directory
associated with their workspace branch or a baseline branch on the same mainline branch. See
Unshelving files, page 163.
Managing shelves
You can work with shelves and shelved files in the Shelves window.
1. Choose View > Shelves.
The Shelves window opens.
Tip: The number of files in a shelf is displayed in parentheses in the Change column.
2. Select a Mainline branch and optionally select a filter to view shelves you have access to.
3. Click Create Shelf to add a shelf. See Creating shelves, page 161.
4. Select a shelf or file and click a button to perform an action.
160
Button
Use to:
More information
Shelve
Files
Add files to the shelf.
Adding files to existing
shelves, page 159
Unshelve
Files
Retrieve the file or all files in a shelf to a local or working
directory.
Unshelving files, page
163
View File
View the shelved file.
Creating shelves
Button
Use to:
More information
Differences
Compare, accept, or reject differences between the shelved
a file in another location.
Viewing shelved file
differences, page 162
Edit Shelf
Edit the shelf to change the name, description, owner, and
sharing settings, and manage the files in the shelf.
Editing shelves, page
162
Delete
Remove the file from the shelf or delete the shelf.
Deleting shelved files
and shelves, page 162
Creating shelves
Shelves are temporary containers on the Surround SCM Server where you can store new and modified files
before adding or checking them in to Surround SCM.
When you create a shelf, you are the only user who can add files to it by default. You can change the owner
after the shelf is created. See Editing shelves, page 162.
Note: You can also create shelves when shelving files in the Source Tree window and the Working
Directory Differences dialog box. See Shelving files, page 157 and Viewing differences between
repositories and working directories, page 112.
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.
161
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 it. See Adding files to existing shelves, page 159.
Editing shelves
You can change the name, description, owner, and sharing settings for shelves, and manage the files in a
shelf. You can only edit shelves you own depending on your security permissions.
1. Choose View > Shelves.
The Shelves window opens.
2. Select a shelf and click Edit Shelf.
The Edit Shelf dialog box opens.
3. Make any changes.
4. Click OK to save the changes.
Deleting shelved files and shelves
You can delete shelves and files from shelves that are no longer used. Before deleting a shared shelf, make
sure users do not need access to it. Deleting a shelf also deletes any files stored in it.
1. Choose View > Shelves.
The Shelves window opens.
2. Select a shelf or file and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
The shelf or file is deleted.
Viewing shelved file differences
You can diff shelved files to compare, accept, or reject differences between the file stored in the shelf and the
file in another location.
Note: You cannot diff shelved files that are not yet under source control.
1. Choose View > Shelves.
The Shelves window opens.
2. Select a shelved file and click Differences.
The Differences dialog box opens. Read-only information is displayed in the First File area.
162
Unshelving files
3. Select a Second File option.
n
Server version of the shelved file compares the shelved file with the current file version in Surround
SCM.
n
Copy in working directory for branch compares the shelved file with the 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 a shelf or file and click Unshelve Files. If you select a shelf, all files in the shelf are retrieved.
The Unshelve Files dialog box opens.
163
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 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.
164
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 371 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 it as a starting
point. When a branch is created, files in both branches are identical. As file contents change, the branched
files become different from each other.
Use branches when you need to make changes to source files without affecting existing files. When you
branch a repository, changes can be promoted to or rebased from associated branches.
Note: Do not create a repository when you mean to create a branch. Repositories are used to organize
new files and other subrepositories while branches are used for parallel development based on existing
files. For example, when you are ready to release a product and start development on a new version,
create a branch for the release code instead of a repository.
Surround SCM includes mainline, baseline, workspace, and snapshot branches.
Tip: Icons indicate the branch type and status. See Branch status icons, page 169
Mainline branch
A mainline branch is the top-level branch that contains all source files, labels, other branches, and
repositories. An administrative user 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 387.
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.
165
When to 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.
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 one user. 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 the fixes, she promotes her changes to the baseline branch and moves on to development
for the next 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 not
available 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 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.
Note: Steps to create baseline, workspace, and snapshot branches are the same. The types of branches
you can create depends on your security permissions. See Creating branches, page 170.
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.
166
Branching example
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.
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.
167
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.
168
Branch status icons
This process of branching and promoting changes continues for all major and minor releases.
Branch status icons
The following icons indicate the status of branches in various areas of Surround SCM, including the branches
menu and tree in the Source Tree window.
Icon
Indicates:
More information
Mainline branch
About branches, page 165
Baseline branch
Snapshot branch
Workspace branch
Frozen mainline or baseline branch
Freezing and unfreezing branches, page 379
Frozen workspace branch
169
Creating branches
Icon
Indicates:
More information
Mainline branch with indexing on for text-based
searches
Indexing branches for optimized searches,
page 374
Baseline branch with indexing on for text-based
searches
Frozen mainline or baseline branch with indexing
on for text-based searches
Mainline branch that cannot load because a
database error occurred or the branch is in an old
format
Upgrading old mainline branches, page 421
Baseline, snapshot, or workspace branch that
cannot load because a database error occurred
Removed baseline branch
Removed snapshot branch
Only used in the Branch Maintenance dialog
box. See Managing branch attributes, page
371.
Removed workspace branch
Creating branches
Create a branch when you need to make changes to source files without affecting existing files. When you
create a branch, you can:
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.
170
Creating branches
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 172.
1. Select a branch and repository to create the new branch from.
If you do not want to include or exclude specific repositories in the new branch, make sure the repository
to use as the root repository in the new branch is selected. To include all repositories in the new branch,
make sure the root repository in the parent branch is selected.
2. Choose Branch > Create Branch.
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 <None>.
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 174.
n
To select the specific repositories to include or exclude in the new branch, select <New template>
and then click Modify to select the repositories. See Including and excluding repositories for new
branches, page 173.
4. Enter the New branch name.
Branch names cannot contain the following characters: \, /, *, ?
5. Enter any Comments, such as the purpose of the new branch.
171
Using branch templates
6. Select a Branch type. The list includes branch types you have security permissions to create. See About
branches, page 165.
7. Select a Create branch based on option.
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 151.
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.
172
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 173.
n
To change the repositories included in an existing branch, update the template in the branch properties.
See Modifying templates for existing branches, page 380.
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 174.
173
Selecting branch templates
1. Select <New template> in the Template field when creating a branch.
2. Click Modify.
The Branch Template dialog box opens and displays the parent branch repository structure.
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 380.
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.
174
Selecting branch templates
The Select Branch Template dialog box opens. Branches that use a template from the selected parent
branch and the included and excluded repositories are displayed.
Note: If multiple branches include and exclude the same repositories, only the branch that most
recently used the repository structure is displayed.
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.
175
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 184 and
Promoting files, page 189.
n
Rebasing changes from a parent branch down to a child branch. See Rebasing branches, page 193 and
Rebasing files, page 198.
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 202.
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 184.
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 193.
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 202.
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.
177
Viewing branch differences
2. Choose Branch > Branch Differences.
The Branch Differences dialog box opens.
3. Select the branch 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.
178
Viewing branch differences
The Differences column displays the reason for the difference.
Column
contains
Description
Color
<Differences>
The repository contains files that are different. Expand the
repository to view specific differences.
Gray
Identical
The file contents are the same.
White (or default
background color)
Changed
The file contents are different.
Yellow
Renamed
The file was renamed in one branch.
Green
Moved
The file was moved from one branch to another.
Blue
Removed
The file was removed from one branch.
Red
Missing
The file exists only in one branch.
Red
Excluded
The file was excluded from one branch based on the
template applied to it.
Gray
Note: If you do not have access to a repository in one of the branches, <restricted> is displayed
instead of the repository and filenames.
6. Select any display options.
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,
<removed> is displayed.
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 to perform.
Button
Use to:
More information
Differences
Compare a changed file with the file in the other branch.
You can only diff binary files if a diff application is
configured for the file extension.
Viewing file differences,
page 43 and Setting
diff/merge options, page
51
179
Copying files across branches during check in
Button
Use to:
More information
Diff Report
Generate a branch differences report.
Running branch
differences reports, page
181
View
View a read-only copy of the file.
Viewing files in Surround
SCM, page 17
History
View the file or repository history. Commands such as Edit
File, Check Out File, and Rollback File are not available in
the History dialog box because they can change the file
version.
Viewing file history, page
84 and Viewing repository
history, page 127
Properties
View the file or repository properties.
Viewing file properties,
page 88 and Viewing
general repository
information, page 128
Remove
Remove a missing file or repository from a branch.
Removing files, page 39
and Removing
repositories, page 120
Restore
Restore a removed file or repository in the branch.
Restoring removed files,
page 40 and Restoring
repositories, page 121
Rename
Rename a file or repository to use the name in the other
branch.
Renaming files, page 38
and Renaming
repositories, page 117
Promote
Update a file in the ancestor branch with changes from the
child branch.
Promoting files, page 189
Rebase
Update a file in the child branch with changes from the
ancestor branch.
Rebasing files, page 198
Merge
Merge a changed file with the file in the other branch.
Merging files, page 45
Copy
Copy a changed file to the other branch.
Copying files across
branches during check in,
page 180
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 177.
1. Select a changed file and click Copy.
The Copy Check In dialog box opens.
180
Running branch differences reports
2. Enter any Comments, such as the reason for copying the file.
3. Click Attach to attach the file to an item in TestTrack or an external issue tracking tool. See Attaching
source files to TestTrack items, page 267 or Attaching source files to external issues, page 281.
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.
Running branch differences reports
Branch differences reports include file differences between two related branches. You can run these reports
when comparing branches. See Viewing branch differences, page 177.
1. Select a branch or repository.
2. Choose Branch > Branch Differences.
The Branch Differences dialog box opens.
181
Running branch differences reports
3. Select the branch to compare the selected branch (Branch 1) with from the Branch 2 list. You can also
click Browse to select a branch.
4. Select Recursive to include all subrepositories and files.
5. Click Show Differences.
The Branch Differences dialog box opens.
6. Select a repository or two or more files and click Diff Report.
The Generate Branch Differences Report dialog box opens.
182
Running 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.
When you view differences, you may also want to see the parts of the files near the lines that differ to help
you understand what changed. This is the context.
If you are distributing new versions of files in the form of diff output, use one of the output formats that
show context so users can easily apply the differences.
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 opens. For information about report symbols, see Running file differences reports, page 48.
10. Click Save As to save the report or Print to print it.
11. Click Close when you finish.
183
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 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.
184
n
Latest version promotes the latest version of each file.
n
Timestamp promotes changes from the specified timestamp.
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 151. 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 and resolve conflicts based on the file status
and your security permissions. See Promote preview, page 186.
7. Select a file and click Promote File to promote it or click Promote All to promote all files.
The Promote Status dialog box opens. You can perform many of the same actions available in the
Promote Preview dialog box.
185
Promote preview
8. Click Close when you finish.
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.
186
Promote preview
2. Select a file and click a button to perform an action.
Button
Action
More information
Differences
Compare the file versions in the specified From branch and
To branch file.
Viewing file differences,
page 43
History
View the file history.
Viewing file history, page
84
Properties
View the file properties.
Attach
Attach the file to an item in TestTrack or an external issue
tracking tool. You can only attach successfully promoted
files that changed the version number on the destination
branch. Files removed, renamed, or in broken shares cannot
be attached.
Attaching source files to
TestTrack items, page
267 and Attaching
source files to external
issues, page 281
Add to
Code
Review
Add the file to a code review. You can only add successfully
promoted files that changed the version on the destination
branch. Files removed, renamed, or in broken shares cannot
be added to reviews.
Adding files to code
reviews, page 62
187
Promote actions
Button
Action
More information
Promote
File
Promote the file. You can view files that were promoted or
were not promoted, and files with conflicts. You can also
perform actions to resolve conflicts and promote files.
Promoting files, page
189
Merge
Locally
Manually merge the files.
Merging files, page 45
Remove
Parent
Remove the file from the parent branch. If you promote a file
that was removed from the child branch, you may need to
remove it from the parent branch.
Removing files, page 39
Break
Share
Unshare a file.
Breaking shares, page
126
Force
Promotion
Promote the file and overwrite the parent branch file.
3. Select Label promoted files in destination to label files in the ancestor branch. Select a label or select
<New label> to create a new label. See Creating labels, page 147. Click Select to view label details or
search for a label. See Selecting labels, page 151.
Labels are only added to files that are successfully promoted, force promoted, or merged locally. Files
removed, renamed, or in broken shares are not labeled. Any promote comments you entered are also
added to the label history.
4. Click Promote All to promote all files.
The Promote Status dialog box opens. You can view files that were promoted, files that were not
promoted, and files with conflicts. See Promote actions, page 188. You can also resolve file conflicts.
5. Click Save As to save the results list or click Print to print it.
6. Click Close when you finish.
Promote actions
Following are actions and corresponding reasons associated with promoting files. See Promoting branches,
page 184 and Promoting files, page 189.
188
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
Promote individual files from a child branch to a parent branch when you need to make sure the most recent
copy is available in the parent branch.
189
Promoting files
You can also promote branches to retrieve all files with changes to a parent branch. See Promoting branches,
page 184.
1. Select the files to promote and choose Branch > Promote File.
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 151. 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 perform actions and resolve conflicts based on the file status
and your security permissions. See Promote preview, page 186.
190
Promoting files
8. Select a file and click Promote File to promote it or click Promote All to promote all files.
The Promote Status dialog box opens. You can perform many of the same actions available in the
Promote Preview dialog box.
191
Rolling back promoted files
9. Click Close when you finish.
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 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.
192
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
43
History
View file history.
Viewing file history, page 84
Properties
View file properties.
Viewing file properties, page
88
Rollback
Rollback the selected file.
Rolling back files, page 29
Merge Locally
Manually merge the files.
Merging files, page 45
Force
Remove
Remove the file from the rollback
list.
6. Click Save As to save the rollback results list or click Print to print the list.
7. Click Rollback All to rollback all the files.
8. Click Close when you finish.
Rebasing branches
Rebasing detects and merges changes from the parent branch down to the child branch. This ensures the
child branch includes the most current files. For example, Cathy and Jon work on bug fixes in their workspace
branches. Jon completes his work and promotes changes to the parent branch. Cathy needs his changes to
fix a bug. She rebases from the parent branch to merge Jon’s changes into her workspace branch.
Rebasing only applies new changes to branches. It does not copy file contents between branches. The file
version that was last rebased from is tracked on the Surround SCM Server. If a version in the parent branch
was already rebased to the child branch, the file cannot be rebased until the version changes in the branch it
was rebased from. It does not matter if the file contents are different. See No Files to Rebase in Surround
SCM for information.
193
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 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 151.
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 perform actions and resolve conflicts based on the file status and
your security permissions. See Rebase preview, page 196.
194
Rebasing branches
6. Select a file and click Rebase File to rebase it or click Rebase All to rebase all files.
The Rebase Status dialog box opens. You can perform many of the same actions available in the Rebase
Preview dialog box.
195
Rebase preview
7. Click Close when you finish.
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.
196
Button
Action
More Information
Differences
Compare the branch file versions.
Viewing file differences,
page 43
History
View the file history.
Viewing file history,
page 84
Properties
View the file properties.
Viewing file properties,
page 88
Rebase actions
Button
Action
More Information
Attach
Attach the file to an item in TestTrack or an external issue
tracking tool. You can only attach files that were already
successfully rebased and changed the version number on the
destination branch. Files removed, renamed, or in broken
shares cannot be attached.
Attaching source files
to TestTrack items,
page 267 and Attaching
source files to external
issues, page 281
Add to
Code
Review
Add the file to a code review.
Adding files to code
reviews, page 62
Rebase
File
Rebase the file.
Rebasing files, page
198
Merge
Locally
Manually merge the files.
Merging files, page 45
Break
Share
Unshare the files.
Breaking shares, page
126
Force
Rebase
Rebase the file and overwrite the child branch file.
3. Select Label rebased files in destination to label files in the parent branch. Select a label or select
<New label> to create a new label. See Creating labels, page 147. Click Select to view label details or
search for a label. See Selecting labels, page 151.
Labels are only added to files that are successfully rebased or merged locally. Files removed, renamed, or
in broken shares are not labeled. Any rebase comments you entered are also added to the label history.
4. Click Rebase All to rebase all files.
The Rebase Status dialog box opens. You can view files that were or were not rebased and files with
conflicts. See Rebase actions, page 197. You can also access actions to resolve file conflicts.
5. Click Save As to save the results list or click Print to print it.
6. Click Close when you finish.
Rebase actions
Following are actions and corresponding reasons associated with rebasing files. See Rebasing branches,
page 193 and Rebasing files, page 198.
197
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 individual files from a parent branch when you need to make sure the most recent changes from other
users are available in a child branch. You can also rebase branches to retrieve all files with changes to a child
branch. See Rebasing branches, page 193.
198
Rebasing files
Rebasing only applies new changes to branches. It does not copy file contents between branches. The file
version that was last rebased from is tracked on the Surround SCM Server. If a version in the parent branch
was already rebased to the child branch, the file cannot be rebased until the version changes in the branch it
was rebased from. It does not matter if the file contents are different. See No Files to Rebase in Surround
SCM for information.
1. Select the files 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 151. 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 196.
199
Rebasing files
7. Select a file and click Rebase File to rebase it or click Rebase All to rebase all files. The Rebase Status dialog box opens. You can perform many of the same actions available in the Rebase
Preview dialog box.
200
Rolling back rebased files
8. Click Close when you finish.
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.
201
Duplicating selected changes across branches
Button
Use to:
More information
Differences
Compare file versions.
Viewing file differences, page
43
History
View file history.
Viewing file history, page 84
Properties
View file properties.
Viewing file properties, page
88
Rollback
Rollback the selected file.
Rolling back files, page 29
Merge Locally
Manually merge the files.
Merging files, page 45
Force
Remove
Remove the file from the rollback
list.
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 from one branch and apply them to another branch. You can
select specific files with changes to duplicate or 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.
202
Duplicating selected changes across branches
2. Select the branch that contains the changes in the From Branch list. If you selected files before opening
the Duplicate Changes dialog box, the branch containing the files is already selected.
3. Select the To Branch to duplicate the changes to.
4. Select a Select files and versions by option. If you selected files with changes before opening the
Duplicate Changes dialog box, <Selected files> is selected and the files are displayed.
n
Changelist duplicates changes associated with the selected changelist. Click Select to search for a
changelist or view changelist details. See Selecting changelists, page 144.
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 275.
n
Label duplicates changes associated with the selected label. Click Select to search for a label or view
label details. See Selecting labels, page 151.
in the Differences between versions column to select different historical file
5. Select a file and click
versions to duplicate changes from. If multiple actions incremented the file version number, you can
change the file versions to duplicate from to ensure that all changes are duplicated and to avoid automerge conflicts.
The History dialog box opens. Ctrl+click two file versions and click Select Versions.
6. Click Track Changes to view the branches that include the selected changes.
The Track Changes dialog box opens. You can view changes in branches by changelist, issue, or label.
See Tracking duplicated changes, page 205.
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.
203
Duplicating selected changes across branches
8. Select a file and click a button to perform an action. The actions you can perform depend on the file status
and your security permissions.
Button
Use to:
More information
Differences
Compare the From and To branch file versions.
Viewing file differences, page 43
History
View file history.
Viewing file history, page 84
Properties
View file properties.
Viewing file properties, page 88
Duplicate
Changes
Duplicate file changes to the destination
branch.
Duplicating selected changes across
branches, page 202
Merge
Locally
Manually merge the files.
Merging files, page 45
Force
Overwrite
Duplicate the file changes and overwrite the file
in the destination branch.
9. Select Label changed files in destination to label the files in the destination branch. Select a label or
select <New label> to create a new label. See Creating labels, page 147. Click Select to view label
details or search for a label. See Selecting labels, page 151.
Labels are only added to files that are successfully duplicated, force overwritten, or merged locally. Any
duplicate comments you entered are also added to the label history.
10. Select a file and click Duplicate Changes to duplicate it or click Duplicate All to duplicate all files.
The Duplicate Changes Status dialog box opens and displays files with duplicate actions and reasons.
See Duplicate changes actions, page 205. You can also perform many of the same actions available in
the Duplicate Changes Preview dialog box.
11. Click Save As to save the results list or click Print to print it.
12. Click Close when you finish.
204
Duplicate changes actions
Duplicate changes actions
Following are actions and corresponding reasons associated with duplicating changes. See Duplicating
selected changes across branches, page 202.
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.
205
Tracking duplicated changes
2. Select a Branch.
3. Select a Track changes for option. If you selected files with changes before opening the Track Changes
dialog box, <Selected files> is selected and the files are displayed.
n
Changelist tracks changes associated with the specified changelist. Click Select to search for a
changelist or view changelist details. See Selecting changelists, page 144.
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 275.
n
Label tracks changes associated with the specified label. Click Select to search for a label or view
label details. See Selecting labels, page 151.
4. Click Save As to save the results list or click Print to print it.
5. Click Close when you finish.
206
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 207.
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 209.
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 207.
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.
207
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 371.
208
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 using 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.
209
Viewing the graphical branch tree
2. Select the Branches 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 177.
4. Click Save As to save the graph or Print to print it.
210
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 211.
You can also search for specific phrases or text in file contents. See Searching for text in files, page 225.
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 231.
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 233.
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 234.
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 235.
Searching for files
You can search for files based on a variety of criteria, such as filename, version number, and file type. You
can use any combination of the available criteria to perform more complex searches.
To search for text in files, see Searching for text in files, page 225.
Tip: Use the Filename Search field above the source file list to quickly search for files by name. Filename
searches are not case sensitive and cannot include wildcard characters.
1. Choose Edit > Advanced Find Files.
The Advanced Find dialog box opens.
211
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 213.
4. Click OK.
The restriction is added. The values are displayed in the Restrictions list and the Summary field.
Note: To change a value, double-click it in the Restrictions list.
5. Add any additional restrictions.
6. Select Search recursively to search the selected repository and any subrepositories.
7. Click Find to search the files.
Files that meet the criteria are displayed. The Find files results filter is applied.
Tip: Create a filter or report if you frequently use the same criteria to perform a search. Filters allow
you to save search criteria and apply it to the source file list. Reports allow you to save search criteria
and set output options so you can analyze the data. See Applying filters to the source file list, page
233 and Creating reports, page 239.
212
Adding restrictions
Adding restrictions
Restrictions are criteria that files must meet to be included in filter results, advanced find results, and reports.
You can combine multiple restrictions to perform more complex searches. For example, you can create a
restriction to find files checked in to a specific repository in the past week by a specific user.
Surround SCM includes the following restriction types.
Restriction type
Limits results to files with:
More information
Text
Text that does or does not match text or a
regular expression.
Adding text restrictions, page 214
Number
Numbers that do or do not match a number
or number in a range.
Adding number restrictions, page
216
Date
Dates that do or do not match a date, date
range, or time period.
Adding date restrictions, page 217
List value
Values that do or do not match selected
values.
Adding list value restrictions, page
217
Condition
Attributes that do or do not match a
condition.
Adding condition restrictions, page
218
Branch/repository
Locations in a repository for a specific
branch or across all branches.
Adding branch and repository
restrictions, page 222
Event
File events that do or do not match events.
Adding event restrictions, page
219
Label
Labels that do or do not match text or a
regular expression.
Adding label restrictions, page 220
TestTrack item
number
TestTrack items that do or do not match a
number or number in a range or list.
Adding TestTrack item number
restrictions, page 221
External issue
tracking tool
attachment ID
Attachments that do or do not match an
item ID in an external issue tracking tool.
Adding external issue tracking
attachment restrictions, page 221
Actions based on user
and date
File actions performed by users on a date or
in a date range.
Adding action restrictions based
on user and date, page 223
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 91 and Configuring triggers, page 336.
213
Adding text restrictions
Adding text restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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, and other textbased information. For example, you can create a restriction to find files checked out to C:\Design.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
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 214.
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.
214
Using regular expressions
To match:
Use:
Example
Any single character
.
ab. matches ‘ab’ followed by any character, such as abc or
ab_
Zero or one occurrences of the
previous character
?
colou?r matches color or colour
Zero or more occurrences of the
previous character
*
a.* matches ‘a’ followed by any number of characters, such
as ab, abb, aab, or aabb
One or more occurrences of the
previous character
+
ba+ matches ‘b’ followed by any number of occurrences or
‘a’, such as ba, baa, or baaa
A specified number of occurrences of
the previous character
{...}
ba{3} matches baaa
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
of characters
[...]
[abc] matches a, b, or c
Any single character not included in a
set of characters
[^...]
[^abc] matches any character except a, b, or c
Any single character in a specified
range
[ - ]
[a-z] matches any lowercase character
[0-9] matches any digit, 0-9
Any single whitespace character
(space, tab, new line)
\s
v\s matches ‘v’ followed by a whitespace character
Any single non-whitespace character
\S
v\s matches ‘v’, not followed by a whitespace character
Any single digit (same as [0-9])
\d
v\d matches ‘v’ followed by a single digit, such as v1
Any single non-digit (same as [^0-9])
\D
v\D matches ‘v’ that are not followed by a digit, such as v_
The following symbols are also helpful for creating regular expressions.
To:
Use:
Example
Separate two or more alternatives to perform an OR search
|
(gray|grey) matches gray or
gray
Group several items as a single unit
(...)
(file1|2|3|4) matches file1,
file2, file3, or file4
Escape special characters for literal interpretation (modify the
meaning of the following character)
\
file\.txt matches occurrences
of file.txt
215
Adding number restrictions
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)
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
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
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.
216
Adding date restrictions
Adding date restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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
information. For example, you can create a restriction to find all files modified in the last two weeks.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
The Restriction dialog box opens.
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 list value restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
List value restrictions limit results to files that do or do not include all or selected values in a list. This
restriction is used to locate files based on checked out by user, status, workflow state, file type, list custom
field values, Surround SCM user custom field values, and other values. For example, you can create a
restriction to find all files with a Modified status.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
217
Adding condition restrictions
1. Select a restriction.
The Restriction dialog box opens.
2. Select is in list or is not in list to indicate if the files include the selected users.
3. Select an option to indicate the values to include.
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
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
The Restriction dialog box opens.
218
Adding event restrictions
2. Select is or is not to indicate the condition to search for.
For example, if you are creating a restriction on a check box custom field, select is checked to include
files with the check box field selected.
3. Click OK to add the restriction.
Adding event restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
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.
219
Adding label restrictions
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
214.
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.
Adding label restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
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
214.
5. If you entered text, select Match case to match the case of the text.
220
Adding TestTrack item number restrictions
6. Click OK to add the restriction.
Adding TestTrack item number restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
The Restriction dialog box opens.
2. Select the TestTrack Connection for the project to search.
3. Select is or is not to indicate if the files are attached to items with the specified number or number in the
specified range or list.
4. Select an option to specify the numbers to include.
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 external issue tracking attachment restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
External attachment ID restrictions limit results to files attached to items in integrated external issue tracking
tools, such as Bugzilla, that match or do not match a specific text string or regular expression for the
attachment ID. For example, you can create a restriction to find files attached to a bug in an issue tracking tool
with ID 10051.
221
Adding branch and repository restrictions
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a restriction.
The Restriction dialog box opens.
2. Select the Connection for the issue tracking tool to search.
3. Select does or does not to indicate if the issue ID includes matching text.
4. Select a matching option.
n
Match includes files attached to issues with IDs that match the specified text string.
n
Match regular expression includes files attached to issues with IDs that matches the specified
regular expression.
5. Enter the value or regular expression.
Surround SCM supports Perl-style regular expressions. See Using regular expressions, page 214.
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.
6. Click OK to add the restriction.
Adding branch and repository restrictions
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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.
Note: Preconditions, which are similar to restrictions, are used in triggers and email notifications. The
following information also applies to preconditions.
1. Select a branch and repository restriction.
The Surround SCM Repository Browser dialog box opens.
222
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 Include all branches to 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 include files in the selected repository and all subrepositories.
6. Click OK to add the restriction.
Adding action restrictions based on user and date
Restrictions are criteria that files must meet to be included in reports, filter results, and advanced find results.
You set restrictions when you add reports, add filters, or perform an advanced find.
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
runs the report.
1. Select the users have performed actions in date range restriction.
The Filter By Action dialog box opens.
223
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.
4. Select any Filter by Dates options.
224
Searching for text in files
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 find and open files you need to work with. For example, 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 one search term, only files that contain the exact term are returned with only whole word
matches. For example, if you enter 'WysiCorp', files that contain 'WysiCorp.h' or 'WysiCorporation'
are not returned. Whole words are defined in the Unicode Standard Annex Word Boundaries. You can
use wildcards for more flexible searching.
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 374.
1. Choose Edit > Find in Files.
The Find in Files window opens.
225
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
Do not use index searches without using the index if an indexed branch is selected. You may want
to select this option if you are searching for punctuation and the results do not include files you expect
them to. Keep in mind that non-indexed searches only include text files in the results and may be
slower. See Differences between indexed and non-indexed searches, page 227 for information about
how indexed and non-indexed searches work.
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 229 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 further refine the search.
226
Differences between indexed and non-indexed searches
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.
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 to find
related file types, page 108.
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 did an indexed
search, a relevance value indicates how closely the results match the search criteria. Click Show more
results to view additional results if the number to display is limited.
n
To narrow the results by filename, enter text in the Filename search field. Click
recently used filename. Click to clear the filename search.
to select a
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
To go to the file in the source files list, select it and click 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.
Differences between indexed and non-indexed searches
Surround SCM supports indexed and non-indexed searches for text in files. See Searching for text in files,
page 225. Indexed searches return results more quickly and include binary files, but you may need to use nonindexed searches depending on your needs.
The following information can help you understand more about indexed versus non-indexed searches.
227
Differences between indexed and non-indexed searches
Non-indexed searches
Non-indexed searches only look for matches in text files using a line-by-line search. Binary files are not
searched. When you search, Surround SCM opens each text file and parses it for the exact phrase you
entered as the search term. These searches can be slow if the branch or repository you are searching
contains thousands of files.
Indexed searches
Indexed searches look for matches in text and binary files. Performing indexed searches requires running the
indexing server and turning on indexing for branches that searches are performed on. See Indexing branches
for optimized searches, page 374.
Indexed searches have two steps:
1. A search engine-style search is performed by the indexing server. The server looks for the individual
words you entered as the search term to narrow the list of potential file matches and assigns a relevance
value.
2. Each text file included as a result from step 1 is opened and searched for the exact phrase you entered as
the search term. This is a line-by-line search similar to a non-indexed search except the search is
performed on a smaller subset of files, which makes the operation much faster.
The indexed search results contain binary files that pass step 1 and text files that pass step 2. Binary files
contain the search term in close proximity, but may not have an exact phrase match.
Tip: If indexing is turned on for a branch, you can still perform a non-indexed search. Select Do not use
index when performing a search.
Comparison
Support for:
Indexed search
Nonindexed
search
More information
Binary files in
search results
Yes
No
File types include Adobe PDF (.pdf), Microsoft
Excel (.xls, .xlsx), Microsoft Word (.doc, .docx),
Open Document Format (.odf), and Rich Text
Format (.rtf).
Common words,
such as ‘for’ and
‘if’, included in the
search term
Only in a phrase
Yes
Common words, such as 'for', 'if', 'in', and 'or' are
not indexed. Searching for ‘the’ finds results in a
non-indexed search, but not in an indexed search.
Searching for ‘the executable’ may find results in
both types of searches.
Punctuation-only
search term
Only when using
wildcards
Yes
Punctuation is not indexed. Searching for '&&'
does not return any results in an indexed search
unless you use wildcards.
228
Text search examples
Support for:
Indexed search
Nonindexed
search
Relevance value
to indicate how
closely results
match the search
term
Yes
No
Matching text
beyond the first
100,000 lines in a
file or first 1,000
characters in a
line
Yes. File is included
in results with a
relevance value, but
specific line numbers
are not in results.
No
More information
When searching text files, only the first 100,000
lines in each file and 1,000 characters in each line
are searched. These limits help prevent Surround
SCM from becoming unresponsive when
searching large files.
Common words
The following common words are not indexed in Surround SCM.
n
a, an, and, are, as, at
n
be, but, by
n
for
n
if, in, into, is, it
n
no, not
n
of, on, or
n
such
n
that, the, their, then, there, these, they, this, to
n
was, will, with
Text search examples
The following examples can help you understand how to use wildcards and regular expressions to perform
more flexible searches for text in files. See Searching for text in files, page 225.
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.
229
Text search examples
Wildcards
You can use wildcard characters to replace characters in search phrases. Wildcards are helpful if you are
searching for terms with spelling variations or text that may include other characters, such as dashes. They
are also helpful for finding partial word matches. For example, searching for 'run' does not find files that
contain 'running' or 'homerun', but a wildcard search using '*run*' will find 'running' and 'homerun'.
To substitute for:
Use:
Example
Zero or more characters,
excluding spaces
Asterisk
(*)
'gr*n' returns files that contain words such as 'green' and 'grain', but
does not return phrases such as 'greater than'.
One character,
excluding spaces
Question
mark (?)
'p?int' returns files that contain words such as 'print', 'point', and
'paint'.
Regular expressions
You can use the following regular expression syntax and symbols to search for text in file contents. Regular
expression searches only support individual terms. To search for a phrase, perform a search with or without
wildcards.
To match:
Use:
Example
Any single character
.
ab. matches ‘ab’ followed by any character, such as 'abc' or
'ab_'
Zero or one occurrence of the
previous character
?
colou?r matches 'color' or 'colour'
One or more occurrences of the
previous character
+
ba+ matches ‘b’ followed by any number of occurrences or
‘a’, such as 'ba', 'baa', or 'baaa'
Zero or more occurrences of the
previous character
*
a.* matches ‘a’ followed by any number of characters, such
as 'ab', 'abb', 'aab', or 'aabb'
Separate two or more alternatives to
perform an OR search
|
(gray|grey) matches 'gray' or 'grey'
A specified number of occurrences
of the previous character
{...}
ba{3} matches 'baaa
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 of characters
[...]
[tw]alk matches 'talk' or 'walk'
Group several items as a single unit
(...)
(file1|2|3|4) matches 'file1', 'file2', 'file3', or 'file4'
Interpret special characters as exact
literals
\
file\.txt matches occurrences of 'file.txt'
230
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 231.
3. Select a filter and click Edit to change it. See Editing filters, page 233.
4. Select a filter and click Duplicate to duplicate it. See Duplicating filters, page 233.
5. Select a filter and click Top, Move Up, Move Down, or Bottom to change the display order.
6. Select a filter and click Delete to delete it. See Deleting filters, page 234.
Adding filters
Filters allow you to quickly find files in the source file list based on specific criteria. For example, you can
create a filter to find files in a specific workflow state. The Filter list in the Source Tree window displays all
filters you have access to.
231
Adding filters
Note: You can also create filters in the Advanced Find dialog box. See Searching for files, page 211.
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 are not shared. You may only be able to create
private filters depending on your security permissions.
5. Select a Restriction to set the criteria files must meet to pass the filter.
The Restriction dialog box opens. The options change based on the selected restriction.
6. Enter or select the restriction values. See Adding restrictions, page 213.
7. Click OK.
The restriction is added. The values are displayed in the Restrictions list and the Summary field.
Note: To change a value, double-click it in the Restrictions list.
232
Applying filters to the source file list
8. Add any additional restrictions.
9. Click OK.
The filter is added. See Applying filters to the source file list, page 233 for information about using filters.
Applying filters to the source file list
You can filter the source file list to display specific files.
1. Select a filter from the Filter list.
Files that meet the filter criteria are displayed. The filter remains applied even if you select another
mainline branch or repository.
Note: Select List recursively to recursively display all files in the selected repository and subrepositories
that meet the selected filter criteria.
2. Select All Files from the list to display all files.
Editing filters
Edit a filter to change the name, if it is public or private, or the restrictions.
1. Choose Tools > Filters.
The Filters dialog box opens.
2. Select a filter and click Edit.
The Edit Filter dialog box opens.
3. Make any changes.
To change a restriction value, double-click the value in the Restrictions list.
4. Click OK to save the changes.
Duplicating filters
If you add filters that are similar, you can save time by duplicating and editing an existing filter.
1. Choose Tools > Filters.
The Filters dialog box opens.
2. Select a filter and click Duplicate.
The Duplicate Filter dialog box opens.
3. Enter a Filter name and modify the filter options.
233
Deleting filters
4. Click OK to save the changes.
Deleting filters
You can delete filters that are no longer needed.
1. Choose Tools > Filters.
The Filters dialog box opens.
2. Select a filter and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
The filter is deleted.
Browsing to files and repositories
Surround SCM addresses make it easy to browse to specific files or repositories. You can enter an address or
copy and paste an address to browse to repositories and files.
Tip: You can also enter web addresses to open web pages in your default browser.
1. Choose File > Go To Location.
The Go To Location dialog box opens. The address for the Surround SCM Server you are connected to is
displayed.
2. Enter the Address for the repository or file 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=<number> to the address. For example,
sscm://dev.wysicorp.com:4900//WysiDev//WysiWrite/Code/main.cpp?ver=3 opens the History
dialog box with version 3 of the main.cpp file selected. Click View File to view the selected version.
3. Click OK.
The repository or file is selected. You may want to bookmark the file or repository to quickly access it in
the future. See Bookmarking files, repositories, and branches, page 235.
Note: Use the Address toolbar to view the address for the selected repository or file. Choose View >
Toolbars > Address to open the toolbar.
234
Bookmarking files, repositories, and branches
Bookmarking files, repositories, and branches
You can bookmark files, repositories, and branches you frequently use to quickly access them from the
Bookmarks menu. The first nine bookmarks in the list are automatically assigned keyboard shortcuts. You
can rearrange bookmarks to change the order they are displayed in the Bookmarks menu and the assigned
keyboard shortcuts. See Managing bookmarks, page 236.
1. Select the file, repository, or branch to bookmark and choose Bookmarks > Add Bookmark.
The Add Bookmark dialog box opens with the bookmark address set in the read-only Address field.
2. Enter a bookmark Name and Description.
If you are bookmarking a branch, the branch name is used by default. If you are bookmarking a file or
repository, the file or repository name prepended with the branch name is used by default. For example,
WysiCorpDevelopment::Code or WysiWrite 2.0.x::main.cpp.
3. If you are bookmarking a repository or file, select a Navigation option to indicate the branch to access
when using the bookmark.
n
Always go to <BranchName> branch always navigates to the branch displayed in the Address
field. For example, if the bookmark contains the WysiCorp branch, Surround SCM always navigates
to the WysiCorp branch when using the bookmark.
n
Do not switch branches navigates to the repository or file in the branch selected in the Source Tree
window. If this option is selected, the branch name is removed from the Address field. For example, if
the bookmark contains the WysiCorp branch and the WysiCorp 1.x branch is selected when you use
the bookmark, Surround SCM navigates to the repository or file in the WysiCorp 1.x branch.
Note: Bookmarks with the Do not switch branches option selected are not available in Surround
SCM Web.
4. Click OK.
The bookmark is added. To use the bookmark, select it in the Bookmarks menu.
Note: If a bookmarked file, repository, or branch is moved or renamed, or the server address
changes, the bookmark may no longer work and an error is displayed when you access it. You can
delete the old bookmark and then create a new one. See Managing bookmarks, page 236.
235
Managing bookmarks
Managing bookmarks
You can rename bookmarks and rearrange them to change the order they are displayed in the Bookmarks
menu and the assigned keyboard shortcut.
1. Choose Bookmarks > Manage Bookmarks.
The Manage Bookmarks dialog box opens.
2. Select a bookmark and click Edit to rename it or change the description.
Note: You cannot change the Navigation option, which indicates if the bookmarked repository or file
opens on a specific branch. To change navigation, delete the old bookmark and then create a new
one.
3. Select a bookmark and click Top, Move Up, Move Down, and Bottom to change the order and keyboard
shortcuts. Only the first nine bookmarks are assigned keyboard shortcuts.
4. Select a bookmark and click Delete to delete it.
5. Click Close when you finish.
236
Creating and Running Reports
Reports provide an easy way to access, analyze, and share information about files, branches, and
repositories and the users who perform actions on them. You can create a variety of reports that focus on the
data you need. You can share reports with other users or keep them private.
Before you create or run reports, you may want to get familiar with the different types and content. See Report
types, page 237.
To create and run most reports, choose Tools > Reports. See Creating reports, page 239 and Running
reports, page 259. Other reports, such as branch and file differences reports, are available in other locations in
Surround SCM.
You can also add and run reports from external reporting services. See Adding external reports to Surround
SCM, page 257.
Report types
Surround SCM includes the following reports.
Report type
Displays:
More information
Audit trail
Information about file versions in workflow states that require
electronic signatures. Use this report to validate signature
records for compliance purposes.
Creating audit trail
reports, page 240
Branch
differences
File differences between two related branches.
Running branch
differences reports,
page 181
Branch
maintenance
List or tree structure of all branches and their attributes (e.g.,
frozen, active, etc.). Use these reports to document branch
configuration at a specific point in time.
Managing branch
attributes, page 371
Changelist
Information about file actions associated with pending or
committed changelists.
Working with pending
changelists, page 133
and Working with
committed
changelists, page 138
Code review
Historical information about a code review and files in it. Use
these reports to review unaddressed comments, review your
code review process, or save process information for audits.
Running code review
reports, page 75
Code review
coverage
Information about file versions in code reviews and if the files are
approved or still in review. Use these reports to determine if you
are ready to release your product, measure coverage of your code
review process, or demonstrate quality control during an audit.
Creating code review
coverage reports, page
244
237
Configuring reports
Report type
Displays:
More information
File
differences
Differences between two or more versions of a text file. Use
these reports to document code changes or generate code patch
files.
Running file
differences reports,
page 48
History
Historical information about actions performed on files, including
details about who, what, where, and when for each action. Use
these reports to determine what changed recently or to find
changes made by a specific team member that may need a code
review.
Creating history
reports, page 247
Labeled file
Files and versions that a label is applied to. Use these reports to
view labeled files that correspond to a milestone, such as a test
or release.
Running labeled files
reports, page 154
List
Current information about files, organized in columns. Optionally
group by value or display data in a chart. Use these reports to find
files currently checked out, files in a specific workflow state, or
files owned by you.
Creating list reports,
page 249
Security
group
Information about access granted or restricted for each security
group. Use these reports to quickly determine which groups have
access to specific actions.
Creating security
group reports, page
252
Trend
Actions performed over time or by user. Use these reports to
determine the activity level of a project.
Creating trend reports,
page 254
Workflow
progress
Information about the state of files as they move through a
workflow.
Creating workflow
progress reports, page
255
Reports from external reporting services, such as SQL Server Reporting Services or Crystal Reports, can
also be added to Surround SCM. External reporting gives you access to more data in the Surround SCM
databases, provides more flexibility and control of the report content and layout, and offers more output format
options. Ask your Surround SCM administrator for information. See Adding external reports to Surround SCM,
page 257.
Note: You can also save and print the source file list for reporting purposes. See Saving the source file
list, page 262 and Printing the source file list, page 263.
Configuring reports
The following information only applies to audit trail, code review coverage, history, list, security group, trend,
and workflow progress reports. Labeled files reports can be generated from the Reports dialog box, but the
steps are slightly different. See Running labeled files reports, page 154.
Other Surround SCM reports are also available: branch differences, branch maintenance, changelist, code
review, and file differences. See Report types, page 237.
1. Choose Tools > Reports.
The Reports dialog box opens.
238
Creating reports
2. Click Add to create a report. See Creating reports, page 239.
3. Select a report and click Edit to change it. See Editing reports, page 258.
4. Select a report and click Duplicate to duplicate it. See Duplicating reports, page 258.
5. Select a report and click Create Plug-in to create a plug-in used to run the report from a shortcut menu on
the Source Tree window. See Adding shortcuts to run reports from the Source Tree window, page 260.
6. Click Quick Report to create and run a report without saving it. See Running quick reports, page 259.
7. Select a report and click Run to generate it. See Running reports, page 259.
8. Select a report and click Delete to delete it. See Deleting reports, page 259.
9. Click Close when you finish.
Creating reports
Surround SCM includes built-in reports for analyzing file information and activity. You can create reports that
contain the exact data you need.
The following information explains how to create these reports:
n
Audit trail
n
Code review coverage
n
History
n
List
n
Security group
n
Trend
n
Workflow progress
See Report types, page 237 for information about other available reports.
1. Choose Tools > Reports.
239
Creating audit trail reports
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select a report type and click OK. See Report types, page 237.
The Add Report dialog box opens.
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The restriction
options depend on the selected report type. See Adding restrictions, page 213.
7. Click the Output tab to select the output format, stylesheet to use, and additional report content options.
The available options depend on the report type.
8. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating audit trail reports
Audit trail reports include information about file versions in workflow states that require electronic signatures.
Use this report to validate signature records for compliance purposes. Signature records are stored in the audit
log table in the Surround SCM mainline database.
Signature information is displayed in the following columns.
Column
Contains:
Signed Client
Type
Surround SCM client type used to enter the signature.
Signed Full
Name
Full name from the user record of the user who entered the signature.
Signed
Computer
Name of the computer used to enter the signature.
Signed Reason
Optional reason or meaning for the signature. Reasons are only required if they are
enabled in the server or mainline compliance options.
Signed
Timestamp
Date/time the signature was entered.
Signed
Username
Username of the user who entered the signature.
State
State set on the file version that required a signature.
240
Creating audit trail reports
Column
Contains:
Validation Result
Information about if a valid signature record is in the audit log. Validated indicates the
record was created using Surround SCM. Failed indicates the record was created or
modified using another method, such as manual changes in a Surround SCM database
table. Failed (missing entry) indicates a record is not available in the audit log
because the state was set on the file version when the state was not configured to
require an electronic signature or the record was manually deleted.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select Audit Trail 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. On the Restrictions tab, select the criteria that files must meet to be included in the report. If you do not
select any restrictions, all file versions in states that require a signature are included in the report.
241
Creating audit trail reports
7. Select [users] changed state to [states] in date range [dates] to limit results based on the user who
set a signature required state on files, the state set on files, or the date the file states were changed. If you
do not select this restriction, the report includes all signature records for files included in the report.
The Filter Signature Required States dialog box opens.
8. Select any Filter by Users options.
n
Is in list or is not in list indicates if the signature records include the selected users.
n
Current user only includes signatures entered by the logged in user.
n
All users includes signatures entered by all users.
n
Selected users only includes signatures entered by the users selected in the list. Click Select All to
select all users or click Select None to clear any selected users.
9. Select any Filter by States options.
n
Is in list indicates the signature records include the selected states.
n
All signature required states includes all states that require an electronic signature.
n
Selected states only includes the selected states. Click Select All to select all states or click Select
None to clear any selected states.
10. Select any Filter by Dates options.
242
Creating audit trail reports
n
Is or is not indicates if the signature records include dates that match the specified date or time
period.
n
All dates includes records with any date.
n
Equal to, before, after, or between includes records relative to the specified date or time period.
n
A specific time period includes records from the selected period, such as last week or last year.
n
In the last or next includes records for a specified number of hours, days, weeks, months, or years
relative to the current date/time.
11. Click OK to add the restriction.
12. Select any additional restrictions, enter or select the restriction values, and click OK to add them to the
report. See Adding restrictions, page 213.
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.
13. Click the Output tab.
14. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
15. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
16. Select the sorting and order options.
243
Creating code review coverage reports
n
Primary sort column and Order sorts the first column of report results.
n
Secondary sort column and Order sorts the second column of report results (optional).
17. Select Only include information for current file version to only include information about the current
versions of files.
If this option is selected, Surround SCM checks if the current version of a file has an electronic signature.
If the current version is in a state that requires signatures and meets the restriction criteria, the
corresponding signature record is included in the report. If the current version is not in a state that requires
signatures, no information about the file is included. If this option is not selected, records for all historical
file versions in a state that requires signatures and meet the restriction criteria are included.
18. Select the Field Options to specify the columns to include in the report.
Select the column to add in the Available columns list and click
to move it to the Selected columns
list. To remove a column, select it in the Selected columns list and click
. Select a column in the
Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order.
19. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating code review coverage reports
Code review coverage reports include information about file versions in code reviews and if the file reviews
are complete or still in progress. Use these reports to determine if you are ready to release your product,
measure coverage of your code review process, or demonstrate quality control during an audit.
Code review information is displayed in the following columns, which are included in the report by default.
Column
Contains:
Reviewed
Versions
Version numbers of a file that are in a code review with an Approved status. A code review is
approved only if all individual file reviews in it are complete.
Unreviewed
Versions
Version numbers of a file that are not in an Approved review.
Code
Reviews
List of code reviews a file is included in and the version numbers, sorted oldest to newest. If
a version is in a review that is not Approved, the review status is also indicated. For
example, 'CodeReviewA (1, 3-5) - Needs Attention ' indicates that versions 1, 3, 4, and 5 of
the file are included in the CodeReviewA review, which has a Needs Attention status.
Tip: When working with code reviews, you can also run reports that provide historical information about a
review and the files in it. Use these reports to review unaddressed comments, review your code review
process, or save process information for audits. See Running code review reports, page 75.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select Code Review Coverage and click OK.
244
Creating code review coverage reports
The Add Report dialog box opens.
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. On the Restrictions tab, select the criteria that files must meet to be included in the report.
The Report Restriction dialog box opens. The options change based on the selected restriction.
7. Enter or select the restriction values. See Adding restrictions, page 213.
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. Add any additional restrictions.
10. Click the Output tab.
245
Creating code review coverage reports
11. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
12. Select a report Stylesheet.
Cascading Style Sheets (CSS) are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets for code review
coverage reports are stored in the StyleSheets\CodeReviewCoverage directory in the Surround SCM
application directory on the Surround SCM Server.
13. Select the sorting and order options.
n
Primary sort column and Order sorts the first column of report results.
n
Secondary sort column and Order sorts the second column of report results (optional).
14. Select Only include information for current file version to only include information about the current
versions of files.
If this option is selected, Surround SCM checks if the current version of a file, which is the version
displayed in the source files list, is included in the code review. If this version is in the review and meets
the restriction criteria, information about the file is included in the report. If the current version is not in the
review, no information about the file is included in the report. If this option is not selected, information
about all versions of files in the review that meet the restriction criteria is included.
15. Select Do not include files with all versions in approved reviews to exclude files that meet the
restriction criteria and have all versions in code reviews with an Approved status.
If Only include information for current file version is also selected, files with the current version in an
Approved review are excluded. Selecting this option is helpful to show unreviewed files and help you
determine files that need review before you release your product.
16. Select the Field Options to specify the columns to include in the report.
246
Creating history reports
Select the column to add in the Available columns list and click
to move it to the Selected columns
list. To remove a column, select it in the Selected columns list and click
. Select a column in the
Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order.
17. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating history reports
History reports include historical information about actions performed on files, including details about who,
what, where, and when for each action. Use these reports to determine what changed recently or to find
changes made by a specific team member that may need a code review.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select History and click OK.
The Add Report dialog box opens.
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
247
Creating history reports
6. On the Restrictions tab, select the criteria that files must meet to be included in the report.
The Report Restriction dialog box opens. The options change based on the selected restriction.
7. Enter or select the restriction values. See Adding restrictions, page 213.
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. Add any additional restrictions.
10. Click the Output tab.
11. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
Note: If a report is in HTML format, a pie chart can be included in it. See Charting report data, page
257.
12. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
13. Select a report style.
Summary style report includes an overview of file details.
248
Creating list reports
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 Running file differences reports, page 48.
Table style report includes file information 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 in the report. To
include a pie chart in the report, you must select this option. See Charting report data, page 257.
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.
14. Select the Field Options to specify the columns to include in the report.
Select the column to add in the Available columns list and click
to move it to the Selected columns
list. To remove a column, select it in the Selected columns list and click
. Select a column in the
Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order.
15. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating list reports
List reports include current information about files, organized in columns. You can optionally group by value or
display data in a chart. Use these reports to find files currently checked out, files in a specific workflow state,
or files owned by you.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select List and click OK.
The Add Report dialog box opens.
249
Creating list reports
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. On the Restrictions tab, select the criteria that files must meet to be included in the report.
The Report Restriction dialog box opens. The options change based on the selected restriction.
7. Enter or select the restriction values. See Adding restrictions, page 213.
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. Add any additional restrictions.
10. Click the Output tab.
250
Creating list reports
11. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
Note: If a report is in HTML format, a pie chart can be included in it. See Charting report data, page
257.
12. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
13. Select 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 in the report. To
include a pie chart in the report, you must select this option. See Charting report data, page 257.
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.
14. Select the Field Options to specify the columns to include in the report.
Select the column to add in the Available columns list and click
to move it to the Selected columns
list. To remove a column, select it in the Selected columns list and click
. Select a column in the
Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order.
15. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
251
Creating security group reports
Creating security group reports
Security group reports include information about access granted or restricted for each security group. Use
these reports to quickly determine which groups have access to specific actions. See Security Commands,
page 447 for information about the available security options.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select Security Group and click OK.
The Add Report dialog box opens.
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. Select the security group name restriction to include only selected security groups. If you do not select
this restriction, the report includes all security groups.
The Report Restriction dialog box opens.
252
Creating security group reports
7. Select a security group name option.
n
Is in list or is not in list indicates if the group name is included in the list of selected groups.
n
All security groups includes all groups in the report.
n
Selected security groups only includes the selected groups in the report.
8. Click OK.
The restriction is added to the report.
9. Click the Output tab.
10. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
11. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
12. Select Include Repository Security and Branch Security tabs to include repository and branch
security commands in the report.
13. Select a report style.
n
Comparison style report displays security groups and commands side-by-side in the same table.
253
Creating trend reports
Tip: You can flag commands 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 commands for each security group in separate tables.
14. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating trend reports
Trend reports include information about actions performed over time or by user. Use these reports to
determine the activity level of a project.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select Trend and click OK.
The Add Report dialog box opens.
4. Enter a Report name.
5. Select a Public/private report option.
254
Creating workflow progress reports
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. On the Restrictions tab, select the criteria that files must meet to be included in the report.
The Report Restriction dialog box opens. The options change based on the selected restriction.
7. Enter or select the restriction values. See Adding restrictions, page 213.
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. Add any additional restrictions.
10. Click the Output tab.
11. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
12. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
13. Select an option to Group actions by. You can group actions by user, day, month, or week.
14. Select One event type per user per file to only include one instance of an event type per user and file.
15. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Creating workflow progress reports
Workflow progress reports include information about the state of files as they move through a workflow.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select Workflow Progress and click OK.
The Add Report dialog box opens.
255
Creating workflow progress reports
4. Enter a Report name.
5. Select a Public/private report option.
Public reports are shared with all users. Private reports are not shared. You may only be able to create
private reports depending on your security permissions.
6. On the Restrictions tab, select the criteria that files must meet to be included in the report.
The Report Restriction dialog box opens. The options change based on the selected restriction.
7. Enter or select the restriction values. See Adding restrictions, page 213.
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. Add any additional restrictions.
10. Click the Output tab.
256
Charting report data
11. Select an Output format.
Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns.
12. Select a report Stylesheet.
Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined
layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the
StyleSheets directory in the Surround SCM application directory on the Surround SCM Server.
13. Select a Start Date, End Date, and time Interval for the files to include in the report.
14. Select Hide unused states to exclude states that are not applied to files.
15. Select Hide <no state> to exclude the <no state> column.
16. Click OK.
The report is added. See Running reports, page 259 for information about running reports.
Charting report data
Pie charts can be included in history and list reports for a visual representation of the report data. See Creating
history reports, page 247 and Creating list reports, page 249.
The following options must be set in the report configuration:
n
The output format must be HTML.
n
The data must be grouped by the primary sort column. To change the data in the chart, change the primary
sort column value.
When the report runs, the chart is included at the bottom of the report. Click Show Labels to display labels
that contain the item name, count, and percentage for each piece in the chart.
You can also use the chart legend to match the report data with the pieces in the chart. Click an item in the
legend to highlight that piece of the chart and display a label with the item name and count. Click Hide
Legend to hide the legend.
Adding external reports to Surround SCM
Adding external reports to Surround SCM gives you the ability to open an external report viewer from Surround
SCM to view reports stored in reporting services, such as SQL Server Reporting Services or Crystal Reports.
257
Editing reports
An administrative user or another user with high-level security permissions is responsible for configuring
external reporting services and security before you can add external reports. See the External Reporting wiki
for information.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Click Add.
The Select Report Type dialog box opens.
3. Select the reporting service as the report type and click OK.
The Select External Reports dialog box opens with a list of available reports.
4. Select the report to add.
To select more than one report, Ctrl+click each report.
Note: Click Create to create a report in the external reporting service. You can only create reports if
an external reporting client plug-in that supports report editing is installed. Ask your Surround SCM
administrator for help.
5. Click Add.
The report is added. See Running reports, page 259 for information about running reports.
Note: By default, external reports are private. You can edit the report name, sharing settings, and
output format after the report is added to Surround SCM. See Editing reports, page 258.
Editing reports
Edit a report to change the name, if it is public or private, the restrictions that control the content included, or
display options.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Select the report and click Edit.
The Edit Report dialog box opens.
3. Make any changes.
Note: If you are editing an external report, you can only change the report name, public/private
sharing, and the output format fields in Surround SCM. Other field information is stored in the external
reporting service. Click Edit to edit the report content in the reporting service. You can only edit
reports if a client plug-in that supports report editing is installed. Ask your Surround SCM
administrator for help.
4. Click OK to save the changes.
Duplicating reports
If you add reports with the same basic information, you can save time by duplicating an existing report and
then editing the new one.
258
Deleting reports
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Select a report and click Duplicate.
The report is duplicated.
3. Modify the new report and save the changes. See Editing reports, page 258.
Deleting reports
You can delete a report if it is no longer needed. If you delete a shared report, users with access to it can no
longer view it.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Select a report and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
The report is deleted.
Note: If you delete an external report, the report is only deleted from Surround SCM and not the external
reporting service.
Running reports
You can run reports to analyze Surround SCM data. You can run private reports you created and reports that
are shared with you.
You may also be able to create reports to analyze specific data you need. See Creating reports, page 239
Tip: By default, reports open in a report viewer. You can set a user option to view HTML reports in a web
browser instead. See Setting general user options, page 8.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Select a report and click Run.
The report opens.
3. Click Save As to save the report or Print to print it.
These options are only available in the internal report viewer. If an HTML report opens in a browser, you
can save, export, or print the report from the browser.
4. Click Close when you finish.
Running quick reports
You can run a quick report when you do not want to save the report for future use.
259
Adding shortcuts to run reports from the Source Tree window
Tip: By default, reports open in a report viewer. You can set a user option to view HTML reports in a web
browser instead. See Setting general user options, page 8.
1. Select the repository to run a quick report on.
2. Choose Tools > Quick Report and select a report type. You can also click Quick Report on the Reports
dialog box and select the report type.
The Quick Report dialog box opens.
3. Create the report. See Creating reports, page 239.
4. Click Run.
The report opens.
5. Click Save As to save the report or Print to print it.
These options are only available in the internal report viewer. If an HTML report opens in a browser, you
can save, export, or print the report from the browser.
6. Click Close when you finish.
Adding shortcuts to run reports from the Source Tree window
You can quickly run reports on files in a specific repository from the Source Tree window without opening the
Reports dialog box. To run a report, right-click the repository and select a report from the shortcut menu.
Before you can run a report from the Source Tree window, you need to create a plug-in for the menu item and
then add the item to the repository shortcut menu.
For example, you may use a Files Awaiting Review Assignment list report to view files in the Awaiting
Review state that are not currently assigned. You can create a plug-in for this report and then add the menu
item to the repository shortcut menu. When you want to run the report, right-click the repository and choose
Files Awaiting Review Assignment.
260
Adding shortcuts to run reports from the Source Tree window
Note: Report plug-ins are supported in Surround SCM 2016 and later. They are saved in the plugins
directory in the Surround SCM application directory by default and you must have permission to modify
this directory to create them.
1. Choose Tools > Reports.
The Reports dialog box opens.
2. Select the report to create a shortcut menu item for. You can only create them for reports configured to run
against the <current selected> branch and <current selected> repository. This information is displayed in
the Reports dialog box.
If you need to create a report, click Add. See Creating reports, page 239.
3. Click Create Plug-in.
The plug-in is created and a summary is displayed. Plug-in files are named RunReport_RecordID.xml
(e.g., RunReport_5.xml) and saved in the plugins directory in the Surround SCM application directory.
Note: If a plug-in with the same name already exists in the directory, you are prompted to overwrite it.
This may occur if you previously created a plug-in for the report or created a plug-in for a different
report with the same record ID on another Surround SCM Server. Before overwriting a plug-in, open it
in a text editor and check the server-name value. If the plug-in is associated with a server you are not
currently connected to, rename the file to avoid the conflict. If you overwrite a plug-in, you must
restart Surround SCM to reload it.
4. Click OK to close the plug-in summary.
5. Click Close to close the Reports dialog box.
261
Changing report menu item names and icons
6. Add the new report menu item to the repository shortcut menu. See Customizing shortcut menus, page
101.
Tip: The menu item name matches the report name when the plug-in is created. To customize the
name and icon, edit the plug-in. See Changing report menu item names and icons, page 262.
After adding the report item to the shortcut menu, right-click a repository in the Source Tree window and
choose it to run the report.
If plug-in errors occur, review information in the SCMPluginErrorLog file in the plugins directory to
troubleshoot. You can also check existing plug-ins and status in the plug-in user options. See Setting plug-in
options, page 278.
Changing report menu item names and icons
Report plug-ins are XML files that define the menu item and the report to run from the repository shortcut
menu. You can change the menu item name and icon in the XML file. You can also rename plug-in files to
more easily identify the report they are related to.
If you need to create a report plug-in, see Adding shortcuts to run reports from the Source Tree window, page
260.
Note: Only make changes to the menu item name and icon values in the XML file. Do not change other
values because the plug-in may stop working.
1. Open the report plug-in XML file in a text editor. Plug-ins are stored in the plugins directory in the Surround
SCM application directory by default.
2. Modify the <menu-item name="Report Name" /> line.
n
To change the name, replace the name value with the text to display in the menu. For example,
<menu-item name="Run Files Awaiting Review Report" />. The name is required and must be
unique. Errors occur if multiple plug-ins use the same menu item name.
n
To change the icon, add an icon value and path to the image file. For example, <menu-item
name="Run Files Awaiting Review Report" icon="NeedsReview.png" />. An icon value is
optional. You can enter a relative file path if the image is in the plugins directory or a full path to an
image in another directory. If an icon is already specified for the plug-in, you can replace the path to
use a different image or delete the icon attribute to use the default report icon. For best results, use an
icon that is 16x16 pixels in BMP, GIF, or PNG format.
3. Save and close the file.
4. Optionally rename the file to use a more intuitive name.
5. Restart Surround SCM for the changes to take effect.
Saving the source file list
You can save the source file list and use the output with third-party applications for reporting and other
purposes. For example, you may want to save a list of all checked out files.
1. Select a repository.
2. Optionally select a filter from the Filter list to only include specific files in the saved list.
3. Choose File > Save File List As.
262
Printing the source file list
The Save File List dialog box opens. The Selected columns list includes the columns currently displayed
in the source file list.
4. Select the column to add in the Available columns list and click
list.
To remove a column, select it in the Selected columns list and click
to move it to the Selected columns
.
5. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to
change the display order.
6. Select an Output format.
You can save the file list in HTML, tab-delimited, or comma-delimited format.
7. Click Save As.
The Save File List As dialog box opens.
8. Select the file location, enter a filename, and select the file type.
9. Click Save.
The list is saved.
Printing the source file list
You can print the source file list, which can be helpful for reporting purposes. For example, you can print a list
of all checked out files.
1. Select a repository.
2. Optionally select a filter from the Filter list to include specific files in the printed list.
3. Choose File > Print File List.
The Print File List dialog box opens. The Selected columns list includes the columns that are currently
displayed in the source file list.
263
Printing the source file list
4. Select the column to add in the Available columns list and click
list.
To remove a column, select it in the Selected columns list and click
to move it to the Selected columns
.
5. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to
change the display order.
6. Click Print to print the list.
264
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 417.
1. Choose Tools > TestTrack Integration > Connections.
The TestTrack Connections dialog box opens.
2. Click Add to create a connection. See Adding TestTrack connections, page 265.
3. Select a connection and click Edit to change it. See Editing TestTrack connections, page 266.
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 266.
Adding TestTrack connections
To access TestTrack issues, requirements, and test cases, you need to add a connection to the TestTrack
project.
1. Choose Tools > TestTrack Integration > Connections.
The TestTrack Connections dialog box opens.
2. Click Add.
265
Editing TestTrack connections
The Add Connection dialog box opens.
3. Enter a Connection name to help users identify the project.
4. Enter the Server address and Port.
The default TestTrack port number is 99 on Windows and 1566 on Unix platforms.
Note: If you received a server settings file from your TestTrack administrator, import it instead of
manually entering the information. Click Import, select the XML file and, click Open. The Server
address, Server port, and Public key fingerprint fields are automatically populated. The public key
provides additional security required to connect to the TestTrack Server. Contact your TestTrack for
additional help.
5. Click Get Projects to retrieve a list of all projects from the TestTrack Server.
6. Select a Project.
7. Click OK.
The connection is added.
Tip: You can set integration options that restrict users to a use a connection associated with a specific
repository. See Setting TestTrack integration options for repositories, page 418.
Editing TestTrack connections
You can change the server address, port number, and project.
1. Choose Tools > TestTrack Integration > Connections.
2. Select the connection and click Edit.
The Edit Connection dialog box opens.
3. Make any changes and click OK.
Deleting TestTrack connections
You can delete any TestTrack connections you no longer use.
1. Choose Tools > TestTrack Integration > Connections.
2. Select the connection and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
266
Entering TestTrack login information
The connection is deleted.
Entering TestTrack login information
You need to enter your TestTrack login information before you can attach files to issues, requirements, or test
cases.
1. Choose Tools > TestTrack Integration > User Settings.
The TestTrack User Settings dialog box opens.
2. Select Use Surround SCM username and password if your TestTrack and Surround SCM login
information is the same.
3. Select Use the following and enter your TestTrack username and password if your login information is
different from Surround SCM.
4. Click OK.
You can now attach Surround SCM source files to TestTrack items.
Attaching source files to TestTrack items
You can attach source files to TestTrack issues, requirements, and test cases. The file information is
attached to the TestTrack item, making it easy to work with the file from Surround SCM or TestTrack.
You can also attach source files to TestTrack items when you add files, check in files, promote or rebase files
and branches, or view file history. If the files to attach are included in a changelist, you can attach the
changelist to TestTrack items from the Changelists dialog box. See Managing changelists, page 132.
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.
To select the files to attach by label, choose Tools > Labels, select the label, and click Attach.
Ctrl+click the files to attach in the Select Files to Attach dialog box and click Attach.
The TestTrack Browser dialog box opens.
267
Attaching source files to TestTrack items
2. Select the TestTrack Connection for the project to access.
Click Configure to create or change a connection. See Configuring TestTrack connections, page 265.
3. Click the tab for the item type to attach the files or repository to.
The items list displays your assigned items. Select a filter from the Filtered By list to display specific
items. You can only attach files to items you have access to in TestTrack.
4. Select the items 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 item details. See
Viewing TestTrack items, page 269.
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 271 and Adding TestTrack issues, page 270. 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 locked for editing by another user in TestTrack, you must wait for them to
unlock it before you can attach files. If you are editing a selected item in TestTrack, you are prompted
to resolve the item lock. Click Save and Close to save the changes and close the item. Click
Discard and Close to discard the changes and close the item. Click Switch to TestTrack to
manually resolve the conflict in TestTrack. Click Cancel to cancel attaching files to the locked item.
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.
268
Viewing TestTrack items
6. If you are attaching files to issues, click Fix to mark the selected issue as fixed. See Fixing external
issues, page 282.
Entering TestTrack workflow 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 Files tab in TestTrack. Keep in mind the tab
may have a different name.
Viewing TestTrack items
After files are attached to TestTrack items, you can view the item details from Surround SCM.
1. Select the file.
269
Adding TestTrack issues
You can search for files attached to items. See Finding files attached to TestTrack items, page 272.
2. Choose Activities > History.
The History dialog box opens.
3. Select the file version attached to the item to view.
4. Click View Attached.
The read-only View Item dialog box opens.
Adding TestTrack issues
You can create new issues to attach source files to from Surround SCM.
Note: You must use TestTrack 2011 or later to add issues to TestTrack from Surround SCM.
1. When you are attaching files to TestTrack, click Add on the Issues tab.
The Add Issue dialog box opens with the Detail tab selected.
2. Enter the issue information.
Refer to the TestTrack help for more information.
3. Click Add when you finish entering the issue information.
The issue is added to the TestTrack project and listed in the issues list.
270
Editing TestTrack issues
Editing TestTrack issues
You can edit issues when you are attaching source files from Surround SCM.
Note: You must use TestTrack 2011 or later to edit issues.
1. When you are attaching files to TestTrack, select an issue and click Edit on the Issues tab.
The Edit Issue dialog box opens.
2. Make any changes.
3. Click OK to save the changes in the TestTrack project.
Fixing TestTrack issues
You can optionally mark issues as fixed when you attach source files.
Note: Issues that require electronic signatures cannot be fixed from Surround SCM.
1. Select the files or repository and choose Activities > Attach to TestTrack.
The TestTrack Browser dialog box opens.
2. Select a TestTrack Connection for the project 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 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 269.
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 the issues to fix and click Fix.
The Fix dialog box opens.
271
Finding files attached to TestTrack items
6. Enter the fix information.
7. Click OK.
The file is attached to the issue and the issue is marked as fixed.
Finding files attached to TestTrack items
1. Choose Edit > Advanced Find Files.
The Advanced Find dialog box opens.
2. Select the issue number, test case number, or requirement number restriction.
The Restriction dialog box opens.
3. Select a TestTrack Connection.
4. Enter or select search criteria.
5. Click OK.
The restriction is added. The restriction values are displayed in the Restrictions list and the Summary
field.
Note: To change the restriction value, double-click the value in the Restrictions list.
6. Repeat steps 2-5 to add additional restrictions.
7. Select Search recursively to search the selected repository and any subrepositories.
8. Click Find to search for the files.
Files that meet the criteria are displayed. The Find files results filter is applied.
272
Analyzing issue risk in files
Analyzing issue risk in files
You can analyze risk to predict potential problems in source files attached to issues and identify files that may
need attention. For example, you may want to analyze risk to identify high risk files that have priority for code
review or that need an owner or workflow state change.
Risk scores are calculated based on the number of issues files are attached to during a specified time period.
Files with higher risk scores compared to related files are more likely to have unresolved problems. Reviewing
files with higher scores can help you address problems and prevent issues from making it into builds. See
Performing Code Reviews, page 57.
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 265 and Integrating with issue tracking tools, page 280.
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.
2. Click Browse and select the branch and repository to analyze.
273
Analyzing issue risk in files
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 84.
View properties for the selected file. See Viewing file properties, page 88.
Change the workflow state of the selected files. See Changing workflow states, page 36.
Change multiple custom field values for the selected files. See Changing multiple custom
fields, page 35.
Perform a code review for the selected file. See Reviewing files, page 70.
Add the selected files to a code review. See Adding files to code reviews, page 62.
View code reviews for the selected file. See Viewing code reviews files are included in,
page 78.
274
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.
275
Integrating with Third-Party Applications
Surround SCM can be integrated with a variety of third-party IDEs, build tools, issue tracking tools, and other
applications, making it easy to work with source control files from the application of your choice. For example,
developers can quickly check in and check out files directly from Visual Studio while project managers can
access files from Microsoft Office without using the Surround SCM Client.
Note: Make sure to log out of Surround SCM and disconnect from Surround SCM in integrated third-party
applications when you finish working with source files. This is important if your team uses floating
licenses because you could be using multiple licenses at one time and preventing other users from logging
in.
The following resources can help you integrate Surround SCM with third-party applications:
n
Surround SCM Third-Party Integrations lists supported integrations. n
The Surround SCM Integrations knowledgebase 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 279
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 280 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 provides information about creating and deploying plug-ins used for
adding custom menus or menu items for third-party applications to the Surround SCM 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 285.
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. These options
apply only to the current user account logged in to the computer.
Note: The Integrations category is not available on Linux.
1. Choose Tools > User Options then select the Integration category.
277
Setting plug-in 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 283.
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 284.
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 234.
Note: If you use Surround SCM on Mac or Linux, you need to manually configure applications to
associate sscm:// addresses with Surround SCM. Refer to the application documentation for
information.
7. Click OK to save the changes.
Setting plug-in options
Plug-ins provide additional functionality in Surround SCM. You can create plug-ins to:
n
Run reports from a repository shortcut menu on the Source Tree window. See Adding shortcuts to run
reports from the Source Tree window, page 260.
278
Integrating with IDEs and applications that support SCCI
n
Add custom menus or shortcut menu items for third-party applications to Surround SCM. See Surround
SCM Custom Client Menus for information.
After creating plug-ins, make sure they are stored in a directory Surround SCM loads plug-ins from. Plug-ins
are loaded from the plugins directory in the Surround SCM application directory by default, but you can add
additional directories to check.
You can also view the plug-ins loaded when Surround SCM started and the status, which can help with
troubleshooting.
Note: User options apply only to the current user account logged in to the computer. Some user options
may be disabled, which indicates they are set on the Surround SCM Server and cannot be changed.
1. Choose Tools > User Options then select the Plug-ins category.
2. Click Add.
The Browse for Folder dialog box opens.
3. Select the plug-in directory and click OK.
4. Click OK to save the changes.
The changes do not take effect until you restart Surround SCM. Plug-in status information is displayed in
the User Options dialog box after restarting.
Note: If plug-ins cannot load, errors are written to the SCMPluginErrorLog file in the plugins folder in
the Surround SCM application directory.
Integrating with IDEs and applications that support SCCI
Surround SCM conforms to the Microsoft Source Code Control Interface (SCCI) standard and can be
integrated with many Windows IDEs and applications. See Surround SCM Third-Party Integrations for a list of
supported integrations. Other IDEs that support the SCCI standard may work with Surround SCM, but are not
supported by Seapine.
279
Integrating with issue tracking tools
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 277. After the integration is enabled, you can perform
Surround SCM tasks from the corresponding application.
Note: Other integration options and plug-ins are available during Surround SCM installation for Windows
and other supported platforms. Some integration plug-ins for Unix applications must be manually installed.
See the Surround SCM Integrations knowledgebase for setup, usage, and troubleshooting information.
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 273.
A server plug-in for the issue tracking integration must be installed in the issueplugins folder in the Surround
SCM application directory. See Issue Tracking API documentation in the issueplugins folder in the Surround
SCM application directory for information about creating plug-ins.
Note: Plug-ins for Bugzilla, JIRA, and Microsoft Team Foundation Server (TFS) can be downloaded from
Seapine's Surround SCM Resources page.
Entering issue tracking login information
You need to enter your issue tracking login information before you can attach files to issues.
1. Choose Tools > Issue Tracking Integration > User Settings.
The Issue Tracking Tool User Settings dialog box opens.
2. Enter your username and password.
3. Click OK.
You can now attach Surround SCM source files to issues.
280
Attaching source files to external 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 to attach are included in a changelist, you can attach the changelist to
issues from the Changelists dialog box. See Managing changelists, page 132.
1. Select the files or repository and choose Activities > Attach to Issue Tracking Tool.
To select the files to attach by label, choose Tools > Labels, select the label, and click Attach.
Ctrl+click the files 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 to connect to.
The items list is populated with issues from the selected project. Select a filter from the Filtered By list to
display specific items.
3. Select the issues 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 282.
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.
281
Viewing external issues
5. Click Fix to mark the selected issue as fixed. See Fixing external issues, page 282.
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 the file version attached to the issue to view.
4. Click View Attached.
The read-only View dialog box opens.
Fixing external issues
You can optionally mark issues as fixed when you attach source files.
1. Select the files or repository and choose Activities > Attach to Issue Tracking Tool.
The Issue Browser dialog box opens. Select a filter from the Filtered By list to display specific issues.
2. Select the issues to attach the files to. To select multiple issues, Ctrl+click each issue.
A read-only description is displayed when you select an issue.
Tip: Select an issue and click View Details to view detailed issue information. See Viewing external
issues, page 282.
3. Click Attach to attach the files to the selected issues.
The Attach to Issue dialog box opens.
4. Select the issues to fix and click Fix.
The Fix dialog box opens.
5. Enter the fix information.
282
Using the Windows Explorer and Mac Finder integrations
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 8.
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 to Surround SCM.
Adding files to
Surround SCM,
page 30
283
Using the Mac Finder plug-in
Action
Use to:
More
information
Check In
Check in the updated file.
Checking in
updated files,
page 26
Check Out
Check out the file.
Checking out
files, page 23
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 25
Launch Surround
SCM
Open Surround SCM. If a working directory is selected, the
branch and repository mapped to the directory is selected in
Surround SCM.
Show Icon
Overlays
Display or hide Surround SCM status icons on directories and
files.
Integration icon
overlays, page
283
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 8.
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.
284
Action
Use to:
More
information
Add
Add the file to Surround SCM.
Adding files to
Surround SCM,
page 30
Check In
Check in the updated file.
Checking in
updated files,
page 26
Integrating with CMIS
Action
Use to:
More
information
Check Out
Check out the file.
Checking out
files, page 23
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 25
Launch Surround
SCM
Open Surround SCM. If a working directory is selected, the
branch and repository mapped to the directory is selected in
Surround SCM.
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 439 for information about setting up the CMIS Server.
Configuring the integration
You must configure a connection to the Surround SCM CMIS Server in the CMIS client application before you
can access Surround SCM files and actions. Ask the Surround SCM administrator for connection information.
Note: To integrate with Adobe CS5 and later applications, you must use Adobe Drive 2.1 or later to
connect to the Surround SCM CMIS Server. See Surround SCM Adobe Illustrator, InDesign, and
Photoshop Integration for setup, usage, and troubleshooting information.
Performing Surround SCM actions
After connecting to the CMIS Server, you can add files, check out files, check in files, undo check outs,
remove files or repositories, and view file history. Refer to the CMIS client’s documentation for information
about working with source control files.
When you check out a file from a CMIS client, a writable copy is checked out exclusively to you on the
Surround SCM Server, but a local copy is not retrieved to your working directory. CMIS clients communicate
with the Surround SCM Server through the CMIS Server and to access the writable version of checked out
files, you must use the same CMIS client to perform all actions on source control files. You cannot check out
files checked out by other users.
285
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 287 and Starting the Surround SCM Server, page 288.
2. Start the Surround SCM Client and log in.
See Starting Surround SCM, page 3.
3. Create a mainline branch.
You must create at least one mainline branch before users can add source files. See Creating mainline
branches, page 387.
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 289.
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 298.
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 305.
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 429.
Starting the Seapine License Server
An administrative user must make sure the Seapine License Server is running before the Surround SCM
Server is started.
Tip: If Surround SCM cannot connect to the license server, an administrative user needs to troubleshoot.
See Surround SCM Cannot Connect to the License Server for information.
Windows
If the license server is installed as a service, it starts automatically. If the license server is installed as an
application, you must start it manually. Choose All Programs > Seapine Software > Seapine License
Server > Seapine License Server from the Start menu.
Note: If the server is installed as a service but not running or you need to restart it, see the Windows
documentation for information about starting a service.
287
Starting the Surround SCM Server
Linux
Enter /usr/bin/spls start.
If you need to restart the server, enter /usr/bin/spls stop and then restart the server.
Starting the Surround SCM Server
An administrative user must make sure the Surround SCM Server is running before users can access
Surround SCM.
Windows
If the Surround SCM Server is installed as a service, it starts automatically. If the server is installed as an
application, you must start it manually. Choose All Programs > Seapine Software > Surround SCM
> Surround SCM Server from the Start menu.
Note: If the server is installed as a service but not running or you need to restart it, see the Windows
documentation for information about starting a service.
Linux
Enter /usr/bin/surroundscm start.
If you need to restart the server, enter /usr/bin/surroundscm stop and then restart the server.
288
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 290 for additional
information.
Security
Type
Description
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 291.
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 295.
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 297.
289
Security examples
Security examples
The following sample scenarios are provided to help you understand how the different security levels work.
Depending on your company’s needs and business processes, you may only want to set server security. If
your needs are more complex, or your business process dictates restricting users to specific data, you may
decide to set repository and/or branch security.
WysiCorp, a fictional company, develops customized software applications for multiple customers. Many of
these customers are competitors and require a high level of security and confidentiality. To ensure that all
development goals are met, WysiCorp’s development teams, TeamA and TeamB, are assigned to one
company for the duration of a project. Other teams, such as Project Leads and QA, may be assigned to more
than one company at a time.
WysiCorp, the mainline branch, includes the following repositories: Client and Server. The Client repository
includes two subrepositories, CompanyA and CompanyB. The CompanyA subrepository includes two
baselines branches, Development and Released.
Server security
Members of the Project Leads security group are administrators and have access to all commands. Members
of the TeamA and TeamB security groups have access to some commands, such as adding files or viewing
file history. The QA security group is restricted to read-only security.
Repository security
WysiCorp does not want TeamA members to have access to the CompanyB subrepository or TeamB
members to have access to the CompanyA subrepository. Repository security is applied to the CompanyA
and CompanyB subrepositories. The TeamA security group is restricted from viewing the CompanyB
subrepository. The TeamB security group is restricted from viewing the CompanyA subrepository.
When viewing CompanyA repository properties, the Inherited From column changes from <server level
default> to <not inherited> for the TeamB security group. This indicates the server security is overridden.
290
Controlling access with security groups
Branch security
After code is released to customers, it is important to stop development on that code. Branch security is
applied to the Released branch in the CompanyA subrepository. The TeamB security group is restricted from
viewing the CompanyB subrepository. In addition, all other groups only have list-only access to the Released
branch.
When viewing CompanyA repository properties, notice the only groups listed are Team B and <All other
groups>. In addition, the Inherited From column changes from <server level default> to <not inherited>. This
indicates the server security is overridden.
Controlling access with security groups
The Security Groups window is used to manage security groups and settings. Many users will not have
access to this view. This view includes group name, description, and security permissions information.
291
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 292.
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 447 for information about the commands in each category and what they
provide access to.
Note: Users do not need read/write access to the database directory on the Surround SCM Server. Only
the Surround SCM Server requires read/write access to this directory. All access permissions are
controlled using the Surround SCM Client and the changes are made by the server in the database. This
adds an additional level of security and prevents users from making changes directly to the files using a
third-party editor and bypassing version control.
Adding security groups
Security groups are used to create a security structure for users. Before you create security groups, it may be
helpful to list the types of users you are creating and what their roles are. You can add as many or as few
security groups as you need.
Note: A default Admin group, which has access to all commands, is created when Surround SCM is
installed. Carefully consider which users are added to this group.
1. Choose View > Security Groups.
292
Adding security groups
The Security Groups window opens.
2. Click Add.
The Add Security Group dialog box opens with the Users tab selected.
3. Enter a Name and Description.
Tip: You may want to include the actions that the security group can perform in the Description field
so you do not have to look at every category to determine the purpose of the group.
4. Select a user and click Add to add users to the group.
To add multiple users, Ctrl+click each user.
5. Click the Server Security tab to enable or disable access to commands.
Make sure you enable or disable commands for all categories. See Controlling access with security
groups, page 291 for a list of commands in each category.
293
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 291.
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 295.
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 297.
7. Click OK to save the changes.
294
Duplicating security groups
Duplicating security groups
If you need to create a security group that is similar to an existing one, you can save time by duplicating and
editing an existing group.
1. Choose View > Security Groups.
2. Select a group and click Duplicate.
The duplicated security group is created using the name of the existing group with .1 appended to the
name. For example, if the existing group is named Development, the duplicated group is named
Development.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.
295
Controlling access to specific repositories
3. Click Modify to change the security. The fields are enabled.
4. Make any changes to security settings.
296
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 <All other groups> to set permissions that apply to security
groups without any security overrides set on the repository.
n
To remove a group, select it and click Remove. You can only remove a group if security is configured
for <All other groups>. When a group is removed, it uses the security permissions set for this group.
n
To revert security overrides, select a group and click Inherit. The group inherits the default security
permissions set for the server.
Controlling access to specific branches
5. Select Force all child repositories to inherit these security permissions to apply security to the
selected repository and all child repositories.
This option applies the permissions you configured to all child repositories and removes any security
overrides set in child repositories.
6. Click OK to save the changes.
Controlling access to specific branches
You can apply security to a branch and override the global security group settings. You can enable or disable
file actions for a specific branch in a repository. The security you set only affects one branch in the selected
repository. For example, you branch your code into multiple versions. When development starts in a new
version, you only want the development group and projects leads to have access to the branch. You can set
branch security that restricts all other groups, such as QA or technical writers, from accessing the branch.
Note: If you do not have access to a branch or any repositories in it, the branch is not displayed in the
Branches tree or Branch menu. If you do not have access to a parent branch but have access to a child
branch, the parent branch is displayed as <restricted>.
1. Select a branch and choose Activities > Properties.
The Properties dialog box opens.
2. Click the Security tab.
3. Select a Branch Security option.
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 298.
297
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 297.
1. Choose View > Security Groups.
The Security Groups window opens.
2. Select the group 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 to configure security for and click OK.
6. Enable or disable the security commands for the branch. See Files security commands, page 453.
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.
298
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 301.
Adding users
Users must be added to Surround SCM before they can access files. You can add users directly to Surround
SCM or retrieve them from the Seapine License Server. See Retrieving global users, page 301.
1. Choose View > Users.
The Users window opens.
2. Click Add.
The Add User dialog box opens.
299
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 292 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 300.
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. Named licenses are best for users who log in
frequently while floating licenses are best for users who log in occasionally.
300
Retrieving global users
n
A named license is dedicated to a specific user and allows the user to access Surround SCM from any
computer on the network. Named licenses cannot be shared.
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.
Note: Users with floating licenses use multiple licenses when logged in to a Surround SCM client
and a third-party application integrated with Surround SCM at the same time. Make sure users know
to log out of clients and disconnect third-party applications from Surround SCM when they finish
working with source files to make licenses available to other users.
Retrieving global users
Global users can be retrieved from the Seapine License Server and given 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 to retrieve.
Select Display inactive users to include inactive global users in the list. Retrieve inactive users if you
know they will be reactivated later. For example, a contractor may be inactivated on the license server
after a project ends and then reactivated when they return to work on another project. When the user is
reactivated on the license server, they are automatically activated in Surround SCM when user data is
refreshed. See Setting Seapine License Server options, page 317.
4. Click Add to add the users to Surround SCM.
After global users are retrieved, they must have a license assigned and be added to a security group
before they can access Surround SCM. See Editing users, page 302.
301
Viewing users
Note: You can only assign licenses to active users.
Viewing users
You can view read-only user information without preventing other users from editing the record at the same
time.
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.
Editing users
You can edit most user information. You can only change the username if renaming usernames is enabled on
the Seapine License Server. See 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
You can delete users if they no longer need Surround SCM access or were added by mistake. When a user is
deleted, all corresponding historic information for the user 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.
The user is deleted.
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.
302
Voiding check out
2. Click Close when you finish.
Voiding check out
Surround SCM users with admin-level security access can void check outs. This removes the lock on a file
and gives other users access to it. Changes users made to the file are not saved.
1. Choose Tools > Administration > Void Check Out.
The Void Check Out dialog box opens.
2. Select a user from the Users list. The Checked out files list shows the user’s checked out files.
3. Select the files and click Void Check Out.
You are prompted to confirm the void.
4. Click Yes.
The check outs are voided.
5. Click Close when you finish.
303
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 388.
Options
Use to:
More
information
General (Global
Server)
Set the local admin password, specify how often to check for new
server stylesheets, enable automatic client upgrades, compress
server files, and encrypt server communications.
Setting
general
global server
options, page
307
Merge
Switch from Diff3 to Guiffy for automatic file merges and
configure Guiffy options.
Setting
server merge
options, page
312
Server Database
Change the server database location or convert it to a different
RDBMS type.
Setting the
default server
database
location,
page 400
RDBMS Connections
Create and modify RDBMS connections to host mainline
branches.
Adding
RDBMS
connections,
page 403
Caching
Set dynamic branch caching options to control the size of the
server cache for improved performance and memory availability.
Setting
branch
caching
server
options, page
383
Logging
Select the type of information to add to the server log and set
options to send email when the server log is updated.
Setting
logging
options, page
314
305
Configuring the Surround SCM Server
Options
Use to:
More
information
Email Servers
Specify protocol and connection information used to email
notifications from Surround SCM.
Setting email
server
options, page
315
Email Notifications
Specify the return address for email notifications and the server
host name for file links included in emails.
Setting email
notification
options, page
316
License Server
Configure Seapine License Server connection information, the
license server communications password, and global user cache
refresh rate.
Setting
Seapine
License
Server
options, page
317
Update Check
Check for and download software updates.
Checking for
new
Surround
SCM
versions ,
page 320
Auto Update Check
Specify how often to automatically check for software updates
and receive email about product releases.
Setting
automatic
software
update check
options, page
318
TestTrack Integration
Enable TestTrack integration and edit or sync item field labels.
Enabling
TestTrack
integration,
page 417
Issue Tracking
Integration
Activate plug-ins to integrate Surround SCM with a third-party
issue tracking tool.
Activating
third-party
issue
tracking plugins, page 314
Purge Scheduling
Schedule when to purge destroyed data from the database.
Scheduling
data purges,
page 320
306
Setting general global server options
Options
Use to:
More
information
General (Mainline)
Set default check in, Unicode file, thumbnail size, and large file
size options for all mainline branches.
Setting
general
mainline
options, page
321
Comments
Set minimum lengths for comments entered by users when
performing specific actions, such as check ins.
Setting
minimum
comment
lengths for
actions, page
325
Changelists
Set default changelist usage for all mainline branches.
Setting
changelist
server
options, page
324
File
Names/Extensions
Specify filenames or extensions to auto-detect or ignore when
adding files.
Setting autodetect and
ignore file
options, page
325
Compliance
Specify maximum attempts before logging out users if an
incorrect electronic signature is entered when changing workflow
states on files, required signature components, and the
certification and testimony message displayed in the Signature
Required dialog box.
Setting
compliance
options, page
327
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 309 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.
307
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 on the server.
4. Select Automatically upgrade Surround SCM clients to the current Surround SCM Server
version to enable automatic client upgrading for clients connecting to this server.
Selecting this option ensures all users are running the correct version of Surround SCM.
5. Select Compress files stored on the Surround SCM Server to compress files and use as little disk
space as possible.
6. Select Encrypt communication between clients and the server to encrypt all communication between
clients and the Surround SCM Server, which reduces the likelihood of eavesdropping by hackers.
Encryption increases security, but may slightly affect performance. Select this option if your
organization’s network is secure and no client applications outside of the network communicate with the
Surround SCM Server.
Tip: Always use encryption to keep data secure unless you are evaluating Surround SCM or
troubleshooting performance issues.
The OpenSSL version used by Surround SCM is displayed. Any vulnerabilities found in OpenSSL are
published on the OpenSSL web site. To check if OpenSSL version displayed in Surround SCM has
vulnerabilities that impact Surround SCM, check Seapine's knowledgebase or contact Seapine
Support for information.
7. Select Use RSA key exchange to use strong key exchange for communication between clients and the
Surround SCM Server.
308
Securing 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 311 for information about setting up RSA.
Note: This option is only available if Encrypt communication between clients and the server is
selected.
8. Click OK to save the changes.
Changing key exchange options
If you change key exchange options, Surround SCM client applications and the Surround SCM web and proxy
servers must be updated. The following scenarios require further action after changing security settings.
If you
use:
And you change it to:
You need to:
No
encryption
RSA key exchange
Download a settings file that Surround SCM client users need
to import in the server connection settings. If you use Surround
SCM Web or proxy servers, import the file in the Surround SCM
Registry Utility on the corresponding server computer.
RSA key
exchange
No encryption or basic
encryption (Encrypt server
communication between
clients and the server is
selected)
Remove the public key fingerprint from any clients that connect
to the server. Click Remove in the server connection
information in clients and in the options for servers in the
Surround SCM Registry Utility.
See Configuring RSA key exchange, page 311 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 307 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 Standard256 (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.
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 307.
309
Securing communication between clients and the Surround SCM Server
Note: Always use encryption unless you are evaluating Surround SCM or troubleshooting a performance
issue. Passwords are always encrypted even if client/server communication is not.
Login credentials sent from web browsers to the Surround SCM web server via HTTP are not encrypted,
even if encryption is enabled on the Surround SCM Server. We strongly recommend using HTTPS to
encrypt communication from the browser to the web server. HTTPS connections use a self-signed
certificate by default, but you can configure the web server to use your own SSL certificate in the Surround
SCM Registry Utility. See the Surround SCM Registry Utility help for information.
Authentication
Authentication is the process of logging in a user to Surround SCM. The following authentication methods are
used in Surround SCM.
Authentication
method
How it works
Seapine
License Server
The username and mathematical proof that the user knows the password (not the actual
password) are sent to the Surround SCM Server. The server sends different
mathematical proof that it knows the password to the client.
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
authentication
Data from the organization's authentication system is sent to the Surround SCM Server.
Key exchange
Key exchange is a method of exchanging secret keys over an insecure network connection without exposing
them to eavesdroppers. The key exchange method used depends on the authentication method.
The following key exchange methods are used in Surround SCM.
Key
exchange
method
When it is
used
How it works
To use it:
Secure
Remote
Password
(SRP)
User is
authenticated
from the
Seapine
License
Server and
RSA key
exchange is
not enabled
A shared secret key is generated during authentication.
To compromise the secret key or impersonate the
server, a hacker must know the user's password.
Select Encrypt
communication
between clients
and the server
in the general
global server
options.
310
Configuring RSA key exchange
Key
exchange
method
When it is
used
How it works
To use it:
DiffieHellman
User is
authenticated
using LDAP or
external
authentication,
and RSA key
exchange is
not enabled
A mathematical process is used to generate a secret
key. To compromise the secret key, a hacker must have
control over an intermediate network node or
impersonate the real server. Does not protect against
man-in-the-middle attacks.
Select Encrypt
communication
between clients
and the server
in the general
global server
options.
RSA
RSA key
exchange is
enabled in the
Security
server options
The client generates a random, 256-bit secret key and
encrypts it with the server's public key. The server
hashes the secret key and signs the hash with its
private key. The private key is only stored on the server
hard drive and never leaves the server. To compromise
the secret key or impersonate the server, a hacker must
know the server's private key or substitute their own
public key in client applications.
Select Encrypt
communication
between clients
and the server
and Use RSA
key exchange in
the general
global server
options.
When to use RSA key exchange
SRP and Diffie-Hellman are low risk key exchange methods if your organization’s network is secure and no
client applications outside of the network can communicate with the Surround SCM Server.
We recommend using RSA key exchange to prevent hackers from eavesdropping on communication if:
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 311.
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.
311
Setting server merge options
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 for
information.
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 the Surround SCM Registry Utility
help for information.
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 the Surround SCM Registry
Utility help for information.
Tip: 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.
312
Setting server merge options
3. Select Enable Guiffy for automatic merges to use the Guiffy diff/merge application. You must enable
this option to auto-merge Unicode text files.
The Diff3 merge application is faster than Guiffy and uses less memory. Each application uses different
algorithms for determining conflicts. You may want to use the same application on the client and server
computers.
4. Enter the number of MB of memory you want Guiffy to use.
The recommended setting is 128 MB. The minimum setting is 96 MB and the maximum setting is 1024
MB.
Tip: This setting should not exceed 50% of the server computer’s physical memory. Other
applications can be negatively affected if you set the amount of memory too high. However, if this
setting is too low, large text files may not be merged.
5. Select Ignore case to ignore the case of characters within lines.
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.
313
Activating third-party issue tracking plug-ins
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 280.
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.
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 280.
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.
314
Setting email server options
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.
Setting email server options
You must enable email and configure settings before email notifications can be 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.
315
Setting email notification options
3. Select Enable sending mail via Simple Mail Transport Protocol to send email via SMTP.
4. Enter the SMTP information.
n
Enter the 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 Negotiate, SSL 3.0, STARTTLS 1.0, or TLS 1.0, 1.1, or 1.2
protocols. Select <not set> if you do not want to use a secure protocol.
n
Enter the Port number. The default port is 465 if you select an SSL protocol and 25 if you do not.
n
Enter the Username and Password if the SMTP host requires an authenticated login. Leave these
fields empty if the host does not require authenticated login.
5. Click Test Connection to test the SMTP connection.
If the test fails, check the settings and contact your system administrator for help.
6. If you are experiencing SMTP problems, select the following options to help with troubleshooting.
n
Pause sending via SMTP stops sending email via SMTP. Make sure you clear this option as soon
as the problem is resolved because outgoing mail will back up in the queue.
n
Only send one message per SMTP connection to send one message per connection. Enable this
option if the server log contains entries stating 'The SMTP host’s reply code to the MAIL command
was 503' or 'only one MAIL per message'.
7. 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.
The Server Options dialog box opens.
2. Select Email Notifications from the Global Server Options category.
316
Setting Seapine License Server options
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.
317
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.
318
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.
319
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. 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.
320
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
You can set options to control how keywords, check outs, Unicode files, thumbnails for image files, and large
files are handled.
Note: These options apply to all branches and users, but can be overridden for specific mainline
branches. See Overriding server options for specific mainline branches, page 388.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select General from the Mainline Options category.
321
Setting general mainline options
3. Select Expand keywords to enable keyword expansion.
Keywords are case-sensitive placeholders that can be inserted into text files and expanded when files are
viewed or checked in. See Supported keywords, page 323.
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.
Note: Binary files are always exclusively checked out.
5. Select Allow check in of files without check out to allow users to check in files that are not checked
out.
If this option is selected, when users check in a repository, all checked out files and any files in a Modified
status are checked in. You may want to select this option if users previously used another source control
tool that supports checking in files without check out and prefer this method.
Note: We do not recommend selecting this option because it provides less control over files.
6. Select Allow workflow state changes during check in to allow users to change file states during
check in.
You may want to disable this option if you use triggers to set states during check in.
7. Select any Unicode File Options.
These options are used when auto-merging text files.
322
Supported keywords
Note: The international version of the Java Runtime Environment (JRE) contains character
conversion classes and support for locales other than the US English locale. If you use this JRE you
can enter the character encoding set 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.
8. Enter the Thumbnail size to set the thumbnail pixel size.
The default size is 128 by 128 pixels.
Tip: If you change the thumbnail size, you can also compact the database to purge the existing,
cached thumbnails.
9. Enter or select the maximum file size for adding or checking in Large Files.
n
Maximum file size specifies the maximum file size limit. The default value is 2000 MB.
n
Delta maximum file size specifies the maximum delta file size limit. Deltas contain the content
differences between file versions and are used to efficiently save new file versions. When deltas are
larger than the specified limit, Surround SCM adds or checks in full copies of updated files instead.
The default value is 100 MB.
10. Click OK to save the changes.
Supported keywords
Keywords are case-sensitive placeholders that can be added to text files. When viewing, getting, or checking
in files, Surround SCM looks for keywords and automatically embeds the corresponding information. For
example, Pat checks in a file that includes the $Author$ keyword. Surround SCM replaces the keyword with
$Author: PatUser$.
Note: Keywords cannot be expanded for binary files.
Keyword
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
323
Setting changelist server options
Keyword
Value
$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 131. You can set
options to enable or disable changelists, and to retain historical information.
Note: These options apply to all branches and users, but can be overridden for specific mainline
branches. See Overriding server options for specific mainline branches, page 388.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Changelists from the Mainline Options category.
3. Select a Changelist Usage option.
4. Clear Retain historical changelist information if you do not want to store changelist data.
Historical data is discarded when a changelist is committed.
5. Click OK to save the changes.
324
Setting minimum comment lengths for actions
Setting minimum comment lengths for actions
You can set the minimum number of characters that users must enter in comment fields when performing
actions. By default, comments are not required for any actions. Setting minimum comment lengths can help
enforce your policy to provide comments when performing actions, which can be helpful for historical
purposes.
Note: These options apply to all branches and users, but can be overridden for specific mainline
branches. See Overriding server options for specific mainline branches, page 388.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Comments from the Mainline Options category.
3. Enter the minimum number of characters required for comments for each action.
Valid values are 0-4096. If you do not want to require comments for an action, enter 0.
4. 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.
325
Setting auto-detect and ignore file options
Note: These options apply to all branches and users, but can be overridden for specific mainline
branches. See Overriding server options for specific mainline branches, page 388.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select File Names/Extensions from the Mainline Options category.
3. Select a file type and click Edit.
The Map File Extensions to File Type dialog box opens.
4. Enter the file extension.
5. Click OK.
The file extension is added.
Note: To remove a file extension, select the file type and click Edit. Delete the extension in the Map
File Extensions to File Type dialog box.
6. Enter file extensions you want Surround SCM to ignore in the Ignore file extension field.
326
Setting compliance options
7. Enter the file or directory names you want Surround SCM to ignore in the Ignore file or directory name
field.
Tip: You can use an asterisk (*) as a wildcard for file and directory names. For example, *uninstall
ignores all files or directories that end in "uninstall". Ignore file or directory name settings are case
sensitive.
8. Click OK to save the changes.
Setting compliance options
Depending on the workflow configuration, users may be required to enter an electronic signature when setting
specific workflow states on files. See Entering electronic signatures, page 37. You can set compliance
options to specify the maximum number of attempts users have to enter the correct signature password
before they are logged out, the signature components, and a certification message to display with the
signature to meet regulatory compliance requirements.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Compliance from the Mainline Options category.
3. Select the Maximum attempts before logging out a user to specify the number of failed attempts to
enter the correct electronic signature password before users are automatically logged out. Any unsaved
changes are discarded when the user is logged out. The default value is 3 attempts. You can select a
value between 1 and 10 or select <unlimited> to allow unlimited attempts.
4. Select a Signature Components option to specify if users are required to enter their password (One
component required) or their username and password (Two components required).
5. Select Signature meaning is required to require users to enter a reason for signing off on files in the
selected state.
327
Configuring default user options
A signature meaning that indicates review, approval, responsibility, or authoring of files is required for Title
21 CFR Part 11 compliance.
6. Enter a Certification and testimony message to display in the Signature Required dialog box.
This read-only message is displayed in the dialog box to explain the purpose of the signature, which is
required for Title 21 CFR Part 11 compliance.
7. 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 to set default user options for.
328
Configuring default user options
Category
Use to:
More
information
General
Enable external authentication, compress file transfers, specify text file
format, set the file comparison option used when updating and retrieving
files, and view HTML reports. The client-level general user options also
include options to set a username and password to connect to the server,
use single sign-on, and override the local computer name, but these
cannot be set on the server.
Setting
general user
options,
page 8
Diff/Merge
Specify applications to diff and merge files, add new diff applications, and
configure Guiffy, the integrated diff/merge application.
Setting
diff/merge
options,
page 51
View/Edit
File
Specify applications to view and edit files from Surround SCM.
Setting file
viewer and
editor
options,
page 18
File Dialog
Defaults
Enable or disable changelists, merge and differences, local directory
creation, and code review settings for file action dialog boxes.
Changing
defaults for
Surround
SCM
dialogs,
page 103
Source
Tree
Control information displayed in the Source Tree window and actions in
the branch, repository, and file list shortcut menus.
Setting
Source Tree
options,
page 99
Proxy
Server
Set the default proxy server and compress file transfers from servers.
Setting
proxy server
options,
page 435
File
Manager
(Linux
only)
Specify the Linux file manager to open working directories.
Setting the
file manager
on Linux,
page 14
Plug-ins
Specify the directories used to load custom plug-ins.
Setting plugin options,
page 278
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.
The default user options are set in clients when they connect to the server for the first time.
329
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 335.
n
Create a Release custom field to track the release a change is assigned to.
Note: See Setting custom fields, page 34 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 291.
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 332.
3. Select a field and click Edit to edit it. See Editing custom fields, page 333.
4. Select a field and click Top, Move Up, Move Down, or Bottom to change the display order in lists,
menus, and dialog boxes.
5. Select a field and click Delete to delete it. See Deleting custom fields, page 333.
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 333.
331
Adding custom fields
Adding custom fields
Add custom fields to capture additional file information. For example, you can add a text field used to enter a
file description or a list field used to select the release file changes are related to.
1. Choose Tools > Administration > Custom Fields.
The Custom Fields dialog box opens.
2. Click Add.
The Add Custom Field dialog box opens.
3. Enter a Field name.
4. Enter a Field code. Field codes are used with triggers. See Automating Actions with Triggers, page 335.
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 81 and Customizing the Source
Tree window, page 98.
332
Editing custom fields
Editing custom fields
You can edit custom fields to change the name, field code, and other properties.
Note: You cannot change the field format. Create a new custom field if you need to change the format.
1. Choose Tools > Administration > Custom Fields.
The Custom Fields dialog box opens.
2. Select a custom field and click Edit.
The Edit Custom Field dialog box opens.
3. Make any changes.
4. Click OK to save the changes.
Deleting custom fields
When a custom field is deleted, it is not permanently deleted from the Surround SCM Server. It is removed
from the list of available custom fields and users can no longer select it.
Note: Values set on files are not deleted from the database when custom fields are deleted.
1. Choose Tools > Administration > Custom Fields.
The Edit Custom Fields dialog box opens.
2. Select Show deleted custom fields.
3. Select a custom field and click Delete.
You are prompted to confirm the deletion.
4. Click Yes.
The custom field is deleted.
Restoring deleted custom fields
You can restore deleted custom fields.
1. Choose Tools > Administration > Custom Fields.
The Edit Custom Fields dialog box opens.
2. Select Show deleted custom fields.
3. Select a deleted custom field and click Restore.
The custom field is restored.
333
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
335
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
You can configure triggers to automatically perform actions when users change files and code reviews. For
example, you can add a trigger to email users when a file is assigned to them or prevent users from checking
out files in specific workflow states.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens. The Summary field displays the files that the trigger applies to, the events
that cause the trigger to run, and the actions to perform if the events occur.
336
Adding triggers
Note: If a trigger includes more than one instance of an action, the number of instances is displayed
next to the action. For example, 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.
3. Click Add to create a trigger. See Adding triggers, page 337.
4. Select a trigger and click Edit to change it. See Editing triggers, page 347.
5. Select a trigger and click Duplicate to duplicate it. See Duplicating triggers, page 349.
6. Select a trigger and click Disable to disable it. See Disabling and enabling triggers, page 349.
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 349.
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.
337
Adding triggers
3. Enter a Trigger Name.
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
338
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.
Adding triggers
5. Click the Preconditions tab to set the condition that files must meet to run the trigger.
6. Select a precondition.
The Precondition dialog box opens. You can add preconditions based on branch and repository, filename,
committed changelists, workflow states, users performing file events, security groups for users
performing file events, or custom field values.
Note: The in branch [<all branches>] and in repository [<all repositories>] precondition is selected by
default. The trigger runs for every file if you do not select additional preconditions. The Preconditions
dialog box does not open if you select the is part of a changelist commit precondition.
7. Enter or select the precondition values.
Preconditions have the same fields used in filter, advanced find, and report restrictions. See Adding
restrictions, page 213.
339
Adding triggers to run executables
8. Click OK.
The precondition values are added. The values are displayed in the conditions list and the Summary field.
9. Repeat steps 6-8 to select any additional preconditions. To change a precondition value, double-click the
value in the list.
When you add more than one precondition, Surround SCM treats them as ‘and’ conditions. Triggers only
fire when all of the selected preconditions are met.
10. Click the Actions tab to select the actions that occur when the trigger runs.
n
Click Add to add an action. See Adding trigger actions, page 347.
n
Select an action and click Edit to change it. See Editing trigger actions, page 348.
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 348.
11. Select Disable trigger after it runs once if you only want the trigger to run once.
12. Click OK to add the trigger.
Adding triggers to run executables
Note: Pre-event triggers that run scripts can cause performance issues because the Surround SCM
Server waits for the script to complete before moving to the next file. Post-event triggers should always be
used to run scripts unless the trigger is used for validation. Even a 1 second pre-event script will
significantly slow down the server because it takes an additional second per file that the trigger fires on.
You can run scripts and compiled programs from both pre- and post-event triggers. Surround SCM accepts
any command line call.
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.
340
Adding triggers to prevent events
Scripts that run from pre-event triggers must return a value that tells the server whether or not the event should
be allowed to complete. A return value of zero means that the event can continue. A non-zero return value
means that the event should be not be performed. If a non-zero value is returned, any messages output by the
script or program (output to stdout) are sent back to Surround SCM with the error. This error is truncated to
1024 characters.
Following are some examples of how to return a value from the trigger application:
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.
Tip: Seapine provides examples you can download to help you use executables with Surround SCM
triggers.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens.
2. Click Add.
The Add Trigger dialog box opens.
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 337.
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.
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.
341
Adding triggers to append comments to events
The Triggers dialog box opens.
2. Click Add.
The Add Trigger dialog box opens.
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 337.
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.
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 337.
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.
342
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.
Adding triggers to email users
7. Enter the Comment.
8. Select Disable trigger after it runs once if you only want the trigger to run once.
9. Click OK to add the trigger.
Adding triggers to 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.
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 337.
4. Click the Actions tab and click Add to add an action.
5. Select Send an email to from the Action list.
343
Editing email templates
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 344.
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.
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 461.
1. Click Edit Email Template when you are adding or editing a trigger or notification. See Adding trigger
actions, page 347 and Adding email notifications, page 91.
The Edit Email Template dialog box opens with the Email Template tab selected.
344
Editing email templates
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 315.
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.
7. Click OK.
The template is saved with the selected trigger or notification.
345
Adding triggers to set workflow states
Adding triggers to set workflow states
You can add a trigger action to change the file workflow state to a specified state or the default state. For
example, you can set the workflow state when files are checked in to track the files that require additional
attention.
Note: Triggers cannot set workflow states that require an electronic signature on files.
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 337.
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 <Default State> to use the default state set in the workflow template.
7. Enter a Comment to include with the state change.
8. Click OK.
9. Select Disable trigger after it runs once if you only want the trigger to run once.
10. Click OK to add the trigger.
Adding triggers to set custom field values
You can add a trigger action to set a custom field to a specified value. For example, you can set a custom field
value based on a file’s workflow state.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens.
2. Click Add.
The Add Trigger dialog box opens.
346
Editing triggers
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 337.
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
Edit a trigger to change the event or activity that causes it to run, the criteria used to select the files it applies
to, and the action it performs.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens.
2. Select a trigger and click Edit.
The Edit Trigger dialog box opens.
3. Make any changes. To edit a condition on the Preconditions tab, double-click the condition.
4. Click OK to save the changes.
Adding trigger actions
You can add multiple actions to a trigger. For example, a trigger can set a workflow state and send an 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.
347
Editing trigger actions
2. Select an Action.
You can add the following actions for triggers that run before an event occurs:
n
Run an executable
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
Note: Triggers cannot set workflow states that require an electronic signature on files.
3. Select the Parameters. The parameters change based on the selected action.
4. Click OK.
The action is added to the trigger.
Editing trigger actions
Edit trigger actions to change the settings. For example, you can edit a send email action to change the
recipients or email template.
1. Select an action on the Actions tab in the Add Trigger or Edit Trigger dialog box.
2. Click Edit.
The Edit Trigger Action dialog box opens.
3. Make any changes.
4. Click OK to save the changes.
Deleting trigger actions
You can delete actions from triggers if you no longer want them to be performed when the trigger runs.
Triggers must include at least one valid action to be enabled. If you delete all actions from a trigger, it is
disabled.
1. Select an action on the Actions tab in the Add Trigger or Edit Trigger dialog box.
2. Click Delete.
348
Duplicating triggers
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
349.
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.
349
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 346 and Changing workflow states,
page 36. 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 364.
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.
351
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.
352
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 <not set> and sends an email notification to
Marcy to inform her that the code review is complete.
About the default workflow template
Surround SCM includes a default workflow template, named General Workflow, that is designed for coding
projects. The default workflow includes the following states:
353
Customizing workflows
State
Destination states
<No State>
Work in Progress
Needs Attention
Awaiting Review
Reviewed
Awaiting Release
Released
Work in Progress
<No State>
Needs Attention
Awaiting Review
Needs Attention
<No State>
Work in Progress
Awaiting Review
Awaiting Review
<No State>
Work in Progress
Needs Attention
Reviewed
Reviewed
<No State>
Work in Progress
Needs Attention
Awaiting Release
Awaiting Release
<No State>
Released
Released
<No State>
Work in Progress
Needs Attention
Awaiting Release
Customizing workflows
Surround SCM’s workflow provides additional control and reporting over the change process of files.
Workflows are based on states, which indicate the current status of a file. For example, a file may be in an
Awaiting Review state after it is checked in. After the review is complete, the state may change to Ready to
Release. All files in a workflow have a State field. Users can manually change file states or you can use
triggers to automatically change states when a specific file event occurs.
Workflow templates define the states used in the workflow and the states that a file can move to from each
state. After you create a workflow template, you can assign it to multiple repositories, which provides
flexibility in managing files with different lifecycles. For example, a repository that contains source code files
may require a different workflow than a repository that contains documentation files.
Customizing a workflow includes the following steps:
354
Planning your workflow
n
Planning your workflow, page 355
n
Configuring workflow states, page 355
n
Configuring workflow templates, page 358
n
Automating workflows, page 355
n
Setting workflows for specific repositories, page 364
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 335.
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 331.
Configuring workflow states
States, which indicate the status of a file in 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 358.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens with the States tab selected.
355
Adding workflow states
2. Click Add to create a new state. See Adding workflow states, page 356.
3. Select a state and click Edit to change it. See Editing workflow states, page 357.
4. Select a state and click Delete to delete it. See Deleting workflow states, page 357.
Note: Select Show deleted states to display deleted states. Deleted states can be restored. See
Restoring deleted workflow states, page 358.
Adding workflow states
Surround SCM includes the following default states: <No State>, Work in Progress, Needs Attention,
Awaiting Review, Reviewed, Awaiting Release, and Released.
If the default states do not match your process, you can edit the state names or add new states. States are
not specific to a workflow template and can be used in any template.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens with the States tab selected.
2. Click Add.
The Add State dialog box opens.
3. Enter a State name and State description.
Make sure you use a descriptive name that users understand.
356
Editing workflow states
4. Select Electronic signature required to require users to enter an electronic signature when the state is
set on files.
Electronic signatures are used for compliance purposes to track who signed off on files in specific states
and when. You can configure compliance options to specify signature settings, such as the signature
components and certification message to include to meet compliance requirements. See Setting
compliance options, page 327.
5. Select Automatically reset to default state when version changes to reset the default state on files in
this state when the file version changes.
Selecting this option helps ensure files are not in an incorrect state when they are updated. For example,
you can set a Reviewed state to automatically reset to the default state to restart a review workflow when
additional changes are made in an updated file version.
Note: If Electronic signature required is selected, this option is automatically selected to ensure
users are prompted to enter another electronic signature when an updated file version is ready to be
signed off on.
6. Click OK.
The state is added.
Tip: You can also add states when you create workflow templates. See Adding states to workflow
templates, page 360.
Editing workflow states
Edit a workflow state to change the name or description.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens with the States tab selected.
2. Select a state and click Edit.
The Edit State dialog box opens.
3. Make any changes.
State changes are applied globally. If you change a state’s name, all files in that state use the new state
name. The old state name is saved in the file history.
Note: You can also edit states when you edit workflow templates. See Editing workflow templates,
page 362.
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 358.
1. Choose Tools > Administration > Workflow.
357
Restoring deleted workflow states
The Workflow dialog box opens with the States tab selected.
2. Select a state and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
The state is deleted.
Restoring deleted workflow states
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens with the States tab selected.
2. Select Show deleted states.
Deleted states are displayed in the list.
3. Select a deleted state and click Restore.
The state is restored.
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 353. 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.
358
Adding workflow templates
3. Click Add to add a template. See Adding workflow templates, page 359.
4. Select a template and click Edit to change it. See Editing workflow templates, page 362.
5. Select a template and click Duplicate to duplicate it. See Duplicating workflow templates, page 362.
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 362.
Adding workflow templates
Workflow templates define the states used in the workflow and the transitions that control the states a file can
move to from each state.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens.
2. Click the Workflow tab.
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 360.
6. Select a state and click Edit to change it. See Editing workflow states, page 357.
7. Select a state and click Top, Move Up, Move Down, or Bottom to change the display order.
8. Select a state and click Remove to remove it. See Removing states from workflow templates, page 361.
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. You cannot set states that
require an electronic signature or automatically reset states to the default state when file versions change
as the default state.
359
Adding states to workflow templates
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 363.
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 128.
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 and enter the state information to add a state to the workflow template and the
global list of available states. See Adding workflow states, page 356.
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 to add to the template. To select multiple states,
Ctrl+click each state.
3. Click OK.
The state is added.
360
Removing states from workflow templates
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 to remove states from and click Edit.
4. Select a state and click Remove.
If the state is not used in other workflow templates, you are prompted to mark the state as deleted.
Deleted states are not permanently deleted and can be restored. See Restoring deleted workflow states,
page 358.
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 <No State>.
3. Click Print to print the workflow transitions.
4. Click OK to save the changes.
361
Editing workflow templates
Editing workflow templates
Edit a workflow template to change the name, description, states, and transitions.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens.
2. Click the Workflow tab.
3. Select a workflow template and click Edit.
The Edit Workflow Template dialog box opens.
4. Make any changes.
You can edit workflow states when you edit workflow templates. State changes are applied globally. If
you change a state’s name, all files in that state use the new state name. The old state name is saved in
the file history. See Editing workflow states, page 357.
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 opens.
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 362.
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.
362
Diagramming workflows
You are prompted to confirm the deletion.
4. Click Yes.
The workflow template is deleted.
Diagramming workflows
Surround SCM's workflow diagram makes it easy to create complex workflows. With the click of a button,
you can diagram a workflow to the states and transitions. This can help you evaluate the workflow to see how
files move through the process and check for orphaned states or conflicts.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens.
2. Click the Workflow tab.
3. Select a workflow template and click Edit.
The Edit Workflow dialog box opens.
4. Click Diagram Workflow.
The diagram opens. The green double circle represents the default state and the blue lines indicate
transitions. A blue double circle indicates the state automatically resets to the default state when versions
change. A blue background indicates the state requires an electronic signature.
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.
363
Setting workflows for specific repositories
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 36.
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 36.
364
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 62. 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.
365
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. Icons indicate the type and status of the branch associated with a
shadow folder, which can help you troubleshoot any issues with updating folders. See Branch status
icons, page 169.
2. Click Add to create a shadow folder. See Adding shadow folders, page 367.
3. Select a folder and click Edit to change it. See Editing shadow folders, page 369.
4. Select a folder and click Force Update to update it. See Refreshing shadow folder contents, page 369.
5. Select a folder and click Delete to delete it. See Deleting shadow folders, page 369.
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.
367
Adding shadow folders
1. Choose Tools > Administration > Shadow Folders.
The Shadow Folders dialog box opens.
2. Click Add.
The Add Shadow Folders dialog box opens.
3. Click Set to select the branch and repository.
The Repository Browser dialog box opens.
4. Select the branch and repository 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.
368
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.
369
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. Icons indicate the branch type and status. See Branch status
icons, page 169.
371
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 to perform.
372
Button
Use to:
More
information
Toggle
Frozen
Freeze or unfreeze the branch. Users can see frozen branches but cannot
perform any activities that change files, such as checking files out or in.
Freezing and
unfreezing
branches,
page 379
Managing branch attributes
Button
Use to:
More
information
Toggle
Active
Make the branch active or inactive. Users cannot see or perform any
actions on inactive branches.
Inactivating
and
activating
branches,
page 379
Toggle
Caching
Change the branch caching mode. By default, all file and repository
information for a branch is cached when the Surround SCM Server starts.
If you have a large number of branches, it can take a while for the server to
cache all information at startup. You can use on demand caching to cache
information only when a user selects a branch.
Changing
branch
caching,
page 382
Toggle
Hidden
Hide or unhide the branch. Users cannot see hidden branches, but they
can still perform actions on them if they choose to view hidden files.
Hiding and
unhiding
branches,
page 378
Change
Type
Change the branch type or owner.
Changing
branch type,
page 381
Edit
Template
Modify the template used to specify the repositories included in the branch.
You can also remove the template from the branch.
Modifying
templates for
existing
branches,
page 380
Remove
Remove the branch. Removed branches are not deleted from the hard
drive and can be restored if needed.
Removing
branches,
page 384
Destroy
Permanently delete a removed branch. Destroyed branches are deleted
from the hard drive and cannot be restored.
Deleting
branches
permanently,
page 385
Restore
Restore a removed branch.
Restoring
removed
branches,
page 384
5. Click Save As to save the list or click Print to print it.
6. Click the Indexing tab to enable indexing to optimize searching for text in files. See Indexing branches for
optimized searches, page 374.
7. Click Close when you finish.
373
Indexing branches for optimized searches
Indexing branches for optimized searches
The Surround SCM indexing server indexes branches for optimized performance and results when searching
for text in files. The indexing server is installed with the Surround SCM Server and starts automatically when
the Surround SCM Server starts.
See Differences between indexed and non-indexed searches, page 227 for information about how indexed
versus non-indexed searches work.
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 375.
n
Start the indexing server if it is not running to enable indexed searching. See Managing the indexing server,
page 374.
n
View indexing status and information. See Viewing branch index details, page 376.
n
View the indexing server log to troubleshoot issues with corrupted indexes. See Viewing the indexing
server log, page 377.
n
Modify the indexing server startup options. See the Surround SCM Registry Utility help for information.
Managing the indexing server
The Surround SCM indexing server starts automatically when the Surround SCM Server starts. You may
need to restart the indexing server if you make changes to the indexing registry settings or stop the server.
You can also view the current server status, memory usage, index storage size, server version, and server
log.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Indexing Server from the Global Server Options category.
3. Click Start to start the indexing server if it is not running.
374
Turning branch indexing on or off
When the indexing server starts, branch indexes are available for searching. You can turn on indexing for
branches and view indexing status in the Branch Maintenance dialog box. See Turning branch indexing on
or off, page 375.
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 the Surround SCM Registry Utility help for
information.
5. Click Refresh to refresh the server information.
6. Click View Log to view the indexing server log and troubleshoot issues. See Viewing the indexing server
log, page 377.
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 the Surround SCM Registry Utility help
for information.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
2. Click the Indexing tab.
All mainline and baseline branches are displayed.
3. Select a Display Mode.
375
Viewing branch index details
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.
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.
376
Viewing the indexing server log
Note: If an index is corrupt, you can turn indexing off and then turn it on again to reindex the branch.
See Turning branch indexing on or off, page 375. 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 377.
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.
377
Renaming branches
4. Review the log information.
5. Click Close when you finish.
Renaming branches
Note: To rename mainline branches, see Renaming mainline branches, page 388.
1. Select the branch and choose Branch > Rename Branch.
The Rename Branch dialog box opens.
2. Enter a new name and any comments.
3. Click OK.
The branch is renamed.
Hiding and unhiding branches
Hidden branches are not displayed in the Branch menu and Branches tree, but they are still active. You may
want to hide branches to display a simplified branch structure. For example, you may want to hide snapshot
branches because they are static and not frequently used. Users can enable a user option to show hidden
branches.
378
Freezing and unfreezing branches
Keep in mind that hiding a parent branch does not hide its child branches. Hidden parent branches are
displayed in the Branches tree if a child branch is not hidden.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
Tip: You can also choose Branch > Branch Attributes > Hidden to hide branches.
2. Select the branch to hide or unhide and click Toggle Hidden.
If the selected branch is unhidden, you are prompted to confirm hiding 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 to freeze or unfreeze.
2. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
Tip: You can also choose Branch > Branch Attributes > Frozen to freeze a branch.
3. Click Toggle Frozen.
If the selected branch is unfrozen, you are prompted to confirm freezing 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 378.
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.
379
Modifying templates for existing branches
If the selected branch is active, you are prompted to confirm inactivating it.
3. Click Close to close the Branch Maintenance dialog box.
Modifying templates for existing branches
You can update an existing baseline or workspace branch to configure a template that specifies the repository
structure for the branch. For example, if a subrepository was excluded when the branch was created, but you
now need to include it, you can update the branch template to rebase the subrepository from the parent
branch. You can also remove templates from branches to use the same structure as the parent repository the
branch was created from.
Note: Templates control the repository structure of individual branches. Changing the repositories
included in the template for one branch does not affect other branches created using the same repository
structure.
1. Select the branch and choose Branch > Branch Properties.
The Branch Properties dialog box opens.
2. Click the Template tab and then click Modify.
3. Select a Template option.
380
Changing branch type
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
manually rebase it later to update it. See Rebasing branches, page 193.
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.
381
Changing branch caching
3. Select a Branch Type to change the workspace branch to a baseline branch.
4. Select a New Owner to change the workspace branch owner.
5. Enter the New Branch Name.
6. Enter any Comments, such as the reason for changing the branch type.
7. Click OK to save the changes.
8. Click Close to close the Branch Maintenance dialog box.
Changing branch caching
Branches are cached when the Surround SCM Server starts. You can change the caching mode to reduce
memory usage. Surround SCM includes the following caching modes:
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 383.
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 changing the cache mode.
3. Click Yes.
382
Setting branch caching server options
The cache mode is changed.
4. Click Close to close the Branch Maintenance dialog box. Setting branch caching server options
You can set dynamic branch caching options to control the size of the Surround SCM Server cache, which
can help reduce memory or performance issues.
Mainline branches are always cached when the Surround SCM Server starts. By default, baseline, snapshot,
and workspace branches are set to Cache on Demand, which means they are cached when users perform
actions that access a branch. When the Surround SCM Server starts, the most recently used Cache on
Demand, or dynamic, branches as of the last server shutdown are cached. If these branch types are changed
to Always Cache, they are always loaded when the server starts.
As additional branches are created, the cache may become too large, which can cause memory issues and
slow server startup times. If this happens, you can adjust the caching server options to reduce the number of
cached dynamic branches and set inactivity timeout limits for unloading inactive dynamic branches or
changing inactive Always Cache branches to Cache on Demand.
Note: If you are experiencing memory or performance issues, you may also want to evaluate if there are
any branches set to Always Cache that you can change to Cache on Demand. See Changing branch
caching, page 382.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Caching from the Global Server Options category.
3. Enter the Minimum dynamic branches to cache to indicate the minimum number of dynamic branches
per mainline branch to cache during server startup and to maintain in the cache.
This setting applies to each mainline branch. For example, if the server includes 10 mainline branches
that each include 10 branches and the minimum branches to cache setting is 10, the cache always stores
100 branches. The default 10 branches.
4. Enter the Inactivity timeout to indicate the number of minutes to leave a dynamic branch in the cache
without activity before it is unloaded.
A branch is considered inactive if no read or write activities that require the branch to be loaded in the
cache are performed in the specified number of minutes. Inactive dynamic branches, excluding the most
recently used branches, are automatically unloaded from the cache. The default is 60 minutes.
5. Enter the Maximum dynamic branches to cache to indicate the maximum number of dynamic
branches per mainline to cache.
383
Removing branches
If this limit is exceeded, inactive dynamic branches, excluding the most recently used branches, that
have not yet reached the inactivity timeout are unloaded until the minimum number of branches to cache
is reached. The default is 100 branches.
6. Select Force branch to cache on demand after inactivity timeout to automatically change unused
branches set to Always Cache to Cache on Demand after the specified number of days.
An informational message is added to the server log if a branch is forced to Cache on Demand. The
default is 120 days.
7. Click OK to save the changes.
Removing branches
Remove a branch if you do not want users to be able to access it. When a branch is removed, it is not deleted
from the hard drive and can be restored if needed. See Restoring removed branches, page 384.
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 375.
Note: To limit access to a branch, you can freeze, hide, or inactivate it instead of removing it. See
Managing branch attributes, page 371.
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.
Tip: You can view removed branches in the Branch Maintenance dialog box. See Managing branch
attributes, page 371.
Restoring removed branches
You can restore removed branches to give users access to them again.
384
Deleting branches permanently
Note: If you restore a branch that was indexed for searching before it was removed, you must manually
turn on indexing for the branch to reindex it. See Turning branch indexing on or off, page 375.
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 384.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
2. Select a branch and click Destroy.
You are prompted to confirm destroying 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.
385
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 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 to store the mainline branch in. See Adding RDBMS connections, page 403 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 using 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.
387
Renaming mainline branches
6. Click OK.
You are prompted to confirm creating the mainline branch.
7. Click Yes.
The mainline branch is created. See Branching, page 165.
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 378.
1. Select the mainline branch to rename and choose Tools > Administration > Rename Mainline
Branch.
The Rename Mainline Branch dialog box opens.
2. Enter a new name and any comments.
You cannot use the same name as any active, inactive, or removed mainline branches.
3. Click OK.
You are prompted to confirm the rename.
4. Click Rename Mainline.
A progress indicator opens and lets you know the mainline branch is being renamed.
Overriding server options for specific mainline branches
You can override general, comment, changelist, filename and extension, and compliance 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 305.
1. Select the mainline branch and choose Branch > Branch Properties.
The Properties dialog box opens.
2. Click the Options tab.
388
Overriding server options for specific mainline branches
3. Select a category.
Category
Includes options for:
More
information
General
Allowing checking in without check out, allowing multiple users
to check out files, expanding keywords, allowing workflow state
changes during check in, Unicode options for merging text files,
enabling thumbnails, and setting the maximum file size for large
files.
Setting
general
mainline
options,
page 321
Comments
Minimum character lengths for comments entered by users when
performing specific actions, such as check ins.
Setting
minimum
comment
lengths for
actions,
page 325
389
Moving repositories to different mainline branches
Category
Includes options for:
More
information
Changelists
Changelist usage and retaining historical changelist information.
Setting
changelist
server
options,
page 324
Files
Names/Extensions
File type extensions and names to automatically detect and
ignore when adding files.
Setting autodetect and
ignore file
options,
page 325
Compliance
Maximum attempts before logging out users if an incorrect
electronic signature is entered when changing workflow states
on files, required signature components, and the certification and
testimony message displayed in the Signature Required dialog
box.
Setting
compliance
options,
page 327
4. Select Override for the options to override and make any changes.
Select Inherit to use the mainline options set on the Surround SCM Server.
5. Click OK to save the changes.
Moving repositories to different mainline branches
To move a repository to another mainline branch, export it from the existing mainline to a new or existing
mainline. The repository, subrepositories, and files are copied to the destination mainline, and include the
following information:
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, reports, and electronic signatures 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.
390
Moving repositories to different mainline branches
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 297
and Overriding server options for specific mainline branches, page 388.
1. Choose Tools > Administration > Export Repository to Mainline.
The Export Repository to Mainline dialog box opens.
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 to store the branch. The list includes all RDBMS connections configured for the
Surround SCM Server. See Adding RDBMS connections, page 403 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 120.
391
Moving mainline branches to different databases or servers
Tip: Remember to inform users about new repository location.
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 400.
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 397.
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 379.
2. Convert the mainline branch to copy it to the other database. See Copying mainline branches to different
databases, page 393.
3. Activate the mainline branch. See Inactivating and activating branches, page 379.
4. Optionally destroy the mainline branch from the original RDBMS database. See Deleting mainline
branches permanently, page 397.
5. Repeat steps 1 - 4 for each mainline branch you want to copy to the new RDBMS database.
392
Copying mainline branches to different databases
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. 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:
1. Inactivate the mainline branch to move. See Inactivating and activating branches, page 379.
2. Convert the mainline branch to move it to the different RDBMS database. See Copying mainline branches
to different databases, page 393.
3. Remove the mainline branch from the current server. See Removing mainline branches, page 394.
4. Log in to the destination server.
5. Add the mainline branch to the destination server. See Restoring removed branches, page 384.
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 397.
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 379.
1. Choose Tools > Administration > Convert Mainline Branch.
The Mainline Destination dialog box opens.
2. Select a database Destination.
393
Removing mainline branches
The list includes RDBMS connections configured for the Surround SCM Server. Select the connection for
the database to store the mainline branch in. See Adding RDBMS connections, page 403 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.
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 399.
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 379.
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.
394
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 395.
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 396.
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 396.
1. Choose Tools > Administration > Add Existing Mainline Branch.
The Add Existing Mainline Branch dialog box opens.
2. Select RDBMS as the Mainline Type.
395
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 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: To restore a mainline branch stored in an RDBMS database, see Restoring RDBMS mainline
branches, page 395.
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.
396
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 421.
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 394.
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 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.
397
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 406.
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 400, Copying mainline branches to different databases, page 393, and Upgrading mainline branches,
page 421.
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.
399
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 402.
4. Click Convert to convert the database to a different type. See Converting the server database to a
different type, page 400.
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 399.
1. Make sure you are logged in to the Surround SCM Server to convert.
2. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
400
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.
Note: You can also manually change the database the Surround SCM Server is using. See Changing
the server database location, page 402.
401
Changing the server database location
Changing the server database location
You can configure the Surround SCM Server to use a different database. For example, you may need to point
to the server database to a new location after moving it or use a backup copy of the database if you
experience problems. You should not need to frequently change the server database.
1. Make sure you are logged in to the Surround SCM Server 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 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 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:
402
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.
Adding RDBMS connections
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 399.
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 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.
The Add Connection dialog box opens.
403
Adding RDBMS connections
4. Select a Connection Type.
The fields depend on the selected connection type.
5. Enter the RDBMS connection information.
n
PostgreSQL—Enter the Database Name, Host Name, Port, and Username and Password.
n
ODBC-SQL Server—Enter the Data Source Name (DSN). Only ODBC System Data Source Name
types are supported. Enter the Username and Password. If you are using Windows NT
authentication, leave these fields empty. The username and password of the logged in user on the
Surround SCM Server computer is automatically used.
n
Oracle—Enter the Service Name of the host to connect to, Port, and Username and Password.
6. Enter the Minimum number of connections to specify the smallest number of connections to store in
the database connection pool.
When the Surround SCM Server starts, it automatically creates the specified number of database
connections. Increasing this value can improve performance because the server does not need to create
a database connection later. If you increase this number, you may need to purchase additional licenses
from the database vendor. 7. Enter the Maximum number of connections to specify the largest number of connections to store in the
database connection pool.
The default number of connections is 999. Only change this value if you have a large number of mainline
branches and are using too many connections to the backend database.
8. Click Test to validate the connection.
The Test Connection dialog box opens and displays the results. If the test connection fails, you can copy
and paste the text into an 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.
404
Editing RDBMS connections
You can now add new mainline branches to the database or copy existing mainlines to it. See Creating
mainline branches, page 387 and Copying mainline branches to different databases, page 393. You can
also move the server database to the new database if you need to relocate it. See Setting the default
server database location, page 400.
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 379.
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.
Note: The RDBMS connection for the Surround SCM Server database is displayed, but you cannot
edit it. See Changing the server database location, page 402 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 379.
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 for information about backing up PostgreSQL
databases on the Surround SCM Server computer using the pgAdmin tool.
405
Locking databases for backups
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.
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 408.
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 help 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.
406
Setting database analyze and repair options
1. Choose Tools > Administration > Analyze/Repair Database.
The Analyze Database dialog box opens.
2. Click Options.
The Analyze and Repair Options dialog box opens.
3. Select Perform CHECKDB (SQL Server only) to verify the integrity of database objects in SQL Server.
This option runs the SQL Server CHECKDB command when analyzing databases and returns a list of
errors found. A DBA must manually repair the issues. Refer to the SQL Server help for information.
4. Select any Analyze and Repair options to check for specific repairable issues. See Repairs for common
database issues, page 410 for information about the repair actions performed when these issues are
found.
Option
Checks for:
Check for share
corruption
Shares that were not removed when a repository was removed, files still
marked as base share files after shares were removed, and invalid shares of
share links.
Check for duplicate
filename conflicts
Duplicate filenames in the same repository.
Check for orphaned
check outs
Files checked out by deleted users.
Check for undestroyed
repositories
Undestroyed child repositories with destroyed parent repositories or
undestroyed repositories in destroyed branches.
407
Analyzing and repairing databases
Option
Checks for:
Check for inconsistent
current versions
Files with inconsistent current version numbers.
Check for invalid tip
versions
Files with invalid tip version numbers.
Check for undestroyed
merge events
Merge event records that were not destroyed when the associated file was
destroyed.
Check for branches
with duplicate root
repositories
Corrupted branches with duplicate or invalid root repositories after a template
was applied.
Check if VACUUM is
needed
PostgreSQL vacuum needed to remove dead table rows to free up database
space and improve performance. PostgreSQL only.
5. Select Force reindex to reindex database tables. You may want to reindex tables if you notice a performance slowdown. This option only applies to
PostgreSQL and SQL Server databases. If you use Oracle, ask your DBA for help checking indexes.
Note: Reindexing may temporarily affect Surround SCM performance. As with any repair, you may
want to consider reindexing only during off-peak hours.
6. Click OK to save the changes.
Analyzing and repairing databases
If issues occur in the server database or databases for active RDBMS connections, you can analyze and
repair the databases to fix the issues.
Note: If you need to analyze and repair issues in databases not currently in use by a Surround SCM
Server, use the analyze utility. See the Surround SCM Analyze Utility help for information.
You can analyze databases at any time without affecting Surround SCM performance. If the analysis
indicates issues, you can repair them from Surround SCM. When repairing, Surround SCM is locked to
prevent users from writing to the database, but users can still perform read-only actions. Some repairs may
make branches temporarily unavailable while mainline branches are reloaded in the cache. You may consider
repairing databases during off-peak hours, such as in the evening or over the weekend.
Note: More advanced issues may require manual repair by your DBA.
1. Choose Tools > Administration > Analyze/Repair Database.
The Analyze Database dialog box opens.
408
Analyzing and repairing databases
2. Select the RDBMS connection to analyze or select <all active connections> to analyze databases for
all RDBMS connections with at least one active mainline branch.
If all mainline branches in an RDBMS connection are inactive or removed, the connection is skipped. You
can analyze these connections individually before reactivating or restoring mainline branches.
3. Click Options to configure analysis and repair options. See Setting database analyze and repair options,
page 406.
4. Click Analyze to analyze the selected database.
The analysis progress and results are displayed. You can copy and save the results for your database
maintenance records or to help DBAs troubleshoot other issues. If issues are found, you should back up
the database before repairing them. See Backing up Surround SCM databases, page 405.
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 410 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 when you finish.
409
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 share bases)
Removes the invalid shares
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 deleted users)
Removes the check outs
Undestroyed child repositories with
destroyed parent repositories
Destroys the child repositories
Undestroyed repositories in
destroyed branches
Removes the repositories in incompletely destroyed 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
Branches with duplicate root
repositories
Destroys duplicate or invalid root repositories and removes
templates from branches to restore them to their original structure
Vacuum needed (PostgreSQL
only)
Vacuums tables requiring it
410
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 412.
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 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.
5. Click Print to print log entries.
411
Server log levels
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
Activity
An event is written to the log when unusual activity occurs, such as a user trying to log in
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.
412
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
You can manually resend emails stuck in the mail queue if you do not want to wait for the Surround
SCM Server to send the email after it restarts.
1. Choose Tools > Administration > Mail Queue.
The Mail Queue dialog box opens.
2. Select the email to resend and click Reattempt.
Surround SCM tries to resend the email.
Deleting mail
You can delete emails stuck in the mail queue to prevent sending them when the mail queue reloads after the
Surround SCM Server is restarted.
1. Choose Tools > Administration > Mail Queue.
The Mail Queue dialog box opens.
413
Deleting mail
2. Select the emails to delete.
3. Click Delete.
The email is deleted from the mail queue.
414
Managing Auditable Processes
When properly implemented and managed, Surround SCM can strengthen most best practices and regulatory
compliance processes. You can use the following Surround SCM features to track your team's internal
processes and provide information about source files to meet compliance requirements.
File history and line-by-line annotation
You can review file history to see all actions performed on source files through the development lifecycle and
view details about specific actions performed on each version, such as the user who performed the action and
when. See Viewing file history, page 84.
You can also view line-by-line annotations to trace the history of changes between file versions, including new
and modified lines of content and the user who made the change. See Viewing line-by-line file changes, page
82.
Code review reports
You can use code review coverage reports to measure coverage of your code review process and
demonstrate quality control. See Creating code review coverage reports, page 244. You can also run reports
to save review process information for audits and provide historical information about code reviews. See
Running code review reports, page 75.
Electronic signatures and audit trail reports
You can configure a Surround SCM workflow to model your organization's change process, track the status of
files during their lifecycle, and ensure your team follows an established process when files are added or
updated. See Configuring Workflows, page 351.
To meet Title 21 CFR Part 11 compliance requirements, you can enable electronic signatures for workflow
states to track when files move to the state and who signed off on the files in that state. Signature records are
stored in the audit log table in the Surround SCM mainline database. You can run audit trail reports to validate
and review the signature records in the audit log during an audit or for other compliance purposes.
Perform the following tasks to enable and capture electronic signatures and create audit trail reports.
1. Configure workflow states that require an electronic signature. You can add new workflow states or edit
existing states to change the signature requirement. See Adding workflow states, page 356 and Editing
workflow states, page 357.
2. Configure compliance server options to specify electronic signature settings, such as the signature
components and the certification message to include with signatures. See Setting compliance options,
page 327. You can also override compliance options for specific mainline branches if needed. See
Overriding server options for specific mainline branches, page 388.
3. Users responsible for signing off on files set states on files and enter electronic signatures. See Entering
electronic signatures, page 37.
4. Create and run audit trail reports to review electronic signature information, such as when files entered
specific states and the users who entered signatures. See Creating audit trail reports, page 240.
415
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 418.
6. Click Restore Default Values to replace all renamed field labels with the default values.
7. Click OK to save the changes.
417
Syncing field labels with TestTrack
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.
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 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.
418
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 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.
419
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 422.
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 421.
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 425.
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'.
421
Upgrading non-RDBMS mainline branches
1. Select the mainline branch to upgrade and choose Tools > Administration > Upgrade Mainline
Branch.
The Upgrade RDBMS Mainline dialog box opens.
2. Select the connection 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'.
1. Select the mainline branch to upgrade and choose Tools > Administration > Upgrade Mainline
Branch.
422
Resolving custom field and workflow issues
You are prompted to upgrade the mainline branch.
2. Click Yes.
The Mainline Destination dialog box opens.
3. Select the Destination database for the upgraded mainline branch.
If the database is not listed, you may need to add an RDBMS connection for it. See Adding RDBMS
connections, page 403.
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 399.
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.
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.
423
Resolving custom field and workflow issues
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.
424
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.
Upgrading RDBMS connections
Note: A workflow template can only be added to the Surround SCM Server if all states that the
workflow uses are on the server.
Upgrading RDBMS connections
If an existing RDBMS connection that does not contain any active mainlines was configured in Surround SCM
2009 or earlier, you must manually upgrade the RDBMS connection before it can be used as a destination for
new mainline branches.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select RDBMS Connections from the General Server Options category.
3. Select the connection to upgrade.
Connections that require upgrading are marked as Old in the Format column. Upgrading a connection also
automatically upgrades all the mainline branches stored in the database.
4. Click Upgrade.
You are prompted to upgrade the mainline branch.
5. Click Yes.
The upgrade information is sent to the Surround SCM Server for validation.
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.
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.
425
Upgrading legacy labels
Labels created in earlier Surround SCM versions were applied to the file version in all branches. Now, you can
create labels for a mainline branch or a specific branch. Upgrading legacy labels allows you to choose the
existing labels to import and the branches to apply them to.
After legacy labels are upgraded, you can manage them the same way as other labels. See Using Labels,
page 145.
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 to upgrade. To select multiple labels, Ctrl+click each label.
4. Click Upgrade.
The Upgrade Legacy Labels dialog box opens. The branches the label can be applied to are displayed.
5. Enter a Label description.
This field is not available if you are upgrading multiple labels.
6. Select Show snapshot branches to include snapshot branches in the branch list.
7. Select the branch to apply the label to. To select multiple branches, Ctrl+click each branch.
If you select a branch that did not previously include any files with the label applied, the label is not applied
to any files.
426
Deleting legacy labels
Tip: The File count field displays the total number of files the label can be applied to. Compare this
number to the File Count column for each branch to determine the branches to apply the label to.
Typically, you will apply the label to the branch with the highest file count because it is a good
indicator of the branch the label is intended for. You may also apply the label to other branches
depending on how it is used. File count information not displayed if you are upgrading multiple labels.
8. Click OK.
The label is upgraded and you return to the Legacy Labels dialog box.
Note: You can also delete legacy labels. See Deleting legacy labels, page 427.
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.
427
Using Proxy Servers
The Surround SCM proxy server is a file caching proxy that improves performance of file retrievals at remote
client sites. The proxy server is usually installed on a separate computer from the master server at the remote
location where the clients using the proxy reside.
Proxy servers can help improve performance issues that are often experienced when source files are retrieved
across distributed development environments. Proxy servers cache files requested by remote Surround SCM
clients. Subsequent requests for the files are handled by the proxy server instead of the Surround SCM
Server, which decreases network usage and response time.
About proxy servers
Proxy servers are typically installed at remote sites to support Surround SCM clients. The proxy server
communicates with the master Surround SCM Server, which contains source files and file-related metadata.
As files are requested, they are retrieved from the master server and cached on the proxy server.
The next time a client issues a request to get the file, the proxy server checks to see if the file is available in
the cache. If the file is in the cache, the proxy server returns it to the client. If the file is not in the cache, it is
retrieved from the master server, added to the proxy server cache, and returned to the client.
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 432.
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.
429
Starting the Surround SCM Proxy Server
Files are cached in the SCMProxyCache directory in the directory where the Surround SCM proxy server
application is installed. As files are cached, a subdirectory is created using the name of the mainline branch
the files are retrieved from. Files are cached until a specified disk space limit is reached. The least recently
used files are deleted from the cache so files can continue to be cached. You can also set an age limit for files
before they are deleted from the cache or delete files manually.
About master servers and proxy servers
The proxy server is a client of the master Surround SCM Server and a server to client applications, which
means it listens for transactions from Surround SCM clients (GUI clients and the CLI) and it connects to the
Surround SCM master server to get files. The proxy server needs the same connection information that the
Surround SCM clients use to connect to the master server. The master server also needs proxy server
connection information to provide to the clients that use the proxy.
The proxy server only handles get operations. Check in operations and file metadata are managed by the
master Surround SCM Server to ensure that file versions and metadata information is always current. The
Surround SCM Server also handles security and licensing.
Before a proxy server can connect to a master Surround SCM Server, you must configure the master server to
accept proxy requests.
n
Master Surround SCM Server proxy settings are configured using a Surround SCM Client. See
Configuring proxy servers, page 431.
n
Proxy server computer options can be modified with the registry utility. See the Surround SCM Registry
Utility help for information.
Starting the Surround SCM Proxy Server
An administrative user must make sure the Surround SCM Proxy Server is running before clients can access
it.
430
Configuring proxy servers
Windows
If the proxy server is installed as a service, it starts automatically. If the server is installed as an application,
you must start it manually. Choose All Programs > Seapine Software > Surround SCM > Surround
SCM Proxy Server from the Start menu.
Note: If the server is installed as a service but not running or you need to restart it, see the Windows
documentation for information about starting a service.
Linux
Enter /usr/bin/surroundscmproxy start.
If you need to restart the server, enter /usr/bin/surroundscmproxy stop and then restart the server.
Configuring proxy servers
To ensure security of the master Surround SCM Server data, you must configure it to accept connections
from known proxy servers before attempting to use the proxy server. The installation and configuration of the
proxy server requires information about both the Surround SCM Server and proxy servers. You must set the
configuration options on both computers.
Note: We recommend adding a proxy server to the master Surround SCM Server before installing the
proxy server. However, if the proxy server is already installed and you add a proxy server to Surround
SCM, you can use the registry utility to configure the proxy server settings. The server name, password,
and port number must match. See the Surround SCM Registry Utility help for information.
1. Choose Tools > Administration > Proxy Maintenance.
The Proxy Server Maintenance dialog box opens.
431
Adding proxy servers
2. Select a proxy server to view the configuration information.
3. Click Add to add a proxy server. See Adding proxy servers, page 432.
4. Select a proxy server and click Edit to modify it. See Editing proxy server settings, page 434.
5. Select a proxy server and click Delete to delete it. See Deleting proxy servers, page 435.
Adding proxy servers
After you install the proxy server, you must set the connection information so the proxy server can
communicate with the master Surround SCM Server. You can also set options to control how the server
caches files and select proxy server users.
1. Choose Tools > Administration > Proxy Maintenance.
The Proxy Server Maintenance dialog box opens.
2. Click Add.
The Add Proxy Server dialog box opens.
432
Adding proxy servers
3. Enter a Proxy name.
Enter a unique name, such as the computer location.
4. Enter and confirm a proxy server Password. You must enter a password.
Note: Make sure the proxy name and password match the values in the registry utility. See the
Surround SCM Registry Utility help for information.
5. Enter the Proxy address.
This is the IP or host address of the computer where the proxy server application is installed. The address
must be resolvable by the clients that use the proxy.
6. Enter the Proxy port.
Surround SCM clients connect to the proxy server on this port via TCP/IP. The default port number is
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.
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.
433
Editing proxy server settings
Files smaller than the specified size are not cached and are always retrieved from the master server. The
default size is 10 KB.
9. Select any additional options.
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 435.
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 the Surround SCM Registry Utility help for information.
Editing proxy server settings
You can edit proxy server settings if the server location changes or you need to modify the configuration
options.
1. Choose Tools > Administration > Proxy Maintenance.
434
Deleting proxy servers
The Proxy Server Maintenance dialog box opens.
2. Select a proxy server and click Edit.
The Edit Proxy Server dialog box opens.
3. Make any changes.
4. Enter the proxy server password in the Confirm password field.
You must confirm the proxy server password before you can save the changes.
5. Click OK to save the changes.
The changes are sent to the proxy server based on the refresh interval value. To immediately send
changes to the proxy server, you must restart the proxy server on the computer where it is installed or use
a remote management utility to restart it. After the proxy server restarts, it retrieves the new settings and
refreshes the cache.
Note: If you change the proxy server name or password, you must also update the proxy server registry
settings. See the Surround SCM Registry Utility help for information.
Deleting proxy servers
You can delete proxy servers if they are no longer used.
1. Choose Tools > Administration > Proxy Maintenance.
The Proxy Server Maintenance dialog box opens.
2. Select a proxy server and click Delete.
The proxy server is deleted.
Setting proxy server options
You may need to set proxy server options if your organization uses proxy servers. See Using Proxy Servers,
page 429.
Note: User options apply only to the current user account logged in to the computer. 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.
435
Setting proxy server 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.
436
Managing the Surround SCM Web Server
The Surround SCM Web Server provides access to Surround SCM Web, a web-based application that allows
users to view and download Surround SCM source files from a browser.
To use Surround SCM Web, the Surround SCM administrator must specify HTTP and HTTPS port numbers
and the Surround SCM Server connection information for the web server configuration during installation. The
Surround SCM Registry Utility includes additional options to change the Surround SCM Web port numbers,
use your own SSL certificate, and import the public key fingerprint if RSA key exchange is configured on the
Surround SCM Server. See the Surround SCM Registry Utility help for information.
Starting the Surround SCM Web Server
An administrative user must make sure the Surround SCM Web Server is running before users can log in
to Surround SCM Web.
Windows
The Surround SCM Web Server is installed as a Windows service and starts automatically.
Note: If the server is not running or you need to restart it, see the Windows documentation for information
about starting a service.
Linux
Enter /usr/bin/surroundscmweb start.
If you need to restart the server, enter /usr/bin/surroundscmweb stop and then restart the server.
437
Managing the Surround SCM CMIS Server
The Surround SCM Content Management Interoperability Services (CMIS) Server provides access to
Surround SCM files and actions through CMIS clients, such as Adobe Drive and CMIS Workbench. CMIS
repositories, which map to Surround SCM repositories, must be configured on the Surround SCM CMIS
Server before users can access Surround SCM from CMIS clients.
Starting the Surround SCM CMIS Server
An administrative user must make sure the Surround SCM CMIS Server is running before configuring CMIS
repositories. The server must also be running before users can access Surround SCM files and actions from
CMIS clients, such as Adobe Drive and CMIS Workbench.
Windows
The Surround SCM CMIS Server is installed as a service and starts automatically.
Note: If the server is not running or you need to restart it, see the Windows documentation for information
about starting a service.
Linux
Enter /usr/bin/surroundscmcmis start.
If you need to restart the server, enter /usr/bin/surroundscmcmis stop and then restart the server.
Starting the Surround SCM CMIS Admin Utility
An administrative user can use the Surround SCM CMIS Admin Utility to configure CMIS repositories so
users can access Surround SCM files and actions from CMIS clients, such as Adobe Drive and CMIS
Workbench.
Windows
Choose All Programs > Seapine Software > Surround SCM > Surround SCM CMIS Admin Utility on
the Start menu.
Linux
Enter /usr/bin/surroundscmcmisadmin.
Configuring CMIS Server options
You can manage CMIS repositories and change the server port number using the Surround SCM CMIS Admin
Utility.
Note: After the Surround SCM CMIS Server is configured, you must provide users with the server
address before they can connect to it from CMIS clients. The default CMIS Server address is
ServerName:PortNumber/atom. For example, localhost:8080/atom.
439
Adding CMIS repositories
1. Start the Surround SCM CMIS Admin Utility. See Starting the Surround SCM CMIS Admin Utility, page
439.
The server admin utility opens.
2. Click Add to add a CMIS repository. See Adding CMIS repositories, page 440.
3. Select a repository and click Edit to edit it. See Editing CMIS repositories, page 441.
4. Select a repository and click Delete to delete it. See Deleting CMIS repositories, page 442.
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 439. 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.
440
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 439.
Editing CMIS repositories
You can edit CMIS repositories to change the name, Surround SCM Server address or port, and mapping to
the Surround SCM repository on a specific branch or all branches.
1. In the Surround SCM CMIS Admin Utility, select a repository and click Edit.
441
Deleting CMIS repositories
2. Make any changes.
3. Click OK to save the changes.
The CMIS Server automatically refreshes data every 30 minutes, but you can restart the CMIS Server for
the changes to take effect immediately. See Starting the Surround SCM CMIS Server, page 439.
Deleting CMIS repositories
You can delete CMIS repositories to prevent users from accessing Surround SCM files in the corresponding
repository from CMIS clients.
1. In the Surround SCM CMIS Admin Utility, select a repository and click Delete.
The CMIS repository is deleted. The CMIS Server automatically refreshes Surround SCM data every 30
minutes, but you can restart the CMIS server for the changes to take effect immediately. See Starting the
Surround SCM CMIS Server, page 439.
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 411.
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.
442
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.
443
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.
444
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.
445
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 289 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:
Login Via
GUI Client
Log in using the GUI
client
Login Via
CLI Client
Log in using the
command line
interface (CLI)
Login Via
SCC DLL
Integration
Log in from SCCIcompliant
applications
Login Via
WebDAV
Log in using
WebDAV
Login Via
Microsoft
Office
Integration
Log in from Microsoft
Office
Login Via
API
Log in using the
Surround SCM API
More information
Enables users to add the Surround SCM menu to Microsoft Word,
Excel, PowerPoint, Access, and Project
447
General security commands
Command
Provides access
to:
Login Via
CMIS Client
Log in from CMIScompliant
applications
Login Via
Web Client
Log in using the
Surround SCM Web
client
Edit
TestTrack
Integration
Tools > TestTrack
Integration >
Connections
Add/Remove
Files from
Labels
Activities >
Advanced > Add
Label
More information
Enables users to configure connections to TestTrack Servers and
projects. TestTrack connections are available to all users, but a
TestTrack username and password is required to access a project.
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
Reports
Tools > Reports
If this command is disabled, users can still generate a differences
report from the History dialog box.
Edit Own
Email
Notifications
Tools > My Email
Notifications
Lets users edit their own email notifications only. The Edit Triggers
command must be enabled for users to add or edit email
notifications.
View Own
Committed
Changelists
My Committed from
the Filter changelists
by list (Tools >
Changelists)
448
Admin security commands
Command
Provides access
to:
More information
Add/Edit
Private
Filters
Tools > Filters
Lets users manage their own filters only.
Add/Edit
Private
Reports
Tools > Reports
Lets users manage their own reports only.
Add External
Reports
Tools > Reports
Lets users only add reports from external reporting services to
Surround SCM. The report is managed in the external reporting
service. The Add/Edit Private Reports command must also be
enabled for users to add external reports.
Edit Own
Comments
Edit Comments
button in the file and
repository History
Details dialog boxes
Lets users edit their own comments only.
Modify
Shelves
Activities > Shelve
Files
Lets users manage their own shelves only.
Buttons on the
Shelves window
(View > Shelves)
Admin security commands
Only enable the following commands for administrator security groups.
Command
Provides access to:
Edit Server
Options
Tools > Administration > Server
Options
More information
Tools > Administration > Default
User Options
Create Mainline
Branch
Tools > Administration > Create
Mainline Branch
Must be enabled to migrate a database to
Surround SCM from another source control
provider.
Tools > Administration > Upgrade
Mainline Branch
449
Admin security commands
Command
Provides access to:
Remove
Mainline Branch
Tools > Administration > Remove
Mainline Branch
More information
Tools > Administration > Destroy
Removed Mainline
Rename
Mainline Branch
Tools > Administration > Rename
Mainline Branch
Analyze
Database
Tools > Administration >
Analyze/Repair Database
Analyze button on the Analyze
Database dialog box (Tools
> Administration > Analyze/Repair
Database)
Repair Database
Tools > Administration
> Analyze/Repair Database
Repair button on the Analyze
Database dialog box (Tools
> Administration > Analyze/Repair
Database)
Void Check Out
Tools > Administration > Void
Check Out
Lock Database
Tools > Administration > Database
Lock
Manage Shadow
Folders
Tools > Administration > Shadow
Folders
Manage Triggers
Tools > Administration > Triggers
Manage Mail
Queue
Tools > Administration > Mail
Queue
Edit Other
Users’ Pending
Changelists
Pending For User from the Filter
changelists by list (Tools >
Changelists)
450
Also lets users enable email notifications for all
users. To allow users to only work with their own
email notifications, enable the Edit Own Email
Notifications command in the General category.
If this command is enabled, users can work with
other users’ changelists, but some actions, such
as Check In, may not be available.
Admin security commands
Command
Provides access to:
View All
Committed
Changelists
All Committed from the Filter
changelists by list (Tools >
Changelists)
Edit Custom
Fields
Tools > Administration > Custom
Fields
Modify
Workflow/States
Tools > Administration > Workflow
Override
Workflow
Activities > Advanced > Change
State
State list in the Properties dialog
box (Activities > Properties)
More information
If this command is enabled, users can set a file’s
workflow state to any available state. The
available states are not restricted by the
workflow.
State list in the Check In Files
dialog box
Manage Public
Filters
Buttons on Filters dialog box for
public filters only (Tools > Filters)
Edit Other Users
Private Filters
Edit button on Filters dialog box for
filters created by other users (Tools
> Filters)
Manage Public
Reports
Buttons on Reports dialog box for
public reports only (Tools > Filters)
Edit Other Users
Private Reports
Edit button on Reports dialog box
for reports created by other users
(Tools > Reports)
Edit Proxy
Server Settings
Tools > Administration > Proxy
Maintenance
Manage Labels
Tools > Administration > Labels
If this command is enabled, users can create
filters that are shared with all other users and
modify other public filters.
If this command is enabled, users can create
reports that are shared with all other users and
modify other public reports.
Tools > Administration > Upgrade
Legacy Labels
451
Users security commands
Command
Provides access to:
Delete Labels
Delete button on the Labels dialog
box (Tools > Labels)
More information
Delete button on the Legacy Labels
dialog box (Tools > Upgrade
Legacy Labels)
Edit Other
Users'
Comments
Edit Comments button in the file
and repository History Details
dialog boxes
If this command is enabled, users can edit
comments entered by other users.
Edit Other
Users' Shelves
Edit Shelf and Delete Shelf buttons
on Shelves window for shelves
owned by other users (View
> Shelves)
If this command is enabled, users can rename,
change ownership and sharing options, and
delete shelves owned by other users.
Edit Other
Authors' Code
Reviews
Open Review and Start Code
Review buttons on Code Reviews
window for code reviews users are
not the author of (View > Code
Reviews)
If this command is enabled, users can create,
edit, add file versions to, and start code reviews
they are not the author of.
Authors and Reviewers lists on
Properties tab in Code Review
dialog box for open code reviews
users are not the author of
Code reviews users are not the
author of are listed on Add to Code
Review dialog box (Activities
> Add to Code Review)
Delete Code
Reviews
Delete button on Code Reviews
window (View > Code Reviews)
Export
Repository to
Mainline
Tools > Administration > Export
Repository to Mainline
Show Licenses
In Use
Tools > Administration > Licenses
In Use
If this command is enabled, users can delete any
existing code reviews.
Users security commands
If all commands in the Users category are disabled, users cannot access the Users window. View > Users is
disabled.
452
Security Groups security commands
Command
Provides access to:
More information
Retrieve User
Retrieve Global Users button on
the Users window (View > Users)
Enables users to retrieve users from the Seapine
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
Integration
Settings
Tools > TestTrack Integration >
User Settings
Enables users to specify their TestTrack or other
issue tracking tool username and password.
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)
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 289.
Command
Provides access to:
More information
View
Repository
List
View the list of all repositories on the
Surround SCM Server
If this command is enabled on the Server
Security tab, users cannot view any repositories
or branches.
453
Files security commands
Command
Provides access to:
More information
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
File
Activities > Remove File
Repository > Remove Repository
Remove button on the Template tab in the
Properties dialog box for baseline
branches (Branch > Branch Properties)
Destroy
File
Activities > Destroy File
Destroy button on the Removed Items tab
in the Properties dialog box (Activities >
Properties)
Permanently destroy repository check
box in the Remove Repository dialog box
(Activities > Destroy File)
Requires the Remove File command to allow
users to destroy repositories.
Destroyed files and repositories cannot be
restored.
The Permanently destroy repository check box
changes to Permanently destroy repository and
contents if the Force recursive remove check
box is selected.
Also allows users to remove repositories from
branch templates when removing and
permanently destroying repositories from
branches that use templates.
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)
Check
In/Out File
Activities > Check Out
Also enables users to check out and check in a
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.
454
Branch security commands
Command
Provides access to:
Rename
File
Activities > Rename File
Change
File Type
File type list in the Properties dialog box
(Activities > Properties)
Change
File
Properties
Expand keywords list in the Properties
dialog box (Activities > Properties)
View File
History
Activities > History
More information
Changing the file type changes it in all
branches.
Requires the Get File command to allow users
to 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 Files
Activities > Share Files
Break
Shares
Activities > Break Shares
Set
Custom
Field
Values
Change field values on Custom Fields tab
in the Properties dialog box (Activities >
Properties) and Custom Fields tab in the
Add Files dialog box
Requires the Add Files command.
Activities > Advanced > Bulk Custom
Field Changes
Change
State
Activities > Advanced > Change State
State list in the Properties dialog box
(Activities > Properties)
The State list in the Check In Files dialog box is
only available if the Allow workflow state
changes from check in option is selected in the
Server Options dialog box.
State list in the Check In Files dialog box
Move
Activities > Move Files
Repository > Move Repository
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 297.
455
Branch security commands
Command
Provides access to:
Create Baseline
Branch
Baseline from the Branch type
list (Branch > Create Branch)
Create
Workspace
Branch
Workspace from the Branch
type list (Branch > Create
Branch)
Create Snapshot
Branch
Snapshot from the Branch type
list (Branch > Create Branch)
View Branch
History
History tab in the Properties
dialog box (Branch > Branch
Properties)
More information
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 in the Branch Maintenance
dialog box (Tools >
Administration > Branch
Maintenance)
Permanently destroy branch
check box in the Remove
Branch dialog box (Branch >
Remove Branch)
456
Destroyed branches cannot be restored.
Branch security commands
Command
Provides access to:
More information
Change Branch
Attributes
Toggle Frozen, Toggle Active,
Toggle Caching, and Toggle
Hidden buttons on the General
tab in the Branch Maintenance
dialog box (Tools >
Administration > Branch
Maintenance)
Users can also freeze and unfreeze branches if the
Freeze/Unfreeze Branch command is enabled.
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
in Branch
Maintenance
Ignore branch security check
box on the General tab in the
Branch Maintenance dialog box
(Tools > Administration >
Branch Maintenance)
Destroy Other
Users’
Workspace
Branches
Destroy button on the General
tab in the Branch Maintenance
dialog box when another user’s
workspace branch is selected
(Tools > Administration >
Branch Maintenance)
Allows users to override the security set for the
selected branch and apply the available options in
the Branch Maintenance dialog box.
Show all private branches
check box on the General tab in
the Branch Maintenance dialog
box
457
Branch security commands
Command
Provides access to:
Change Branch
Type
Change Type button on the
General tab in the Branch
Maintenance dialog box (Tools
> Administration > Branch
Maintenance)
Promote Branch
Branch > Promote Branch
Branch > Promote File
Rebase Branch
Branch > Rebase Branch
Branch > Rebase Files
Duplicate
Changes
More information
Users must also have some file permissions for the
repository being promoted to. The following
commands must also be enabled to promote to a
branch: Add File to promote an add, Check In File to
promote a change, Remove File to promote a
remove.
Users must also have some file permissions for the
repository being rebased from. The following
commands must also be enabled to rebase from a
branch: Add File to rebase an add, Check in File to
rebase a change (also requires Get File in the parent
branch), Remove File to rebase a remove.
Branch > Duplicate Changes
Duplicate Changes button in
the Manage Changelists dialog
box (Tools > Changelists)
Rollback
Promote/Rebase
Branch > Rollback Promote
Branch > Rollback Rebase
Rename Branch
Branch > Rename Branch
Freeze/Unfreeze
Branch
Toggle Freeze button on the
General tab in the Branch
Maintenance dialog box (Tools
> Administration > Branch
Maintenance)
Branch > Branch Attributes >
Freeze
458
Enable this command to allow users to freeze and
unfreeze branches if the Change Branch Attributes
command is not enabled.
Branch security commands
Command
Provides access to:
Manage Branch
Indexes
Toggle Indexing button on the
Indexing tab in the
Branch Maintenance dialog box
(Tools > Administration >
Branch Maintenance)
More information
Branch > Branch Indexing >
On/Off
Indexing on check box on the
Index tab in the
Branch Properties dialog box
(Branch > Branch Properties)
459
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 344.
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_<field code> *
Custom field code
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_
EXTERNALATTACHMENTCONNECTION
Issue tracking tool connection name
SSCM_EXTERNALATTACHMENTID
Issue ID the file is attached to
SSCM_
EXTERNALATTACHMENTPROVIDER
Issue tracking tool name
SSCM_FILE *
Filename
SSCM_FILELINK *
File hyperlink in sscm:// format
461
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_<field code> *
Custom field code
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
462
Appendix B: Environment Variables
Variable
Definition
SSCM_CLIENTIP
User’s IP address
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 *
Code review file status
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
463
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.
465
Windows network place
3. Click the branch or repository that contains the file to view.
4. Click the file to view.
The file opens.
Tip: You can save a copy of the file from the web browser to a local directory, but you cannot check
in any changes.
Windows network place
Add a network place to access a WebDAV directory in Windows. You can work with Surround SCM
repositories and files the same way you work with folders and files in Windows. For example, you can add
files, delete files, create folders to add new repositories. Keep in mind that these changes are made on the
Surround SCM Server.
Note: You can only add a Windows network place to access a WebDAV directory if the WebDAV CGI is
hosted on an Apache web server.
1. Open My Network Places.
466
Windows network place
2. Double-click Add Network Place.
The Add Network Place Wizard starts.
3. Click Next.
4. Click Choose Another Network Location.
5. Click Next.
6. Enter the WebDAV directory address.
For example, enter 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.
467
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.
468
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 <WebDAV directory address> /mnt/dav.
The WebDAV directory is mounted as a local directory.
2. Change (cd) to the alias directory to access Surround SCM branches, repositories, or files.
469
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.
471
Glossary
Common ancestor
Originating file used to compare one or two sets of changes. Used to perform two-way and three-way
merges when promoting and rebasing files.
Delta
The content differences between file versions. Instead of storing full copies of each file version, Surround
SCM uses compressed deltas to efficiently save new versions.
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.
472
Glossary
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.
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.
473
Glossary
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.
Workspace branch
A private branch that other users cannot access. Workspace branches isolate work and changes from
other users.
474
Index: Adding – Branch templates
Index
Advanced find files 211
Analyze and repair options 406
A
Analyzing databases 406, 408
Adding
Analyzing issue risk in files 273
actions to changelists 132
Annotating files 82
changelists 131
CMIS repositories 440
results 83
API 443
custom fields 332
.NET 445
diff/merge applications 51
avoiding conflicts 443
email notifications 91
C 443
existing mainline branches 394
Java 444
non-RDBMS format 396
Attaching files
RDBMS format 395
external issues 281
external reports to Surround SCM 257
TestTrack items 267
files 30
Audit trail reports 240
files to code reviews 62
Authentication methods 310
filters 231
B
licenses 4
plug-in directories 278
proxy servers 432
RDBMS connections 403
reports 239
repositories 111
security groups 292
server connections 5
shadow folders 367
TestTrack connections 265
TestTrack issues 270
trigger actions 347
triggers 337
users 299
workflow states 356
workflow templates 359
working directories 12
Address toolbar 234
Backups
databases 405
locking databases 406
Base file 125
Baseline branches 165
Blame See Annotating files
Bookmarks
adding 235
changing keyboard shortcuts 236
deleting 236
editing 236
Branch menu 7
Branch templates 172
applying to existing branches 380
creating 173
modifying 380
removing from branches 380
selecting for new branches 174
475
Index: Branches – Changelists
Branches
rolling back promoted files 192
activating 379
rolling back rebased files 201
adding existing mainlines 394
selecting templates 174
applying templates to existing branches 380
shortcut menu 8, 101
baseline 165
snapshot 166
bookmarking 235
templates 172
caching 382
turning indexing on or off 375
changing type 381
unfreezing 379
controlling access 297-298
unhiding 378
creating 170
upgrading mainlines 421
creating mainline 387
viewing 209
creating templates 173
viewing index details 376
deleting permanently 385
when to branch 166
differences 177
workspace 166
differences report 181
Branches tree 8
example 167
Break shares
freezing 379
476
files 126
hiding 378
Bulk custom field changes 35
history 207
C
icons 169
Caching
inactivating 379
branches 382
including and excluding repositories 173
proxy server 430
indexing 374
server options 383
mainline 165
Certification and testimony message 328
managing attributes 371
Changelists
modifying templates 380
adding comments to files 137
promoting 184
adding file actions 132
properties 208
committed 138
rebasing 193
committing 137
removing 384
creating 131
removing mainlines 394
editing file actions 136
removing templates 380
managing 132
renaming 378
moving actions 136
restoring 384
pending 133
restoring mainlines 394
printing 135, 139
Index: Changing server database location – Compliance
removing 136
Code reviews 57
removing file actions 137
adding comments 72
renaming 135
adding files 62
rolling back 140
addressing comments 73
saving 135, 139
configuring settings for repositories 365
searching for committed 139
coverage reports 244
selecting 144
creating 61
server options 324
deleting 79
viewing details 133
deleting comments 73
Changing server database location 402
editing 68
Charting report data 257
editing comments 73
Checking for new versions 320
finding 74
Checking in files 26
managing 60
copying files 180
moving comments 73
entering comments 27
opening 67
merged files 46
removing files 66
Checking out files 23
reports 75
undoing 25
reviewing files 68
voiding 303
selecting 65
Cherry-picking See Duplicating changes
starting 66
Client-side plug-ins 277
status 59
Cloaking repositories 119
viewing included files 78
CMIS Admin Utility
viewing unaddressed comments 73
starting 439
CMIS repositories
Columns
changing contents 98
adding 440
changing width 98
deleting 442
sorting 99
editing 441
CMIS Server
configuring 439
Comments
editing for file actions 87, 128
setting minimum length 325
port number 440
Committing changelists 137
server address 439
Compliance 415
starting 439
audit trail reports 240
troubleshooting 442
server options 327
477
Index: Converting – Deleting
Converting
Check Out Files 106
mainline branches to different databases 393
Get Files 104
server database to a different type 400
Shelve Files 109
Copied files
checking in 180
Creating
branches 170
Undo Check Out Files 106
Default server database 400
Default user options 328
Deleting
changelists 131
branches 385
labels 147
CMIS repositories 442
mainline branches 387
custom fields 333
repositories 111
diff/merge applications 54
shelves 161
email notifications 94
Custom fields
files 40
adding 332
filters 234
changing multiple 35
labels 149
configuring 331
legacy labels 427
deleting 333
mail 413
editing 333
mainline branches 397
resolving issues 423
proxy servers 435
restoring 333
RDBMS connections 405
setting 34
reports 259
Custom toolbar 103
repositories 122
D
security groups 295
Databases
server connections 6
analyzing and repairing 406, 408
shadow folders 369
backing up 405
shelved files 162
creating tables 399
shelves 162
locking 406
Surround SCM Server log entries 412
maintaining 399
TestTrack connections 266
repairing 410
trigger actions 348
scheduling data purges 320
triggers 349
setting analyze and repair options 406
users 302
Default file dialog options 103
478
viewer and editor settings 20
Add Files 107
workflow states 357
Check In Files 105
workflow templates 362
Index: Destroying – Electronic signatures
working directories 14
Destroying
Editing
changelist file actions 136
branches 385
CMIS repositories 441
files 40
code reviews 68
removed mainline branches 397
custom fields 333
repositories 122
diff/merge applications 53
Diagramming workflows 363
email notifications 94
Diff applications
email templates 344
adding 51
files 26
deleting settings 54
filters 233
editing settings 53
labels 148
Diff/merge application settings 54
proxy server settings 434
Diffing 43
RDBMS connections 405
branch differences report 181
reports 258
branches 177
security groups 294
file differences report 48
server connections 6
files 43
shadow folders 369
image files 50
shelves 162
labels 152
TestTrack connections 266
shelved files 162
TestTrack issues 271
working directories 112
trigger actions 348
Downloading RSA keys 312
triggers 347
Duplicating
users 302
email notifications 94
viewer and editor settings 20
filters 233
workflow states 357
labels 149
workflow templates 362
reports 258
working directories 13
security groups 295
triggers 349
adding for specific file types 18
workflow templates 362
changing text display options 20
Duplicating changes 177, 202
E
Editor for files
deleting settings 20
actions 205
editing settings 20
tracking changes 205
setting default application 18
Electronic signatures
certification and testimony message 328
479
Index: Email notifications – Files
compliance options 327
Get Files 104
entering 37
Shelve Files 109
Email notifications
Undo Check Out Files 106
adding 91
File extension user options 108
deleting 94
File information 88
disabling 94
File list
duplicating 94
printing 263
editing 94
saving 262
enabling 94
File manager user options 14
setting server options 316
File names/extensions server options 325
setting up 91
File status 17
Email server options 315
Filename search 211
Email templates
Files
editing 344
adding 30
field codes 461
bookmarking 235
Encryption 309
enabling 308
breaking shares 126
checking in 26
Environment variables 461
checking out 23
Executables
deleting from shelves 162
running from triggers 340
deleting permanently 40
Expanding keywords 322
destroying 40
Exporting
differences 43
repositories to different mainlines 390
External reports
editing 26
finding 211
adding to Surround SCM 257
getting 15
creating 258
history 84
F
image differences 50
Favorites
labeling 150
see Bookmarks 235
merging 45
Field codes 461
merging unrelated 46
File details pane 8, 81
moving 37
File dialog defaults 103
opening local copies 21
480
Add Files 107
promoting 189
Check In Files 105
rebasing 198
Check Out Files 106
removing 39
Index: Filters – Indexing server
removing labels 155
Global users
renaming 38
retrieving 301
restoring 40
Go To Location 234
retrieving from shelves 163
Graphical Branch Tree 209
rolling back 29
Graphical History 87
searching for text in contents 225
Grouping file type extensions 108
sharing 125
H
shelving 157
Hiding
shortcut menu 8, 101
branches 378
undoing check out 25
labels 149
unsharing 126
unshelving 163
toolbars 102
History
viewer and editor 18
branch 207
viewing 17
branch details 207
viewing in working directory 14
file 84, 87
viewing line-by-line file changes 82
file details 86
voiding check out 303
labels 153
Filters
reports 247
adding 231
applying to source file list 233
configuring 231
repositories 127
HTTPS 310
I
deleting 234
IDE integrations 277
duplicating 233
user options 277
editing 233
Image file differences 50
Finding See Searching
Inactivating branches 379
Fixing
Indexing
external issues 282
indexed vs. non-indexed searches 227
TestTrack issues 271
turning on or off for branches 375
Font
viewing details for branches 376
changing in text viewer/editor 21
Indexing branches 374
changing in viewer and editor 20
Indexing server
Freezing branches 379
checking status 374
G
Getting files 15
starting 374
stopping 374
viewing log 377
481
Index: Integrations – Local directories
viewing server log 374
Key exchange 310
Integrations
changing 309
Adobe CS5 and later 285
client-side plug-ins 277
Keywords
CMIS clients 285
expanding 322
installing plug-ins 279
supported 323
installing third-party 277
issue tracking 314
Mac Finder 284
supported 277
third-party 277
user options 277
Windows Explorer 283
Interface 7
Branch menu 7
Branches tree 8
file details pane 8
Pending Changelists 8
Repositories tree 8
source file list 8
Issue tracking integration
L
Labeled file reports 154
Labels
applying to files 150
configuring 145
creating 147
deleting 149
deleting legacy 427
duplicating 149
editing 148
hiding 149
removing from files 155
renaming 148
searching 151
selecting 151
activating 314
unhiding 149
attaching source files 281
upgrading 425
fixing issues 282
viewing 148
user settings 280
viewing differences 152
viewing issues 282
Issues
adding TestTrack issues 270
attaching source files 267, 281
Legacy labels
deleting 427
upgrading 425
Licenses
editing TestTrack issues 271
adding 4
finding attached files 272
viewing in use 302
fixing external issues 282
fixing TestTrack 271
K
RSA 311
List reports
creating 249
Local directories
creating 25
482
Index: Local SCM admin login – Printing
Local SCM admin login 4
Locking databases 406
unrelated files 46
Moving
M
files 37
Mac Finder plug-in 284
repositories 118
Mail queue
repositories to different mainlines 390
deleting mail 413
O
managing 413
Open Containing Folder 14
resending mail 413
Opening
Mainline branches 165
local files 21
adding existing 394
toolbars 102
non-RDBMS format 396
RDBMS format 395
copying to different databases 393
creating 387
deleting permanently 397
exporting repositories 390
moving to different databases or servers 392
overriding options 388
removing 394
working directories 14
Oracle database connections 404
P
Passwords
changing 10
Pending changelists
viewing 8
Pending Changelists tab 134
Plug-ins
renaming 388
changing report menu items 262
restoring 394
client-side 277
non-RDBMS format 396
Mac Finder 284
RDBMS format 395
status 278
upgrading 421
user options 278
upgrading non-RDBMS 422
Windows Explorer 283
upgrading old 421
Pop-up file details 100
Master proxy servers 430
Post-event triggers 335
Merge applications
PostgreSQL database connections 404
adding 51
Pre-event triggers 335
deleting settings 54
Previewing
editing settings 53
Merging 43
checking in files 46
promoted branches 186
rebased branches 196
Printing
files 45
repository differences 115
server options 312
server log 411
483
Index: Process management – Reports
source file list 263
workflow diagrams 363
workflow transitions 361
branches 193
preview 196
files 198
Process management 415
Refreshing Source Tree window 99
Promoting 177
Regenerating RSA key pairs 312
actions 188
Regular expressions 214
branches 184
Removing
preview 186
files 189
Properties
branches 384
changelist file actions 137
changelists 136
branch 208
files 39
file 88
files from code reviews 66
repository 128
labels from files 155
Proxy servers 429
mainline branches 394
adding 432
repositories 120
cache directory 430
states from workflow templates 361
configuring 431
Renaming
deleting 435
branches 378
editing settings 434
changelists 135
starting 430
files 38
user options 435
labels 148
Purging data 320
mainline branches 388
Pushing changes to repositories 116
repositories 117
Q
TestTrack field labels 417
Quick reports 259
Repairing databases 406, 408
common issues 410
R
Reports
RDBMS connections
adding external to Surround SCM 257
adding 403
branch differences 181
deleting 405
charting data 257
editing 405
code review 75
upgrading 425
configuring 238
Reactivating branches 379
creating 239
Rebasing 177
audit trail 240
actions 197
code review coverage 244
484
Index: Repositories – Reveal in Finder
external 258
viewing shadow folders 129
history 247
Repositories tree 8
list 249
Requirements
menu item plug-ins 260
attaching source files 267
security group 252
finding attached files 272
trend 254
viewing 269
workflow progress 255
Resending mail 413
deleting 259
Resolving custom field and workflow issues 423
duplicating 258
Restoring
editing 258
deleted custom fields 333
file differences 48
files 40
printing 259
mainline branches
running 259
non-RDBMS format 396
running quick 259
RDBMS format 395
saving 259
removed branches 384
types 237
removed mainline branches 394
Repositories
bookmarking 235
cloaking and uncloaking 119
repositories 121
workflow states 358
Restrictions
controlling access 295
adding 213
creating 111
branch and repository 222
deleting permanently 122
condition 218
diffing 112
date 217
resolving missing items 115
event 219
exporting to mainlines 390
external issue tracking attachment 221
history 127
filter by action 223
moving 118
label 220
properties 128
list value 217
pushing changes 116
number 216
removing 120
regular expressions 214
renaming 117
TestTrack items 221
restoring 121
text 214
setting workflows 364
wildcard search 214, 222
shortcut menu 8, 101
Retrieving global users 301
viewing cloaked 120
Reveal in Finder 14
485
Index: Reviewing – Server log
Reviewing
changes between versions 69
file contents 70
Risk score 273
Rolling back
changelist actions 140
resolutions 142
files 29
promoted files 192
rebased files 201
RSA key exchange 311
downloading key pair 312
regenerating keys 312
controlling access to specific branches 295,
297
examples 290
levels 289
overriding branch security 298
server 291
Security commands
admin 449
branch 455
files 453
general 447
security groups 453
users 452
Security groups
S
adding 292
Saving
deleting 295
repository differences 115
source file list 262
Surround SCM Server log 411
SCCI plug-in installation 279
Seapine License Server
options 317
starting 287
Searching
committed changelists 139
file content 225
regular expression examples 229
wildcard examples 229
files 211
files attached to TestTrack items 272
indexed vs. non-indexed 227
labels 151
Surround SCM Servers 5
Security
client/server communication 309
commands 447
486
duplicating 295
editing 294
reports 252
Security Groups window 291
viewing 294
Server connections
adding 5
connecting to different server 5
deleting 6
editing 6
finding servers 5
Server database
changing location 402
converting database type 400
setting default location 400
Server log
indexing server 377
Surround SCM Server
deleting entries 412
log levels 412
Index: Server options – sscm addresses
printing 411
Shelves
saving 411
adding new files 159
setting options 314
creating 161
viewing 411
deleting 162
Server options
diffing files 162
branch caching 383
editing 162
changelists 324
managing 160
comments 325
Shelves window 160
compliance 327
shelving files 157
email notifications 316
unshelving files 163
file names and extensions 325
Shortcut menus 8
general global options 307
adding items to run reports 260
general mainline options 321
changing report names and icons 262
issue tracking integration 314
customizing 101
local SCM admin password 308
Signatures 37
merge 312
Snapshot branches 166
RDBMS connections 403
Sorting columns 99
RSA key exchange 311
Source file list 8
Seapine License Server 317
Source Tree window 7
send mail 315
Branch menu 7
server database 400
Branches tree 8
software update check 318
customizing 98
manual check 320
TestTrack integration 417
displaying panes 99
file details pane 8
Server security 291-292
file status 17
Shadow folders
hiding panes 99
adding 367
Pending Changelists 8
configuring 367
printing source file list 263
deleting 369
refreshing automatically 99
editing 369
Repositories tree 8
updating 369
saving source file list 262
viewing for repository 129
source file list 8
Share link 125
Sharing files 125
user options 99
SQL Server database connections 404
sscm addresses 234
487
Index: Starting – TestTrack integration
Starting
CMIS Admin Utility 439
CMIS Server 439
indexing server 374
proxy server 430
Seapine License Server 287
Surround SCM 3
Surround SCM Server 288
Surround SCM Web Server 437
States
adding 356
adding to workflow templates 360
configuring 355
deleting 357
editing 357
restoring 358
setting 36
Status 17
Surround SCM interface 7
Surround SCM Server
T
Tab width
changing 21
Tables
creating database 399
Templates
adding workflow 359
adding workflow states 360
deleting workflow 362
diagramming workflow 363
duplicating workflow 362
editing email 344
editing workflow 362
editing workflow transitions 361
removing states from workflow 361
setting default workflow 363
workflow 358
Test cases
attaching source files 267
adding connections 5
finding attached files 272
connecting to different 5
viewing 269
deleting connections 6
TestTrack integration
editing connections 6
adding connections 265
finding on network 5
adding issues 270
setting up connections 4
attaching source files 267
starting 288
configuring connections 265
Surround SCM Web
starting server 437
Syncing
deleting connections 266
editing connections 266
editing field labels 417
moved items 115
enabling 417
renamed items 115
finding attached files 272
repositories and working directories 112
fixing issues 271
TestTrack field labels 418
options 418
Syntax highlighting 20
488
System user 335
renaming field labels 417
Index: Text search examples – User options
selecting items 275
editing actions 348
syncing field labels 418
enabling 349
user settings 267
environment variables 461
viewing items 269
examples 336
Text search examples 229
post-event 335
Third-party integrations 277
pre-event 335
user options 277
Thumbnail file details 100
Toolbars
changing the custom toolbar 103
customizing 102
display options 102
displaying 102
hiding 102
Tracking changes 205
Transitions
editing 361
Trend reports
creating 254
Trigger actions
append event comment text 342
running executables 340
U
Uncloaking repositories 119
Undoing check out 25
Unfreezing branches 379
Unhiding
branches 378
labels 149
Unlocking databases 406
Unsharing files 126
Unshelving files 163
Update check options 318
Upgrading
legacy labels 425
mainline branches 421
prevent an event 341
non-RDBMS 422
send email 343
old 421
set a custom field value 346
set event comment text 342
set workflow state 346
Triggers
RDBMS connections 425
User interface mode
changing 103
User options
adding 337
Add/Find In Files extensions 108
adding actions 347
diff/merge 51
configuring 336
file dialog defaults 103
deleting 349
Add Files 107
deleting actions 348
Check In Files 105
disabling 349
Check Out Files 106
duplicating 349
Get Files 104
editing 347
Shelve Files 109
489
Index: Users – Workflows
Undo Check Out Files 106
file properties 88
file manager 14
files 15, 17
general 8
graphical branch structure 209
integration 277
graphical file history 87
plug-ins 278
issues 282
pop-up file details 100
label differences 152
proxy server 435
label history 153
setting default 328
labels 148
source tree 99
repository history 127
thumbnail file details 100
repository shadow folders 129
view/edit file 18, 20
security groups 294
TestTrack items 269
Users
adding 299
users 302
deleting 302
working directory differences 112
editing 302
Voiding check out 303
retrieving global 301
W
viewing 302
Web server
viewing current license usage 302
Users window 298
starting 437
WebDAV
V
accessing directories 465
Viewer for files
Linux access 469
adding for specific file types 18
Mac OS X access 468
changing text display options 20
web browser access 465
deleting settings 20
Windows network place access 466
editing settings 20
Windows Explorer plug-in 283
setting default application 18
Workflows
Viewing
branch differences 177
creating progress reports 255
branch history 207
customizing 354
branch index details 376
editing transitions 361
branch properties 208
planning 355
changelist details 133
printing transitions 361
cloaked repositories 120
resolving issues 423
file history 84
setting default 363
file history details 86
490
automating 355
Index: Working directories – Workspace branches
states
adding 356
changing 36
configuring 355
deleting 357
editing 357
restoring 358
templates
adding 359
adding states 360
configuring 358
default 353
deleting 362
diagramming 363
duplicating 362
editing 362
removing states 361
setting for repositories 364
Working directories
adding 12
deleting 14
diffing 112
editing 13
editor 12
opening 14
setting 11
Workspace branches 166
491