Surround SCM User Guide

Surround SCM User Guide Version 2017.1

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 [email protected]

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 72 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

265

Charting report data

267

Adding external reports to Surround SCM

267

Editing reports

268

Duplicating reports

268

Deleting reports

269

Running reports

269

Running quick reports

269

vii

Adding shortcuts to run reports from the Source Tree window Changing report menu item names and icons

271

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

406

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.1 includes the following key features. For a complete list of features, enhancements, and bug fixes, check out the release notes.

Improved code review file differences When reviewing files in code reviews, you now have more flexibility to see the exact changes you are interested in and how the changes look. You can show differences for versions not included in the review for more information. You can also ignore case and white space differences, change the differences output, and change the font and tab width. See Changing code review view options, page 72. You can also set code review user options to save your default preferences for ignoring case differences and white space, and the differences output type. See Configuring diff/merge application settings, page 57.

Get files with historical filenames When getting files by label or timestamp, you can now retrieve them using the name they had when they were labeled or at the time specified by the get. 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. See Getting files, page 15.

More flexible text file end-of-line formatting Additional file types are now supported when adding files, setting file properties, and setting server options to auto-detect or ignore files based on filename or extension: Text (CR/LF), Text (LF), UTF-8 Text (CR/LF), and UTF-8 Text (LF). When getting text files using the Surround SCM CLI, you can now override the default end-of-line format set in the user options. Using the CLI get command and new file types is helpful when build scripts that run on one operating system get files used exclusively in builds for another operating system. See the CLI help for information.

Other enhancements n

When switching branches in the Surround SCM Client, information is loaded in the background so you can continue to work while branches load.

n

Automatically check for and fix more problems when analyzing and repairing databases with the analyze utility: pending changelists created by deleted users, filters with deleted users as owners, checked out files missing a check out computer, and file revision records incorrectly marked to destroy. See Setting database analyze and repair options, page 416.

n

Administrators can generate a file about the Surround SCM installation to send to Perforce Support for more thorough troubleshooting. See Generating support diagnostic reports, page 340. Note: TestTrack was renamed to Helix ALM. Seapine License Server was renamed to Helix ALM License Server.

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 \ . 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 to close the Working Directories dialog box.

Adding working directories Add working directories to specify the local or network directories to map repositories to. When you check out files, writable copies are added to the corresponding working directory. 1. Choose Tools > Working Directories. The Working Directories dialog box opens.

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. 3. Select Only use for files smaller than and enter the maximum file size to control when syntax highlighting is applied.

22

Opening local files from Surround SCM

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 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 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 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 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 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 .

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. 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 72. 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 . 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 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 . 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 . 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 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 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 to view the review history.

Editing code reviews You can edit code review names, notes, authors, and reviewers, even after reviews are started. For example, you may want to add additional reviewers or provide additional information in the review notes. Note: You cannot edit a review in a Needs Attention or Approved status. If a review needs attention, you must restart it after addressing review comments. If a review is approved, you can create a new review to request additional feedback. See Starting code reviews, page 68 and Creating code reviews, page 62.

69

Reviewing files in code reviews

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. 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 72.

71

Changing code review view options

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. Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page 76. 9. Click Previous Comment and Next Comment to go to the previous or next comment. Note: The content that a comment applies to may move to a different line as the file is updated and reviewed again. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 10. Select a comment and click Mark Addressed to address it or click Address All to address all comments. See Addressing code review comments, page 77. 11. Select Show addressed comments to view comments the author already addressed from other reviews. 12. Select Completed when you finish reviewing the file. You can only mark files as completed if you are a reviewer in the code review. n

To add review comments to a file marked as completed, clear the Completed check box. You can add comments as long as at least one file in the review is not complete.

n

When you complete the last file needing review, you are prompted to confirm you are finished reviewing all files. Click Yes to confirm your entire review is complete. If all files are marked completed, you can no longer add or edit comments in the review.

The file status changes to Needs Attention or Approved when all reviewers complete the review. See Understanding code review status, page 61.

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

72

when viewing a file in a code review and select an option.

Changing code review view options

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.

Option

Select to:

Normal differences

Show differences between versions using the normal diff.

73

Reviewing files

Option

