Surround SCM User Guide v2017.2

User Guide
Version 2017.2
Copyrights
© 1996-2017 Perforce Software, Inc. and its subsidiaries. All rights reserved.
Defect Scribe, Helix ALM, Helix ALM Suite, Helix Issue Management, Helix Requirements Management, Helix Test Case Management,
QA Wizard Pro, Resource Thief, SoloBug, SoloSubmit, Surround SCM, and TestTrack are trademarks or registered trademarks of
Perforce Software, Inc. and its subsidiaries in the United States and other countries.
Acrobat Reader is a registered trademark of Adobe, 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, macOS, Macintosh, Objective-C, and Safari are registered trademarks of Apple Computer, Inc.
Chrome is a registered trademark of Google Inc.
Debian is a registered trademark of Software in the Public Interest, Inc.
Firefox is a registered trademark of the Mozilla Foundation.
Linux is a trademark of Linus Torvalds.
Microsoft, Windows, 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.
openSUSE and SUSE are registered trademarks of Novell Inc. in the United States and other countries.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Red Hat, Red Hat Enterprise Linux, and Fedora are registered trademarks of Red Hat, Inc. in the United States and other countries.
Ubuntu is a registered trademark of Canonical Ltd.
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 Perforce Software, Inc. and its subsidiaries.
Your license agreement with Perforce Software, Inc. or any of its subsidiaries, 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 Perforce Software,
Inc. or any of its subsidiaries. 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.
Perforce Software, Inc. and its subsidiaries
400 N 1st Avenue
Suite 200
Minneapolis, Minnesota 55401
USA
+1 510.864.7400
documentation@seapine.com
Contents
What's New
Getting Started
1
3
Starting Surround SCM
4
Managing server connections
4
Adding server connections
5
Editing server connections
6
Deleting server connections
6
Surround SCM interface
7
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
File status
17
Viewing files in Surround SCM
19
Setting file viewer and editor options
19
Setting the application for viewing and editing specific file types
20
Editing and deleting file viewer and editor settings
21
Changing file viewer and editor text display options
22
Opening local files from Surround SCM
Modifying Files
Checking out files
Creating local directories
23
25
25
27
Undoing check out
27
Editing files in Surround SCM
28
Checking in updated files
28
Rolling back files
31
Adding files to Surround SCM
32
i
Setting custom fields
Changing multiple custom fields
Changing workflow states
Entering electronic signatures
37
38
39
Moving files
39
Renaming files
40
Removing files
41
Restoring removed files
42
Deleting files permanently
42
Comparing and Merging Files
45
Viewing file differences
45
Merging files
47
Merging unrelated files
48
Running file differences reports
50
Viewing image file differences
52
Setting diff/merge options
53
Adding diff/merge applications
54
Editing diff/merge applications
57
Deleting diff/merge applications
57
Configuring diff/merge application settings
57
Performing Code Reviews
59
About the code review process
59
Understanding code review status
61
Managing code reviews
61
Creating code reviews
62
Adding files to code reviews
63
Selecting code reviews
67
Removing files from code reviews
67
Starting code reviews
68
Opening code reviews
69
Editing code reviews
69
Reviewing files in code reviews
70
Reviewing changes between file versions
Changing code review view options
Reviewing files
ii
36
70
73
74
Adding review comments to files
76
Editing and deleting review comments
77
Addressing code review comments
77
Viewing unaddressed review comments
78
Searching for code reviews
78
Running code review reports
79
Viewing code reviews files are included in
82
Deleting code reviews
83
Viewing File Information
85
Using the file details pane
85
Viewing line-by-line file changes
86
Working with annotate results
87
Viewing file history
88
Viewing file history details
90
Viewing graphical file history
91
Viewing file properties
92
Setting Up Email Notifications
95
Adding email notifications
95
Editing email notifications
98
Duplicating email notifications
98
Disabling and enabling email notifications
98
Deleting email notifications
98
Customizing Surround SCM
Customizing the Source Tree window
101
102
Setting Source Tree options
103
Setting file information display options
104
Customizing shortcut menus
105
Customizing toolbars
106
Changing the user interface mode
107
Changing defaults for Surround SCM dialogs
107
Setting Get Files dialog defaults
108
Setting Check In Files dialog defaults
109
Setting Check Out Files dialog defaults
110
Setting Undo Check Out Files dialog defaults
110
Setting Add Files dialog defaults
111
iii
Grouping file extensions to find related file types
112
Setting Shelve Files dialog defaults
113
Managing Repositories
115
Creating repositories
115
Viewing differences between repositories and working directories
116
Resolving missing moved and renamed items
Pushing changes to repositories
120
Renaming repositories
121
Moving repositories
122
Cloaking and uncloaking repositories
123
Viewing cloaked repositories
Removing repositories
124
124
Restoring repositories
125
Deleting repositories permanently
126
Sharing Files Between Repositories
129
Breaking shares
Viewing Repository Information
130
131
Viewing repository history
131
Viewing general repository information
132
Viewing repository shadow folders
133
Using Changelists
Creating changelists
Adding file actions to changelists
Managing changelists
Viewing changelist details
135
135
136
136
137
Working with pending changelists
138
Renaming pending changelists
140
Removing pending changelists
140
Editing pending changelist file actions
141
Moving pending changelist actions
141
Removing pending changelist file actions
141
Adding comments to changelist files
142
Committing pending changelists
142
Working with committed changelists
142
Searching for committed changelists
iv
119
144
Attaching changelists and files to Helix ALM items
145
Rolling back changelist actions
147
Rollback changelist action resolutions
Selecting changelists
Using Labels
Configuring labels
149
151
153
153
Creating labels
155
Viewing labels
156
Editing labels
156
Duplicating labels
157
Hiding labels
158
Deleting labels
158
Labeling files
158
Selecting labels
159
Searching for labels
160
Viewing label differences
161
Viewing label history
162
Running labeled files reports
163
Removing labels from files
164
Using Shelves
165
Shelving files
165
Adding files to existing shelves
167
Managing shelves
168
Creating shelves
169
Editing shelves
170
Deleting shelved files and shelves
170
Viewing shelved file differences
170
Unshelving files
171
Branching
About branches
173
173
When to branch
174
Branching example
175
Branch status icons
177
Creating branches
Using branch templates
178
180
v
Including and excluding repositories for new branches
181
Selecting branch templates
182
Merging Files Between Branches
Deciding between promoting, rebasing, and duplicating
185
Viewing branch differences
185
Copying files across branches during check in
188
Running branch differences reports
189
Promoting branches
192
Promote preview
194
Promote actions
196
Promoting files
197
Rolling back promoted files
200
Rebasing branches
201
Rebase preview
204
Rebase actions
205
Rebasing files
206
Rolling back rebased files
209
Duplicating selected changes across branches
210
Duplicate changes actions
213
Tracking duplicated changes
213
Viewing Branch Information
215
Viewing branch history
215
Viewing branch history details
215
Viewing general branch information
216
Viewing the graphical branch tree
217
Finding Files
Searching for files
Adding restrictions
Adding text restrictions
Using regular expressions
vi
185
219
219
221
222
222
Adding number restrictions
225
Adding date restrictions
225
Adding list value restrictions
226
Adding condition restrictions
227
Adding event restrictions
228
Adding label restrictions
229
Adding Helix ALM item number restrictions
230
Adding external issue tracking attachment restrictions
230
Adding branch and repository restrictions
231
Adding action restrictions based on user and date
232
Searching for text in files
234
Differences between indexed and non-indexed searches
236
Text search examples
238
Configuring filters
239
Adding filters
240
Applying filters to the source file list
241
Editing filters
242
Duplicating filters
242
Deleting filters
242
Browsing to files and repositories
243
Bookmarking files, repositories, and branches
244
Managing bookmarks
Creating and Running Reports
245
247
Report types
247
Configuring reports
248
Creating reports
249
Creating audit trail reports
250
Creating code review coverage reports
254
Creating history reports
257
Creating list reports
259
Creating security group reports
262
Creating trend reports
264
Creating workflow progress reports
266
Charting report data
267
Adding external reports to Surround SCM
268
Editing reports
268
Duplicating reports
269
Deleting reports
269
Running reports
269
Running quick reports
270
vii
Adding shortcuts to run reports from the Source Tree window
Changing report menu item names and icons
272
Saving the source file list
272
Printing the source file list
273
Integrating with Helix ALM
275
Configuring Helix ALM connections
275
Adding Helix ALM connections
275
Editing Helix ALM connections
276
Deleting Helix ALM connections
276
Entering Helix ALM login information
277
Attaching source files to Helix ALM items
277
Viewing Helix ALM items
280
Adding Helix ALM issues
280
Editing Helix ALM issues
281
Fixing Helix ALM issues
281
Finding files attached to Helix ALM items
282
Analyzing issue risk in files
283
Selecting Helix ALM items
285
Integrating with Third-Party Applications
287
Setting integration options
287
Setting plug-in options
288
Integrating with IDEs and applications that support SCCI
289
Integrating with issue tracking tools
290
Entering issue tracking login information
290
Attaching source files to external issues
291
Viewing external issues
292
Fixing external issues
292
Using the Windows Explorer and Mac Finder integrations
293
Using the Windows Explorer plug-in
293
Using the Mac Finder plug-in
294
Setting Up Surround SCM
297
Starting the Helix ALM License Server
297
Starting the Surround SCM Server
298
Controlling Security and User Access
Security levels
viii
270
299
299
Security examples
300
Controlling access with security groups
301
Adding security groups
302
Viewing security groups
304
Editing security groups
304
Duplicating security groups
305
Deleting security groups
305
Controlling access to specific repositories
305
Controlling access to specific branches
307
Setting branch security commands
308
Managing users
308
Adding users
309
Retrieving global users
311
Viewing users
312
Editing users
312
Deleting users
313
Viewing licenses in use
313
Voiding check out
314
Configuring the Surround SCM Server
Setting general global server options
315
317
Securing communication between clients and the Surround SCM Server
319
Configuring RSA key exchange
321
Setting server merge options
322
Activating third-party issue tracking plug-ins
324
Setting logging options
324
Setting email server options
325
Setting email notification options
326
Setting Helix ALM License Server options
327
Setting automatic software update check options
328
Checking for new Surround SCM versions
329
Scheduling data purges
330
Setting general mainline options
331
Supported keywords
333
Setting changelist server options
334
Setting minimum comment lengths for actions
335
ix
Setting auto-detect and ignore file options
335
Setting compliance options
337
Configuring default user options
338
Generating support diagnostic reports
340
Configuring Custom Fields
Adding custom fields
342
Editing custom fields
343
Deleting custom fields
343
Restoring deleted custom fields
343
Automating Actions with Triggers
345
Trigger examples
346
Configuring triggers
346
Adding triggers
347
Adding triggers to run executables
350
Adding triggers to prevent events
352
Adding triggers to append comments to events
352
Adding triggers to email users
353
Editing email templates
354
Adding triggers to set workflow states
356
Adding triggers to set custom field values
356
Editing triggers
357
Adding trigger actions
357
Editing trigger actions
358
Deleting trigger actions
358
Duplicating triggers
359
Disabling and enabling triggers
359
Deleting triggers
359
Configuring Workflows
About workflows
x
341
361
361
Workflow example
361
About the default workflow template
363
Customizing workflows
364
Planning your workflow
365
Automating workflows
365
Configuring workflow states
365
Adding workflow states
366
Editing workflow states
367
Deleting workflow states
367
Restoring deleted workflow states
368
Configuring workflow templates
368
Adding workflow templates
369
Adding states to workflow templates
370
Removing states from workflow templates
371
Editing workflow transitions
371
Editing workflow templates
372
Duplicating workflow templates
372
Deleting workflow templates
372
Diagramming workflows
373
Setting the default workflow
373
Setting workflows for specific repositories
374
Configuring Code Review Settings
Configuring Shadow Folders
375
377
Adding shadow folders
378
Editing shadow folders
379
Refreshing shadow folder contents
379
Deleting shadow folders
379
Maintaining Branches
381
Managing branch attributes
381
Indexing branches for optimized searches
384
Managing the indexing server
384
Turning branch indexing on or off
385
Viewing branch index details
386
Viewing the indexing server log
387
Renaming branches
388
Hiding and unhiding branches
388
Freezing and unfreezing branches
388
Inactivating and activating branches
389
Modifying templates for existing branches
389
Changing branch type
391
Changing branch caching
391
xi
Setting branch caching server options
392
Removing branches
393
Restoring removed branches
394
Deleting branches permanently
394
Managing Mainline Branches
397
Creating mainline branches
397
Renaming mainline branches
398
Overriding server options for specific mainline branches
398
Moving repositories to different mainline branches
400
Moving mainline branches to different databases or servers
402
Copying mainline branches to different databases
403
Removing mainline branches
404
Restoring removed mainline branches
404
Restoring RDBMS mainline branches
405
Restoring non-RDBMS mainline branches
406
Deleting mainline branches permanently
407
Maintaining Surround SCM Databases
409
Creating Surround SCM database tables
409
Setting the default server database location
409
Converting the server database to a different type
410
Changing the server database location
412
Adding RDBMS connections
413
Editing RDBMS connections
415
Deleting RDBMS connections
415
Backing up Surround SCM databases
415
Locking databases for backups
416
Resolving database issues
416
Setting database analyze and repair options
416
Analyzing and repairing databases
418
Repairs for common database issues
420
Working with the Surround SCM Server Log
Server log levels
Managing Mail
xii
423
424
425
Resending mail
425
Deleting mail
425
Managing Auditable Processes
Configuring Helix ALM Integration
427
429
Enabling Helix ALM integration
429
Syncing field labels with Helix ALM
430
Setting Helix ALM integration options for repositories
430
Upgrading Surround SCM
Upgrading mainline branches
433
433
Upgrading old mainline branches
433
Upgrading non-RDBMS mainline branches
434
Resolving custom field and workflow issues
435
Upgrading RDBMS connections
437
Upgrading legacy labels
437
Deleting legacy labels
439
Using Proxy Servers
441
How proxy servers work
442
Starting the Surround SCM Proxy Server
443
Configuring proxy servers
443
Adding proxy servers
444
Editing proxy server settings
447
Deleting proxy servers
447
Setting proxy server options
447
Managing the Surround SCM Web Server
Starting the Surround SCM Web Server
Using the Surround SCM API
449
449
451
Avoiding conflicts with the Surround SCM Client and CLI
451
Using the C API
451
Using the Java API
452
Using the .NET API
453
Surround SCM Best Practices
Appendix A: Security Commands
455
457
General security commands
457
Admin security commands
459
Users security commands
462
Security Groups security commands
463
Files security commands
463
xiii
Branch security commands
Appendix B: Environment Variables
Glossary
Index
xiv
465
471
475
479
What's New
Surround SCM 2017.2 includes the following key features. For a complete list of features, enhancements, and
bug fixes, check out the release notes.
Search in windows and dialog boxes
You can now search in the following windows and dialog boxes to quickly find information: Cloaked
Repositories, Code Reviews, Email Notifications, Labels, Reports, Security Groups, Shadow Folders,
Shelves, Triggers, Users, and Working Directories.
View history and go directly to files from code reviews
When reviewing files in code reviews, you can now view historical file version information and perform actions
on historical versions. See Reviewing files, page 74 and Reviewing changes between file versions, page 70.
You can also right-click a file in a review and choose Go to File to go directly to it in the Source View window.
View users and server security permissions in security group reports
When you create security group reports, you can now include users in the group and server security
permissions to see more details about each group. See Creating security group reports, page 262.
Other enhancements
n
Merge Microsoft Word and other binary files when duplicating changes across branches.
n
Select additional events in the following filter, advanced find, and report event restrictions: Change custom
field, Change state, Promote from, Promote from with merge, Rollback file.
n
Log in using single sign-on from the API with the new sscm_connect_ext call.
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 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 297.
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 server to access. Ask an administrator for the server name and address. See Starting Surround
SCM, page 4 and Managing server connections, page 4.
2. Familiarize yourself with the 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 178.
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 25.
n
Check in files to share changes with other users. See Checking in updated files, page 28. 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 45.
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 178.
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
115.
n
Add files to Surround SCM. See Adding files to Surround SCM, page 32.
5. As you become more familiar with Surround SCM, you may want to configure user options.
You can customize the 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 101 and Setting
general user options, page 8.
3
Starting Surround SCM
Starting Surround SCM
Make sure the Helix ALM License Server and Surround SCM Server are running before you start Surround
SCM.
If this is your first time using Surround SCM and you have not set up any users, you can log in as the default
administrative user. The username is Administrator and there is no password.
Note: If you try to log in and the 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 license server settings.
1. Windows—Choose Programs > Perforce > 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 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 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
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 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 server. Contact your 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.
You are prompted to confirm the deletion.
6
Surround SCM interface
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 102.
#
Area
Use to:
Menu bar
Access all Surround SCM actions.
Toolbars
Access the most commonly used 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 106.
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 177.
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 102.
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 105.
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 85.
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 138.
Setting general user options
Surround SCM user options can be customized to help you work more efficiently. For example, you can
automatically log in.
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 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 login dialog box, except for the file compression option.
n
Always login with this username automatically logs in to the current server using the specified
username and password.
n
Use single sign-on automatically logs in to the current server using your network credentials. Ask
your administrator for more information.
n
Use external authentication prompts for your credentials when logging in. Ask your administrator for
more information.
n
Compress file transfers compresses data during file transfers, which is helpful if you have a slow
connection to the 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 cached computer name and enter a new name.
9
Changing your password
Select this option if you always want 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 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
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.
Repositories and working directories serve different purposes.
n
A repository is part of the Surround SCM database managed by the Surround SCM Server. A repository
often reflects the directory structure of a project. Repositories organize and group files and
subrepositories.
n
A working directory is the local folder on your hard drive that a repository is mapped to. The working
directory generally mirrors the repository structure. The working directory is generally mapped to a local
drive directory, but can be mapped to a different location, such as a network drive.
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.
11
Configuring working directories
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. For example, if the repository
structure is MyProject/src/lib/common and you set the working directory for the MyProject repository to
C:\MyProject, the resulting working directory is C:\MyProject\src\lib\common.
5. Select Inherit working directory from parent to use the parent repository’s working directory.
The working directory is set as <parent’s path> \ <repository name>.
6. Select Get files to working directory to retrieve a copy of the files to the working directory.
Files in subrepositories are also copied to local directories if the Allow child repositories to inherit this
working directory option is selected. If the local directories do not exist, you are prompted to create
them. See Creating local directories, page 27.
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 when you finish.
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.
12
Editing working directories
2. Click Add.
The Surround SCM Repository Browser opens.
3. Select a branch and repository and click OK.
The Add Working Directory dialog box opens.
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 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 105.
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 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 159.
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.
n
Optionally select Get with historical filename when you get files based on timestamp or label.
Selecting this option gets files with the filename they had when the selected label was applied or at
the selected timestamp. If the working directory you are retrieving files to has a copy of the same file
with the current name, the file with the historical name replaces it.
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. Surround SCM checks the local
copy to determine if the file is current. Select this option to retrieve a new copy of the file 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.
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 27.
File status
Columns in the Source Tree window display the status of local files in your working directory and files on the
Surround SCM Server.
Local files
Every working directory contains a .MySCMServerInfo file, which stores information about local files in the
directory, such as the filename, file location on the server, timestamp, and latest merge performed. The file is
updated when you get or check out files.
Surround SCM compares the .MySCMServerInfo file to the working directory files to determine the file status.
The Status column in the Source Tree window displays this status, which can help you determine if local files
are out of sync with the server.
Status
Indicates:
current
The local file is the same as the current server file.
missing
The file was not found on your computer.
modified
The local file was modified and does not match the 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 (e.g., a shared network drive).
unknown
Surround SCM cannot determine the file status. This happens if the .MySCMServerInfo file is
removed or modified.
17
File status
Note: Do not modify or delete any .MySCMServerInfo files because Surround SCM will not be able to
determine file status. This could cause problems if you are updating files in a working directory. For
example, if you check out or get a file more current in your working directory than on the server, your
changes will be lost.
Server files
The Icon column displays icons that indicate the status of files on server. This information can help you
determine if files are checked out, shared, or in pending changelists.
Icon
Indicates the file is:
Not checked out, shared, or in a pending changelist
Shared, but not checked out
Checked out to you
Checked out exclusively to you
Checked out to you and shared
Checked out exclusively to you and shared
Checked out to another user
Checked out exclusively to another user
Checked out to another user and shared
Checked out exclusively to another user and shared
Checked out to multiple users
Checked out to multiple users and shared
Checked out to you and another user and shared
In a pending changelist, but not checked out
Shared and in a pending changelist, but not checked out
Checked out to you and in a pending changelist
Checked out exclusively to you and in a pending changelist
18
Viewing files in Surround SCM
Icon
Indicates the file is:
Checked out to you, shared, and in a pending changelist
Checked out exclusively to you, shared, and in a pending changelist
Checked out to another user and in a pending changelist
Checked out exclusively to another user and in a pending changelist
Checked out to another user, shared, and in a pending changelist
Checked out exclusively to another user, shared, and in a pending changelist
Checked out to multiple users and in a pending changelist
Checked out to multiple users, shared, and in a pending changelist
Checked out to you and another user, and in a pending changelist
Checked out to you and another user, shared, and in a pending changelist
Viewing files in Surround SCM
When you view a file, the associated viewer or application opens. See Setting file viewer and editor options,
page 19.
1. Select the file.
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 server and cannot be changed.
1. Choose Tools > User Options then select the View/Edit File category.
19
Setting the application for viewing and editing specific file types
2. Click Add to add settings for specific file types. See Setting the application for viewing and editing
specific file types, page 20.
3. Select a setting and click Edit to change it. See Editing and deleting file viewer and editor settings, page
21.
4. Select a setting and click Delete to delete it. See Editing and deleting file viewer and editor settings, page
21.
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 22.
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.
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 file viewer
Application associated with the file type in the
operating system
20
Editing and deleting file viewer and editor settings
File
type
Default viewer setting
Default editor setting
Text
files
Built-in file viewer
Built-in 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 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 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.
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 server and cannot be changed.
21
Changing file viewer and editor text display options
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 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 the 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 19.
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.
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 Perforce does not support these files.
22
Opening local files from Surround SCM
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.
23
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.
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.
25
Checking out files
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 136.
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.
The files are checked out.
26
Creating local directories
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
27.
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 123.
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.
27
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 19.
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.
If multiple users can check out files, you may want to check in and 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.
28
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 136.
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 62. Click Select to view code review details and determine which review to add the files
to. See Selecting code reviews, page 67.
29
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.
30
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 155. Click Select to view label details or search for a label.
See Selecting labels, page 159. 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. You may want to select this option if you are working with related files and want the
version numbers to always match. This can help you and other team members visually confirm that
the files are in sync and changes were not missed. For example, you work with two related files:
WysiWrite.cpp and WysiWrite.h. Both are currently version 29. You make changes to
WysiWrite.cpp. WysiWrite.h does not have changes. If you select this option when you check the
files in, both files are updated to version 30. If this option is not selected, WysiWrite.h remains at
version 29. 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 45.
7. Click Attach to attach files to an item in Helix ALM or an external issue tracking tool. See Attaching
source files to Helix ALM items, page 277 or Attaching source files to external issues, page 291.
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 47.
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 39. 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 38.
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 147.
31
Adding files to Surround SCM
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.
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.
32
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 335.
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 112.
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.
33
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 36.
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 136.
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 62. Click Select to view code review details
and determine which review to add the files to.
34
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 38.
n
Select Label and select a label if your organization uses labels. Select <New label> to create a label.
See Creating labels, page 155. Click Select to view label details or search for a label. See Selecting
labels, page 159. 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, Text (CR/LF), Text (LF),
Binary, Mac Binary, UTF-8 Text, UTF-8 Text (CR/LF), UTF-8 Text (LF), or UTF-16 if you need to
explicitly set the file type.
35
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 Helix ALM or an external issue tracking tool. See Attaching
source files to Helix ALM items, page 277 or Attaching source files to external issues, page 291.
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 39.
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 341 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 32.
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 92.
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 178.
n
Promoting and rebasing does not change the custom field values set on files that already exist in the
destination branch.
n
You can only set one custom field value for shared files.
36
Changing multiple custom fields
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 85 and Customizing the Source Tree window,
page 102. 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.
37
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 92.
n
Add Files dialog box—See Adding files to Surround SCM, page 32.
n
Check In Files dialog box—See Checking in updated files, page 28.
n
History dialog box—See Viewing file history, page 88.
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 88.
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 39.
38
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.
39
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 136.
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.
40
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 136.
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.
41
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 136.
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.
42
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.
43
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
53.
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
47.
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 86.
1. Select the file and choose Activities > Differences.
The Differences dialog box opens. Read-only information is displayed in the File to Compare area.
45
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:
46
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 48.
Merging files
5. Click Differences.
The differences application opens.
Note: You can change the application for diffing files. See Adding diff/merge applications, page 54.
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 used for merging files. See Setting diff/merge options, page 53.
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.
3. Click Advanced to select a different file.
47
Merging unrelated files
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 48.
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.
48
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.
49
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 88.
Tip: If you need to create patches for distributing source code updates, run a differences report and save
the output as a text file. This text file contains the patch code. You can send the file to a customer to apply
to their copy of the source file using GNU Project's Patch utility. See Tips for Making and Using Patches
for information.
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 257.
2. Select the files to include in the report.
3. Click
.
The Generate File Differences Report dialog box opens.
50
Running file differences reports
4. Select a Version to Include option.
n
Selected version to selected version displays differences between the file versions selected in the
History dialog box. For example, if you select versions 2 and 3, the report displays the differences
between the two versions. If you select versions 2, 3, and 5, the report displays differences between
versions 2 and 3, and versions 3 and 5.
n
Selected version to previous version displays differences between the selected file version and
the previous version. For example, if you select version 3, the report displays differences between
versions 2 and 3. If you select versions 2, 3, and 5, the report displays differences between versions 1
and 2, versions 2 and 3, and versions 4 and 5.
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.
51
Viewing image file differences
When you view differences, you may also want to see the parts of the files near the lines that differ to help
you understand what changed. This is the context.
If you are distributing new versions of files in the form of diff output, use one of the output formats that
show context so users can easily apply the differences.
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.
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.
52
Setting diff/merge options
4. Click a view button to change how differences are displayed. You can also zoom in or out or enter a
percentage to increase or decrease the magnification.
Button
Use to:
View images side by side
View images top over bottom
View combined differences, which is the result of subtracting the pixel values of one
image from the other
View the high contrast result of subtracting the pixel values of one image from the
other. This view can help you identify subtle color differences.
Display the images at actual size
Zoom in
Zoom out
5. Click Close when you finish.
Setting diff/merge options
You can select the 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.
53
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 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
54.
3. Select a diff/merge setting and click Edit to change the configuration. See Editing diff/merge applications,
page 57.
4. Select a diff/merge setting for a specific file type and click Delete to delete the configuration. See
Deleting diff/merge applications, page 57.
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.
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 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.
54
Adding diff/merge applications
Option
Uses:
Binary
comparison
The internal binary file comparison utility to perform a byte-to-byte comparison between
two binary files.
Integrated
Guiffy
Guiffy to compare two text files. See the Guiffy help for more information.
Integrated
image
compare
The internal utility to compare image files.
Microsoft
Word
Word’s compare/merge utility. (Windows only)
Selected
application
An application you select. Click Browse to select the application.
%1 and %2 variables are automatically added as parameters to the application path to
identify the files to diff. When diffing two files, %1 is the server file and %2 is the file to
compare it to.
If the selected application supports displaying alternate file names, you can also use
%4 and %5 variables with the appropriate options. These variables are replaced with a
description that includes the repository path, filename, branch, and version number for
Surround SCM files, or the full file path for local files. %4 is a description of the server
file (%1) and %5 is a description of the file to compare it to (%2). For example,
"C:\Program Files\BeyondCompare\bcomp.exe" "%1" "%2" /Title1="%4" /Title2="%5".
You may need to change the parameters or add different ones for the diff application to
work correctly. See the diff application help for information about the command line
requirements for integrating with source control 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.
55
Adding diff/merge applications
Option
Uses:
Integrated
Guiffy
Guiffy to merge two text files. See the Guiffy help for more information.
Microsoft
Word
Word’s compare/merge utility. (Windows only)
Selected
application
An application you select. Click Browse to select the application.
%1 and %2 variables are automatically added as parameters to the application path to
identify the files to merge. When merging files, %1 is the server file to merge from and
%2 is the file to merge to.
If the selected application supports displaying alternate file names, you can also use %4
and %5 variables with the appropriate options. These variables are replaced with a
description that includes the repository path, filename, branch, and version number for
Surround SCM files, or the full file path for local files. %4 is a description of the file to
merge from (%1) and %5 is a description of the file to merge to (%2).
You may need to change the parameters or add different ones for the merge application
to work correctly. See the merge application help 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 variables are automatically added as parameters
to the application path to identify the files to merge. %3 is the common ancestor file. If the application
supports displaying alternate file names, you can also use the %6 variable with the appropriate option to
display a description of the ancestor file (%3). For example, "C:\Program
Files\Perforce\P4Merge\P4Merge.exe" -nl "%4" -nb "%6" "%3" "%1" "%2".
6. Click OK to save the changes.
56
Editing diff/merge applications
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 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.
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 applications you use to view differences and merge files. You can set options
for:
n
Using Guiffy, the integrated diff/merge application
n
Comparing Microsoft Word documents
n
Viewing differences between file versions in code reviews
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 server and cannot be changed.
1. Choose Tools > User Options then select Application Settings from the Diff/Merge category.
57
Configuring diff/merge application settings
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 maximum amount of memory for 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 Surround SCM default Guiffy toolbars to display only the Guiffy toolbars used in
Surround SCM.
3. Select a Microsoft Word Configuration option to indicate how to display differences between Word
document versions.
n
Compare and Merge displays differences as tracked changes.
n
Side by Side compares documents side-by-side.
4. Select any Code Review Configuration options to indicate how to display differences between file
versions in code reviews by default. You can change the options while working with code reviews. See
Changing code review view options, page 73.
n
Select the changes to Ignore when displaying differences in each line in a file. Case differences
excludes differences in character case. White space excludes all white space differences (spaces
and tabs). White space changes excludes additions or deletions to existing white space.
n
Select a Differences output option to indicate how to generate diff results. You may want to change
this option to diff results more quickly or view a more compact set of changes. Normal compares
versions using the normal diff and is the default option. Minimal may show a smaller set of
differences, but may run more slowly. Fast may run more quickly than the other options and be the
best way to compare large files with small groups of scattered changes.
5. Click OK to save the changes.
58
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 59.
Depending on your role and security permissions, you can use perform the following tasks related to code
reviews.
n
Use the Code Reviews window to view the reviews you have a role in. You can also create new 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 61.
The following flowchart illustrates the built-in code review workflow, which uses triggers to automatically
email users when reviews are started and completed.
59
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 345.
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 62.
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 63.
Tip: If you use Helix ALM 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 283.
3. Start the review
When all files needing review are added to the code review, start it to indicate it is ready for review and
automatically email the reviewers. See Starting code reviews, page 68. 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 70. 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 74 and Reviewing changes between file versions, page 70.
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 77.
6. Repeat the review until all files are approved
60
Understanding code review status
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 79. 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 254.
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.
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.
61
Creating code reviews
Note: Administrators can configure code review settings for individual repositories to require or prevent
users from adding files to reviews when adding or checking in files. See Configuring Code Review
Settings, page 375.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select the Mainline branch that contains the reviews 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 78.
4. Click Create Review to add a new review. See Creating code reviews, page 62.
5. Click Add Files to select files by changelist, label, or Helix ALM item to add to the review. See Selecting
related files to add to code reviews, page 66.
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 63.
6. Select a review and click Open Code Review to open it. See Opening code reviews, page 69.
7. Select a review and click Start Code Review to notify reviewers that files are ready for review. See
Starting code reviews, page 68.
8. To report on reviews, select a Report on Code Reviews option and click Report On. See Running code
review reports, page 79.
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 67 and Deleting code reviews, page 83.
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.
62
Adding files to code reviews
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 63.
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.
63
Adding files to code reviews
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 70.
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
To create a new review, select <New code review> and enter the review details. See Creating code
reviews, page 62.
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 67. 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 68.
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 32.
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.
64
Adding files to code reviews
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 62.
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 67.
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 28.
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 62.
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 67.
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 136.
1. Select a changelist or file in a committed changelist in the Changelists dialog box.
2. Click Add to Code Review.
n
If you selected a pending changelist, the Select Code Review dialog box opens. Select the review to
add the files to after the changelist is committed. See Selecting code reviews, page 67.
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 62. 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 67.
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 185.
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 62.
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 67.
65
Adding files to code reviews
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 88.
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 67 and Creating code reviews, page 62.
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 76. You can add the file
version to an existing review or create a new review. See Selecting code reviews, page 67 and
Creating code reviews, page 62.
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 283.
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
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 67 and Creating code reviews, page 62.
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 76. You can add the file to an existing review or
create a new review. See Selecting code reviews, page 67 and Creating code reviews, page 62.
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 Helix ALM issue, test case, or
requirement. When the files are opened in a review, the differences between file versions are displayed.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select the review to add files to and click Add Files.
The Add Files to Code Review dialog box opens.
66
Selecting code reviews
3. Select a source type in Select files and versions by list and then select a source to display files from.
n
Changelist displays files included in the selected committed changelist. Select a changelist from the
list or click Select to search for a changelist or view changelist details. See Selecting changelists,
page 151.
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 159.
n
Issue, Test Case, and Requirement display files attached to the selected Helix ALM item. Select an
item from the list or click Select to search for an item or view item details. See Selecting Helix ALM
items, page 285.
4. Select the files to add to the review and click Add to Code Review.
The files are added to the review.
Selecting code reviews
You can view code review details to make sure you add files to the correct review.
1. Click Select next to the code review field in the Add to Code Review or file action dialog box, such as the
Add Files dialog box.
The Select Code Review dialog box opens. Reviews you have permission to add files to are displayed.
2. Click Create Review to create a new review. See Creating code reviews, page 62.
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.
67
Starting code reviews
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.
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
68
To edit the review information, open it, make any changes on the Properties tab, and click Apply. See
Editing code reviews, page 69.
Opening code reviews
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.
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 70.
6. Click the Properties tab to view general review information.
7. Click the History tab next to the Properties 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.
69
Reviewing files in code reviews
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 68 and Creating code reviews, page 62.
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 70.
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 74.
Note: You can also add comments to source files without using the code review process. You are
prompted to add the file to a review when you add the first comment. If the comments are related to an
existing review, add the files to it. If a review does not exist, create one and select the author who needs
the feedback. The comments are available when the author views their unapproved code reviews, but you
may want to separately notify the author that you added comments to make sure they address them.
Reviewing changes between file versions
You can review changes made between code review file versions. The latest file version in the code review is
compared to the version before the oldest version in the review. For example, if versions 3, 6, and 8 are in the
review, differences between versions 2 and 8 are displayed. As you review the changes, you can select
different versions to display to view only the changes made between specific versions or since you last
reviewed the file.
You can also review entire files without highlighted changes. See Reviewing files, page 74.
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 22.
70
Reviewing changes between file versions
2. Click Previous Change and Next Change to go to the previous or next change.
The Previous Change button is disabled if the first change in the file is selected and the Next Change
button is disabled if the last change is selected.
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.
Tip: To include differences for file versions that are not included in the review, click
and choose
Show differences for versions not included in the review. Changes in the excluded versions are
highlighted.
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.
71
Reviewing changes between file versions
Button
Displays:
Differences side by side
Differences top over bottom
Differences combined in a single file
One file version without highlighted differences
5. Click
to apply syntax highlighting or change the differences output, text font, or tab width in files. See
Changing code review view options, page 73.
6. 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 52.
7. To find text in the file, enter the text in the search field and click Find.
8. On the Comments tab, add comments, navigate between them, or mark them as addressed.
n
To add a comment, select content you have feedback about and click Add Comment. See Adding
review comments to files, page 76.
n
To navigate between comments, click Previous Comment and Next Comment.
n
To mark a comment as addressed, select it and click Mark Addressed. Click Address All to
address all comments. See Addressing code review comments, page 77.
n
To view comments the author already addressed from other reviews, select Show addressed
comments.
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. Click the History tab to view history information for the file.
You can also perform actions on historic file versions. See Viewing file history, page 88. The code review
is updated based on actions you perform. For example, if you select a version on the History tab and add
it to the code review, the review updates to include that version.
10. Select the check box in the Completed column 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 61.
72
Changing code review view options
Changing code review view options
When reviewing files in code reviews, you can change how to display differences between file versions, apply
syntax highlighting, select a different font, and change the tab width.
To change how files are displayed, click
when viewing a file in a code review and select an option.
Tip: You can change the default settings for diffing file versions in code reviews in user options. See
Configuring diff/merge application settings, page 57. You can also change the default settings for syntax
highlighting, font, and tab width. Keep in mind that changes to these user options also apply to viewing
and editing files in other areas of Surround SCM. See Changing file viewer and editor text display options,
page 22.
Ignore options
When comparing file versions, you can hide differences in letter case and white space to reduce the number of
changes displayed.
To ignore differences, click
and choose any of the following options.
Option
Select to:
Ignore case differences
Ignore differences in character case.
Ignore white space
Exclude all white space differences (spaces and tabs) in a line.
Ignore white space changes
Exclude only additions or deletions to existing white space in a line.
Differences output options
When comparing file versions, you can change how to generate the diff results.
To change the differences output, click
and choose one of the following options.
73
Reviewing files
Option
Select to:
Normal
differences
Show differences between versions using the normal diff.
Minimal
differences
Try to show a smaller set of differences than the normal diff. May be slow.
Fast
differences
Try to show differences more quickly than the normal diff. May be the best option when
comparing large files with small groups of scattered changes.
Syntax highlighting
You can apply syntax highlighting to display specific text in different styles and colors. 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.
To apply syntax highlighting, click
and choose Syntax highlighting.
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 Perforce does not support
these files.
Font
You can change the font, style, and size used to display text in files.
1. Click
and choose Font.
The Select Font dialog box opens.
2. Select any options.
3. Click OK to save the changes.
Tab width
You can change the number of spaces used in tabs in files.
1. Click
and choose Tab width.
The Set Tab Width dialog box opens.
2. 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.
3. Click OK to save the changes.
Reviewing files
You can review entire files in a code review. For example, you may want to review all file contents before a
new set of changes are made to existing files.
74
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 63.
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 22.
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. Click
to apply syntax highlighting or change the differences output, text font, or tab width in files. See
Changing code review view options, page 73.
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 52.
6. 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 70.
75
Adding review comments to files
7. On the Comments tab, add comments, navigate between them, or mark them as addressed.
n
To add a comment, select content you have feedback about and click Add Comment. See Adding
review comments to files, page 76.
n
To navigate between comments, click Previous Comment and Next Comment.
n
To mark a comment as addressed, select it and click Mark Addressed. Click Address All to
address all comments. See Addressing code review comments, page 77.
n
To view comments the author already addressed from other reviews, select Show addressed
comments.
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. Click the History tab to view history information for the file.
You can also perform actions on historic file versions. See Viewing file history, page 88. The code review
is updated based on actions you perform. For example, if you select a version on the History tab and add
it to the code review, the review updates to include that version.
9. Select the check box in the Completed column 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 61.
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 on the
Comments tab.
The Add Comment dialog box opens.
2. Enter the comment.
76
Editing and deleting review comments
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.
Note: If you need to make changes to a comment, you can edit, move, or delete it. See Editing and
deleting review comments, page 77.
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 69.
2. Double-click the reviewed file.
The file opens in a new tab in the Code Review window. Review comments are displayed on the
Comments tab.
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 63.
6. Repeat steps 1 and 2.
77
Viewing unaddressed review comments
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.
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.
78
Running code review reports
The Code Reviews window opens.
Tip: To quickly find a review in the list, enter a value in the Search field. Matching reviews are
displayed as you type.
2. Select <Advanced find> in the Filter list.
The Advanced Find dialog box opens.
3. Select the criteria that reviews must meet to pass the filter.
The Restriction dialog box opens. The options change based on the selected restriction.
4. Select the restriction value.
5. Click OK.
6. Repeat steps 3-5 to add additional restrictions.
7. Click Find.
Reviews that meet the criteria are displayed and the Find results filter is applied.
Running code review reports
When working with code reviews, you can run reports to view historical information about a code review and
files in it. Use these reports to see unaddressed comments, review your code review process, or save
process information for audits.
You can run the following types of code review reports:
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 254.
1. Choose View > Code Reviews.
The Code Reviews window opens.
2. Select the Mainline branch that includes the files and code reviews.
79
Running code review reports
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 78.
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 server.
7. Select a report type. See Examples, page 81.
80
Running code review reports
n
Summary style report includes general information about the review, including the name, status, due
date, authors, reviewers, and notes.
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.
81
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 88 and Analyzing issue risk in files, page 283.
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 69.
3. Click Close when you finish.
82
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.
83
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.
4. Click the History tab to view history information.
85
Viewing line-by-line file changes
You can also access commands to work with a historic file version. See Viewing file history, page 88.
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 45.
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.
86
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 159.
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 87.
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
87
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.
88
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 90
View differences for the selected versions
Viewing file differences, page 45
Generate a report of differences between
versions
Running file differences reports, page 50
Retrieve a copy of the selected version
Getting files, page 15
Check out the selected version
Checking out files, page 25
View the selected version
Viewing files in Surround SCM, page 19
Edit the file
Editing files in Surround SCM, page 28
Revert to a previous file version
Rolling back files, page 31
View branches that contain changes made
in the selected version
Tracking duplicated changes, page 213
Review changes made in the selected
version
Reviewing changes between file versions,
page 70
Add the selected version to a code review
Adding files to code reviews, page 63
89
Viewing file history details
Button
Action
More information
View code reviews for the selected
version
Viewing code reviews files are included in,
page 82
Attach the selected version to an item in
Helix ALM item or an external issue
tracking tool
Attaching source files to Helix ALM items,
page 277 and Attaching source files to external
issues, page 291
View the Helix ALM item the selected
version is attached to
Viewing Helix ALM items, page 280
View the committed changelist. Only
enabled if the action was performed as
part of a changelist.
Working with committed changelists, page 142
Set the workflow state for the file
Changing workflow states, page 38
Label the selected version
Labeling files, page 158
View labels applied to the selected version
Viewing labels, page 156
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.
90
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.
91
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 45.
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.
92
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 25.
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 129.
93
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 36.
3. Click OK when you finish.
94
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 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 95.
4. Select a notification and click Edit to change it. See Editing email notifications, page 98.
5. Select a notification and click Duplicate to duplicate it. See Duplicating email notifications, page 98.
6. Select a notification and click Disable to disable it. See Disabling and enabling email notifications, page
98.
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 98.
8. Click Close when you finish.
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.
95
Adding email notifications
The My Email Notifications dialog box opens.
2. Click Add.
The Add My Email Notification dialog box opens.
3. Enter a Notification Name.
4. On the Trigger When tab, select the events that cause the email to be sent.
5. Click the Preconditions tab to set the condition that files must meet to send the email.
96
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 221.
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 354.
14. Click OK to add the notification.
97
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 354.
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
98.
1. Choose Tools > My Email Notifications.
The My Email Notifications dialog box opens.
2. Select a notification and click Delete.
98
Deleting email notifications
You are prompted to confirm the deletion.
3. Click Yes.
The notification is deleted.
99
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 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 107 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 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.
101
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.
102
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 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.
103
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 19 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 129.
n
Move automatically moves files to a location. See Moving files, page 39.
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 server and cannot be changed.
1. Choose Tools > User Options then select Display File from the Source Tree category.
104
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 270.
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 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 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.
105
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.
106
Changing the user interface mode
Note: On Mac, 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).
The Customize Toolbar dialog box opens. All available buttons and the default custom toolbar are
displayed.
Note: On Mac, 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.
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.
107
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 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 135.
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 45 and Merging files, page 47.
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 server and cannot be changed.
1. Choose Tools > User Options then select Get Files from the File Dialog Defaults category.
108
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 28.
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 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.
109
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 Helix ALM (IDE integrations only) prompts you to attach files to Helix ALM
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
25.
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 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 27.
110
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 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 32.
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 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.
111
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 server and cannot be changed.
1. Choose Tools > User Options then select the Add/Find In Files Extensions category.
112
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 server and cannot be changed.
1. Choose Tools > User Options then select Shelve Files from the File Dialog Defaults category.
113
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.
114
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.
115
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 136.
6. Click OK.
After creating a repository, you need to add source files to it. See Adding files to Surround SCM, page 32.
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 389.
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 120.
1. Select the repository and choose Repository > Working Directory Differences.
The Working Directory Differences dialog box opens.
116
Viewing differences between repositories and working directories
2. Click
to switch between tree view and list view.
3. Select Recursive to show all files in the repository and any subrepositories.
4. Select any Files to show options to control which files and repositories are included in the list.
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.
117
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.
118
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 45
Merge
Merge the file in the working directory with the file in Surround
SCM.
Merging files, page
47
View
View the file. You can view the local or Surround SCM file.
History
View the file or repository history.
Viewing file history,
page 88 and Viewing
repository history,
page 131
Properties
View the file or repository information.
Viewing file
properties, page 92
and Viewing general
repository
information, page 132
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
32
Check In
Check in the file.
Checking in updated
files, page 28
Shelve
Shelve the file or repository.
Shelving files, page
165
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
41 and Removing
repositories, page
124
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 119
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.
119
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.
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 116.
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.
120
Button
Use to:
More information
Differences
Compare, accept, or reject
differences between file versions.
Viewing file differences, page 45
Renaming repositories
Button
Use to:
More information
View
View the local or server copy of
changed files.
Viewing files in Surround SCM, page 19 and
Opening local files from Surround SCM, page 23
History
View the file history.
Viewing file history, page 88
Properties
View the file properties.
Viewing file properties, page 92
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 136.
8. Click Attach to attach the files with changes you want to push to an item in Helix ALM or an external
issue tracking tool. See Attaching source files to Helix ALM items, page 277 or Attaching source files to
external issues, page 291.
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 142.
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.
121
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 136.
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 400.
1. Select a repository and choose Repository > Move Repository.
The Move Repository dialog box opens.
122
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.
123
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 when you finish.
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.
124
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 136.
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.
125
Deleting repositories permanently
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.
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
124.
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.
126
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.
127
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: See Shares Explained for 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.
129
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.
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.
130
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.
131
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 142.
9. If file history is included, select a file and click File History to view the history. See Viewing file history,
page 88.
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.
132
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 377.
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.
133
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 135. 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 Helix ALM item, or add it to a
code review. See Managing changelists, page 136.
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 142.
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 147.
Note: The administrator or another high-level user sets access to changelists. See Setting changelist
server options, page 334.
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 Helix ALM or an external issue tracking tool. See
Attaching source files to Helix ALM items, page 277 or Attaching source files to external issues, page
291.
5. Click OK.
135
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 142.
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
107.
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.
136
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 Helix ALM item, or add it to a code review so the changes are reviewed after they are
committed. See Working with pending changelists, page 138.
n
To work with a committed changelist, select the My Committed, Committed by User, or All
Committed filter. You can attach the changelist or files to a Helix ALM item, add files 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 142.
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 Helix ALM 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.
4. Click Close when you finish.
137
Working with pending changelists
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.
To view and work with committed changelists, see Working with committed changelists, page 142.
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 changelists are displayed. A Helix ALM icon is displayed next to changelists and files attached to
Helix ALM items.
3. Select a changelist or file and click a button to perform an action.
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.
138
Working with pending changelists
Button
Use to:
More
information
View
Details
View details about the changelist or file actions.
Viewing
changelist details,
page 137
Commit
Changelist
Commit the changelist, which perform actions on all files in the
changelist at the same time.
Committing
pending
changelists, page
142
Rename
Changelist
Rename the changelist.
Renaming
pending
changelists, page
140
Remove
Changelist
Remove the changelist and all related file actions.
Removing
pending
changelists, page
140
Set
Comment
Add comments to the file or all files in the changelist.
Adding comments
to changelist files,
page 142
Edit Action
Details
Change the file action options.
Editing pending
changelist file
actions, page 141
Move
Action
Move the file action to another changelist.
Moving pending
changelist
actions, page 141
Remove
Action
Remove the file action from the changelist.
Removing
pending
changelist file
actions, page 141
Differences
Compare the file to another version.
Viewing file
differences, page
45
Edit File
Edit the file.
Editing files in
Surround SCM,
page 28
Merge
Merge the file with another version.
Merging files,
page 47
139
Renaming pending changelists
Button
Use to:
More
information
Attach
Attach the file or changelist to an item in Helix ALM or an external
issue tracking tool. Changelists and files are attached to items
when changelists are committed. If a changelist is selected, the
Attach button is only available if at least one file has an Add, Check
In, Remove, or Rename action. If files are selected, the Attach
button is only available if at least one file has an Add or Check In
action.
Attaching
changelists and
files to Helix ALM
items, page 145
or Attaching
source files to
external issues,
page 291
Add to
Code
Review
Add the changelist to a code review.
Adding files to
code reviews,
page 63
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 pending changelists
You can rename pending changelists.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the changelist and click Rename Changelist.
The Rename Changelist dialog box opens.
3. Enter a new name and click OK.
The changelist is renamed.
Removing pending 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.
140
Editing pending changelist file actions
The changelist and all of the actions associated with it are removed.
Editing pending changelist file actions
You can edit pending 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 pending changelist actions
You can move actions from one pending 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.
3. Select the Destination changelist to move the files to.
You can also create a new changelist. See Creating changelists, page 135.
4. Click OK.
The file actions are moved.
Removing pending changelist file actions
You can remove file actions from pending 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 files and click Remove Action.
You are prompted to confirm the removal.
141
Adding comments to changelist files
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.
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 39.
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 actions, such as adding them to labels or code reviews, duplicating changes across
branches, or rolling back actions.
To view or work with pending changelists, see Working with pending changelists, page 138.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
142
Working with committed changelists
2. Select My Committed from the Filter changelists by list. You may also be able to view other users' or
all committed changelists.
The committed changelists are displayed. You can also search for changelists to further narrow the list.
See Searching for committed changelists, page 144.
A Helix ALM icon is displayed next to changelists and files attached to items.
3. Select a changelist or file and click a button to perform an action.
Button
Use to:
More information
View
Details
View details about the changelist or file actions.
Viewing changelist
details, page 137
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 88
Differences
View differences between the version of the changelist file and
the version the action modified.
Viewing file
differences, page 45
View File
View the file.
Viewing files in
Surround SCM, page
19
143
Searching for committed changelists
Button
Use to:
More information
Attach
Attach the file or changelist to an item in Helix ALM or an
external issue tracking tool. If a changelist is selected, the
Attach button is only available if at least one file has an Add,
Check In, Remove, or Rename action. If files are selected, the
Attach button is only available if at least one selected file has an
Add or Check In action.
Attaching
changelists and files
to Helix ALM items,
page 145 or
Attaching source
files to external
issues, page 291
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
158
Add to
Code
Review
Add the changes to a code review.
Adding files to code
reviews, page 63
Duplicate
Changes
Duplicate changes to another branch.
Duplicating selected
changes across
branches, page 210
Rollback
Changes
Rollback changelist actions.
Rolling back
changelist actions,
page 147
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 committed date 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.
144
Attaching changelists and files to Helix ALM items
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.
Attaching changelists and files to Helix ALM items
You can attach changelists and files in changelists to Helix ALM issues, requirements, and test cases. The
changelist and file information is attached to the item, making it easy to work with them from Surround SCM or
Helix ALM.
1. Choose Tools > Changelists.
The Changelists dialog box opens.
2. Select the changelist or files to attach. To select multiple files in a changelist, Ctrl+click each one.
You can only attach changelists that have at least one file with an Add, Check In, Remove, or Rename
action. You can only attach files with Add or Check In actions.
3. Click Attach to Helix ALM.
The Helix ALM Browser dialog box opens.
Note: If you are attaching a changelist or files with pending item attachments, the Attach to Helix
ALM dialog box opens. Skip to step 8.
145
Attaching changelists and files to Helix ALM items
4. Click the tab for the item type to attach the changelist or files to.
5. Select the items to attach the changelist or files to. To select multiple items, Ctrl+click each item.
Your assigned items are displayed by default. Select a filter from the Filtered By list to narrow the list of
items or select <Not Filtered> to view all items. To display specific items, click
, enter the item
number or multiple numbers separated with spaces, and click OK. You can only attach files to items you
have access to.
6. Click a button to perform any additional actions.
Button
Use to:
More information
View
View details about the selected item.
Viewing Helix ALM items,
page 280
Add
Add a new issue. Not available for requirements and test
cases.
Adding Helix ALM issues,
page 280
Edit
Edit details for the selected issue. Not available for
requirements and test cases.
Editing Helix ALM issues,
page 281
7. Click Attach to attach the changelist or files to the selected items.
Note: If an item is locked for editing by another Helix ALM user, you must wait for them to unlock it
before you can attach the changelist or files. If you are editing a selected item, 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 Helix ALM to manually
resolve the conflict. Click Cancel to cancel attaching files to the locked item.
146
Rolling back changelist actions
The Attach to Helix ALM dialog box opens. Items you added are displayed in the Pending Attachments
list.
8. Select an item and click a button to perform an action.
Button
Use to:
More information
Add
Add other items to the Pending Attachments list.
Remove
Remove the selected item from the Pending Attachments list.
View
View details about the selected item.
Viewing Helix ALM items,
page 280
Edit
Issue
Edit details for the selected issue. Not available for
requirements and test cases.
Editing Helix ALM issues,
page 281
Fix
Mark the selected issue as fixed. Not available for
requirements and test cases.
Fixing Helix ALM issues,
page 281
9. Click OK to attach the files to the selected items.
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.
147
Rolling back changelist actions
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 149 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.
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
137
Differences
Compare file versions.
Viewing file differences, page 45
History
View the file history.
Viewing file history, page 88
Properties
View the file properties.
Viewing file properties, page 92
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.
148
Rollback changelist action resolutions
4. Enter any Comments, such as a reason for undoing the change.
5. Click a rollback resolution button.
Button
Use to:
More
information
Rollback
Changes
Undo the changelist action.
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
47
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
31
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.
149
Rollback changelist action resolutions
Changelist action
Rollback resolution
Reason
Remove file
--
Remove file
New file added, not latest version
No resolution required
File removed
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
Add
Check In
Create Repository
Move Repository
Remove
150
Status
Selecting changelists
Changelist action
Remove Repository
Rename
Rename Repository
Status
Rollback resolution
Reason
Restore repository
--
No resolution required
Repository no longer removed
No resolution available
Repository destroyed
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 144.
3. Select changelist or file and click View Details to view the details. See Viewing changelist details, page
137.
4. Select a changelist and click Select to use it.
151
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.
153
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 437.
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 160.
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 155.
6. Select a label and click the button for the action to perform.
154
Button
Use to:
More information
View
View the label details.
Viewing labels, page 156
Edit
Edit the label to rename it, change the
branches it is available in, or remove it
from files.
Editing labels, page 156
Delete
Delete the label.
Deleting labels, page 158
Duplicate
Duplicate the label.
Duplicating labels, page 157
Differences
Compare two labels to determine the
missing, different, or identical files
between the labels.
Viewing label differences, page 161
Creating labels
Button
Use to:
More information
Attach
Attach labeled files to an item in Helix
ALM or an external issue tracking tool.
Attaching source files to Helix ALM items,
page 277 or Attaching source files to external
issues, page 291
Add to
Code
Review
Add labeled files to a code review.
Adding files to code reviews, page 63
Toggle
Hidden
Hide or unhide the label.
Hiding labels, page 158
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.
155
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. A progress indicator may open if the label is applied to several
files.
4. Click the Files tab to view the files that the label is applied to.
Tip: Use the Repository/Filename Search field to limit the file list to filenames and repositories that
contain the text you enter. Searches are not case sensitive and cannot include wildcard characters.
5. Click the History tab to view the label history. See Viewing label history, page 162.
6. Click Close when you finish.
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 (scope) 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. A progress indicator may open if the label is applied to several files.
156
Duplicating labels
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 164.
Tip: Use the Repository/Filename Search field to limit the file list to filenames and repositories that
contain the text you enter. Searches are not case sensitive and cannot include wildcard characters.
6. Click the History tab to view the label history. See Viewing label history, page 162.
7. Click OK to save the changes.
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.
157
Hiding labels
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 158.
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.
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.
158
Selecting labels
2. Select a Label.
Select <New Label> to create a label. See Creating labels, page 155. Click Select to view label details or
search for a label. See Selecting labels, page 159.
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.
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.
159
Searching for labels
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 160.
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 155.
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 156.
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 219.
1. In the Select Label dialog box, select Search For File in the Filter labels by field.
The Label Search dialog box opens.
160
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 221.
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.
Tip: Use the Filename Search field to limit the list to filenames that contain the text you enter.
Searches are not case sensitive and cannot include wildcard characters.
4. Click Differences.
The Label Differences dialog box opens. A progress indicator may open if the labels are applied to several
files.
161
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 with version differences and click Differences to compare versions. See Viewing file
differences, page 45.
7. Click Save As to save the label differences or click Print to print the differences.
8. Click Close when you finish.
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.
162
Running labeled files reports
5. Click Close when you finish.
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.
163
Removing labels from files
The report opens.
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 162.
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.
164
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. 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 165.
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 167.
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 116.
When you are ready to continue work on shelved files, unshelve the files to a working directory and then
check them in when the changes are complete. See Unshelving files, page 171.
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 167.
1. Select the files or repositories to shelve and choose Activities > Shelve Files.
The Shelve Files dialog box opens.
165
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 169.
3. Expand the Local file options to select options for handling local files.
n
Get original version replaces the local file with the original version and reverts the check out if files
are checked out.
n
Get latest version replaces the local file with the latest 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.
166
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 171.
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.
167
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 171.
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 169.
4. Select a shelf or file and click a button to perform an action.
168
Button
Use to:
More information
Shelve
Files
Add files to the shelf.
Adding files to existing
shelves, page 167
Unshelve
Files
Retrieve the file or all files in a shelf to a local or working
directory.
Unshelving files, page
171
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 170
Edit Shelf
Edit the shelf to change the name, description, owner, and
sharing settings, and manage the files in the shelf.
Editing shelves, page
170
Delete
Remove the file from the shelf or delete the shelf.
Deleting shelved files
and shelves, page 170
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 170.
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 165 and Viewing differences between
repositories and working directories, page 116.
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.
169
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 167.
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.
170
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.
171
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.
172
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 381 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 177
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 397.
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.
173
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 178.
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.
174
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.
175
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.
176
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 173
Baseline branch
Snapshot branch
Workspace branch
Frozen mainline or baseline branch
Freezing and unfreezing branches, page 388
Frozen workspace branch
177
Creating branches
Icon
Indicates:
More information
Mainline branch with indexing on for text-based
searches
Indexing branches for optimized searches,
page 384
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 433
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
381.
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.
178
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 180.
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 182.
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 181.
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.
179
Using branch templates
6. Select a Branch type. The list includes branch types you have security permissions to create. See About
branches, page 173.
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 159.
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 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.
180
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 181.
n
To change the repositories included in an existing branch, update the template in the branch properties.
See Modifying templates for existing branches, page 389.
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 182.
181
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 389.
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.
182
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.
183
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 192 and
Promoting files, page 197.
n
Rebasing changes from a parent branch down to a child branch. See Rebasing branches, page 201 and
Rebasing files, page 206.
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 210.
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 192.
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 201.
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 210.
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.
2. Choose Branch > Branch Differences.
185
Viewing 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.
186
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 45 and Setting
diff/merge options, page
53
187
Copying files across branches during check in
Button
Use to:
More information
Diff Report
Generate a branch differences report.
Running branch
differences reports, page
189
View
View a read-only copy of the file.
Viewing files in Surround
SCM, page 19
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
88 and Viewing repository
history, page 131
Properties
View the file or repository properties.
Viewing file properties,
page 92 and Viewing
general repository
information, page 132
Remove
Remove a missing file or repository from a branch.
Removing files, page 41
and Removing
repositories, page 124
Restore
Restore a removed file or repository in the branch.
Restoring removed files,
page 42 and Restoring
repositories, page 125
Rename
Rename a file or repository to use the name in the other
branch.
Renaming files, page 40
and Renaming
repositories, page 121
Promote
Update a file in the ancestor branch with changes from the
child branch.
Promoting files, page 197
Rebase
Update a file in the child branch with changes from the
ancestor branch.
Rebasing files, page 206
Merge
Merge a changed file with the file in the other branch.
Merging files, page 47
Copy
Copy a changed file to the other branch.
Copying files across
branches during check in,
page 188
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 185.
1. Select a changed file and click Copy.
The Copy Check In dialog box opens.
188
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 Helix ALM or an external issue tracking tool. See Attaching
source files to Helix ALM items, page 277 or Attaching source files to external issues, page 291.
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 185.
1. Select a branch or repository.
2. Choose Branch > Branch Differences.
The Branch Differences dialog box opens.
189
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.
190
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 50.
10. Click Save As to save the report or Print to print it.
11. Click Close when you finish.
191
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.
192
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 159. 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 194.
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.
193
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.
194
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 45
History
View the file history.
Viewing file history, page
88
Properties
View the file properties.
Attach
Attach the file to an item in Helix ALM 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
Helix ALM items, page
277 and Attaching
source files to external
issues, page 291
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 63
195
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
197
Merge
Locally
Manually merge the files.
Merging files, page 47
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 41
Break
Share
Unshare a file.
Breaking shares, page
130
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 155. Click Select to view label details or
search for a label. See Selecting labels, page 159.
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 196. 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 192 and Promoting files, page 197.
196
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.
197
Promoting files
You can also promote branches to retrieve all files with changes to a parent branch. See Promoting branches,
page 192.
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 159. 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 194.
198
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.
199
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.
200
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
45
History
View file history.
Viewing file history, page 88
Properties
View file properties.
Viewing file properties, page
92
Rollback
Rollback the selected file.
Rolling back files, page 31
Merge
Locally
Manually merge the files.
Merging files, page 47
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.
201
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 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 159.
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 204.
202
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.
203
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.
204
Button
Action
More Information
Differences
Compare the branch file versions.
Viewing file differences,
page 45
History
View the file history.
Viewing file history,
page 88
Properties
View the file properties.
Viewing file properties,
page 92
Rebase actions
Button
Action
More Information
Attach
Attach the file to an item in Helix ALM 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 Helix ALM items,
page 277 and Attaching
source files to external
issues, page 291
Add to
Code
Review
Add the file to a code review.
Adding files to code
reviews, page 63
Rebase
File
Rebase the file.
Rebasing files, page
206
Merge
Locally
Manually merge the files.
Merging files, page 47
Break
Share
Unshare the files.
Breaking shares, page
130
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 155. Click Select to view label details or
search for a label. See Selecting labels, page 159.
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 205. 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 201 and Rebasing files, page 206.
205
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 201.
206
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 159. 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 204.
207
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.
208
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.
209
Duplicating selected changes across branches
Button
Use to:
More information
Differences
Compare file versions.
Viewing file differences, page
45
History
View file history.
Viewing file history, page 88
Properties
View file properties.
Viewing file properties, page
92
Rollback
Rollback the selected file.
Rolling back files, page 31
Merge
Locally
Manually merge the files.
Merging files, page 47
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.
210
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 151.
n
Issue duplicates changes associated with files attached to the selected Helix ALM issue. Click
Select to search for an issue or view issue details. See Selecting Helix ALM items, page 285.
n
Label duplicates changes associated with the selected label. Click Select to search for a label or view
label details. See Selecting labels, page 159.
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 213.
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.
211
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 45
History
View file history.
Viewing file history, page 88
Properties
View file properties.
Viewing file properties, page 92
Duplicate
Changes
Duplicate file changes to the destination
branch.
Duplicating selected changes across
branches, page 210
Merge
Locally
Manually merge the files.
Merging files, page 47
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 155. Click Select to view label
details or search for a label. See Selecting labels, page 159.
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 213. 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.
212
Duplicate changes actions
Duplicate changes actions
Following are actions and corresponding reasons associated with duplicating changes. See Duplicating
selected changes across branches, page 210.
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.
213
Tracking duplicated changes
2. Select a Branch.
3. Select a Track changes for option. If you selected a specific file version 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 151.
n
Issue tracks changes associated with files attached to the specified Helix ALM issue. Click Select to
search for an issue or view issue details. See Selecting Helix ALM items, page 285.
n
Label tracks changes associated with the specified label. Click Select to search for a label or view
label details. See Selecting labels, page 159.
4. Click Save As to save the results list or click Print to print it.
5. Click Close when you finish.
214
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 215.
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 217.
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 215.
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.
215
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 381.
216
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.
217
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 185.
4. Click Save As to save the graph or Print to print it.
218
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 219.
You can also search for specific phrases or text in file contents. See Searching for text in files, page 234.
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 240.
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 241.
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 243.
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 244.
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 234.
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.
219
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 221.
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
241 and Creating reports, page 249.
220
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 222
Number
Numbers that do or do not match a number
or number in a range.
Adding number restrictions, page
225
Date
Dates that do or do not match a date, date
range, or time period.
Adding date restrictions, page 225
List value
Values that do or do not match selected
values.
Adding list value restrictions, page
226
Condition
Attributes that do or do not match a
condition.
Adding condition restrictions, page
227
Branch/repository
Locations in a repository for a specific
branch or across all branches.
Adding branch and repository
restrictions, page 231
Event
File events that do or do not match events.
Adding event restrictions, page
228
Label
Labels that do or do not match text or a
regular expression.
Adding label restrictions, page 229
Helix ALM item
number
Helix ALM items that do or do not match a
number or number in a range or list.
Adding Helix ALM item number
restrictions, page 230
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 230
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 232
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 95 and Configuring triggers, page 346.
221
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 222.
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.
222
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
223
Using regular expressions
To match:
Use:
Example
Any single
whitespace
character
(space, tab,
new line)
\s
v\s matches ‘v’ followed by a whitespace character
Any single
nonwhitespace
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
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,}
224
Adding number restrictions
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.
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.
225
Adding list value restrictions
2. Select is or is not to indicate if the files include the specified date or time period.
Note: If the restriction is for a date/time custom field, select is not set to include files with date/time
custom fields that are not set to a value.
3. Select the time period to search.
n
Equal to, before, after, or between includes files relative to the specified date or time period.
n
A specific time period includes files from the selected period, such as last week or last year.
n
In the last or next includes files for a specified number of hours, days, weeks, months, or years
relative to the current date/time.
4. Click OK to add the restriction.
Adding 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, 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.
1. Select a restriction.
The Restriction dialog box opens.
226
Adding condition restrictions
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.
227
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.
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.
228
Adding label restrictions
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
222.
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
222.
5. If you entered text, select Match case to match the case of the text.
6. Click OK to add the restriction.
229
Adding Helix ALM item number restrictions
Adding Helix ALM 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.
Helix ALM item number restrictions limit results to files attached to 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 Helix ALM 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.
230
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 222.
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.
231
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.
232
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.
233
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 384.
1. Choose Edit > Find in Files.
The Find in Files window opens.
234
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 236 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 238 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.
235
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 112.
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 234. 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.
236
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 384.
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.
237
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.
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 234.
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.
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'.
238
Configuring filters
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'
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.
239
Adding filters
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 240.
3. Select a filter and click Edit to change it. See Editing filters, page 242.
4. Select a filter and click Duplicate to duplicate it. See Duplicating filters, page 242.
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 242.
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.
Note: You can also create filters in the Advanced Find dialog box. See Searching for files, page 219.
1. Choose Tools > Filters.
The Filters dialog box opens.
2. Click Add.
The Add Filter dialog box opens.
240
Applying filters to the source file list
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 221.
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.
8. Add any additional restrictions.
9. Click OK.
The filter is added. See Applying filters to the source file list, page 241 for information about using filters.
Applying filters to the source file list
You can filter the source file list to display specific files.
241
Editing filters
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.
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.
242
Browsing to files and repositories
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
Each Surround SCM repository and file has a unique URL that starts with the sscm:// protocol. You can use
an address to easily browse to repositories and files.
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. You can also enter web addresses to open web
pages in your default browser.
n
Repository—sscm://ServerAddress:Port//Branch//Repository/SubRepository
n
File—sscm://ServerAddress:Port//Branch//Repository/SubRepository/File
Tip: To go 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 244.
Sharing addresses with other users
You may want to share Surround SCM addresses with other users to direct them to a specific repository or
file. You can copy and paste an address from the Address toolbar. Choose View > Toolbars > Address to
open the toolbar. Keep in mind that users must have Surround SCM access to open items using sscm
addresses.
Email or other external application
If you are sharing addresses using an external application, such as an email application, you may want to
change addresses pasted as plain text to hyperlinks to help users quickly open items. For example, to create
an sscm hyperlink in a Microsoft Outlook email, click Hyperlink on the Insert tab and then paste the Address
in the Insert Hyperlink dialog box.
243
Bookmarking files, repositories, and branches
Web page
You may also find it useful to provide hyperlinks to repositories or files on a web page. For example, your
development team wants to provide read-only access to design documents to people on other teams who
need to read them. To do this, an administrative user needs to perform the following steps.
1. Add a security group named Guest with permissions to only view the design document repository list and
get files. See Adding security groups, page 302.
2. Add a user named Guest and add them to the Guest security group. See Adding users, page 309.
3. Copy the address for the design document from the Address toolbar.
4. Paste the address on the web page, create the link, and add the username and password for the Guest
user to the address. For example,
sscm://Guest:password@server.wysicorp.com:4900//Mainline//Mainline/Design/WysiDraw/1.0.0/Wysi
Draw Design 1.0.docx.
When users click the link, Surround SCM opens with the WysiDraw design document selected. Users
can only get the file based on the security group permissions.
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 245.
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
244
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.
Managing bookmarks
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 245.
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.
245
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 247.
To create and run most reports, choose Tools > Reports. See Creating reports, page 249 and Running
reports, page 269. Other reports, such as branch and file differences reports, are available in other locations.
You can also add and run reports from external reporting services. See Adding external reports to Surround
SCM, page 268.
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 250
Branch
differences
File differences between two related branches.
Running branch
differences reports,
page 189
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 381
Changelist
Information about file actions associated with pending or
committed changelists.
Working with pending
changelists, page 138
and Working with
committed
changelists, page 142
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 79
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
254
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 50
247
Configuring reports
Report type
Displays:
More information
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 257
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 163
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 259
Security
group
Information about commands enabled or disabled for each
security group. Use these reports to quickly determine which
groups have access to specific actions and the users in each
group.
Creating security
group reports, page
262
Trend
Actions performed over time or by user. Use these reports to
determine the activity level of a project.
Creating trend reports,
page 264
Workflow
progress
Information about the state of files as they move through a
workflow.
Creating workflow
progress reports, page
266
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 administrator for information. See Adding external reports to Surround SCM, page 268.
Note: You can also save and print the source file list for reporting purposes. See Saving the source file
list, page 272 and Printing the source file list, page 273.
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 163.
Other reports are also available: branch differences, branch maintenance, changelist, code review, and file
differences. See Report types, page 247.
1. Choose Tools > Reports.
The Reports dialog box opens.
248
Creating reports
2. Click Add to create a report. See Creating reports, page 249.
3. Select a report and click Edit to change it. See Editing reports, page 268.
4. Select a report and click Duplicate to duplicate it. See Duplicating reports, page 269.
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 270.
6. Click Quick Report to create and run a report without saving it. See Running quick reports, page 270.
7. Select a report and click Run to generate it. See Running reports, page 269.
8. Select a report and click Delete to delete it. See Deleting reports, page 269.
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 247 for information about other available reports.
1. Choose Tools > Reports.
The Reports dialog box opens.
249
Creating audit trail reports
2. Click Add.
The Select Report Type dialog box opens.
3. Select a report type and click OK. See Report types, page 247.
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 221.
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 269 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 mainline database.
Signature information is displayed in the following columns.
Column
Contains:
Signed Client
Type
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.
250
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 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.
251
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.
252
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 221.
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 server.
16. Select the sorting and order options.
253
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 269 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 79.
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.
254
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 221.
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.
255
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 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.
256
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 269 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.
257
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 221.
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
267.
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 server.
13. Select a report style.
Summary style report includes an overview of file details.
258
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 50.
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 267.
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 269 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.
259
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 221.
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.
260
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
267.
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 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 267.
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 269 for information about running reports.
261
Creating security group reports
Creating security group reports
Security group reports include information about commands enabled or disabled and users in each security
group. Use these reports to quickly determine which groups have access to specific actions and the users in
each group. See Security Commands, page 457 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.
262
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 server.
12. Select a report style.
263
Creating trend reports
n
Comparison style report displays security groups and commands side-by-side in the same table.
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.
13. Select the information to include in the report.
n
Server security permissions includes commands enabled on the Server Security tab in the Edit
Security Group dialog box.
n
Repository and branch security permissions includes commands enabled on the Repository
Security and Branch Security tabs.
n
Users in the group includes users in the Users in Group list on the Users tab.
14. Click OK.
The report is added. See Running reports, page 269 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.
264
Creating trend 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 221.
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.
265
Creating workflow progress 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) 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 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 269 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.
266
Charting report data
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 221.
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 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 269 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 257 and Creating list reports, page 259.
The following options must be set in the report configuration:
267
Adding external reports to Surround SCM
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.
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.
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 administrator for
help.
5. Click Add.
The report is added. See Running reports, page 269 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 268.
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.
268
Duplicating reports
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 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.
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 268.
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 249
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.
269
Running quick reports
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.
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 249.
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.
270
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 249.
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.
271
Changing report menu item names and icons
6. Add the new report menu item to the repository shortcut menu. See Customizing shortcut menus, page
105.
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 272.
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 288.
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
270.
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.
272
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.
273
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.
274
Integrating with Helix ALM
You can integrate Surround SCM with Helix ALM 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 Helix ALM.
For example, an issue is created in Helix ALM 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 Helix ALM and selects the Helix ALM project
to view her assigned issues. She then selects the appropriate issue and attaches the file to it. Helix ALM
users with security access to the Source Code tab can work with the file Jane attached.
Configuring Helix ALM connections
Helix ALM projects are stored on servers, which you need to provide access to. Each connection is mapped
to a single project on the Helix ALM Server.
Note: The administrator or another high-level user must enable Helix ALM integration before you can
configure connections. See Enabling Helix ALM integration, page 429.
1. Choose Tools > Helix ALM Integration > Connections.
The Helix ALM Connections dialog box opens.
2. Click Add to create a connection. See Adding Helix ALM connections, page 275.
3. Select a connection and click Edit to change it. See Editing Helix ALM connections, page 276.
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 Helix ALM connections, page 276.
Adding Helix ALM connections
To access Helix ALM issues, requirements, and test cases, you need to add a connection to the Helix ALM
project.
1. Choose Tools > Helix ALM Integration > Connections.
The Helix ALM Connections dialog box opens.
2. Click Add.
275
Editing Helix ALM 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 port number is 99 on Windows and 1566 on Unix platforms.
Note: If you received a server settings file from your 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 Helix ALM Server. Contact your administrator for
additional help.
5. Click Get Projects to retrieve a list of all projects from the Helix ALM 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 Helix ALM integration options for repositories, page 430.
Editing Helix ALM connections
You can change the Helix ALM Server address, port number, and project.
1. Choose Tools > Helix ALM Integration > Connections.
2. Select the connection and click Edit.
The Edit Connection dialog box opens.
3. Make any changes and click OK.
Deleting Helix ALM connections
You can delete any Helix ALM connections you no longer use.
1. Choose Tools > Helix ALM Integration > Connections.
2. Select the connection and click Delete.
You are prompted to confirm the deletion.
3. Click Yes.
276
Entering Helix ALM login information
The connection is deleted.
Entering Helix ALM login information
You need to enter your Helix ALM login information before you can attach files to issues, requirements, or test
cases.
1. Choose Tools > Helix ALM Integration > User Settings.
The Helix ALM User Settings dialog box opens.
2. Select Use Surround SCM username and password if your Helix ALM and Surround SCM login
information is the same.
3. Select Use the following and enter your Helix ALM username and password if your login information is
different from Surround SCM.
4. Click OK.
You can now attach Surround SCM source files to Helix ALM items.
Attaching source files to Helix ALM items
You can attach source files to Helix ALM issues, requirements, and test cases. The file information is
attached to the item, making it easy to work with the file from Surround SCM or Helix ALM.
You can attach source files to items from the source file list and when you add files, check in files, promote or
rebase files and branches, or view file history. You can also attach changelists and files in changelists to
items. See Attaching changelists and files to Helix ALM items, page 145.
Note: You must use Helix ALM (or TestTrack 2010.1 - 2016.1) to attach files to requirements and test
cases.
1. Select the files or repository and choose Activities > Attach to Helix ALM.
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 Helix ALM Browser dialog box opens.
277
Attaching source files to Helix ALM items
2. Select the Helix ALM Connection for the project to access.
Click Configure to create or change a connection. See Configuring Helix ALM connections, page 275.
3. Click the tab for the item type to attach the files or repository to.
4. Select the items to attach the files to. To select multiple items, Ctrl+click each item.
Your assigned items are displayed by default. Select a filter from the Filtered By list to narrow the list of
items or select <Not Filtered> to view all items. To display specific items, click
, enter the item
number or multiple numbers separated with spaces, and click OK. You can only attach files to items you
have access to.
5. Click a button to perform any additional actions.
Button
Use to:
More information
View
View details about the selected item.
Viewing Helix ALM items,
page 280
Add
Add a new issue. Not available for requirements and test
cases.
Adding Helix ALM issues,
page 280
Edit
Edit details for the selected issue. Not available for
requirements and test cases.
Editing Helix ALM issues,
page 281
6. Click Attach to attach the files to the selected items.
278
Attaching source files to Helix ALM items
Note: If an item is locked for editing by another user in Helix ALM, you must wait for them to unlock it
before you can attach files. If you are editing a selected item, 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 Helix ALM to manually resolve the conflict.
Click Cancel to cancel attaching files to the locked item.
The Attach to Helix ALM dialog box opens. Items you added are displayed in the Pending Attachments
list.
7. Select an item and click a button to perform an action.
Button
Use to:
More information
Add
Add other items to the Pending Attachments list.
Remove
Remove the selected item from the Pending Attachments list.
View
View details about the selected item.
Viewing Helix ALM items,
page 280
Edit
Issue
Edit details for the selected issue. Not available for
requirements and test cases.
Editing Helix ALM issues,
page 281
Fix
Mark the selected issue as fixed. Not available for
requirements and test cases.
Fixing Helix ALM issues,
page 281
8. Click OK to attach the files to the selected items.
279
Viewing Helix ALM items
Viewing Helix ALM items
After files are attached to Helix ALM items, you can view the item details from Surround SCM. You can view
details from the file history, when working with changelists, or when using an item to search for related files,
such as when adding files to code reviews.
File history
1. Select the file.
You can search for files attached to items. See Finding files attached to Helix ALM items, page 282.
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 dialog box opens.
5. Click OK when you finish.
Changelists and other areas
1. Select a Helix ALM item in the Helix ALM Browser or Attach to Helix ALM dialog box and click View.
The read-only View dialog box opens.
2. Click OK when you finish.
Adding Helix ALM issues
You can create new Helix ALM issues and attach source files to them from Surround SCM.
Note: You must use Helix ALM (or TestTrack 2011 - 2016.1) to add issues from Surround SCM.
1. When you are attaching files to Helix ALM, click Add on the Issues tab.
The Add Issue dialog box opens with the Detail tab selected.
280
Editing Helix ALM issues
2. Enter the issue information.
See the Helix ALM help for information.
3. Click Add when you finish entering the issue information.
The issue is added to the Helix ALM project.
Editing Helix ALM issues
You can edit Helix ALM issues when you are attaching source files from Surround SCM.
Note: You must use Helix ALM (or TestTrack 2011- 2016.1) to edit issues.
1. When you are attaching files to Helix ALM, 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 Helix ALM project.
Fixing Helix ALM 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.
281
Finding files attached to Helix ALM items
1. Select the files or repository and choose Activities > Attach to Helix ALM.
The Helix ALM Browser dialog box opens.
2. Select a Helix ALM 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 Helix ALM
items, page 280.
4. Click Attach to attach the files to the selected issues.
The Attach to Helix ALM 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.
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 Helix ALM 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.
282
Analyzing issue risk in files
3. Select a Helix ALM 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.
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 59.
Keep the following in mind:
n
To analyze risk, Surround SCM must be integrated with Helix ALM or a supported third-party issue
tracking tool. See Integrating with Helix ALM, page 275 and Integrating with issue tracking tools, page
290.
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.
283
Analyzing issue risk in files
2. Click Browse and select the branch and repository to analyze.
3. Select the Analysis settings.
n
Select a Helix ALM 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.
284
Selecting Helix ALM items
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 19.
View the history of the selected file. See Viewing file history, page 88.
View properties for the selected file. See Viewing file properties, page 92.
Change the workflow state of the selected files. See Changing workflow states, page 38.
Change multiple custom field values for the selected files. See Changing multiple custom
fields, page 37.
Perform a code review for the selected file. See Reviewing files, page 74.
Add the selected files to a code review. See Adding files to code reviews, page 63.
View code reviews for the selected file. See Viewing code reviews files are included in,
page 82.
Selecting Helix ALM items
You can search for a Helix ALM issue, test case, or requirement to use when performing some actions in
Surround SCM. For example, you can select Helix ALM items with attached files to add to code reviews or
search for an issue to use when duplicating or tracking file changes across branches.
1. Select a Helix ALM item filter when performing an action and click Select.
The Helix ALM Browser dialog box opens.
285
Selecting Helix ALM items
2. Select a filter from the Filtered By list to narrow the list of items or select <Not Filtered> to view all
items. The available filters depend on the action you are performing. To display specific items, click
enter the item number or multiple numbers separated with spaces, and click OK.
3. Select an item to view the summary and description.
4. Click a button to perform any additional actions.
Button
Use to:
More information
View
View details about the selected item.
Viewing Helix ALM items,
page 280
Add
Add a new issue. Not available for requirements and test
cases.
Adding Helix ALM issues,
page 280
Edit
Edit details for the selected issue. Not available for
requirements and test cases.
Editing Helix ALM issues,
page 281
5. Click Select to use the selected item.
286
,
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 a 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 with third-party applications:
n
Third-Party Integrations lists supported integrations. n
The 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 289
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 290 for
information about the API and working with issues in an external issue tracking tool in the Surround
SCM Client.
n
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.
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.
287
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 293.
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 294.
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 243.
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 270.
288
Integrating with IDEs and applications that support SCCI
n
Add custom menus or shortcut menu items for third-party applications to Surround SCM. See 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 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 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 Perforce.
289
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 287. After the integration is enabled, you can perform
Surround SCM tasks from the corresponding application.
Note: Other integration options and plug-ins are available during Surround SCM installation for Windows
and other supported platforms. Some integration plug-ins for Unix applications must be manually installed.
See the Integrations knowledgebase 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 Surround
SCM.
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 283.
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: Download plug-ins for Bugzilla, JIRA, and Microsoft Team Foundation Server (TFS) from the
Integrations 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.
290
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 attach source files to issues from the source file list and when you add files, check in files, promote
or rebase files and branches, or view file history. You can also attach changelists and files in changelists to
issues.
1. To attach files or repositories, select them in the Source Tree window 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.
To attach changelists or files in a changelist, select them in the Changelists 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 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 issues, Ctrl+click each one.
Click View Details to view the issue details. See Viewing external issues, page 292.
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.
291
Viewing external issues
5. Select an issue and click a button to perform an action.
Button
Use to:
More information
Add
Add other issues to the Pending Attachments list.
Remove
Remove the selected issue from the Pending
Attachments list.
View
View details about the selected issue.
Viewing external issues, page
292
Fix
Mark the selected issue as fixed.
Fixing external issues, page
292
6. Click OK to attach the files to the selected issues.
The files are attached.
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.
292
Using the Windows Explorer and Mac Finder integrations
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 292.
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.
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 actions 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 server file.
The local file was modified and does not match the 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 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.
293
Using the Mac Finder plug-in
1. Right-click a file or directory in Windows Explorer and choose Surround SCM to access Surround SCM
actions.
2. Choose one of the following actions.
Action
Use to:
More
information
Add
Add the file to Surround SCM.
Adding files to
Surround SCM,
page 32
Check In
Check in the updated file.
Checking in
updated files,
page 28
Check Out
Check out the file.
Checking out
files, page 25
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 27
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
293
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.
294
Using the Mac Finder plug-in
Action
Use to:
More
information
Add
Add the file to Surround SCM.
Adding files to
Surround SCM,
page 32
Check In
Check in the updated file.
Checking in
updated files,
page 28
Check Out
Check out the file.
Checking out
files, page 25
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 27
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.
295
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 Helix ALM License Server and Surround SCM Servers are started.
See Starting the Helix ALM License Server, page 297 and Starting the Surround SCM Server, page 298.
2. Start the Surround SCM Client and log in.
See Starting Surround SCM, page 4.
3. Create a mainline branch.
You must create at least one mainline branch before users can add source files. See Creating mainline
branches, page 397.
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 299.
5. Add users and then add them to security groups.
You can add new users in Surround SCM or retrieve global users from the license server. Users must be
in a security group to use Surround SCM. See Managing users, page 308.
6. Configure the Surround SCM Server.
The server is managed from a client. You can change server settings, such as mail, logging, and
database settings. See Configuring the Surround SCM Server, page 315.
7. Optionally configure proxy servers.
If remote sites need access to files, you can configure proxy servers to improve file retrieval. See Using
Proxy Servers, page 441.
Starting the Helix ALM License Server
An administrative user must make sure the Helix ALM 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 > Perforce > Helix ALM License Server
> Helix ALM 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.
297
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 > Perforce > 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.
298
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.
Tip: See the Security Best Practices for recommendations about user, database, and server
management to keep data secure.
Example
For example, a project team may include one or more of the following:
n
An administrator with access to all commands
n
A project lead with access to most commands, but is restricted from advanced features, such as creating
mainline branches, adding users, or editing server options
n
One or more developers with access to most file and branch commands, but are restricted from most
admin, user, and group commands
n
One or more testers with access only to basic commands, such as getting and viewing files
n
A customer 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 300 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 301.
299
Security examples
Security
Type
Description
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 305.
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 307.
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.
300
Controlling access with security groups
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.
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.
301
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 302.
Server security commands are grouped in the following categories:
n
General—Common Surround SCM actions (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 457 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 server requires read/write access to this directory. All access permissions are controlled using
Surround SCM 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.
302
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 301 for a list of commands in each category.
303
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 301.
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 305.
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 307.
7. Click OK to save the changes.
304
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.
305
Controlling access to specific repositories
3. Click Modify to change the security. The fields are enabled.
4. Make any changes to security settings.
306
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 308.
307
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 307.
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 463.
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.
308
Adding users
You need to create user records before users can access Surround SCM. Keep in mind that users can be
created in Surround SCM or in the Helix ALM License Server.
Note: If you create users with the license server, you need to retrieve global users. See Retrieving global
users, page 311.
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 Helix ALM License Server. See Retrieving global users, page 311.
New users are automatically added to the license server, making them global users that can be shared among
all Helix ALM products. See Setting Helix ALM License Server options, page 327.
Note: Users with usernames and passwords longer than 32 characters cannot use Surround SCM or
TestTrack 2016.0 and earlier.
1. Choose View > Users.
The Users window opens.
2. Click Add.
The Add User dialog box opens.
309
Adding users
3. Enter the First name, MI (middle initial), and Last name. You can enter up to 32 characters for the first
and last names and up to 8 characters for the middle initial.
Note: Multiple users can have the same first and last names. Make sure to enter additional contact
information to distinguish between these users in Helix ALM applications.
4. Enter a unique Username. You can enter up to 128 characters.
You cannot use System as a username because it is reserved to perform trigger actions.
5. 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. You can enter
up to 128 characters for the password. Users can change their passwords when they log in
unless password restrictions are set on the Helix ALM License Server. See the license
server help for information.
Groups
Add the user to a security group. Users can only access commands added to the group they
belong to and must be assigned to at least one group. See Adding security groups, page 302
for information about creating groups.
License
Assign a license to the user. Users cannot log in if a license is not assigned to them. See
License types, page 311.
Address
Enter the user's address.
Notes
Enter any notes about the user.
6. Click OK.
310
Retrieving global users
The user is added.
License types
Helix ALM 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.
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 Helix ALM
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 an integrated third-party application 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 Helix ALM 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.
311
Viewing users
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 Helix ALM License Server options, page 327.
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 312.
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
Edit users to update contact information, change security settings, and assign licenses. You may also be able
to change usernames based on license server settings. See the license server help for information.
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 to the information.
Multiple users can have the same first and last names. Make sure to enter additional contact information
to distinguish between these users in Helix ALM applications.
You cannot edit any information on the Info and Address tabs for LDAP users in Surround SCM. This
information is managed in the corresponding LDAP or Active Directory server.
312
Tab
Use to:
Info
Enter the user's phone numbers and email address and create a password. You can enter
up to 128 characters for the password. Users can change their passwords when they log in
unless password restrictions are set on the Helix ALM License Server. See the license
server help for information.
Deleting users
Tab
Use to:
Groups
Add the user to a security group. Users can only access commands added to the group they
belong to and must be assigned to at least one group. See Adding security groups, page 302
for information about creating groups.
License
Assign a license to the user. Users cannot log in if a license is not assigned to them. See
License types, page 311.
Address
Enter the user's address.
Notes
Enter any notes about the user.
Note: Users with usernames and passwords longer than 32 characters cannot use Surround SCM or
TestTrack 2016.0 and earlier.
4. Click OK to save the changes.
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.
2. Click Close when you finish.
313
Voiding check out
Voiding check out
Surround SCM users with admin-level security access can void check outs. This removes the lock on a file
and gives other users access to it. Changes users made to the file are not saved.
1. Choose Tools > Administration > Void Check Out.
The Void Check Out dialog box opens.
2. Select a user from the Users list. The Checked out files list shows the user’s checked out files.
3. Select the files and click Void Check Out.
You are prompted to confirm the void.
4. Click Yes.
The check outs are voided.
5. Click Close when you finish.
314
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.
Some server options can be overridden for specific mainline branches. See Overriding server options for
specific mainline branches, page 398.
Tip: See the Security Best Practices for recommendations about properly managing and securing the
Surround SCM Server and Helix ALM License Server.
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
317
Merge
Switch from Diff3 to Guiffy for automatic file merges and
configure Guiffy options.
Setting
server merge
options, page
322
Server Database
Change the server database location or convert it to a different
RDBMS type.
Setting the
default server
database
location,
page 409
RDBMS Connections
Create and modify RDBMS connections to host mainline
branches.
Adding
RDBMS
connections,
page 413
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
392
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
324
315
Configuring the Surround SCM Server
Options
Use to:
More
information
Email Servers
Specify protocol and connection information used to email
notifications.
Setting email
server
options, page
325
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
326
License Server
Configure license server connection information, the license
server communications password, and global user cache refresh
rate.
Setting Helix
ALM License
Server
options, page
327
Update Check
Check for and download software updates.
Checking for
new
Surround
SCM
versions,
page 329
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
328
Helix ALM Integration
Enable Helix ALM integration and edit or sync item field labels.
Enabling
Helix ALM
integration,
page 429
Issue Tracking
Integration
Activate plug-ins to integrate with a third-party issue tracking tool.
Activating
third-party
issue
tracking plugins, page 324
Purge Scheduling
Schedule when to purge destroyed data from the database.
Scheduling
data purges,
page 330
316
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
331
Comments
Set minimum lengths for comments entered by users when
performing specific actions, such as check ins.
Setting
minimum
comment
lengths for
actions, page
335
Changelists
Set default changelist usage for all mainline branches.
Setting
changelist
server
options, page
334
File
Names/Extensions
Specify filenames or extensions to auto-detect or ignore when
adding files.
Setting autodetect and
ignore file
options, page
335
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
337
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 server. You can use RSA key exchange
for stronger encryption keys if your network is potentially insecure or if users log in from outside of your
network. See Securing communication between clients and the Surround SCM Server, page 319 for
information about encryption, authentication, and key exchange methods used.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens with the General category selected.
317
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 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.
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 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
server.
Tip: Always use encryption to keep data secure unless you are evaluating Surround SCM or
troubleshooting performance issues.
The OpenSSL version used 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 the knowledgebase or contact Perforce Support for information.
7. Select Use RSA key exchange to use strong key exchange for communication between clients and the
server.
318
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 server. See Configuring RSA key exchange, page 321 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, 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 client users need to import in
the server connection settings. If you use Surround SCM
Web or proxy servers, import the file in the 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 registry utility.
See Configuring RSA key exchange, page 321 for information about adding and removing keys in 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 317 for
information about configuring secure client/server communication.
Encryption
Encryption scrambles data to prevent interception, or eavesdropping, as it passes between clients and the
server. Surround SCM uses the OpenSSL implementation of Advanced Encryption Standard-256 (AES-256)
to encrypt communication between clients and servers in Surround SCM 2014.1 and later. RC4 encryption is
used for backward compatibility with earlier Surround SCM and Helix ALM 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 317.
319
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 registry
utility. See the Registry Utility help for information.
Authentication
Authentication is the process of logging in a user. The following authentication methods are used.
Authentication
method
How it works
Helix ALM
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.
Key
exchange
method
When it is
used
How it works
To use it:
Secure
Remote
Password
(SRP)
User is
authenticated
from the
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.
320
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 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 using LDAP, single sign-on, or external authentication.
Using RSA requires additional setup for users. See Configuring RSA key exchange, page 321.
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 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 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.
321
Setting server merge options
A public key is generated on the 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 server computer. To keep these key files secure, make sure only the
user that runs the server has read and modify access to them.
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 clients and server settings in the registry
utility for web and proxy servers.
3. Click Download Public Key to save an XML file that contains the server address, port number, and
public key fingerprint.
This file must be distributed to users so they can import it to clients that connect to the server. Make sure
the file is securely stored and only administrative users have access to modify it. If a hacker has
unauthorized access to the file, changes it, and it is imported to clients, your installation could be hacked.
Note: The server address in the XML file includes the default hostname of the 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 clients that connect to the server.
n
Desktop 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
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 CLI help for information.
n
Web client—Import the server settings file in the web server options in the registry utility so users can
log in. See the Registry Utility help for information.
n
Proxy server—Import the server settings file in the proxy server options in the registry utility so users
can connect to the server. See the Registry Utility help for information.
Tip: If you suspect the private key on the server was compromised because of unauthorized 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.
322
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.
323
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 290.
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 Helix ALM integration.
4. Click OK to save the changes.
The changes do not take effect until after Surround SCM 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 290.
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 server is running.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Logging from the Global Server Options category.
324
Setting email server options
3. Select a Write to server database option to indicate the types of messages written to the 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 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.
325
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.
326
Setting Helix ALM 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 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 Helix ALM 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.
327
Setting automatic software update check options
3. Enter the address and port number of the Helix ALM License Server to connect Surround SCM to.
4. Optionally enter a License server communications password.
This password provides additional security and prevents unauthorized Surround SCM or Helix ALM users
from using the licenses.
Note: If a communications password is set on the license server, Surround SCM must use the same
communications password.
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 Perforce update server, which returns update information.
n
Unique user ID—A unique ID, generated by the Surround SCM Server, used to identify each server. It
does not include any information that identifies your company or users.
n
Surround SCM version—The server version installed.
n
Operating system and version—The operating system and version of the computer hosting the server,
including if it is 32-bit or 64-bit.
n
Client connections—The timestamps when clients connect to the server. This information also includes
the client type, the browser used if the client is Surround SCM Web, and the client operating system.
n
Licenses—The number of Surround SCM licenses on the Helix ALM License Server and if they are
evaluation licenses.
328
Checking for new Surround SCM versions
n
Number of mainlines per RDBMS database type—The number of mainline branches in each RDBMS
database type.
n
Configuration settings—Specifies if the following settings are configured: inactive branches, cached
branches, indexed branches, triggers, changelists, comments required, SMTP, custom fields, workflows,
shadow folders, Helix ALM integration, reports, filters, code reviews, RSA, shelves, labels, bookmarks,
and proxy server.
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 release notes. If this option is
selected, the release options are also enabled. Select the type of releases 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.
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.
329
Scheduling data purges
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 Perforce. 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 Perforce’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.
330
Setting general mainline options
3. Select a purge scheduling option.
n
Automatically purge destroyed data purges data automatically when the 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 398.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select General from the Mainline Options category.
331
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 333.
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.
332
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
333
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 135. 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 398.
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.
334
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 398.
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 when users recursively add files.
Note: These options apply to all branches and users, but can be overridden for specific mainline
branches. See Overriding server options for specific mainline branches, page 398.
335
Setting auto-detect and ignore file options
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 to ignore in the Ignore file extension field.
7. Enter the file or directory names to ignore in the Ignore file or directory name field.
336
Setting compliance options
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 39. 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.
A signature meaning that indicates review, approval, responsibility, or authoring of files is required for Title
21 CFR Part 11 compliance.
337
Configuring default user options
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 default 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 can change user options. If you do not want to allow changes, you can require using the
default options.
1. Choose Tools > Administration > Default User Options.
The Default User Options dialog box opens.
2. Select the category to set default user options for.
338
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
Configuring default user options
Category
Use to:
More
information
Diff/Merge
Specify applications to diff and merge files and add new diff applications.
Setting
diff/merge
options,
page 53
Application
Settings
Configure diff/merge settings for Guiffy (integrated diff/merge
application), Microsoft Word, and code reviews.
Configuring
diff/merge
application
settings,
page 57
View/Edit
File
Specify applications to view and edit files from Surround SCM.
Setting file
viewer and
editor
options,
page 19
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 107
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 103
Proxy
Server
Set the default proxy server and compress file transfers from servers.
Setting
proxy server
options,
page 447
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 288
3. Select an option to specify how to apply the default options.
339
Generating support diagnostic reports
n
<no default> does not set any default options.
n
Default sets the options as the default for new clients that connect to the server, but users can
change the settings at any time.
n
Required sets the options in all clients that connect to the server and users cannot change the
settings.
Note: Options set as Required are changed in clients for existing users. Options set as Default for
existing users are not changed.
4. Make any changes to the default options.
5. Click OK to save the changes.
The default user options are set in clients when they connect to the server for the first time.
Generating support diagnostic reports
If you are experiencing Surround SCM problems and need help from Perforce Support, you can generate a
report that includes detailed information about the server configuration. You can then email the report to
Perforce Support to provide information for troubleshooting the issues.
1. Choose Help > Generate Support File.
The Save Support Information File As dialog box opens.
2. Choose a location to save the file in and enter a File name.
The default filename is supportinfo.zip.
3. Click Save.
The file is saved.
340
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 345.
n
Create a Release custom field to track the release a change is assigned to.
Note: See Setting custom fields, page 36 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 301.
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 342.
3. Select a field and click Edit to edit it. See Editing custom fields, page 343.
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 343.
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 343.
341
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 345.
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 or triggers run that sets fields to the default value.
Note: Date/Time field default values use the current date and time from the Surround SCM Server.
7. Click OK to save the custom field.
342
Editing custom fields
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 85 and Customizing the Source
Tree window, page 102.
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.
343
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
345
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 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 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 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.
346
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 347.
4. Select a trigger and click Edit to change it. See Editing triggers, page 357.
5. Select a trigger and click Duplicate to duplicate it. See Duplicating triggers, page 359.
6. Select a trigger and click Disable to disable it. See Disabling and enabling triggers, page 359.
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 359.
8. Click Close when you finish.
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.
347
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
348
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 221.
349
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 357.
n
Select an action and click Edit to change it. See Editing trigger actions, page 358.
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 358.
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
You can run scripts and compiled programs from pre- and post-event triggers. Surround SCM accepts any
command line call.
The executable must be located on the Surround SCM Server computer. The administrator needs to make
sure the executable has appropriate directory access permissions and the same run privileges as the server.
If the executable is not found when the trigger runs, an error is returned to Surround SCM and the event does
not complete. If multiple triggers are associated with a file and one trigger fails, the remaining triggers do not
run.
Note: Use environment variables in scripts and programs to retrieve data about the file that caused a
trigger to run and pass data back to the executable. See Environment Variables, page 471.
Pre-event triggers
Pre-event triggers can run server scripts that perform additional checks on files before an event completes.
For example, you can create scripts to verify that text is included in specific files before they are checked in.
350
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 one second pre-event script will
significantly slow down the server because it takes an additional second per file that the trigger runs on.
Scripts that run from pre-event triggers must return a value that tells the server if an event should be allowed to
complete. A return value of zero indicates the event can continue. A non-zero return value indicates the event
should be not be performed. If a non-zero value is returned, any messages output by the executable (output to
stdout) are sent back to Surround SCM with the error. The error is truncated to 1024 characters.
Following are some examples of how to return a value from an executable:
n
C program—Specify the value in the return( ) statement in the main( ) routine. You can also use a
parameter in the exit statement.
n
Windows/DOS batch file—Set the ERRORLEVEL value. In Windows 2000/XP batch scripts the
command “exit /B #” can be used.
n
Windows application—Use the CWinApp::ExitInstance( ) function.
Post-event triggers
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 Surround SCM file
activity, to synchronize two separate servers, or start your build process on a server computer.
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 347.
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.
351
Adding triggers to prevent events
Adding triggers to prevent events
You can add a trigger action that prevents users from performing file events and displays a message to inform
them why they cannot perform the event. For example, you can prevent users from checking out files in
specific workflow states.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens.
2. Click Add.
The Add Trigger dialog box opens.
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 347.
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.
352
Adding triggers to email users
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 347.
4. Click the Actions tab and click Add to add an action.
5. Select [Set | Append] event’s comment with [text] from the Action field.
6. Select how to add the comment.
n
Set replaces any user comments with the text you enter in the Comment field.
n
Append adds the Comment field text to any comments the user enters.
7. Enter the Comment.
8. Select Disable trigger after it runs once if you only want the trigger to run once.
9. Click OK to add the trigger.
Adding triggers to email users
You can add a trigger action to send an email. For example, you can email users when a file is assigned to
them.
1. Choose Tools > Administration > Triggers.
The Triggers dialog box opens.
2. Click Add.
The Add Trigger dialog box opens.
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 347.
4. Click the Actions tab and click Add to add an action.
5. Select Send an email to from the Action list.
353
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 354.
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 471.
1. Click Edit Email Template when you are adding or editing a trigger or notification. See Adding trigger
actions, page 357 and Adding email notifications, page 95.
The Edit Email Template dialog box opens with the Email Template tab selected.
354
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 325.
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.
355
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 347.
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.
356
Editing triggers
3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding
triggers, page 347.
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.
357
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.
358
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
359.
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.
359
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 356 and Changing workflow states,
page 38. 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 374.
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.
361
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.
362
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:
363
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:
364
Planning your workflow
n
Planning your workflow, page 365
n
Configuring workflow states, page 365
n
Configuring workflow templates, page 368
n
Automating workflows, page 365
n
Setting workflows for specific repositories, page 374
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 345.
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 341.
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 368.
1. Choose Tools > Administration > Workflow.
The Workflow dialog box opens with the States tab selected.
365
Adding workflow states
2. Click Add to create a new state. See Adding workflow states, page 366.
3. Select a state and click Edit to change it. See Editing workflow states, page 367.
4. Select a state and click Delete to delete it. See Deleting workflow states, page 367.
Note: Select Show deleted states to display deleted states. Deleted states can be restored. See
Restoring deleted workflow states, page 368.
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.
366
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 337.
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 370.
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 372.
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 368.
1. Choose Tools > Administration > Workflow.
367
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.
The default workflow template is named General Workflow and 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 363. 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.
368
Adding workflow templates
3. Click Add to add a template. See Adding workflow templates, page 369.
4. Select a template and click Edit to change it. See Editing workflow templates, page 372.
5. Select a template and click Duplicate to duplicate it. See Duplicating workflow templates, page 372.
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 372.
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 370.
6. Select a state and click Edit to change it. See Editing workflow states, page 367.
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 371.
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.
369
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 373.
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 132.
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 366.
n
Select Add existing states to add an existing state to the workflow template. All defined states 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.
370
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 368.
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.
371
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 367.
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 372.
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.
372
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.
373
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 38.
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 38.
374
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 63. 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.
375
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.
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 177.
2. Click Add to create a shadow folder. See Adding shadow folders, page 378.
3. Select a folder and click Edit to change it. See Editing shadow folders, page 379.
4. Select a folder and click Force Update to update it. See Refreshing shadow folder contents, page 379.
5. Select a folder and click Delete to delete it. See Deleting shadow folders, page 379.
6. Click Close when you finish.
377
Adding shadow folders
Note: You can also use triggers to perform the same functionality as shadow folders, but triggers are more
complicated to use. For a trigger to update files on a network share, you must create a script using the CLI
or a programming language. Shadow folders automatically update files regardless of any action performed
on them, but triggers run based on actions. You must select the action to perform when you create a
trigger. For example, you could create a trigger that updates files on a network share when a changelist is
committed.
Adding shadow folders
When shadow folders are created, Surround SCM assumes it can add, override, and delete files. You must
create an empty directory before you add a shadow folder. Creating an empty directory protects against files
being overwritten and security issues, such as hackers.
1. Choose Tools > Administration > Shadow Folders.
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.
378
Editing shadow folders
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.
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.
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.
379
Deleting shadow folders
The shadow folder is deleted.
380
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 177.
381
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.
382
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 388
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 389
Toggle
Caching
Change the branch caching mode. By default, all file and repository
information for a branch is cached when the 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 391
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 388
Change
Type
Change the branch type or owner.
Changing
branch type,
page 391
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 389
Remove
Remove the branch. Removed branches are not deleted from the hard
drive and can be restored if needed.
Removing
branches,
page 393
Destroy
Permanently delete a removed branch. Destroyed branches are deleted
from the hard drive and cannot be restored.
Deleting
branches
permanently,
page 394
Restore
Restore a removed branch.
Restoring
removed
branches,
page 394
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 384.
7. Click Close when you finish.
383
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 server starts.
See Differences between indexed and non-indexed searches, page 236 for information about how indexed
versus non-indexed searches work.
The 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 385.
n
Start the indexing server if it is not running to enable indexed searching. See Managing the indexing server,
page 384.
n
View indexing status and information. See Viewing branch index details, page 386.
n
View the indexing server log to troubleshoot issues with corrupted indexes. See Viewing the indexing
server log, page 387.
n
Modify the indexing server startup options. See the 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.
384
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 385.
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 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 387.
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 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.
385
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.
386
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 385. 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 387.
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.
387
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 398.
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.
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.
388
Inactivating and activating branches
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 388.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
Tip: You can also choose Branch > Branch Attributes > Active to inactivate a branch.
2. Select a branch to inactivate or activate and click Toggle Active.
If the selected branch is active, you are prompted to confirm 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.
389
Modifying templates for existing branches
2. Click the Template tab and then click Modify.
3. Select a Template option.
n
To remove the template from the branch, select Do not use template. The Repositories preview is
updated and displays the root repository that will be used for the branch. If multiple subrepositories
were included in the template, the virtual root repository is used as the root repository for the updated
branch. Continue with step 5.
n
To change the repositories included in the branch, select Use template to define repositories in the
branch.
4. If you chose to use a template, select the Repositories to include in the branch. Only repositories
available in the parent branch are displayed.
n
To exclude a subrepository from the branch, select it and click Exclude. To include an excluded
subrepository, select it and click Include.
n
To remove a repository from the current template, select it and click Remove.
5. Click OK to save the changes.
The branch template is updated.
n
390
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
Changing branch type
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 201.
n
If you removed or excluded repositories, you are prompted to destroy them. Click Destroy to
permanently delete the repositories. All files in the repositories and historical information are destroyed
and cannot be restored.
Changing branch type
You can change the workspace branch owner or convert workspace branches to baseline branches. For
example, a developer starts working on a feature in her workspace branch but realizes it will require more time
to complete than originally planned. In this case, you can change the user’s workspace branch to a baseline
branch so other developers can access the code or change the branch owner so another user can complete
the work.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
2. Select a workspace branch and click Change Type.
The Change Branch Type dialog box opens.
3. Select a Branch Type to change the workspace branch to a baseline branch.
4. Select a New Owner to change the workspace branch owner.
5. Enter the New Branch Name.
6. Enter any Comments, such as the reason for changing the branch type.
7. Click OK to save the changes.
8. Click Close to close the Branch Maintenance dialog box.
Changing branch caching
Branches are cached when the Surround SCM Server starts. You can change the caching mode to reduce
memory usage. Surround SCM includes the following caching modes:
391
Setting branch caching server options
n
Always—Branches are cached when the 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 server starts based on the server options.
See Setting branch caching server options, page 392.
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.
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 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 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 391.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Caching from the Global Server Options category.
392
Removing branches
3. Enter the Minimum dynamic branches to cache to indicate the minimum number of dynamic branches
per mainline branch to cache during server startup and to maintain in the cache.
This setting applies to each mainline branch. For example, if the server includes 10 mainline branches
that each include 10 branches and the minimum branches to cache setting is 10, the cache always stores
100 branches. The default 10 branches.
4. Enter the Inactivity timeout to indicate the number of minutes to leave a dynamic branch in the cache
without activity before it is unloaded.
A branch is considered inactive if no read or write activities that require the branch to be loaded in the
cache are performed in the specified number of minutes. Inactive dynamic branches, excluding the most
recently used branches, are automatically unloaded from the cache. The default is 60 minutes.
5. Enter the Maximum dynamic branches to cache to indicate the maximum number of dynamic
branches per mainline to cache.
If this limit is exceeded, inactive dynamic branches, excluding the most recently used branches, that
have not yet reached the inactivity timeout are unloaded until the minimum number of branches to cache
is reached. The default is 100 branches.
6. Select Force branch to cache on demand after inactivity timeout to automatically change unused
branches set to Always Cache to Cache on Demand after the specified number of days.
An informational message is added to the server log if a branch is forced to Cache on Demand. The
default is 120 days.
7. Click OK to save the changes.
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 394.
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 385.
Note: To limit access to a branch, you can freeze, hide, or inactivate it instead of removing it. See
Managing branch attributes, page 381.
1. Select the branch and choose Branch > Remove Branch.
The Remove Branch dialog box opens.
393
Restoring removed branches
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 381.
Restoring removed branches
You can restore removed branches to give users access to them again.
Note: If you restore a branch that was indexed for searching before it was removed, you must manually
turn on indexing for the branch to reindex it. See Turning branch indexing on or off, page 385.
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 393.
1. Choose Tools > Administration > Branch Maintenance.
The Branch Maintenance dialog box opens.
2. Select a branch and click Destroy.
394
Deleting branches permanently
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.
395
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 413 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.
397
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 173.
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 388.
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 315.
1. Select the mainline branch and choose Branch > Branch Properties.
The Properties dialog box opens.
2. Click the Options tab.
398
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 331
Comments
Minimum character lengths for comments entered by users when
performing specific actions, such as check ins.
Setting
minimum
comment
lengths for
actions,
page 335
399
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 334
Files
Names/Extensions
File type extensions and names to automatically detect and
ignore when adding files.
Setting autodetect and
ignore file
options,
page 335
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 337
4. Select Override for the options to override and make any changes.
Select Inherit to use the mainline options set on the 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.
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 307
and Overriding server options for specific mainline branches, page 398.
1. Choose Tools > Administration > Export Repository to Mainline.
400
Moving repositories to different mainline branches
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 413 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 124.
Tip: Remember to inform users about new repository location.
401
Moving mainline branches to different databases or servers
Moving mainline branches to different databases or servers
By default, the Surround SCM Server database and all mainline branches are stored in one RDBMS database.
You can convert mainline branches to store them in a different RDBMS database, distribute them across
multiple RDBMS databases, or move them to a different Surround SCM Server.
Note: When you convert the server database or mainline branches, the data is copied from the current
RDBMS database to the destination database. The data is not deleted from the original database.
Following are common scenarios for changing database configurations for mainline branches.
Converting mainline branches stored with the server database to a new
RDBMS database
You may decide to switch to a different RDBMS type or host mainlines and the server database in a different
RDBMS database. To do this, you need to convert the server database, which copies all the server database
and mainline branches to a different RDBMS database.
To copy the mainline branches and server database to the new RDBMS database:
1. Convert the server database. See Converting the server database to a different type, page 410.
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 407.
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 389.
2. Convert the mainline branch to copy it to the other database. See Copying mainline branches to different
databases, page 403.
3. Activate the mainline branch. See Inactivating and activating branches, page 389.
4. Optionally destroy the mainline branch from the original RDBMS database. See Deleting mainline
branches permanently, page 407.
5. Repeat steps 1 - 4 for each mainline branch to copy to the new RDBMS database.
Converting a mainline branch to a different server
Some organizations use multiple Surround SCM Servers for load balancing reasons or to support
geographically-dispersed teams. Only one server can connect to an RDBMS database at a time. To host a
mainline branch on a different server, copy the mainline to an empty RDBMS database that is not connected
to a server, remove it from the source server, and then add it to the destination server.
To copy a mainline branch to a different server:
402
Copying mainline branches to different databases
1. Inactivate the mainline branch to move. See Inactivating and activating branches, page 389.
2. Convert the mainline branch to move it to the different RDBMS database. See Copying mainline branches
to different databases, page 403.
3. Remove the mainline branch from the current server. See Removing mainline branches, page 404.
4. Log in to the destination server.
5. Add the mainline branch to the destination server. See Restoring removed branches, page 394.
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 407.
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 389.
1. Choose Tools > Administration > Convert Mainline Branch.
The Mainline Destination dialog box opens.
2. Select a database Destination.
The list includes RDBMS connections configured for the server. Select the connection for the database to
store the mainline branch in. See Adding RDBMS connections, page 413 if you need to add an RDBMS
connection.
3. Select Ignore errors during upgrade to allow processing to continue even if errors occur.
Note: Only select this option if you have already used the analyze utility and were unable to repair
issues causing errors.
403
Removing mainline branches
4. Click OK.
The conversion information is sent to the 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 database tables, page 409.
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 389.
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.
404
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 405.
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 406.
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 406.
1. Choose Tools > Administration > Add Existing Mainline Branch.
The Add Existing Mainline Branch dialog box opens.
2. Select RDBMS as the Mainline Type.
405
Restoring non-RDBMS mainline branches
3. Select the Location where the mainline branch is stored.
The list includes RDBMS connections configured for the 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 405.
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.
406
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 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 433.
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 404.
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.
407
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 maintenance contract does not include support for recovering
from these types of database changes.
Tip: See the Security Best Practices for recommendations about keeping databases secure.
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 database format and the
rules enforced at the software level.
Database table changes
Do not reconfigure the 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.
Live updates
Surround SCM caches data to improve performance. Do not perform live updates at the database level unless
the Surround SCM Server has been shut down. Adding, editing, or deleting 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 cache.
Surround SCM does not prevent users from opening the database in read/write mode while the server is
running. To perform live data updates, use methods available in the desktop or CLI client.
Note: You can lock databases to prevent users from performing actions that write to the database, such
as checking out files. See Locking databases for backups, page 416.
Creating Surround SCM database 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 automatically create them. 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 410, Copying mainline
branches to different databases, page 403, and Upgrading mainline branches, page 433.
The table creation scripts are stored in the Oracle, PostgreSQL, and SQLServer directories in the Surround
SCM Server application directory. DBAs can refer to these scripts when editing database attributes. See the
installation help for information.
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.
409
Converting the server 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 server database type, name, and username are displayed.
3. Click Change to change the database location. See Changing the server database location, page 412.
4. Click Convert to convert the database to a different type. See Converting the server database to a
different type, page 410.
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. See Creating Surround SCM database tables, page 409.
1. Make sure you are logged in to the server to convert the database for.
2. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
3. Select Server Database from the General Server Options category.
4. Click Convert.
The Surround SCM Server Database Connection dialog box opens.
410
Converting the server database to a different type
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 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 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 server to before users can access files.
Note: You can also manually change the database the server is using. See Changing the server
database location, page 412.
411
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 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:
412
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
database tables, page 409.
11. You return to the Server Database category. Click OK to apply the changes.
Note: You must stop and restart the 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.
413
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
Oracle—Enter the Service Name of the host to connect to, Port, and Username and Password.
n
ODBC-SQL Server—Select the Data Source Name (DSN). Only ODBC System DSNs are
supported. Enter the SQL Server Username and Password. If the DSN is configured to use 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.
Note: If you use SQL Server, each database used to host Surround SCM data must have a unique
DSN. See Creating DSNs for SQL Server Databases.
6. Enter the Minimum number of connections to specify the smallest number of connections to cache in
the database connection pool. The default value is 1.
When the 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 cache 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.
414
Editing RDBMS connections
You can now add new mainline branches to the database or copy existing mainlines to it. See Creating
mainline branches, page 397 and Copying mainline branches to different databases, page 403. 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 409.
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 389.
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 412 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 389.
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 2009 and Later Databases for information about backing up PostgreSQL databases on the
Surround SCM Server computer using the pgAdmin tool.
415
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 desktop client, CLI, or analyze utility.
n
Desktop client—Use to analyze and repair active database connections on the server you are connected
to. See Analyzing and repairing databases, page 418.
n
CLI—Use the analyzedb command from a command line to analyze and repair active database
connections on the server you are connected to. See the CLI help for information.
n
Analyze utility—Use to analyze RDBMS databases not in use by a server and clear database server
associations. You can also analyze and repair databases for active connections as you can in the desktop
client or CLI. See the Analyze Utility help for information.
Setting database analyze and repair options
You can specify the types of issues to check for and repair when analyzing databases.
1. Choose Tools > Administration > Analyze/Repair Database.
416
Setting database analyze and repair options
The Analyze Database dialog box opens.
2. Click Options.
The Analyze and Repair Options dialog box opens.
3. Select Perform CHECKDB (SQL Server only) to verify the integrity of database objects in SQL Server.
This option runs the SQL Server CHECKDB command when analyzing databases and returns a list of
errors found. A DBA must manually repair the issues. Refer to the SQL Server help for information.
4. Select any Analyze and Repair options to check for specific repairable issues. See Repairs for common
database issues, page 420 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 missing
check out computer
Checked out files missing a check out computer name.
417
Analyzing and repairing databases
Option
Checks for:
Check for orphaned
changelists
Pending changelists created by deleted users.
Check for undestroyed
repositories
Undestroyed child repositories with destroyed parent repositories or
undestroyed repositories in destroyed branches.
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 for orphaned
filters
Filters with deleted users as the owners.
Check for mismarked
revision records
File revision records that were incorrectly marked as destroyed.
Check if VACUUM is
needed
PostgreSQL vacuum needed to remove dead table rows to free up database
space and improve performance. PostgreSQL only.
Note: Click Select All to select all options or click Select None to clear any selected options.
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 Analyze Utility help for information.
418
Analyzing and repairing databases
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.
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 416.
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 415.
Note: To cancel an analysis or repair in progress, click Cancel Processing.
419
Repairs for common database issues
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 420 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.
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)
Missing check out computer
Replaces the empty check out computer field with '<unknown>'
Orphaned check outs (files
checked out by deleted users)
Removes the check outs
Orphaned changelists (pending
changelists created by deleted
users)
Removes the changelists
Orphaned public filters (owner is
deleted user)
Changes the filter owner to the user with the lowest record ID in the
database, which is typically the default Administrator user unless
deleted
Orphaned private filters (owner is
deleted user)
Removes the filters
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
420
Repairs for common database issues
Database issue
Repair
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
Mismarked file revision records
Removes the flag that indicates the records should be destroyed
Vacuum needed (PostgreSQL
only)
Vacuums tables requiring it
421
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 424.
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.
423
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.
424
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.
425
Deleting mail
The Mail Queue dialog box opens.
2. Select the emails to delete.
3. Click Delete.
The email is deleted from the mail queue.
426
Managing Auditable Processes
When properly implemented and managed, Surround SCM can strengthen most best practices and regulatory
compliance processes. You can use the following 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 88.
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
86.
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 254. 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 79.
Electronic signatures and audit trail reports
You can configure a 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 361.
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 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 366 and Editing
workflow states, page 367.
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 337. You can also override compliance options for specific mainline branches if needed. See
Overriding server options for specific mainline branches, page 398.
3. Users responsible for signing off on files set states on files and enter electronic signatures. See Entering
electronic signatures, page 39.
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 250.
427
Configuring Helix ALM Integration
Before users can attach source files to Helix ALM items, a Surround SCM administrator must enable the
integration on the Surround SCM Server. You can also set additional integration settings to customize Helix
ALM field labels or sync them with the field labels used in the Helix ALM project.
Enabling Helix ALM integration
You can rename issue, requirement, and test case field labels in Surround SCM after you enable the Helix
ALM integration.
1. Choose Tools > Administration > Server Options.
The Server Options dialog box opens.
2. Select Helix ALM Integration from the Global Server Options category.
3. Select Enable Helix ALM integration to enable the integration between Surround SCM and Helix ALM.
4. Select a Helix ALM 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 Helix ALM to synchronize the field label values with labels in a specified Helix ALM
project. See Syncing field labels with Helix ALM, page 430.
6. Click Restore Default Values to replace all renamed field labels with the default values.
7. Click OK to save the changes.
429
Syncing field labels with Helix ALM
Syncing field labels with Helix ALM
If users will attach files to items in a Helix ALM project that uses renamed field labels, you can sync the field
labels with the project for consistency.
Syncing field labels eliminates the need to manually rename individual Helix ALM field labels. However, if the
field label values change in the 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 Helix ALM Integration from the General Server Options category.
3. Click Sync with Helix ALM.
The Sync with Helix ALM Project dialog box opens.
4. Enter the Helix ALM 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 Helix ALM integration options for repositories
You can configure Helix ALM 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 Helix ALM when checking in or adding files.
1. Select a repository and choose Activities > Properties.
The Properties dialog box opens.
2. Click the Helix ALM Integration tab.
430
Setting Helix ALM integration options for repositories
3. Select Configure repository settings to set Helix ALM 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 Helix ALM 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 Helix ALM items when checking in or adding files to
the repository.
7. Click OK to save the changes.
431
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 434.
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 433.
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 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 Helix ALM 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 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 437.
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'.
1. Select the mainline branch to upgrade and choose Tools > Administration > Upgrade Mainline
Branch.
The Upgrade RDBMS Mainline dialog box opens.
433
Upgrading non-RDBMS mainline branches
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 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.
You are prompted to upgrade the mainline branch.
2. Click Yes.
The Mainline Destination dialog box opens.
434
Resolving custom field and workflow issues
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 413.
4. Select Ignore errors during upgrade to continue the upgrade even if errors occur.
Only select this option if you have already used the analyze utility to identify any data integrity issues in
the database and could not repair issues causing errors.
5. Click OK.
The upgrade information is sent to the 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 database tables, page 409.
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 server.
1. Choose Tools > Administration > Resolve Custom Fields/Workflow.
The Resolve Custom Fields/Workflow dialog box opens with the Custom Fields tab selected.
435
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 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 server.
n
Select a state and click Delete to delete it.
4. Click the Workflow tab to resolve any workflow template issues.
436
n
Select a template and click Add to Server to add it to the server.
n
Select a template and click Delete to delete it.
Upgrading RDBMS connections
Note: A workflow template can only be added to the 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 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.
437
Upgrading legacy labels
Labels created in earlier 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 153.
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.
438
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 439.
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.
439
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 Surround SCM
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. See How proxy servers work, page 442.
The tasks to configure proxy servers depend on your role.
Administrators
An administrative user must perform the following tasks to configure a proxy server before users can access
it.
Tip: We recommend following these steps in order for installing and configuring a proxy server. If the
proxy server application is already installed and you add the connection information to Surround SCM, use
the registry utility to configure the proxy server settings. The server name, password, and port number
must match between the registry utility and Surround SCM. See the registry utility help for information
about editing proxy server options.
1. Add a proxy server connection to the master Surround SCM Server
Specify the proxy name, address, port, password, users who can access it, and other options. See
Adding proxy servers, page 444.
2. Install the proxy server application
Install the application on a computer at the remote location where the clients using the proxy server
reside. Run the Surround SCM installer and only install the Surround SCM Proxy Server application. See
the installation help for information.
3. Configure the proxy server information in the registry utility
The proxy server information in the registry utility must match the information configured on the master
server. See the registry utility help for information about editing proxy server options.
4. Start the proxy server
See Starting the Surround SCM Proxy Server, page 443.
Tip: See the Proxy Server Best Practices for recommendations about properly configuring and using
proxy servers.
Users
If your team uses a proxy server, your administrator can help you connect to it. You may be able to set options
to specify the proxy server to use and to compress files. See Setting proxy server options, page 447.
441
How proxy servers work
How proxy servers work
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. Performance
improvements are noticeable only after files are cached.
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. If the proxy
server is not available, clients retrieve files directly from the master server.
Files are cached in the SCMProxyCache directory in the proxy server application directory. 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.
Proxy server maintenance is minimal. Proxy servers do not require backups or extra monitoring when a cache
age limit option is set.
Example
For example, your organization’s master Surround SCM Server is located in North America, but Europeanbased development teams need to perform a get when a new branch is created. Without a proxy server, each
user gets the files from the master server, which impacts bandwidth, 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
master server.
442
Starting the Surround SCM Proxy Server
Master server and proxy server communication
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 clients (GUI clients and the CLI) and connects to the master server to
get files. The proxy server needs the same connection information that 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. Each Surround SCM Server can support multiple proxy servers.
The proxy server only handles get actions. Check in actions and file metadata are managed by the master
server to ensure that file versions and metadata information is always current. The master server also handles
security and licensing.
Each proxy server can only use one master server.
Before a proxy server can connect to a master server, you must configure the master server to accept proxy
requests.
n
Configure proxy server settings that the master server needs using Surround SCM. See Adding proxy
servers, page 444.
n
Modify proxy server computer options as needed using the registry utility. See the 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.
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 > Perforce > 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 server data, you must configure it to accept connections from known proxy
servers before attempting to use the proxy server. Installing and configuring the proxy server requires
information about both server computers, and you must set configuration options on both computers.
443
Adding proxy servers
Note: We recommend adding a proxy server to the master server before installing the proxy server
application. If the proxy server application is already installed and you add the connection information to
Surround SCM, use the registry utility to configure the proxy server settings. The server name, password,
and port number must match between the registry utility and Surround SCM. See the registry utility help
for information about editing proxy server options.
1. Choose Tools > Administration > Proxy Maintenance.
The Proxy Server Maintenance dialog box opens.
2. Select a proxy server to view the configuration information.
3. Click Add to add a proxy server. See Adding proxy servers, page 444.
4. Select a proxy server and click Edit to modify it. See Editing proxy server settings, page 447.
5. Select a proxy server and click Delete to delete it. See Deleting proxy servers, page 447.
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.
444
Adding proxy servers
3. Enter a Proxy name.
Enter a unique name, such as the geographical location of the proxy server computer.
4. Enter and confirm the proxy server Password. The password authenticates the proxy server with the
master server. You must enter a password.
Note: Make sure the proxy name and password match the values set for the proxy server in the
registry utility. See the 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.
Clients connect to the proxy server on this port via TCP/IP. The default port number is 4901. Valid values
are 1-65535. Because the proxy is a client to the master server, this port does not need to be open on the
firewall to the master server. It only needs to be open on the firewall of the proxy server computer
(between the proxy and Surround SCM clients using it).
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.
445
Adding proxy servers
The proxy server periodically connects to the master server to check the proxy server settings. The
default interval is 0.5 hours. Valid values are 0.25-24 hours.
8. Enter the Minimum file size for cache to set the minimum size of files to be cached.
Files smaller than the specified size are not cached and are always retrieved from the master server. The
default size is 10 KB.
9. Select any additional options.
n
Maximum cache disk space sets the maximum amount of space the proxy server can use to the
specified limit. If the cache exceeds the maximum disk space, the least recently used files are deleted
from the cache.
n
Age limit sets the number of days to keep retrieved files in the proxy server cache.
n
Auto pre-cache recently requested files automatically checks for and retrieves newer file versions
from the master server based on the files in the proxy server cache. Select Every day to pre-cache
files every day at the specified time. Select Every refresh to pre-cache files when the proxy server
refreshes, which is set in the Refresh interval field.
Tip: An automatic pre-cache only evaluates the last 1,000 files in the cache. If you need to pre-cache
more than 1,000 files, use a batch file to get the files to a temporary or working directory. See the
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 447.
11. Click OK.
The proxy server is added.
Note: We recommend adding a proxy server to the master server before installing the proxy server
application. If the proxy server application is already installed and you add the connection information to
Surround SCM, use the registry utility to configure the proxy server settings. The server name, password,
and port number must match between the registry utility and Surround SCM. See the registry utility help
for information about editing proxy server options.
446
Editing proxy server settings
Editing proxy server settings
You can edit proxy server settings if the server location changes or you need to modify the configuration
options.
1. Choose Tools > Administration > Proxy Maintenance.
The Proxy Server Maintenance dialog box opens.
2. Select a proxy server and click Edit.
The Edit Proxy Server dialog box opens.
3. Make any changes. For information about proxy server options, see Adding proxy servers, page 444.
4. Enter the proxy server password in the Confirm password field.
You must confirm the 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 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 441.
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 server and cannot be changed.
1. Choose Tools > User Options then select the Proxy Server category.
447
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.
448
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 administrator must specify HTTP and HTTPS port numbers and the 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
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.
449
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 desktop 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, 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.
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.
451
Using the Java API
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 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.
Using the API on Mac
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, create a symlink called libsscmapi.jnilib that points to the native library.
452
Using the .NET API
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 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.
453
Surround SCM Best Practices
The following best practices are available to help you use Surround SCM more effectively.
n
Surround SCM Best Practices
n
Security Best Practices
n
Proxy Server Best Practices
455
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 299 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 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 desktop client apply to the command line interface
(CLI).
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
Microsoft
Office
Integration
Log in from Microsoft
Office
Login Via
API
Log in using the
Surround SCM API
Login Via
Web Client
Log in using the
Surround SCM Web
client
More information
Enables users to add the Surround SCM menu to Microsoft Word,
Excel, PowerPoint, Access, and Project
457
General security commands
Command
Provides access
to:
More information
Edit Helix
ALM
Integration
Tools > Helix ALM
Integration >
Connections
Enables users to configure connections to Helix ALM Servers and
projects. Helix ALM connections are available to all users, but a
Helix ALM username and password is required to access a project.
Add/Remove
Files from
Labels
Activities >
Advanced > Add
Label
Label field in the Add
Files dialog box
(Activities > Add
Files
Label field in the
Check In Files dialog
box (Activities >
Check In)
Add to Label button
in the History dialog
box (Activities >
History)
Remove button on
the Files tab in the
Edit Label dialog box
(Tools > Labels)
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)
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.
458
Admin security commands
Command
Provides access
to:
More information
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
Remove
Mainline Branch
Tools > Administration > Remove
Mainline Branch
Tools > Administration > Destroy
Removed Mainline
Rename
Mainline Branch
Tools > Administration > Rename
Mainline Branch
459
Admin security commands
Command
Provides access to:
Analyze
Database
Tools > Administration >
Analyze/Repair Database
More information
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)
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
460
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:
More information
Override
Workflow
Activities > Advanced > Change
State
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 Properties dialog
box (Activities > Properties)
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
Delete Labels
Delete button on the Labels dialog
box (Tools > Labels)
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.
461
Users security commands
Command
Provides access to:
More information
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.
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 Helix ALM
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)
462
Security Groups security commands
Command
Provides access to:
More information
Edit Own
Integration
Settings
Tools > Helix ALM Integration >
User Settings
Enables users to specify their Helix ALM 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 299.
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.
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)
463
Files security commands
Command
Provides access to:
Remove
File
Activities > Remove File
More information
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.
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)
464
Changing the file type changes it in all
branches.
Branch security commands
Command
Provides access to:
More information
View File
History
Activities > History
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
Requires the Add Files command.
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
Activities > Advanced > Bulk Custom
Field Changes
Change
State
Activities > Advanced > Change State
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 Properties dialog box
(Activities > Properties)
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 307.
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)
More information
465
Branch security commands
Command
Provides access to:
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)
466
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
467
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
468
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)
469
Appendix B: Environment Variables
Environment variables are used in scripts and compiled programs to pass values to the executable from the
file that caused a trigger to run. See Adding triggers to run executables, page 350.
Any variable that does not apply to the event that caused the trigger to run is empty.
You can also use these values as field codes in email templates. Add percent symbols (%) before and after
the variable (for example, %SSCM_FILELIST%). See Editing email templates, page 354.
Note: 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 *
Helix ALM 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
471
Appendix B: Environment Variables
Variable
Definition
SSCM_FILELINK *
File hyperlink in sscm:// format
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 *
Helix ALM 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 *
Helix ALM 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
472
Appendix B: Environment Variables
Variable
Definition
SSCM_BRANCH *
Branch the specified file is in
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
473
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.
475
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.
Helix ALM License Server
A client/server application that concurrently manages users and licenses.
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.
476
Glossary
Proxy server
A server that caches files retrieved from the Surround SCM Server and handles subsequent file requests.
Rebase
Update a selected branch, repository, or file with changes made in an ancestor branch.
Recursive
Apply a command to a repository and all of its files and subrepositories.
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.
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.
477
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.
478
Index: Adding – Branch templates
Index
Analyze and repair options 416
Analyzing databases 416, 418
A
Analyzing issue risk in files 283
Adding
Annotating files 86
actions to changelists 136
changelists 135
results 87
API 451
custom fields 342
.NET 453
diff/merge applications 54
avoiding conflicts 451
email notifications 95
C 451
existing mainline branches 404
Java 452
non-RDBMS format 406
Attaching files
RDBMS format 405
external issues 291
external reports to Surround SCM 268
Helix ALM items 277
files 32
Audit trail reports 250
files to code reviews 63
Authentication methods 320
filters 240
B
Helix ALM connections 275
Helix ALM issues 280
licenses 4
plug-in directories 288
proxy servers 444
RDBMS connections 413
reports 249
repositories 115
security groups 302
server connections 5
shadow folders 378
trigger actions 357
triggers 347
users 309
workflow states 366
workflow templates 369
working directories 12
Address toolbar 243
Backups
databases 415
locking databases 416
Base file 129
Baseline branches 173
Blame See Annotating files
Bookmarks
adding 244
changing keyboard shortcuts 245
deleting 245
editing 245
Branch menu 7
Branch templates 180
applying to existing branches 389
creating 181
modifying 389
removing from branches 389
selecting for new branches 182
Advanced find files 219
479
Index: Branches – Changelists
Branches
rolling back promoted files 200
activating 389
rolling back rebased files 209
adding existing mainlines 404
selecting templates 182
applying templates to existing branches 389
shortcut menu 8, 105
baseline 173
snapshot 174
bookmarking 244
templates 180
caching 391
turning indexing on or off 385
changing type 391
unfreezing 388
controlling access 307-308
unhiding 388
creating 178
upgrading mainlines 433
creating mainline 397
viewing 217
creating templates 181
viewing index details 386
deleting permanently 394
when to branch 174
differences 185
workspace 174
differences report 189
Branches tree 8
example 175
Break shares
freezing 388
hiding 388
Bulk custom field changes 37
history 215
C
icons 177
Caching
inactivating 389
branches 391
including and excluding repositories 181
proxy server 442
indexing 384
server options 392
mainline 173
managing attributes 381
480
files 130
Certification and testimony message 338
Changelists
modifying templates 389
adding comments to files 142
promoting 192
adding file actions 136
properties 216
attaching to Helix ALM items 145
rebasing 201
committed 142
removing 393
committing 142
removing mainlines 404
creating 135
removing templates 389
editing file actions 141
renaming 388
managing 136
restoring 394
moving actions 141
restoring mainlines 404
pending 138
Index: Changing server database location – Creating
printing 140, 144
editing 69
removing 140
editing comments 77
removing file actions 141
finding 78
renaming 140
managing 61
rolling back 147
moving comments 77
saving 140, 144
opening 69
searching for committed 144
removing files 67
selecting 151
reports 79
server options 334
reviewing files 70
viewing details 137
selecting 67
Changing server database location 412
starting 68
Charting report data 267
status 61
Checking for new versions 329
syntax highlighting 74
Checking in files 28
view options 73
copying files 188
viewing included files 82
entering comments 29
viewing unaddressed comments 78
merged files 48
Checking out files 25
Columns
changing contents 102
undoing 27
changing width 102
voiding 314
sorting 103
Cherry-picking See Duplicating changes
Comments
Client-side plug-ins 287
editing for file actions 91, 132
Cloaking repositories 123
setting minimum length 335
Code reviews 59
adding comments 76
Committing changelists 142
Compliance 427
adding files 63
audit trail reports 250
addressing comments 77
server options 337
changing font 74
Converting
changing tab width 74
mainline branches to different databases 403
configuring settings for repositories 375
server database to a different type 410
coverage reports 254
creating 62
deleting 83
Copied files
checking in 188
Creating
deleting comments 77
branches 178
differences options 73
changelists 135
481
Index: Custom fields – Diff applications
labels 155
custom fields 343
mainline branches 397
diff/merge applications 57
repositories 115
email notifications 98
shelves 169
files 42
Custom fields
filters 242
adding 342
Helix ALM connections 276
changing multiple 37
labels 158
configuring 341
legacy labels 439
deleting 343
mail 425
editing 343
mainline branches 407
resolving issues 435
proxy servers 447
restoring 343
RDBMS connections 415
setting 36
reports 269
Custom toolbar 107
repositories 126
D
security groups 305
Databases
server connections 6
analyzing and repairing 416, 418
shadow folders 379
backing up 415
shelved files 170
creating tables 409
shelves 170
locking 416
Surround SCM Server log entries 424
maintaining 409
trigger actions 358
repairing 420
triggers 359
scheduling data purges 330
users 313
setting analyze and repair options 416
Default file dialog options 107
viewer and editor settings 21
workflow states 367
Add Files 111
workflow templates 372
Check In Files 109
working directories 14
Check Out Files 110
Destroying
Get Files 108
branches 394
Shelve Files 113
files 42
Undo Check Out Files 110
removed mainline branches 407
Default server database 409
repositories 126
Default user options 338
Diagramming workflows 373
Deleting
Diff applications
branches 394
482
adding 54
Index: Diff/merge application settings – Email notifications
deleting settings 57
Helix ALM issues 281
editing settings 57
labels 156
Diff/merge application settings 57
proxy server settings 447
Diffing 45
RDBMS connections 415
branch differences report 189
reports 268
branches 185
security groups 304
file differences report 50
server connections 6
files 45
shadow folders 379
image files 52
shelves 170
labels 161
trigger actions 358
shelved files 170
triggers 357
working directories 116
users 312
Downloading RSA keys 322
viewer and editor settings 21
Duplicating
workflow states 367
email notifications 98
workflow templates 372
filters 242
working directories 13
labels 157
Editor for files
reports 269
adding for specific file types 20
security groups 305
changing text display options 22
triggers 359
deleting settings 21
workflow templates 372
editing settings 21
Duplicating changes 185, 210
actions 213
tracking changes 213
setting default application 19
Electronic signatures
certification and testimony message 338
E
compliance options 337
Editing
entering 39
changelist file actions 141
Email notifications
code reviews 69
adding 95
custom fields 343
deleting 98
diff/merge applications 57
disabling 98
email notifications 98
duplicating 98
email templates 354
editing 98
files 28
enabling 98
filters 242
setting server options 326
Helix ALM connections 276
setting up 95
483
Index: Email server options – Files
Email server options 325
File status 17
Email templates
Filename search 219
editing 354
field codes 471
Encryption 319
enabling 318
Files
adding 32
bookmarking 244
breaking shares 130
Environment variables 471
checking in 28
Executables
checking out 25
environment variables 471
deleting from shelves 170
running from triggers 350
deleting permanently 42
Expanding keywords 332
destroying 42
Exporting
differences 45
repositories to different mainlines 400
External reports
editing 28
finding 219
adding to Surround SCM 268
getting 15
creating 268
history 88
F
image differences 52
Favorites
labeling 158
see Bookmarks 244
merging 47
Field codes 471
merging unrelated 48
File details pane 8, 85
moving 39
File dialog defaults 107
opening local copies 23
Add Files 111
Check In Files 109
promoting 197
rebasing 206
Check Out Files 110
removing 41
Get Files 108
removing labels 164
Shelve Files 113
renaming 40
Undo Check Out Files 110
restoring 42
File extension user options 112
retrieving from shelves 171
File information 92
rolling back 31
File list
searching for text in contents 234
printing 273
sharing 129
saving 272
shelving 165
File manager user options 14
shortcut menu 8, 105
File names/extensions server options 335
undoing check out 27
484
Index: Filters – Image file differences
unsharing 130
attaching source files 277
unshelving 171
configuring connections 275
viewer and editor 19
deleting connections 276
viewing 19
editing connections 276
viewing in working directory 14
editing field labels 429
viewing line-by-line file changes 86
enabling 429
voiding check out 314
finding attached files 282
Filters
fixing issues 281
adding 240
options 430
applying to source file list 241
renaming field labels 429
configuring 239
selecting items 285
deleting 242
syncing field labels 430
duplicating 242
user settings 277
editing 242
viewing items 280
Finding See Searching
Helix ALM License Server
Fixing
options 327
external issues 292
Helix ALM issues 281
starting 297
Hiding
Font
branches 388
changing in text viewer/editor 23
labels 158
changing in viewer and editor 22
toolbars 106
Freezing branches 388
History
branch 215
G
branch details 215
Getting files 15
file 88, 91
Global users
file details 90
retrieving 311
Go To Location 243
labels 162
Graphical Branch Tree 217
reports 257
Graphical History 91
repositories 131
Grouping file type extensions 112
HTTPS 320
H
I
Helix ALM integration
Icons 18
adding connections 275
adding issues 280
attaching changelists 145
IDE integrations 287
user options 287
Image file differences 52
485
Index: Inactivating branches – Labels
Inactivating branches 389
Issues
Indexing
adding Helix ALM issues 280
indexed vs. non-indexed searches 236
attaching changelists 145
turning on or off for branches 385
attaching source files 277, 291
viewing details for branches 386
editing Helix ALM issues 281
Indexing branches 384
finding attached files 282
Indexing server
fixing external issues 292
checking status 384
fixing Helix ALM issues 281
starting 384
K
stopping 384
Key exchange 320
viewing log 387
changing 319
viewing server log 384
RSA 321
Integrations
Keywords
client-side plug-ins 287
expanding 332
installing plug-ins 289
supported 333
installing third-party 287
L
issue tracking 324
Labeled file reports 163
Mac Finder 294
Labels
supported 287
applying to files 158
third-party 287
configuring 153
user options 287
creating 155
Windows Explorer 293
deleting 158
Interface 7
deleting legacy 439
Branch menu 7
duplicating 157
Branches tree 8
editing 156
file details pane 8
hiding 158
Pending Changelists 8
removing from files 164
Repositories tree 8
renaming 156
source file list 8
searching 160
Issue tracking integration
selecting 159
activating 324
unhiding 158
attaching source files 291
upgrading 437
fixing issues 292
viewing 156
user settings 290
viewing differences 161
viewing issues 292
486
Index: Legacy labels – Plug-ins
Legacy labels
deleting 439
upgrading old 433
Merge applications
upgrading 437
adding 54
Licenses
deleting settings 57
adding 4
viewing in use 313
editing settings 57
Merging 45
List reports
checking in files 48
creating 259
files 47
Local directories
server options 322
creating 27
Local SCM admin login 4
unrelated files 48
Moving
Locking databases 416
files 39
M
repositories 122
Mac Finder plug-in 294
repositories to different mainlines 400
Mail queue
MySCMServerInfo file 17
deleting mail 425
O
managing 425
Open Containing Folder 14
resending mail 425
Opening
Mainline branches 173
local files 23
adding existing 404
toolbars 106
non-RDBMS format 406
RDBMS format 405
working directories 14
Oracle database connections 414
copying to different databases 403
P
creating 397
Passwords
deleting permanently 407
changing 10
exporting repositories 400
Patches 50
moving to different databases or servers 402
Pending changelists
overriding options 398
viewing 8
removing 404
Pending Changelists tab 138
renaming 398
Plug-ins
restoring 404
changing report menu items 272
non-RDBMS format 406
client-side 287
RDBMS format 405
Mac Finder 294
upgrading 433
status 288
upgrading non-RDBMS 434
user options 288
487
Index: Pop-up file details – Renaming
Windows Explorer 293
Quick reports 270
Pop-up file details 104
R
Post-event triggers 345
RDBMS connections
PostgreSQL database connections 414
adding 413
Pre-event triggers 345
deleting 415
Previewing
editing 415
promoted branches 194
rebased branches 204
Printing
upgrading 437
Reactivating branches 389
Rebasing 185
repository differences 119
actions 205
server log 423
branches 201
source file list 273
workflow diagrams 373
workflow transitions 371
preview 204
files 206
Refreshing Source Tree window 103
Process management 427
Regenerating RSA key pairs 322
Promoting 185
Regular expressions 222
actions 196
branches 192
preview 194
files 197
Properties
Removing
branches 393
changelist file actions 141
changelists 140
files 41
branch 216
files from code reviews 67
file 92
labels from files 164
repository 132
Proxy servers 442
adding 444
cache directory 442
mainline branches 404
repositories 124
states from workflow templates 371
Renaming
configuring 443
branches 388
deleting 447
changelists 140
editing settings 447
files 40
starting 443
Helix ALM field labels 429
user options 447
labels 156
Purging data 330
mainline branches 398
Pushing changes to repositories 120
repositories 121
Q
488
Index: Repairing databases – Restrictions
Repairing databases 416, 418
common issues 420
Reports
diffing 116
resolving missing items 119
exporting to mainlines 400
adding external to Surround SCM 268
history 131
branch differences 189
moving 122
charting data 267
properties 132
code review 79
pushing changes 120
configuring 248
removing 124
creating 249
renaming 121
audit trail 250
restoring 125
code review coverage 254
setting workflows 374
external 268
shortcut menu 8, 105
history 257
viewing cloaked 124
list 259
viewing shadow folders 133
menu item plug-ins 270
Repositories tree 8
security group 262
Requirements
trend 264
attaching changelists 145
workflow progress 266
attaching source files 277
deleting 269
finding attached files 282
duplicating 269
viewing 280
editing 268
Resending mail 425
file differences 50
Resolving custom field and workflow issues 435
printing 269
Restoring
running 269
deleted custom fields 343
running quick 270
files 42
saving 269
mainline branches
support diagnostics 340
non-RDBMS format 406
types 247
RDBMS format 405
Repositories
removed branches 394
bookmarking 244
removed mainline branches 404
cloaking and uncloaking 123
repositories 125
controlling access 305
workflow states 368
creating 115
deleting permanently 126
Restrictions
adding 221
branch and repository 231
489
Index: Retrieving global users – Server connections
condition 227
file content 234
date 225
regular expression examples 238
event 228
wildcard examples 238
external issue tracking attachment 230
files 219
filter by action 232
files attached to Helix ALM items 282
Helix ALM items 230
indexed vs. non-indexed 236
label 229
labels 160
list value 226
Surround SCM Servers 5
number 225
Security
regular expressions 222
client/server communication 319
text 222
commands 457
wildcard search 222, 231
controlling access to specific branches 305,
307
Retrieving global users 311
Reveal in Finder 14
Reviewing
changes between versions 70
file contents 74
Risk score 283
Rolling back
changelist actions 147
resolutions 149
files 31
promoted files 200
rebased files 209
RSA key exchange 321
downloading key pair 322
regenerating keys 322
examples 300
levels 299
overriding branch security 308
server 301
Security commands
admin 459
branch 465
files 463
general 457
security groups 463
users 462
Security groups
adding 302
deleting 305
duplicating 305
S
editing 304
Saving
repository differences 119
source file list 272
Surround SCM Server log 423
SCCI plug-in installation 289
Searching
committed changelists 144
490
reports 262
Security Groups window 301
viewing 304
Server connections
adding 5
connecting to different server 5
deleting 6
Index: Server database – Source Tree window
editing 6
Server security 301-302
finding servers 5
Shadow folders
Server database
adding 378
changing location 412
configuring 377
converting database type 410
deleting 379
setting default location 409
editing 379
Server log
indexing server 387
Surround SCM Server
updating 379
viewing for repository 133
Share link 129
deleting entries 424
Sharing files 129
log levels 424
Shelves
printing 423
adding new files 167
saving 423
creating 169
setting options 324
deleting 170
viewing 423
diffing files 170
Server options
editing 170
branch caching 392
managing 168
changelists 334
Shelves window 168
comments 335
shelving files 165
compliance 337
unshelving files 171
email notifications 326
Shortcut menus 8
file names and extensions 335
adding items to run reports 270
general global options 317
changing report names and icons 272
general mainline options 331
customizing 105
Helix ALM integration 429
Signatures 39
Helix ALM License Server 327
Snapshot branches 174
issue tracking integration 324
Sorting columns 103
local SCM admin password 318
Source file list 8
merge 322
Source Tree window 7
RDBMS connections 413
Branch menu 7
RSA key exchange 321
Branches tree 8
send mail 325
customizing 102
server database 409
displaying panes 103
software update check 328
file details pane 8
manual check 329
file status 17
491
Index: SQL Server database connections – Text search examples
hiding panes 103
setting up connections 4
Pending Changelists 8
starting 298
printing source file list 273
Surround SCM Web
refreshing automatically 103
Repositories tree 8
starting server 449
Syncing
saving source file list 272
Helix ALM field labels 430
source file list 8
moved items 119
user options 103
renamed items 119
SQL Server database connections 414
repositories and working directories 116
sscm addresses 243
Syntax highlighting 22
Starting
System user 345
Helix ALM License Server 297
T
indexing server 384
Tab width
proxy server 443
Surround SCM 4
Surround SCM Server 298
Surround SCM Web Server 449
States
Tables
creating database 409
Templates
adding workflow 369
adding 366
adding workflow states 370
adding to workflow templates 370
deleting workflow 372
configuring 365
diagramming workflow 373
deleting 367
duplicating workflow 372
editing 367
editing email 354
restoring 368
setting 38
Status 17
icons 18
Support diagnostics report 340
Surround SCM interface 7
Surround SCM Server
editing workflow 372
editing workflow transitions 371
removing states from workflow 371
setting default workflow 373
workflow 368
Test cases
attaching changelists 145
adding connections 5
attaching source files 277
connecting to different 5
finding attached files 282
deleting connections 6
viewing 280
editing connections 6
finding on network 5
492
changing 23, 74
Text search examples 238
Index: Third-party integrations – User options
Third-party integrations 287
pre-event 345
user options 287
running executables 350
Thumbnail file details 104
U
Toolbars
Uncloaking repositories 123
changing the custom toolbar 107
Undoing check out 27
customizing 106
Unfreezing branches 388
display options 106
Unhiding
displaying 106
branches 388
hiding 106
labels 158
Tracking changes 213
Unlocking databases 416
Transitions
Unsharing files 130
editing 371
Trend reports
creating 264
Trigger actions
append event comment text 352
Unshelving files 171
Update check options 328
Upgrading
legacy labels 437
mainline branches 433
prevent an event 352
non-RDBMS 434
send email 353
old 433
set a custom field value 356
set event comment text 352
set workflow state 356
Triggers
adding 347
adding actions 357
configuring 346
RDBMS connections 437
User interface mode
changing 107
User options
Add/Find In Files extensions 112
diff/merge 53
file dialog defaults 107
deleting 359
Add Files 111
deleting actions 358
Check In Files 109
disabling 359
Check Out Files 110
duplicating 359
Get Files 108
editing 357
Shelve Files 113
editing actions 358
Undo Check Out Files 110
enabling 359
file manager 14
environment variables 471
general 8
examples 346
integration 287
post-event 345
plug-ins 288
493
Index: Users – Workflows
pop-up file details 104
issues 292
proxy server 447
label differences 161
setting default 338
label history 162
source tree 103
labels 156
thumbnail file details 104
repository history 131
view/edit file 19, 22
repository shadow folders 133
Users
security groups 304
adding 309
users 312
deleting 313
working directory differences 116
editing 312
Voiding check out 314
retrieving global 311
W
viewing 312
Web server
viewing current license usage 313
starting 449
Users window 308
Windows Explorer plug-in 293
V
Workflows
Viewer for files
adding for specific file types 20
creating progress reports 266
changing text display options 22
customizing 364
deleting settings 21
editing transitions 371
editing settings 21
planning 365
setting default application 19
printing transitions 371
Viewing
resolving issues 435
branch differences 185
setting default 373
branch history 215
states
branch index details 386
adding 366
branch properties 216
changing 38
changelist details 137
configuring 365
cloaked repositories 124
deleting 367
file history 88
editing 367
file history details 90
restoring 368
file properties 92
494
automating 365
templates
files 15, 19
adding 369
graphical branch structure 217
adding states 370
graphical file history 91
configuring 368
Helix ALM items 280
default 363
Index: Working directories – Workspace branches
deleting 372
diagramming 373
duplicating 372
editing 372
removing states 371
setting for repositories 374
Working directories
adding 12
deleting 14
diffing 116
editing 13
editor 12
opening 14
setting 11
Workspace branches 174
495
Download PDF
Similar pages