Select to:

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 the 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 72. 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. Select content you have feedback about and click Add Comment to add a comment. See Adding review comments to files, page 76. 8. Click Previous Comment and Next Comment to go to the previous or next comment. Note: The content that a comment applies to may move to a different line as the file is updated and reviewed again. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 9. Select a comment and click Mark Addressed to address it or click Address All to address all comments. See Addressing code review comments, page 77. 10. Select Show addressed comments to view comments the author already addressed from other reviews. 11. Select Completed when you finish reviewing the file. You can only mark files as completed if you are a reviewer in the code review. n

To add review comments to a file marked as completed, clear the Completed check box. You can add comments as long as at least one file in the review is not complete.

n

When you complete the last file needing review, you are prompted to confirm you are finished reviewing all files. Click Yes to confirm your entire review is complete. If all files are marked completed, you can no longer add or edit comments in the review.

The file status changes to Needs Attention or Approved when all reviewers complete the review. See Understanding code review status, page 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. The Add Comment dialog box opens.

2. Enter the comment. 3. Select Comment addressed if the comment does not need to be addressed later. This option is only available if you are the author. For example, you may want to add a comment to mention a specific change you made to address a review comment. You can mark the new comment as addressed so it does not affect the overall review status. 4. Click OK.

76

Editing and deleting review comments

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 and review comments open in a new tab in the Code Review window. 3. To display only unaddressed comments, clear Show addressed comments. 4. Review the comments and make the requested changes. Note: The content that a comment applies to may move to a different line as the file is updated. To view the content a comment applies to in the version it was originally added to, right-click or next to the line number and choose Show Version. The available options depend on the view you are using (e.g., side by side or top over bottom) and the version currently displayed. 5. Add the updated file to the code review. See Adding files to code reviews, page 63. 6. Repeat steps 1 and 2. 7. Select the comment you addressed and click Mark Addressed or click Address All to address all comments. Note: If you address the wrong comment, you can change it back to unaddressed. Double-click the comment, clear Comment addressed, and click OK.

77

Viewing unaddressed review comments

Viewing unaddressed review comments You can check if a file has unaddressed review comments to make sure they are addressed before files are added, promoted, or rebased across branches. For example, if a file was added to a code review from a baseline branch and then promoted to the mainline branch, users retrieving the file from the mainline can view the unaddressed review comments to see what changes other users still need to make to the file. 1. Select the file in the Source Tree window and choose Activities > Code Review > View Unaddressed Comments. The View Unaddressed Comments window opens.

2. Make sure the corresponding Version is selected to view the content the comment applies to. The version the comment was added to and the line number is displayed next to the comment. You can only view the current version and versions that include unaddressed comments. 3. Close the window when you finish.

Searching for code reviews You can search for code reviews based on status, author, reviewer, and files awaiting review by user. 1. Choose View > Code Reviews. The Code Reviews window opens. 2. Select in the Filter list. The Advanced Find dialog box opens.

78

Running code review reports

3. Select the criteria that reviews must meet to pass the filter. The Restriction dialog box opens. The options change based on the selected restriction. 4. Select the restriction value. 5. Click OK. 6. Repeat steps 3-5 to add additional restrictions. 7. Click Find. Reviews that meet the criteria are displayed and the Find results filter is applied.

Running code review reports When working with code reviews, you can run reports to view historical information about a code review and files in it. Use these reports to see unaddressed comments, review your code review process, or save process information for audits. You can run the following types of code review reports: n

Summary reports include a list of code reviews and the files in them.

n

Detail reports include more detailed information about each code review, the files in it, and comments added to the files. Tip: Code review coverage reports are also available. Use these reports to see file versions in code reviews and if the individual file reviews are complete or still in progress. This report can you help you determine if you are ready to release your product, measure coverage of your code review process, or demonstrate quality control during an audit. See Creating code review coverage reports, page 254.

1. Choose View > Code Reviews. The Code Reviews window opens. 2. Select the Mainline branch that includes the files and code reviews. 3. Select a Report on Code Reviews option. n

All code reviews includes all reviews in the report.

n

Selected code reviews only includes specific reviews. Select the code reviews to include. To limit the reviews displayed, select a Filter. To search for a review, select . See Searching for code reviews, page 78.

79

Running code review reports

Tip: All files in a selected code review are included in detail style reports. To only include specific files, select the files to include in the review.

4. Click Report On. The Code Review Report dialog box opens.

5. Select an Output format. Reports can be formatted in HTML or plain text format. 6. If the selected output format is HTML, select a Stylesheet to format the report. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Code review report stylesheets are stored in the StyleSheets/CodeReview directory in the Surround SCM application directory on the server. 7. Select a report type. See Examples, page 81. n

80

Summary style report includes general information about the review, including the name, status, due date, authors, reviewers, and notes.

Running code review reports

n

Detail style report includes detailed information about the review and files in it. Select any of the following options for these reports. n

Include unaddressed comments includes all unaddressed comments for a file.

n

Include addressed comments includes all addressed comments for a file.

n

Include commented file contents with # lines of context includes the specified number of context lines from the file before and after a comment. Including context lines can help you understand more about the code a comment applies to. Context lines are only included for comments in text files and not binary files.

8. Select a Sort comments by option to indicate the order to display review comments in the report. n

Location in file organizes comments in the same order they are in the file.

n

Timestamp organizes comments based on date and time, from oldest to newest.

9. Click Run. The report opens. 10. Click Save As to save the report or Print to print it. These options are only available in the internal report viewer. If an HTML report opens in a browser, you can save, export, or print the report from the browser. 11. Click Close when you finish.

Examples Summary style report The following example is a summary style code review report in HTML format.

Detail style report The following example is a detail style code review report in HTML format. It includes unaddressed comments only, commented file contents with two lines of context, and sorts comments by the location in the file.

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.

Adding email notifications Add email notifications to be automatically notified of file, code review, or code review file changes. For example, you can add a notification to be informed when files are checked in to a specific branch. 1. Choose Tools > My Email Notifications. The My Email Notifications dialog box opens. 2. Click Add.

95

Adding email notifications

The Add My Email Notification dialog box opens.

3. Enter a Notification Name. 4. On the Trigger When tab, select the events that cause the email to be sent.

5. Click the Preconditions tab to set the condition that files must meet to send the email.

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 [] and in repository [] 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 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, 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 to close the Cloaked Repositories dialog box.

Removing repositories Remove a repository if it is no longer needed, but you want to keep it in case you need to use it again later. When a repository is removed, its contents are not permanently deleted and can be restored. 1. Select the repository and choose Repository > Remove Repository. The Remove Repository dialog box opens.

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. 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.

125

Deleting repositories permanently

Tip: Click History to view repository history. Click Properties to view repository properties. 5. Click Restore. The Restore Files/Repositories dialog box opens. 6. Enter any Comments, such as the reason for restoring the repository. 7. Select Recursive restore to recursively restore all subrepositories and files. 8. Click OK. The repository is restored.

Deleting repositories permanently When a repository is removed, it remains in the Surround SCM database unless it is destroyed. You may want to destroy repositories that are no longer needed to free up space in the database. Destroyed repositories are permanently deleted from Surround SCM and cannot be restored. Note: You can also remove and destroy repositories at the same time. See Removing repositories, page 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 from the 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 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 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 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 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 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 .

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 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 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



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, 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, 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 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 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, 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 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, 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= 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:[email protected]: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 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 267.

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 access granted or restricted for each security group. Use these reports to quickly determine which groups have access to specific actions.

Creating security group reports, page 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 265

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 267. 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 268. 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 269. 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 access granted or restricted for each security group. Use these reports to quickly determine which groups have access to specific actions. See Security Commands, page 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 Include Repository Security and Branch Security tabs to include repository and branch security commands in the report. 13. Select a report style. n

Comparison style report displays security groups and commands side-by-side in the same table.

263

Creating trend reports

Tip: You can flag commands to review later. Double-click a command in the report to add a flag. Double-click a flagged command to change the flag to a green checkmark, which indicates the setting was reviewed. n

Detail style report displays commands for each security group in separate tables.

14. Click OK. The report is added. See Running reports, page 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.

4. Enter a Report name. 5. Select a Public/private report option.

264

Creating workflow progress reports

Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page 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 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.

265

Creating workflow progress reports

4. Enter a Report name. 5. Select a Public/private report option. Public reports are shared with all users. Private reports are not shared. You may only be able to create private reports depending on your security permissions. 6. On the Restrictions tab, select the criteria that files must meet to be included in the report. The Report Restriction dialog box opens. The options change based on the selected restriction. 7. Enter or select the restriction values. See Adding restrictions, page 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.

266

Charting report data

11. Select an Output format. Reports can be formatted in HTML, space-delimited columns, or tab-delimited columns. 12. Select a report Stylesheet. Cascading Style Sheets (CSS) files are installed with Surround SCM to create reports with a predefined layout and design. You can customize these stylesheets or create your own. Stylesheets are stored in the StyleSheets directory in the Surround SCM application directory on the 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 to exclude the 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: 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.

267

Editing reports

An administrative user or another user with high-level security permissions is responsible for configuring external reporting services and security before you can add external reports. See the External Reporting wiki for information. 1. Choose Tools > Reports. The Reports dialog box opens. 2. Click Add. The Select Report Type dialog box opens. 3. Select the reporting service as the report type and click OK. The Select External Reports dialog box opens with a list of available reports. 4. Select the report to add. To select more than one report, Ctrl+click each report. Note: Click Create to create a report in the external reporting service. You can only create reports if an external reporting client plug-in that supports report editing is installed. Ask your 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. 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.

268

Deleting 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. 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.

269

Adding shortcuts to run reports from the Source Tree window

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

Changing report menu item names and icons

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 branch and 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. 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 271. 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.

271

Saving the source file list

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 line. n

To change the name, replace the name value with the text to display in the menu. For example, . 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, . 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. 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

272

to move it to the Selected columns .

Printing the source file list

5. Select a column in the Selected columns list and click Top, Move Up, Move Down, or Bottom to change the display order. 6. Select an Output format. You can save the file list in HTML, tab-delimited, or comma-delimited format. 7. Click Save As. The Save File List As dialog box opens. 8. Select the file location, enter a filename, and select the file type. 9. Click Save. The list is saved.

Printing the source file list You can print the source file list, which can be helpful for reporting purposes. For example, you can print a list of all checked out files. 1. Select a repository. 2. Optionally select a filter from the Filter list to include specific files in the printed list. 3. Choose File > Print File List. The Print File List dialog box opens. The Selected columns list includes the columns that are currently displayed in the source file list.

4. Select the column to add in the Available columns list and click 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.

273

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 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 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: Plug-ins for Bugzilla, JIRA, and Microsoft Team Foundation Server (TFS) can be downloaded from the Resources page.

Entering issue tracking login information You need to enter your issue tracking login information before you can attach files to issues. 1. Choose Tools > Issue Tracking Integration > User Settings. The Issue Tracking Tool User Settings dialog box opens.

2. Enter your username and password. 3. Click OK. You can now attach Surround SCM source files to issues.

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 to 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 . In addition, the Inherited From column changes from to . 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 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 . 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 . 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 accounts 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 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 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

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.

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 [] and in repository [] 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 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 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



Work in Progress Needs Attention Awaiting Review Reviewed Awaiting Release Released

Work in Progress

Needs Attention Awaiting Review

Needs Attention

Work in Progress Awaiting Review

Awaiting Review

Work in Progress Needs Attention Reviewed

Reviewed

Work in Progress Needs Attention Awaiting Release

Awaiting Release

Released

Released

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: , 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 . 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.

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 406.

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 406. 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 406.

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. 4. Click OK. The conversion information is sent to the server for validation.

403

Removing mainline branches

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.

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.

405

Restoring non-RDBMS mainline branches

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. 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.

406

Deleting mainline branches permanently

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 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 ''

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.

433

Upgrading non-RDBMS mainline branches

The Upgrade RDBMS Mainline dialog box opens.

2. Select the connection to upgrade. To select multiple connections, Ctrl+click each connection. 3. Click Upgrade. You are prompted to upgrade the mainline branch. 4. Click Yes. The upgrade information is sent to the 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.

434

Resolving custom field and workflow issues

2. Click Yes. The Mainline Destination dialog box opens.

3. Select the Destination database for the upgraded mainline branch. If the database is not listed, you may need to add an RDBMS connection for it. See Adding RDBMS connections, page 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_ *

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_ *

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 267

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 72

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 72

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 406

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 406

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 268

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 267

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 406

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 271

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 269

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 267

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 265

attaching source files 277

deleting 269

finding attached files 282

duplicating 268

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 269

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 271

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 265

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