1 Starting up the GUI

The Plastic SCM GUI provides simple access to the functionality of Plastic SCM. The Plastic GUI is a client that connects to a repository server and manages workspaces in the user’s machine.

The Plastic SCM GUI client is normally started from:

The Start-up menu in Windows platforms, under the “Codice Software Plastic SCM” / “Client components” folder
The Applications folder on Mac OS X systems
The Start-up menu in Linux platforms, under the Development or Programming menu.

In every platform, using the command “plastic” from a shell on Unix, Mac platforms or in a DOS command window in Windows.

1.1 The main screen

The main Plastic SCM GUI screen is composed of several areas, designed to present the user with a clear view of the versioned environment on which work is being done. The Figure 1: Plastic GUI main screen areas, shows an example of the main window of Plastic SCM.

Figure 1: Plastic GUI main screen areas

Descriptions of each area noted in Figure 1:

The workspaces tabstrip allows the user to switch among the available workspaces on the local machine. Clicking on a workspace name, causes the rest of the window below this bar to display the information of that workspace.

The currently selected workspace is highlighted in orange, while the rest of the available workspaces are displayed in white.

The current workspace information area displays details about the currently selected workspace:

Specific workspace information shown is:

Workspace name (same as the workspaces tabstrip).
Workspace directory on disk which is the location of the files and folders loaded by this workspace
Repository from which this workspace is loading its items and revisions.
Branch for this workspace within the repository shown.
Label is an optional field which indicates that the workspace is pointing to a label instead of to a branch. This is a read-only scenario, meaning that the workspace points to a configuration where no revisions can be created (since a branch is needed for that). This setup is convenient, for example, on deployment workspaces, where no changes are made, but a stable codebase needs to be downloaded (i.e. a label)
The refresh button on the right hand side of the window is used to refresh the contents of this area, to check if any changes have been made to the workspace configuration outside this instance of the Plastic GUI.
Right clicking on this area displays the current workspace operations, shown in the figure below. These operations are explained in detail in the “The workspaces view” section of this guide.

Figure 2: Workspace operations

The quick access bar to workspace views contains buttons to open the different views in the workspace. A detailed explanation of the views is contained in the “GUI views” section of this guide.

Clicking on a workspace view button opens a new instance of the view if no previous view of that type has been already opened. If the view is already opened, clicking the button in the toolbar will scroll the views area to make that view visible on the top.

Since the list of view buttons may not fit in the window width, scroll arrows (the arrows on the right) are displayed for accessing non-visible buttons in this bar.

Workspace views can also be accessed by using the keyboard shortcut Control+number. The “number” is the position of the button. For instance, the combination Ctrl + 1 opens the items view, Ctrl + 2 opens branches, Ctrl + 3 the Branch Explorer etc.

The View’s area is the main work area where the information for the current workspace is displayed in the form of ‘views’. Views of the workspace/repository show different elements, such as the items (files and folders) in the workspace, or the list of branches in the repository configured on the workspace.

This area can contain several views opened simultaneously and it is possible to scroll between them with the control on the left.
Most views are a classic list view, displaying tabular data in columns. However, some views represent trees (i.e. the items’ view) or graphical content, such as the branch explorer view.

Figure 3: sample items view

The Workspace views scrollbar allows scrolling among the different open views until the desired view is visible.

Figure 4: view area scroll

Note that this scrollbar affects the views’ area. Each individual view will have its own scrollbars if needed to fully display its contents.
The scroll bar also displays the icons of the opened views. These icons can be clicked and the view area will automatically scroll to that view. When icons are hovered over with the mouse, the cursor changes to a hand indicating that the icon can be clicked or dragged.

Note: If the Plastic SCM GUI is closed and opened again, it reminds the opened views before closing, showing them in the scroll in the same order that they had before closing. The scroll will appear in the upper part of the list of opened views.

The Log window toggle button displays or hides the log window. This window will display additional output from some commands such as the update command.

Figure 5: log window detail

2 GUI views

2.1 Common view elements

All views in the Plastic GUI share some common properties and elements, independent of their content. The common items are shown in the following figure:

Figure 6: Common view elements

View icon and caption is the same icon found on the left scrollbar (the view area scrollbar). The title consists of the name of the view and, additionally, the object (repository, workspace, label, branch…) whose information is shown.
Maximize button maximizes the size of the view to the full visible view area. The view area can still be scrolled.
Close button closes the view. The keyboard shortcut Ctrl-F4 (Windows/Linux) or Command-W (Mac OS X) performs the same action. Also, double-clicking on the left corner of the view closes the view.
Refresh button reloads the content of the view from the server.

Note: The refresh button in the items view does not retrieve information from the server, so it is not equivalent to an update operation. It refreshes the status of every item in the workspace. This is very useful, for instance, in case that having the items view opened, the status of an item has been changed from the command line or from a plugin.

Help hints button toggles the visibility of the help hints panel
Help hints displays a hints panel about the view contents or usage. It usually contains a “more help” button that opens the online help with additional information about the view’s contents.

Views can be resized by dragging with the mouse the bottom border. Only vertical resize is possible, since views will always have the same width and will automatically grow to have the width of the main window. Resize is possible only if the view is not maximized.

In addition to the common properties for all views, some views share other elements like these:

Figure 7: Other common view elements

Column headers display the name of the column.

Clicking on any column header sorts the view rows by that column. Clicking again the same column header reverses the sorting (ascending or descending).
Dragging with the mouse in the column header resizes the column width.

View filter is a text box where the user can specify a filter for the view. As soon as the user types something inside it, the rows will be filtered and only those that contain the typed text in their columns will be visible. To display all the rows again, clear/delete the text in the view filter text box.

· Advanced options button toggles the advanced options panel, as shown in the following figure:

Figure 8: View’s advanced options panel

This panel appears on views whose content is based on a query of the Simple Query System, for instance the changesets, labels or branches views. The panel displays a text area with the query used to populate the view content, so that it can be modified. To get more information related to the Simple Query System, take a look into the User’s Guide.

Once the query has been customized, pressing enter or the Execute button on the right reloads the view content. A history of the queries used can be retrieved using the dropdown list in the query text area.

Three additional buttons are available below the query text box:

o Reset query resets the current query to the default one. This button only resets the text of the query. It does not refresh the view content.

o Clear history deletes the history of queries shown in the query dropdown.

o Set as default query sets the current query in the text box as the default query that is used when opening a new instance of the view.

Selecting elements in table views

It is possible to select several elements in the table-based views using the usual mouse and keyboard combinations of the host operating system. These combinations are:

Windows and Linux:

Select multiple items one by one by holding down the ‘Control’ key while clicking on each of the elements to be selected
Select multiple contiguous items by clicking on the first element to select, then hold down the ‘Shift’ key and click on the last element of the selection. All elements between the first and the last will be selected.

With the keyboard, use the up and down arrow keys to select the first element. Hold down the ‘Shift’ key and then use the up and down arrow keys to select the last element. The elements between the initial and the last element will be selected.

To cancel the selection, click anywhere on the view or use the arrow keys without holding any other modifier key.

Mac OS X:

Select multiple items one by one by holding down the ‘Command’ key and clicking on each of the elements to be selected
Select multiple contiguous items by clicking on the first element to select, hold down the ‘Alt’ key and click on the last element of the selection. All elements between the first and the last elements will be selected.
To cancel the selection, click anywhere on the view or use the arrow keys without holding any other modifier key.

Operations in the views

All the operations in the Plastic SCM GUI are available via context menus. The elements shown in the view content (i.e. the rows in the tabular views) can be right clicked and a context menu with additional operations appears. More than one element can be selected in the table views. When multiple elements are selected, only the operations common to all of the selected elements will be available.

The default operation, that happens when an option is double clicked, is displayed in the context menu in bold.

2.2 The items view

The items view displays the tree of files and directories for the current workspace, plus additional information about the specific loaded versions of each item, such as item status, branch and version number, the date created, the author of the revision, the changeset number and some other useful information.

The items view is the default view loaded when the Plastic SCM GUI is opened for the first time or no previous configuration is available and the items view is where the common operations like adding, checking out or checking in will happen.

Items (files or directories) can be displayed in tree or list form, using the two buttons in the items view toolbar, as shown in the picture below:

Figure 9: tree and list buttons in items view

The tree view will display files and folders arranged in the familiar tree layout. The list layout will only display the contents of the current folder. In the list view, there is an additional “current folder” textbox, displaying the full path of the folder displayed.

Double click on a folder to open that folder in the view. Click on the up arrow button in the toolbar to navigate up one level in the folder hierarchy. It is also possible to navigate to a specific folder inside the current workspace by typing its path in the “current folder” textbox and pressing enter or by clicking the right arrow button next to the folder.

Figure 10: Items view in list mode

Columns in the items view

Item is the item name, either file or folder.
Status is the version control item status. Possible status values are:

Private: The item is not controlled by Plastic SCM, although it’s inside the workspace. Any changes made to the item won’t be traced by Plastic.
Ignored: The item is private and the user has decided to not add it to Plastic SCM, so an add operation will take no effect on it. A file ignore.conf placed in the root of the workspace will handle the rules to manage ignored items.
Controlled: The item is controlled by Plastic SCM. New revisions of the item can be checked into Plastic SCM so their history is traced.
Checked out: The item has been checked out for modification. This status indicates to Plastic SCM that the item will be modified. Checked out items can be shelved. That means that the content of the checked out item will be saved in the server despite a new revision will not be created until a check in is performed.
Changed: The item has changed and is not checked out. Changed but not checked out files cannot be shelved.
Not on disk: The item is controlled, but is currently not saved on the disk. Right clicking on the item and selecting “Update” will download a copy of the item to the local workspace.
Cloaked: the item is controlled, but is handled by one of the rules in the cloaked.conf file, meaning that it will not be affected by an update operation. This situation is useful to manage items that rarely change because they are loaded once in the workspace and then they can be cloaked so Plastic SCM does not spend time downloading them or even evaluating if they need to be downloaded.
Not on workspace: this status is never displayed on the items view, but it is possible for an item displayed on other views to have this state, for instance on a view listing the content of a branch that is not loaded in the current workspace.

An item can have multiple status values. It is common to have controlled and changed items or controlled and checked out items.

Size: the size of the file in bytes, kilobytes or megabytes. Folder size is not displayed in this column.
Type: There are three types:.

Text: the item is a text file. This is usually the case with source code files. The contents of text files can be merged line by line.
Binary: the item is a binary file.
Directory: the item is a directory. Plastic SCM versions directories as well as files which is convenient in order to trace item moves and renames.

Revision: the revision of the item loaded in the workspace, including the branch.
Changeset: the changeset of the revision loaded in the workspace.
Created by: the user that created the revision loaded in the workspace.
Date: the date when the loaded revision was created.
Repository: the repository from which the revision of the item is loaded. Useful in case of loading information of several repositories in the same workspace.

Note: To get further information about the item, revision, branch, changeset and repository concepts among others, take a look at the User’s Guide.

Operations available in the items view

Right clicking on the items view displays a menu of the available operations for the selected items. The available operations depend on the item status. For instance, check out cannot be performed on a private item, since that item is not a version controlled item.

Figure 11: item operations

These possible item operations are:

Add: available for private items, this option adds the selected item(s) to the version control. Once the item(s) are added, version control operations are available, such as creating new versions (check in) or viewing history. Ignore rules, configured in the ignore.conf file, apply to this operation. Thus, items matching the rules in ignore.conf will be ignored and not added to version control.
Add (recursive): available for private folders. It adds the selected folders and all the items that the folders contain. Ignore rules, configured in the ignore.conf file, apply to this operation i.e. items matching the rules in that file will be ignored and not added to version control.
Update: available for controlled items. This option checks if the selected items contents need to be downloaded from the repository to match the configuration of the workspace. For instance, if the workspace selector rules are changed to point to a different branch, the items that change between the current configuration and the new configuration will be downloaded from the server.

Performing an update on a file will check if the file requires updating. Performing an update on a folder will check the folder and all its items within the folder. This means that performing an update operation on the root of the workspace will update all of the workspace items.

The update operation will not overwrite changed items. If a changed item is found during the update operation, it will be reported when the operation finishes in the “Update report” dialog.

If, because of a change in the workspace selector configuration, a checked out item is no longer loaded (for instance, the workspace points to different branch), the update operation will automatically shelve the checked out item’s content so it is available again when the selector loads the old configuration.

Note: Cloaked items will be updated if the update option is explicitly invoked on the cloaked item. Otherwise cloaked items are ignored by the update operation.

Update forced: available for controlled items and will force the download of the items’ contents from the repository, even if those contents are up-to-date in the workspace.

If an item is checked out in the workspace, its contents will be automatically shelved to the repository so they will not be lost.

Open and Open with: available for files. The Open operation opens the file with default associated application. Open With requests the user to select a program to use for opening the file.
Check in: available for controlled and checked out or changed items. This operation creates a new revision of the selected items. All the revisions generated this way in the same check in operation are grouped into a changeset.

The user will be asked to provide a comment describing the changes performed, so it will be recorded together with the new version created.

Figure 12: Check-in comments dialog

If the items have been checked out but the content has not changed, a dialog box is displayed prompting the action to perform, as shown in this figure:

Figure 13: Checking in an unmodified item

This dialog box presents 3 options:

· Undo checkout since the item has not changed. The check out can be safely undone and this is the normally selected option.

· Force check-in will create a new version of the item with the same contents as the previous version.

· Cancel will simply cancel the check in.

The option “Don’t show this message again for this operation” applies to the selected option for all other items in the same situation.

Check-in (recursive): same as check in, but only available on folders, it will check in the selected folder and all its contents.
Check-out: available for controlled, non checked-out items, this operation checks the selected items out, indicating to Plastic that the items will be modified.
Check-out (recursive): same as check out, but only available on folders. It will check out the folder itself and all of the folder contents.

Notes: This option is only useful on small folder trees since later on the user has to either check-in all of the items or undo the checkouts, which can be time consuming if there are no changes in the checked out items.

For instance, it is not recommended to recursively checkout the root of the workspace in order to change a few files within the root and then undo the checkouts or force the check in for all of the items.

Check out exclusive: available for controlled, non checked-out items. This option is the same as the check-out operation, except that only one user can check out the item. If other users have already checked out the item, it is not possible to check it out exclusively. Useful when several users are working on the same binary file (not easy to merge changes in a binary file) and on the same branch.
Un-check out: available for controlled, checked-out items. This operation undoes the check-out, loading the item revision that was loaded in the workspace before making changes to it.

Warning: This option discards any changes made to the item while it was checked out.

· Add to ignored list: Available for private items, it allows to add the selected item to the ignored list, so that it will not be added to Plastic SCM. An ignored.conf file, located in the root of the workspace, specifies which files must not be added to Plastic SCM, by means of rules. There are three possible rules to specify in the ignored.conf file:

Figure 14: Rules available for ignoring items

o Ignore the full file name.

o Ignore the file extension.

o Ignore the full location.

Once the appropriate rule is selected, the following dialog appears:

Figure 15: Ignore dialog

If the ‘Apply rules to all workspaces’ option is selected, an ignore.conf will be created in the local user directory, containing rules to apply to all the workspaces available on the machine.

Figure 16: Example of ignored item

When a directory is added to the ignored list, any item contained on it will also be ignored in Plastic SCM from that moment on.

An ignored item can be removed from the ignored list. The available option in this case will be ‘Removed from ignored list’, and the user will have to select the appropriate rule to remove from ignore.conf.

To get further information about ignored items, look at the user’s guide.

· Add to cloaked list: Available for controlled items, it allows marking items to not download them in an update operation, so that the update will be faster. Very useful when applied to big files, usually binary files, that are rarely changed. The first time an item is added to the cloaked items list, a cloaked.conf file is created in the root of the workspace. It works the same way as ignore.conf, that is: three types of rules:

o Cloak the full file name.

o Cloak the file extension.

o Cloak the full location.

Once the appropriate option is selected, the Setup filters confirmation dialog appears, as in the ignored case. You can apply the rules for all the workspaces on the machine by selecting the ‘Apply rules to all workspaces’ option. A cloaked.conf file will be created in the local dir of the user.

Figure 17: Example of cloaked item

When a directory is added to the cloaked list, every item contained on it will also be updated from that moment on.

A cloaked item can be removed from the cloaked.conf list, the same way as ignored files.

To get further information about cloaked items, look at the user’s guide.

Rename: changes the name of the item. If it is a controlled item, its parent directory is checked out because this option does not change the item itself but does change the folder it is in: every folder has a list of the items that the folder contains. If any of those items change its name or location, a new revision of the folder has to be created in order to save those changes.
Move: moves the selected item from its current folder to the specified folder. A folder selection dialog is displayed so the user can choose the destination folder.

Figure 18: Move destination dialog

Delete: removes the item.

If the item is a controlled item, the parent folder will be automatically checked out and the item removed from the folder. This means that the item is removed in the current version loaded in the workspace. A dialog prompts to ask the user if the item must also be removed on disk.

Figure 19: item removal options

If the item is private, it will be removed from disk, once the user confirms that this is the intended operation.

Change revision type: only available for controlled items. This operation changes the type of the selected items to either Binary or Text.

Plastic SCM recognizes commonly used file extensions and determines whether the file contains text or binary content. However, some files can be unknown to Plastic SCM and they will be marked as binary by default. If the files are actually text files, they can be marked as text file so the diff and merge processes handle them more effectively.

New: only available if the selected item is a folder. This operation creates a new file or folder within the selected folder. A dialog box appears asking for the name of the new item. If the new item is a file, an empty file (0 bytes long) is created.
Annotate: Available for controlled items, it opens the annotate view. See “The annotate view” for more details.
View revision history: only available for controlled items. This operation will open a new view with the revision history of the selected item. For more information on the history view, see the “The commit view” section of this guide.
View revision tree: available for controlled items. This operation will open a new dialog with the 3D version tree of the selected item. For more information on the 3D version tree, see the “The 3D version tree” section of this guide.
Permissions: available for controlled items. This operation displays the permissions dialog for the selected item(s). For more details on permissions and the security setup, please refer to the Plastic SCM Security Guide.
Compare modified items: available for controlled folders. This operation will open a new review dialog with the item(s) that have been modified in the workspace below the selected folder, including both checked out and modified items.
View changed items: available for controlled folders This operation will open a new view with the item(s) that have changed in the workspace below the selected folder. For more details on this view, refer to the “The changed items” section of this guide.
View private items: available on controlled folders. This operation will open a new view with the private items in the workspace found below the selected folder. For more details on this view, refer to the “The private items” section of this guide.

2.3 The branches view

Branches are an important and extremely useful part of Plastic SCM operation. Branches are easy to manage, so branch-intensive development patterns such as branch per task development, can be easily and effectively implemented using Plastic SCM.

By default, the branch view displays a tabular list of the all branches in the repositories of the current workspace. The content of this view is retrieved using the Simple Query System, so it can be customized using the “Advanced” button.

Figure 20: the branch view

The branch view has a “Show extended information” button in the top toolbar, next to the refresh button. This button displays the extended information panel containing additional information about the selected branches. For more details on this panel, see the “Panels” section of this guide.

Columns in the branch view

The columns in the branch view support the sorting and resizing functionality available in all tabular views, as previously described. The column contents are:

Name: this is the full name of the branch. Since branches are normally created as children of other branches, the full name here includes all parent branches separated by slashes ‘/’.
Repository: The repository of the branch. A workspace can load contents from more than one repository and then the view will by default load the branches of all the repositories used in the workspace. See the User’s Guide for more information about Selectors.
Owner: The user who owns the branch. When a branch is created, the user who created the branch is its owner. The owner can be changed using the permissions dialog. See the Security Guide to get further information about Security and Permissions.
Creation date: The date the branch was created.
Comment: The comment associated with the branch. The comment can be modified using the “Properties” tab of the Extended Information panel.

Operations in the branch view

Right clicking on a branch or a group of branches in the branch view, displays a context menu with the available operations for those branches.

Figure 21: branch context menu

The branch view operations are:

View branch content: this is the default operation, meaning that it will be invoked when a branch is double clicked.

This operation will open a new view with the items that have been changed in the branch. This is normally referred to as the content of the branch; the rest of the items in the workspace are inherited from the parent branch, depending on the configured branch base. For more information on branch bases, see the “Properties” section of this guide below.

Browse repository on this branch: It opens the Selector Explorer view, showing how the repository looks like in the selected branch. More information in the “The selector explorer view” section.

View changesets in branch: this operation opens a new view with the list of changesets created in the selected branch.

For more details on the content of the changesets view, see the “The changeset” section of this guide.

Explore changesets in branch: this operation opens up a new window with the details of the “changeset walk” interface, as shown in this figure:

Figure 22: Changeset walking window

The ability to “walk” a changeset is an extremely useful feature of Plastic SCM. This window allows users to review, changeset by changeset, the modifications that have been made on a branch. See the “Changeset walking” section of this guide for more details on this valuable feature.

Create child branch: this option is commonly used to create branches. Once the branch is created, the ‘Switch workspace to this branch’ option can be used to modify the items of the workspace, an operation that will be described below.

The create child branch operation will create a new branch with the selected branch as parent. When selecting this option, a dialog for setting the new branch properties will be displayed:

Figure 23: New branch dialog

The content of the different sections in the dialog box are:

Parent branch details: this area contains the full location specification of the parent branch from which the new branch will be created. This specification contains the full branch name plus the complete repository specification. For a complete reference on objects specifications see the Plastic SCM User’s guide.
New branch basic properties: this area contains text boxes for the user to enter the new branch name (only the branch name, it is not necessary to write the full name including the parent branch).

Optionally, comments can be provided which will be displayed with the branch properties in the branch view. The comments can include, for example, details about the branch and its use.

Branch base options: this area contains the options to set the branch base. Only one option can be selected. This is the initial base that will be set when the branch is created and it can be modified afterwards via the branch Properties dialog. A branch base is the starting point of the branch, that is, which contents the branch should include initially.

To select the type of base for the branch, click on the radio button next to the option chosen. The type of base which can be set are:

An existing label: the branch will inherit its contents from the selected label. To select the base label, click on the … button and the label selection dialog box will appear:

Figure 24: label selection dialog

A list of all labels in the repository of the parent branch will be displayed. The filter text box allows the user to filter the contents of the view as usual. Double clicking an element in the list or single clicking on an element and then clicking OK will select the label. Once the label has been selected, it will appear as the branch base.

Setting a label as a branch base is a common scenario, for example, when a release is created and shipped. At this point in the development, a branch base is usually marked with a label.

Notes: if a label that has not been applied is selected as branch base, when pointing the workspace to that branch a “Cannot load the root item” error will be reported, since the starting point of the branch does not contain any revision and the branch does not know which contents to load.

An existing changeset in the parent branch: the new branch will inherit its contents from the parent branch in the specific status marked by the changeset chosen here.

To select the changeset, click on the … button and a changeset selection dialog box will appear:

Figure 25: changeset selection dialog

By default, this dialog displays a list of the changesets created during the last month in the parent branch. Since this is a standard changesets view, similar to the one available in the main window (See “The changeset” for more details), the date restriction can be changed, as needed, by clicking in the “Advanced” button.

Choose one changeset by double clicking it or single clicking the desired element and then clicking OK.

When using the branch in a workspace (by switching the workspace to that branch, operation that will be described later, the workspace will load the revisions of items as they were when the changeset was created. Any subsequent changes to items will be new revisions created in the branch. The rest of the items revisions will be inherited from the parent branch at the time the base changeset is created.

Last changeset on parent branch: It automatically uses the last changeset created in the parent of the branch in the moment of the creation of the child branch.
No branch base: or “None” means that the branch will not have a fixed starting point and the contents inherited from the parent branch will change as the parent branch evolves.

In this configuration, all items not modified in the branch will be inherited from the parent branch. If the parent branch changes, those changes will be inherited, except for the items that have been modified within the branch itself. The rule of thumb is: anything not in the current branch is loaded from the branch base on the parent branch. Since this base is set as “None”, the elements loaded from the parent branch will be the latest available.

Note that this is a moving base so the changes in the branch itself are not stable, but depend on the stability of the parent branch. If the parent branch evolves, this branch will evolve too, even if no changes are made directly on it. While this desirable in some scenarios, it might not be in others, so often the label or changeset bases should be used when creating a child branch.

Once the base has been selected, clicking OK creates the child branch. This branch is now ready to be used and it contains an empty changeset for holding information about the base.

Switch workspace to this branch: this operation loads the selected branch into the workspace and it will update the workspace to load the revisions contained in the branch itself and those of its parent as dictated by the branch base.
Merge from this branch: this operation merges the contents of the selected branch with the configuration loaded in the current workspace, taking into account merge traceability information. See the “Merge” section of this guide for more details on merging branches in the Plastic SCM GUI.
Cherry pick from this branch: this operation merges only the contents of the selected branch with the configuration loaded in the current workspace, without considering merge traceability information. See the “Merge” section of this guide for more details on merging branches in the Plastic SCM GUI.
Replication: this submenu contains the options for branch replication between repositories (normally located in different servers, but this does not have to be necessarily this way). All of the replication background and operations are described in the “Distributed System Guide”. Please refer to that guide for in-depth information of the replication feature.
Rename: this operation renames the selected branch. A dialog box will appear after selecting this option so that the user can enter the new name and confirm the operation.

Important Note: Take into account that renaming a branch does not update the workspace configuration, so if the current branch used in the workspace is renamed, the user needs to “Switch the workspace” to the renamed branch for the workspace to function properly.

Figure 26: rename dialog

Delete: this operation deletes the selected branch only when it is empty (i.e. doesn’t contain any revisions). A dialog box is displayed prompting the user to confirm this operation.
Compare branch content: this operation launches the review interface for the modified items in the branch. See the “Comparing changes: review” section of this guide for more details.
Compare with other branch: this operation launches the review interface comparing the items of the selected branch with the contents of other branch that is selected using the dialog box that is displayed:

Figure 27: Branch selection dialog

After the branch has been selected, the review interface is launched. See the “Comparing changes: review” section of this guide for more details.

Compare with label: this operation compares the revisions loaded by the selected branch, with the revisions in the label selected in the label selection dialog box that is displayed.

Once the label has been selected, the review interface will be displayed. See the “Comparing changes: review” section of this guide for more details.

Create top-level branch: this operation creates a top level branch, similar to /main, which doesn’t have a parent branch. This is a special purpose type of branch and should not be required in normal day-to-day development.

By default, a top level branch will not have a branch base either, so if a workspace is switched to a top level branch, Plastic SCM will not be able to load anything.

To be useful, a top level branch must contain a revision of the root directory. This can be achieved by merging from any other branch or setting a branch base. These branches can be useful for holding very specific revision configurations or totally divergent repository contents. For a more detailed explanation of branch concepts, see the Plastic SCM User’s guide.

Permissions: this operation displays the permissions dialog box of the selected branch. See the Plastic SCM Security Guide for more details on the security settings for branches.
Properties: This operation launches the branch properties dialog box that allows modification of some branch options and attributes. This dialog is very similar to the branch creation dialog box.

When the branch base is modified in this dialog, it normally means that the branch contents will be affected by the new base. Specifically:

If this is the branch currently loaded in the workspace, an update of the workspace is recommended since the base has changed and the inherited revisions should be updated to this new configuration.

This operation is called rebase. In this operation, a merge from the branch to which the base is pointing is recommended, because if any item has been changed in both branches, it will be merged and the rebase will be complete. If items have been modified in only one of the branches, the merge is not required, but it is a good standard practice to perform a merge to assure code integrity. To get further information of the merge operation, take a look at the chapter “Merge”.

Tip: A good standard practice when changing the base of a branch is to perform a workspace update and a merge from the branch to which the base points in order to assure that the code base in the branch is up to date.

If the branch is not loaded by the current workspace, the update is not needed (since it won’t have any effect). The merge should be performed at some point because otherwise the branch may not be up to date with its base, but that requires the branch to be loaded in the workspace and perform the merge operation described before.

The branch view and the branch explorer view share a lot of functionality, since both views display branches and can launch operations on the branch. However, the branch explorer contains more functionality related to changesets and links, in addition to branches. For more information, see the “The branch explorer” section of this guide.

2.4 The changesets view

Changesets are created when a check-in operation is performed. All the items that are checked in together form a changeset that is assigned a unique number in the repository.

The changeset view is another tabular view based on the Simple Query System. This picture shows a sample changeset view:

Figure 28: changesets view sample

By default, the changesets view displays only the changesets of the last 30 days in the repository. Being a view based on a Simple Query, the default date range can be changed using the “Advanced” button.

Notes: Since this view will only display changesets in one repository, if more than one repository is configured in the workspace, a dialog box will be displayed to select from which repository view changesets, as shown below:

Figure 29: Repository selection dialog

Information displayed in the changeset view

The changeset view contains a list of rows representing changesets created in the repository. For each row, the following data is displayed:

Name: this is the changeset identifier inside the repository. It consists of an integer number, normally in sequence although not necessarily so (for instance, a replicated branch can alter the numbering sequence).
Comment: The comment associated to the changeset when the check-in operation that created the changeset was performed. This is a user created comment during check-in.
Creation date: this is the date on which the changeset was created.
Branch: this is the branch to which the changeset belongs.
Created by: the user that performed the check-in operation.
Repository: the repository to which the changeset belongs.

Operations in the changesets view

This picture shows the operations available when right clicking on a changeset in the list:

Figure 30: Changeset operations context menu

The changeset options are:

Show changeset content: this is the default changeset operation, meaning that this is the operation invoked when double clicking on a changeset in the list.

It opens a new view with the list of revisions belonging to the changeset. For more details on this view, see the “The revisions views” section of this guide.

Browse repository on this changeset: It opens the Selector Explorer view, showing how the repository looks like in the selected changeset. More information in the “The selector explorer view” section.

Create branch from this changeset: this operation opens up the branch creation dialog box described previously in the “Operations in the branch view” section of this guide. See that section for more details on the branch creation dialog box.

The new branch base will already be set to the selected changeset and the parent branch will be the branch of the changeset.

Compare changeset content: this operation will launch the review interface, in this case with the items in the changesets, compared against their immediate parent revisions. The code review window will display the changes that have been made in the changeset. For more information on the review interface, see the “Comparing changes: review” section of this guide.
Compare with another changeset: this operation will compare the selected changeset against another changeset, to be selected in the pop up dialog box that appears after clicking this menu option. For more information on the review interface, see the “Comparing changes: review” section of this guide.
Cherry pick from this changeset: this operation launches the merge interface for cherry picking, in order to merge the content of the selected changeset with the current contents loaded in the workspace. See the “Merge” section of this guide for more details on how cherry picking functions for a changeset.
Subtractive merge from this changeset: this operation opens the subtractive merge dialog box. It will perform a “reverse” merge with the contents of the changeset in the current branch. The result is that the content of the selected changeset will be removed from the revisions in the current workspace. See the “Merge” section of this guide for more details on the merge operation and refer to the Plastic SCM User’s Guide for more information about the subtractive merge feature.

2.5 The labels view

Labels are used to mark a set of revisions with a special meaning. For example, it is common practice to label all revisions that form a specific code release delivered to a customer. Labels are normally applied to all items in a workspace.

Figure 31: Sample labels view

The labels view lists all labels in all repositories in the current workspace. This view relies on the Simple Query System to gather its contents from the repository, so it is possible to customize what content gets downloaded using the “Advanced” option as described in the “Common view elements” section of this guide.

The labels view has a special button (not found on other views) that allows the creation of a new label object. Clicking this button opens a dialog box to enter the information for the new label to be created, like name and comment. Clicking OK in this dialog will create the label. The new label will appear selected in the view.

If more than one repository is used in the workspace, the label creation dialog will display a list of repositories in addition to the name and comments text boxes. The list of repositories allows selection of the repository in which the label will be created. In the picture below, a label called “my_new_release” is to be created in the repositories “codice” and “importers”:

Figure 32: creating a label in a workspace with multiple repositories

Creating a label is the first step in using labels. The next step, in order for the label to be useful, is to apply it to the workspace content. This step is described in detail in the “Operations in the labels view” section of this guide.

Information displayed in the labels view

Each row in the labels view contains the following information:

Name: the name of the label
Repository: the repository of the label. If only one repository is used in the workspace, then this column will have the same value for all rows. It varies when the workspace contains several repositories.
Owner: the user currently owning the label. When the label is created, the owner is the user who creates it. Later, the owner can be modified using the permissions dialog box. For more details on owners and security, refer to the Plastic SCM Security Guide.
Creation date: the date the label was created.
Comment: an optional user comment. This value can be modified in the “Properties” tab on the extended information panel. For more details, see the “The extended information panel” section of this guide.

Operations in the labels view

The picture below shows the operations available for labels from the labels view:

Figure 33: Label operations

The operations are:

Show labeled revisions: this is the default operation when a label is double clicked on in this view. This option opens a new view with the revisions that have the selected label applied. For more details on the revisions view, see the “The revisions views” section of this guide.

Since normally all the items in the workspace are labeled, this view can contain a large number of elements.

Browse repository on this label: It opens the Selector Explorer view, showing how the repository looks like in the selected label. More information in the “The selector explorer view” section.
Apply label to workspace contents: this operation applies the label to the revisions currently loaded in the workspace. Checked out items are not labeled, so this operation checks first if any checkout is left in the workspace and prevents the operation from continuing in case any are found. If the label operation were allowed to continue, checked out items would not be labeled and, later, the labeled configuration would not be complete. Some items would be missing and the code base would be incomplete.

In the case of a workspace that uses more than one repository, this operation will try to apply the label with the same name as the selected one on the other repositories. If such label doesn’t exist in any other repository, Plastic SCM will continue applying the available labels.

Tip: ensure that every item is checked in before labeling items to assure that the configuration marked is usable and that it is possible to load the label in a workspace.

Rename: this operation renames the selected label. A dialog box prompting the user for the new label name is displayed.

Note: If the renamed label is loaded in the current workspace, the selector of the workspace has become obsolete. To solve this problem, right-click on the label recently renamed and select the operation “Switch workspace to this label”. This operation is described later on this section.

Delete: this operation deletes the selected labels. Before proceeding, the user is prompted for confirmation.
Compare with label: This operation will compare the selected label in the view with the label selected in the dialog box that pops up. Once the second label is chosen, the review interface is loaded and the revisions in both labels are compared. For more details on the review interface, see the “Comparing changes: review” section of this guide.
Merge from this label: this operation will try to merge the revisions marked with the selected label with those loaded in the current workspace. A merge dialog box will be displayed and the potential items to merge will be calculated. For more details on the merge operation, see the “Merge” section of this guide.
Switch workspace to this label: this operation makes the current workspace point to the selected label. This will produce a workspace where no item can be checked out, since it is pointing to a label and the only way to create revisions in Plastic SCM is through a branch.

Tip: If you are looking for a way to make changes to a specific label, the correct way is to create a branch whose base is the desired label and then switch the workspace to that branch.

This option will prompt for confirmation before continuing with a dialog box asking for confirmation and, if the user decides to proceed, an automatic update of the workspace will be performed.

· Permissions: this operation displays the permissions dialog of the selected labels. Refer to the Plastic SCM Security Guide for more details on the security settings for labels.

2.6 The commit view

The commit view allows the users to manage the checked out items, changed items, private items and ignore items in a single view, which is much more comfortable. The following figure shows all the options that this view allows to do.

Figure 34: The commit view

In addition to this, if you commit private items, those items and the parent items that are private are added and checked in automatically.

Additionally, you can add comments to the operation, typing them on the text box provided. Also, you can specify comments specified in previous operations by clicking on the button provided.

Finally, you can review the changes done in a task before committing it by clicking on ‘Compare changes…’, which will open the comparing tool, showing the differences between the previous revisions and the new revisions created.

The commit view is a powerful tool to allow the developers to review their changes before committing them.

2.7 The item history view

This view displays in chronological order the history of an item. All the revisions of the file are displayed, together with the labels applied to each revision.

Figure 35: Sample item's history view

For each revision, the full revision name, creation date, associated changeset, the markers in which that revision is labeled, the user who created the revision, any comment and the list of markers applied is displayed.

Operations in the history view

Figure 36: Operations of a revision in the history view

The operations are:

Open/Open with: this operation opens the revision with the default associated program or with a program that the user chooses.
View changeset content: opens a new view with the content of the changeset to which this revision belongs. More in “The revisions views”.
Diff with previous: this operation opens a differences window comparing this revision with its previous revision. This operation effectively shows the changes introduced in this specific revision. More in “Comparing changes: review”.
Differences: opens up the differences windows, which will allow the user to select which revisions to compare. Any or all items can be compared by selecting them in the dialog box. More in “Comparing changes: review”.
Revision tree: this operation displays Plastic SCM’s 3D version tree of the selected item. The tree will contain the same set of revisions that are available on the history view, however it shows the graphical relationship among the revisions. For more details, see the “The 3D version tree” section of this guide. More in “The 3D version tree”.
Save revision as: this operation saves the selected revision on disk in a file with the specified name.
Revert to this revision: this operation creates a new revision at the end of the current branch with the contents of the selected version. This effectively discards the changes made in previous revisions, reverting to the specified revision; thus the “revert” name. This operation must be used carefully, because the right form of discard changes is undoing a checkout. Otherwise the repository will be filled up with non-sense revisions.
Merge from this revision: this operation starts a merge of the selected revision with the current contents of the workspace (for that item), taking into account merge traceability.
Merge from this revision interval: this operation is enabled when a pair of revisions is selected. It will merge the contents of the range between both revisions (it is a cherry pick of the revision interval). See “Merge”.
Cherry pick from this revision: this operation will perform a merge of the revision contents (only the changes introduced in the revision). This operation does not take into account merge tracking. See “Merge”.
Subtractive merge from this revision: this operation will remove the changes introduced in the selected revision from the current revision of the item loaded in the workspace. This is a regular merge operation, but it is “reversed” so that the result is that the changes are subtracted instead of added. Merge tracking is not taken into account for this operation. See “Merge”.
Subtractive merge from this revision interval: this operation is similar to the previous one, with the difference that, instead of removing the changes of one revision, the changes for the selected revision interval are removed. Similar to the “Merge from this revision interval” operation. . See “Merge”.
Permissions: this operation displays the permissions dialog box for the selected revision. Refer to the Plastic SCM Security Guide for more details on the security settings for revisions.

2.8 The changed items view

The changed items view displays the items in the selected path that have been modified without being checked out. These items are drawn with a blue icon overlay and their status in the Status column is “Controlled / Changed”. Changed items can be selected in the view and directly checked in; it is not necessary to check them out first.

Warning: Checked out items can be shelved, while changed items cannot be shelved.

Figure 37: The changed items view

By default, Plastic SCM is configured to set read-only attributes (or to remove the write permission on non-Windows platforms). Plastic SCM can be instructed not to set the read-only setting on items by default. This behavior can be managed in the preferences dialog box. For more information, see the “Other options” section of this guide.

Information displayed in the changed items view

The information available in the changed items view is a subset of the information in the items view. For details on the contents of each column in the changed items view, see the “Columns in the items view” section of this guide.

Operations in the changed items view

Since the information displayed in the changed items view is a subset of the information in the items view, the operations are the same as described in the items view. See the “Operations available in the items view” section of this guide for details.

2.9 The private items view

Private items in Plastic SCM are those that are not under version control. These items are regular files and directories inside a developer’s local workspace which are not available to other developers on other workspaces, as controlled items are.

Figure 38: The private items view

Information displayed in the private items view

The information displayed in the private items view is a subset of the information in the items view. For more details on this information, see the “ Columns in the items view” section of this guide.

Operations in the private items view

Since the elements in the private items view are items, the operations are the same as described in the items view. For private items, the most relevant action is adding to source control. For more details, see the “Operations available in the items view” section of this guide. An additional operation provided in this view is the possibility of showing or hiding the ignored items by clicking on the checkbox located in the upper part of the view.

2.10The removed items view

The removed items view is used to access the list of removed items in Plastic SCM in order to restore (un-delete) one or more of them. This view displays a list of all the removed items in the repositories loaded in the workspace.

Figure 39: The removed items view

Information displayed in the removed items view

Path: this is the full path of the deleted item when it was deleted (i.e. this is the name it had before being deleted. In other branches the same item may have a different name or not be deleted).
Branch: this is the branch in which the item was deleted.
Changeset: this is the changeset in which the item was deleted.
Creation date: this is the date of the check-in (changeset) that deleted the item.
Owner: this is the owner of the changeset that deleted the item.
Comment: this is the (optional) comment of the changeset that deleted the item.

Important Note: An item can be deleted from a branch but not on other branches (For example, because those branches have not received the changes that deleted it, either because the branch with the item deleted has not been merged yet, or because they do not inherit from the branch/changeset of the deletion).

Operations in the removed items view

The operations for the removed items view are:

Figure 40: operations of a removed item

View revision tree: this operation displays Plastic SCM’s 3D version tree for the deleted item. This can be a convenient way of browsing the history of the item prior to deletion.

For more details on the 3D version tree, see the “The 3D version tree” section of this guide.

View revision history: this operation opens a new view with the revision history of the deleted item.
Restore: this operation restores the deleted item in its parent directory. The directory is checked out and the item is re-linked in the checked out revision.

Notes: If Plastic SCM detects that there is an item with the same name in the restoring location of the item, it will inform the user and not allow to restore it.

2.11The code review

The Code review window is especially valuable in task per branch or task per changeset environments, where every piece of functionality (new, bugfix, defect or whatever) is encapsulated in a single changeset or branch. This tool allows inspecting the code created or changed in that task, increasing the quality of that piece of code and thus the code of the whole system.

In the next few pages we will show how a user working on an item can generate a code review for the item/file and assign it to be reviewed by another user.

Let’s suppose that a user create a branch to do some changes, commit them and mark the task as resolved. Now, he or she wants that someone else, probably a senior developer or an expert in the issue that involves the task, inspect the code. So, the user creates a review for that code.

Figure 59 and Figure 60 illustrates two ways to generate a code review, from the changeset view or from the branch view.

Figure 41: Code review for a changeset

Figure 42: Code review for a branch

When clicking on the appropriate option shown above, the ‘Create code review’ dialog will appear. See Figure 43 for details of this dialog.

Figure 43: Create code review window

When the ‘Show diffs after creation’ check button is marked, a Diff with previous window will open, enabling the review with the previous version of the item, and adding comments to the lines on the actual version of the file as illustrated in Figure 44 and Figure 45.

Figure 44: Diff with previous - with no comments

Figure 45: Diff with previous with comments

In Figure 45 the senior developer that was assigned the review added some comments to the lines, and a blue comment tag is applied beside the line, be noted the number inside the tag (1 in this case) indicates how many comments are added for that line, the idea is that many comments can be added for each line.

Once you have added the first comment in a line, more comments can be added by clicking on the grey side of the arrow.

Figure 46: Clicking on the grey zone to add more comments to the same line

After that, you can edit the comments added on a single line by clicking on the blue arrow. If there are more than one comment, a dialog will show the list of comments that are contained in the single line.

Figure 47: Editing the comments of a line which has several comments

At the bottom of the Diff window, the comment list that was empty in Figure 44 is now populated with the list of comments. You can at any time Edit, delete comments from the comment list window.

The list of code reviews are shown in the ‘Reviews’ view. See Figure 48.

Figure 48: Code Review window

You can Open code reviews, change their properties (title, assignee, status) or delete them by right-clicking on a specific review. Pending reviews appear in a red background color.

When double-click on a shown created code review (in this case ModuleHelloWorld), the code review window will open as previously illustrated in Figure 45.

2.12The change statistics view

The purpose of the change statistics view is to highlight where code modifications are taking place. It is often useful to see what items changes a lot because, for example, a large file with many changes may be a sign that the file should be splitted into smaller more manageable chunks.

Figure 49: sample change statistics view

The information displayed on the Change Statistics View are:

Query of revisions to include in the chart: this is the query that retrieves the revisions that comprise the chart. It is mandatory that this query follows the syntax of the Simple Query System (take a look at the User’s Guide). It is possible to use any of the modifiers available to revisions. By default, the chart is built by retrieving the information of the previous month of activity in the current repository. Here are some samples of queries:

# All activity (revisions) on the year 2008 on current repository
find revisions where date between “1/1/2008” and “3/31/2008”

# All my changes since 2008 on current repository
find revisions where owner = “ME” and date > “1/1/2008”

# Activity on branch /main/feature2
find revisions where branch = “/main/feature2”

Refer to the Plastic SCM User’s Guide for more details on the Simple Query System.

Settings for sorting and minimum number of changes: the two boxes in this area are:

Min. changes/item: this box sets the minimum number of changes that an item needs to have to be displayed. Since interest normally lies in the items with more changes, this setting allows filtering out of the less interesting items (those with fewer changes).
Sorting: by default items are displayed sorted by item name. It is also possible to sort by number of changes.

Selected item information: this displays name and number of changes of the selected element, either an item or a user.
Chart of changes per item: this is the area that displays the item changes as a bar chart split into columns. Clicking on any of the items highlights the changes made to that item in the user’s area on the right.
Chart of changes per user: this is the area that displays the user’s changes as a vertical bar chart. Clicking on a user’s bar highlights the changes made by that user on the left chart.

2.13The attributes view

Attributes are used to define user properties that will be applied to objects in the repository. For instance, branches or changesets that require review may have a “Needs review” attribute applied and, once they have been reviewed, a “Reviewed by” attribute with the developer who performed the review.

The attributes view defines the attribute types which are later applied to specific objects via the attributes tab in the extended options panel of the different views. For more details on applying attribute values, see the “The extended information panel” chapter of this guide. It is also possible to create attribute types and apply them to objects from the command line, which can be useful for automating certain operations.

Note: the attributes view may not be visible by default on the views toolbar in the main Plastic SCM GUI window due to the width of the window. The user may need to scroll the toolbar to the right in order to make the attributes view visible.

Figure 50: Views toolbar scroll buttons

Figure 51: Sample attributes view

Information displayed in the attributes view

The attributes view contains the usual information including: name, repository, owner and creation date, having the same meaning as previously described in other views.

Operations in the attributes view

The context menu operations available in the attributes view area are limited to adding new attribute types, renaming, deleting and setting the permissions on the attribute types. These work as expected and described in other views.

Using attributes in queries

Attributes can be used in the “where” clause of the Simple Query System to filter results of any object. The fields used to set attribute conditions are “attribute” and “attrvalue”, the first being the attribute type name and the second being the filter value. Some samples of queries are:

find changesets where attribute = “TaskStatus” and attrvalue = “Resolved”
find branches where attribute = "ReviewedBy" and attrvalue = "David"
find labels where attribute = “Public Release”

These queries can be used in the different views (for instance the branch or changeset views) to get the list of branches that have attributes applied.

There is also a conditional format rule in the branch explorer view that allows specifying a branch filter in the “where” clause. This rule is especially useful in combination with attributes, to highlight items that have attributes applied.

For more details on the Simple Query System, refer to the Plastic SCM User’s Guide.

2.14The repository view

The repository view displays a list of the known repositories in the current server. It is possible to register more than one server in the same client. For more details, refer to the Plastic SCM User’s Guide.

Figure 52: The repositories view

Information displayed in the repository view

For each row in the repositories list, only the repository name and the server are displayed.

Operations in the repository view

The repository view offers a “Create new repository” button for adding new repositories. This button will display a dialog box like the sample shown below:

Figure 53: repository creation dialog

In the dialog box, a new name for the repository is entered, as well as the server on which the repository should be created. The server field will remember the last value that used.

When right clicking on a repository, this is the detailed list of operations available:

Figure 54: operations of a repository

View branches: opens a new branch view for the selected repository. With this view opened, it is simple to switch the current workspace to a branch of the repository.
View labels: opens a new view with the labels of the selected repository displayed.
View changesets: opens a new view with the changesets of the selected repository.
View attributes: opens an attributes view displaying the attributes defined in the selected repository.
Rename: renames the selected repository.

Notes: It is important to change the workspace’s selector if it used the repository recently renamed. To do this, select the renamed repository, and then right click on it; select “View branches” and from the branches view change to the branch that you were using before the renaming operation was done. The selector will be changed accordingly.

Delete: removes the repository from the list of available repositories on the server. Note that Plastic SCM will not delete the repository database files; it will only de-register the repository on the repository server so it is no longer visible. The database itself must be manually removed by the administrator. The user is prompted for confirmation before proceeding with this operation.

For more details on deleting and reconnecting repositories, refer to the Plastic SCM Administrator’s Guide.

Permissions: displays the permissions dialog box for the selected repository. Since security settings are inherited, setting the permissions of the repository is the normal method of setting the basic security. Refer to the Plastic SCM Security Guide for more details on the security settings for revisions.
Repository server permissions: displays the permissions dialog box for the repository server. By default repositories inherit their security settings from the setting of the repository server. It is important to set the administrative user by setting the repository server owner user. Refer to the Plastic SCM Security Guide for more details on the security settings for revisions.

2.15The workspaces view

The workspaces view will display the details of workspaces on the local machine.

Figure 55: sample workspaces view

Information displayed in the workspaces view

The workspaces view displays the workspace name and the path on the local computer where each workspace is located.

Operations in the workspace view

Figure 56: available operations for a workspace

This list of operations available in the workspaces view is also available by right clicking on the Workspace Status bar in the main GUI window of Plastic SCM.

Set selector: this operation is only available if the selected workspace is the current workspace. This option sets the selector of the workspace. A new dialog box is displayed with the current selector configuration, as shown in the following figure:

Figure 57: workspace selector dialog

Once the selector rules have been set in the text box, the selector is confirmed with the Ok button. After setting the workspace selector it is generally advisable to perform an update operation to load the versions indicated by the new selector rules. This is automatically done after clicking Ok if the checkbox “Update workspace after setting selector” is checked.

For more details on the selector rules, refer to the Plastic SCM User’s Guide.

Make active workspace: only available on workspaces that are not the current workspace. This option causes the GUI to switch to the selected workspace. It may be the case that no views have been previously opened for the new current workspace, so the GUI main window may appear empty. Click on the items view or any other view in the views bar on the top to start working on the workspace.
Rename: changes the name of the selected workspace. The name is also updated on the workspaces bar on the top.
Delete: deletes the selected workspace. A workspace cannot be removed if it is the current workspace or if it contains checked out items. To delete the workspace, either un-check out pending items or check them in and then switch to another workspace. This is required because the Plastic SCM GUI always needs a workspace to run and to avoid lose changes done, respectively.

2.16The revisions views

The revisions view is launched from other views (for example, the changeset view or the label view) and it displays a set of item revisions that match a particular criteria, i.e: revisions contained in a changeset, revisions labeled in a marker, and so on.

Figure 58: Sample changeset content view

Note: the set of columns of this view is frequently used in the Plastic SCM GUI to display revision information in different contexts (like the private or changed items views). Some columns might seem redundant in a particular view, but are useful in other views representing revisions as well.

This is the meaning of the columns:

Item: the full item path on disk.
Revision: the revision name including full branch and revision number inside the branch.
Status: the status of this item.
Changeset: the changeset number in which this revision was created.
Created by: the user that created this revision
Revision date: the date in which the revision was created.

The operations available in this view are limited to a small subset of those available in the items view. The meaning of these operations is the same as previously described in the items view section. For more details, see the “Operations available in the items view” section of this guide.

2.17The annotate view

The annotate view window is specially valuable in multiuser environment, when multiple users are working on the same item or file, and a convenient tracking system is desired to review the changes made to that item or file, by whom, when, and what has been modified.

In the next few pages we will show how two users modify, add, delete lines from a project file controlled by Plastic SCM, and how we can track every single modification history of that file through the annotate view.

Let’s suppose that a user, mauker, creates a file. Then, the user miller adds a line to the file and checks it in. Finally, the user luis will also edit the same file and add another line.

Note that for each check in the revision column number is increased. Figure 59 illustrates the Annotate menu-item which was brought forward by right-mouse click the controlled file in the Plastic SCM GUI.

Figure 59: Annotate menu-item from Plastic GUI

Figure 60 Illustrates the Annotate view window that shows line by line which user modified the file and in which version of the file the modification took place.

Figure 60: Annotate window - Full description

2.18The selector explorer view

Imagine that for some reason (let’s suppose that you want to integrate a specific revision or study the history of an item or whatever) you want to know which revision of a specific file or directory is loaded in a specific configuration of branch, label or changeset. Or let’s suppose that you want to study the general structure of the repository in a specific branch, label or changeset. In order to do this, you have two options: you can change the selector to that configuration and update your workspace, which will take more or less time depending on the items that need to be updated or, on the other hand, you can use the selector explorer view.

The selector explorer view allows you to study the structure of a repository in a specific configuration without downloading any revision to your workspace. This way you can query the repository faster.

To open the selector explorer, right click on a branch, label or changeset and select the option “Browse repository on this branch…” (branch, changeset or label, depending on the case).

Figure 61: Browse repository from a branch

Figure 62: Browse repository from a changeset

Figure 63: Browse repository from a label

A view like the following will be opened:

Figure 64: Selector explorer

The contents shown in the main area are those revisions loaded in the selected configuration (branch, changeset or label). You can change manually the selector shown by clicking on the Selector Editor button; this way the user has plenty of flexibility to explore the content of a repository.

Despite this view is quite similar to the items view, you can only perform read-only operations with the items shown in the Selector Explorer, such as: view the history, open the 3D tree, diff with other revisions, etc. You cannot check out or check in revisions from the Selector Explorer view.

As you can see, the paths that appear in the Selector Explorer are not workspace paths (C:\mywkspace\...) but server paths, where ‘/’ is the root item and the rest are child items of the root path.

3 The branch explorer view

The branch explorer view is a powerful navigable diagram that represents the evolution of changes and the branch hierarchy. The following picture shows a sample of the branch explorer:

Figure 65: Sample Branch Explorer view

In this view, there is a toolbar at the top and a diagram area representing the branch hierarchy and evolution. Additional panels can be shown or hidden to access their functionality using the buttons on the toolbar.

Note: Since this view displays a single repository, if more than one repository is used in the workspace, a dialog box appears for repository selection to be displayed in the view.

Figure 66: Repository selection dialog

3.1 The diagram area

The diagram in the branch explorer represents several objects of the repository, represented by a single view. Branches contain changesets and changesets are sorted according to their creation date. Branches are in a hierarchy and they are drawn accordingly.

By default the branch explorer will only display the last 3 months of repository activity. However, this interval can be changed in the display options panel, as described in the “Toolbars and panels” section of this guide.

Figure 67: Branch Explorer diagram axes

In the diagram, the horizontal axis represents time. The columns of the Branch Explorer are days, and each day contains the changesets for that day. The vertical axis represents the branch hierarchy, where child branches are below their parent branches. Changesets are drawn horizontally in their order of creation, inside the column for the day when they were created and vertically inside the branch to which they belong.

Objects in the Branch Explorer

Branches and changesets can be selected by clicking them. When selected, their properties will appear in the Properties tab of the “extended information panel”, when it is visible (see “The extended information panel”).

Right clicking on a branch or changeset also selects it and displays the context menu with the available operations. These operations are the same described in the branches and changesets views, respectively. For more details on the operations available for branches or changesets, see the “Operations in the branch view” section or the “Operations in the changesets view” section of this guide.

Figure 68: Branch Explorer with a branch context menu

Double clicking on a branch or changeset has the same effect as selecting the default operation, similar to the behavior of the branches or changesets views.

There are two other types of objects displayed in the Branch Explorer: links and labels.

Labels are represented with a vertical green line starting in the changeset loaded in the workspace when they were applied.

Figure 69: Label representation in the Branch Explorer

It is important to note that labels cannot be selected by clicking them with the mouse. However, labels can be a search result and can be navigated as with it is done with branches (see “Navigator panel”).

Links are the other type of object that can be displayed in the Branch Explorer. Links represent the relationship between two objects, one of them is the source and the other one is the destination. The following figure summarizes the types of links that can be found in the Branch Explorer:

Figure 70: Branch Explorer link types and colors

This is an explanation of the possible link types:

Merge link: drawn between a source branch and the changeset in the destination branch that received the merged items.

Figure 71: Merge link sample in the Branch Explorer

The merge link in Figure 71 has been generated in the following scenario:

The workspace was loading the /main branch
The branch /main/scm4862 was merged (to the branch in the workspace)
Once the merged items were verified (maybe after a successful build), the items were checked in.

Note: The merge link is only drawn in the Branch Explorer once the items are checked in.

Branch base link: connects a branch with its base object. That base object can be a label, a changeset or no base. This picture summarizes the type of bases and how they are represented in the Branch Explorer:

Figure 72: Branch base links in the Branch Explorer

Outgoing merge link: when a branch is clicked, its outgoing merge links are drawn in green.
Incoming merge link: similarly, when the branch is clicked, its incoming merge links are drawn in blue.

The color of the link changes when it is clicked and becomes selected in order to distinguish that link from the other links. An information box will pop up at the click point detailing information about the link, like its source and destination objects. This is a convenient mechanism to find the source or destination of a link that is larger than the current visible area.

Figure 73: Sample link information box in the Branch Explorer

Scrolling

The diagram area can be scrolled using several mechanisms:

The scrollbars on the right and bottom sides. These work as regular scrollbars.
Dragging with the mouse. To scroll the diagram the user can simply drag the diagram by clicking on an empty zone (where there are no objects such as branches or links) and dragging.

Figure 74: Scrolling the diagram with the mouse

Using the navigator. Click on the “Show navigator” button to display the navigator panel. It will open a small window on the bottom of the Branch Explorer view that represents the whole diagram area. The visible area is represented with the blue box. This picture shows the navigator area:

Figure 75: Branch Explorer navigator

The navigator also displays a representation of the branches in the complete diagram. This preview also displays colored branches when they are a search result or conditional format is applied.

Clicking anywhere on the navigator panel makes that zone visible and dragging the cursor also scrolls the visible area. If the diagram is scrolled using any of the mechanism described above, the blue box is moved to the visible area inside the diagram.

3.2 Toolbars and panels

The Branch Explorer can offer additional information about the selected elements and also includes some navigational aids. The top toolbar contains the basic zoom and search controls as well as the buttons to toggle additional panels. This picture summarizes the contents of the toolbar:

Figure 76: Branch Explorer top toolbar

The elements in the toolbar are:

Zoom controls: these can make the diagram larger or smaller to either view the entire picture or the details of specific zones.
Additional panels’ buttons: these toggle the visibility of the other available panels in the branch explorer. These panels will be described in more detail in the “Panels” section of this guide.
Search controls: this area contains a search text box and buttons to navigate the search results, as detailed in the following picture:

Figure 77: Branch Explorer search controls

Behavior of the controls:

· Search text box: enter the search text here. Pressing the enter key or clicking the magnifying glass in the text box will highlight in blue color the branches and labels that contain the entered text. The diagram will scroll to make the first search result visible.

· Go to previous/next search result buttons: these buttons navigate the search results selecting and scrolling the diagram as needed to make the current result visible.

· Clear search result button: this button clears the search results from the diagram and the text from the search text box. It has the same effect as clearing the text in the text box and hitting enter.

Panels

The Branch Explorer provides three additional panels that can be toggled with the buttons on the tool bar as explained above. Panel visibility is saved from session to session, so when a Branch Explorer view is closed and a new Branch Explorer view is opened, or the GUI client itself is closed and re-opened, the Branch Explorer zoom and visible panels are restored, but the settings on each specific panel are preserved.

3.2.1.1 Navigator panel

The navigator panel is an aid to move around the diagram. See the “Scrolling” section of this guide for more details on the navigator usage.

3.2.1.2 Statistics panel

The statistics panel displays a chart with the number of changesets created per day. A sample is shown in the following picture:

Figure 78: Branch Explorer change statistics

In the chart, a column representing the number of changesets created that day is displayed for each day in the period loaded of the Branch Explorer. Moving the mouse over the columns displays a tooltip with the data and the number of changes.

3.2.1.3 Extended options panel

The extended options panel offers additional options and information. When visible, it is located on the right side of the Branch Explorer. This panel has several independent panels within it that can be switched like tabs by clicking on their header.

Figure 79: the extended options panel in the Branch Explorer

When a tab title (header) is clicked, it becomes the active tab and hides the previous one. The tabs are:

Display options tab: allows customizing the appearance of the diagram in the branch Explorer by specifying which objects are drawn or the range of dates to display. The options for this tab are:

Display changesets: toggles the display of changesets in the diagram.
Display merge links: toggles the display of merge links in the diagram.
Display labels: toggle the display of labels in the diagram.
Display all parent links: this option and the next are mutually exclusive, if one is selected the other is not, but both can deselected. This option toggles the display of all the branch bases. A branch can have more than one branch base, since they can change as time evolves. Because each time a branch base changes, a changeset is created, they are dynamically painted.
Display only latest parent link: toggles the display of the last branch base. This is the base normally used, so it is generally more convenient to have this option checked instead of the previous one since it will help reduce the number of lines drawn on the diagram.
Display task information on branch: this setting controls whether the task title associated with the branch is displayed below the branch name in the diagram.
Date filter: these two dates control the date range that will be displayed by the Branch Explorer. Only the changesets that fall into this range will be displayed, as well as the branches that contain them.
Toggle visibility edition mode button: toggles the visibility edition mode. In this mode, the Branch Explorer turns gray and allows selection of which branches will be hidden or visible.

Figure 80: Branch Explorer in visibility edition mode

When the button is pressed, a short description of how the editor works is shown:

Double clicking on a branch turns on or off the visibility of the clicked branch and its children.

Note: new child branches of that branch will not be hidden by default.

Double clicking a branch while holding the Shift key turns on or off the visibility of that branch.

Note: branches hidden in the Branch Explorer are also hidden in the branch view.

Conditional format tab: Allows specification of different color rules to highlight branches that match certain criteria, determined by the different types of rules.

Figure 81: Sample conditional format tab in the Branch Explorer

The rules are displayed as a list in the central part of the tab. Several rules can be applied simultaneously to the diagram. A new rule is added with the “Add Format Rule” button, which displays a menu with the available types of rules, as detailed here:

· Simple query rule: this rule contains a text box that allows specifying conditions with the syntax of the WHERE clause in the Simple Query Language, as if a “find branches” query would be issued. This means that this filter is the same as performing a “find branches where…” query and assigns a color to the resulting branches in the diagram.

Note that only the conditions that would go to the WHERE clause in the query need to be introduced in the rule. For instance, to highlight all the branches in which I am the owner, the rule filter would be:

owner = ‘ME’

since the Simple Query to retrieve that list of branches would be

find branches where owner = ‘ME’

For complete details on the Simple Query System, refer to the Plastic SCM User’s Guide.

· Non-integrated branches rule: Highlights with the selected color the branches that have changesets not integrated in any other branch. A branch will match if it has one or more changesets after an outgoing merge link. If those changesets have not been integrated in any other branch, the branch is considered as “not integrated”.

· Branches used in the workspace rule: a simpler rule to highlight the branch or branches used in the current workspace. Only the specific branches pointed to in the workspace area highlighted, but not the parent branches of those highlighted branches. For instance, if the current workspace branch is /main/feature1/task019, only that branch will be highlighted. Its parent branches /main and /main/feature1 will not be highlighted.

When the rule is created, it is added to the list with a default color. The color for the rule can be changed by double clicking on the rule’s color tag. A standard color selection dialog will pop up and a new color for the rule can be chosen.

Rules can be deleted with the red X button that each of them have on the right.

Once the rules have been configured, clicking the apply button will perform the queries to the server and calculate the results, applying the defined colors to branches matching the criteria.

Properties (of the selected object): displays the properties of the selected branch or changeset. This is the same panel available on other views and is described in detail in the “Properties” section of this guide.
Task information: displays the task information associated to the selected branch or changeset. This is the same panel available on other views and is described in detail in the “Task info” section of this guide.

4 The extended information panel

Several views in the Plastic SCM GUI share a common control containing information panels organized in tabs. These panels are accessible with the “Extended information” button in the view and appear on the right side of the view.

Figure 82: Extended information panel in a view

The top bar on the panel provides access to the available tabs of the view. If the tabs’ text is longer than the visible width of the panel, two scroll buttons will appear so that the complete list of tabs is accessible. The ‘X’ button closes the panel.

Figure 83: Tabs in the extended information panel

The following sections will describe the tabs available on the different views.

4.1 Properties tab

The properties tab will display additional details of the selected object, normally a branch or a changeset.

Figure 84: Sample branch properties tab

This tab allows changing the comment associated to the selected object by simply clicking on the comments box and typing the changes. As soon as the comment text changes, a save button appears.

Figure 85: detail of the "save" button in comments edition

To save the modified comment, click that button. The user does not need to perform any actions to discard the changes to the comment, simply click on another object in the view and the properties for that object will be displayed instead.

4.2 Attributes tab

The attributes tab displays the attributes applied to the selected objects. While attribute types are created in the attributes view (see “The attributes view” section of this guide for more details on creating attributes types), they are applied to objects in this tab.

Figure 86: Attributes tab in the extended information panel

The tab is composed of the following elements:

Refresh button: refreshes the list of applied attributes of the selected object.
List of applied attributes: lists the attributes and values that have already been applied to the object, as well as buttons to delete or confirm changes, as described in the following figure:

Figure 87: Applied attribute components

Each entry in the list is built from the following components:

· Attribute name

· Attribute value that can be edited if clicked with the mouse. When that happens, the value box becomes a dropdown list where possible values of the attribute are displayed. A new value can be selected from the list or typed in the text box.

· Confirm attribute edition button: used to save the changes made to the attribute value.

· Delete attribute from current object button: used to remove the attribute from the current object.

Add attribute button: used to apply a new attribute to the object. When clicked, an “Apply attribute” dialog pops up:

Figure 88: The apply attribute dialog window

The name field is used to select the attribute to be applied. Click the … button to select the attribute type from the list of available types.

The value field is used to write the attribute value. When clicked, it can also display a dropdown list with the values that this attribute already has in other objects. If the desired value is there, click to select it, otherwise, type it and click Ok to add the attribute.

4.3 Task info tab

The task info tab displays information for the task associated with the selected object (either a branch of a changeset), only when a third party issue tracking system has been configured. See the “Integration with third party issue tracking tools” section of this guide for more details on configuring the link to a supported issue tracking tool.

Figure 89: Sample task information provided by a third party issue management tool

For more information on this tab, please refer to the Plastic SCM Extensions Guide, where an in-depth description of the options available on issue tracking integrations is available.

5 Comparing changes: review

Reviewing the code history is one of the main functions of a version control tool. Plastic SCM provides a powerful change review mechanism for ease of visualization to optimize the review process.

5.1 What can be reviewed

The review interface compares two sets of revisions. The Plastic GUI offers the review operations as context menu operations for a variety of objects including branches, changesets and labels. The operations normally start with “Compare…” and will compare the set of item revisions contained in the selected object with other set of revisions. The following sections describe what can be compared in the Plastic SCM GUI.

Branch comparison operations

Compare branch content: compares the items that have revisions in the branch. The latest revisions of the items in the branch will be compared against the versions of those items before the branch was created. This means that the changes compared will be exactly those introduced in the branch.
Compare branch with other branch: compares the latest revisions in a branch with the latest revisions in other branch.
Compare branch with label: compares the latest revisions in the selected branch with the revisions in the selected label.

More information about branches operations in “Operations in the branch view”.

Changeset comparison options

Compare changeset content: shows the changes performed in the revisions of the selected changeset.
Compare with other changeset: compares the sets of revisions contained in each of the changesets.

More information related to changeset operations available in the section “Operations in the changesets view”.

Label comparison

Compare with label: compares the revisions marked with one label against the revisions marked with a second label.

More information about label operations in “Operations in the labels view”.

Item comparison

Compare changed items: compares the set of modified and checked out files with their previous versions.

This operation shows all the changes made in the workspace that can be checked in. This can be a good method to review the changes done before checking in them, but Plastic SCM provides a useful tool which is better to do this, the Commit View (see “The commit view”).

More information about items operations in “Operations available in the items view”.

5.2 The review interface

This Interface has two main areas, one for the items that will be compared, and another for displaying the differences between the selected items.

Figure 90: Review interface main areas

The areas are described in detail below.

List of items in the selected comparison: contains a list of the items that are being compared, detailing the item names as well as the revision numbers.

Figure 91: Items to compare in the review interface

This area has several components, as depicted in the figure above:

· Item list navigation buttons: buttons to navigate to the first, previous, next and last items in the tabular list.

· “Hide elements list” button: toggles the visibility of the items list, leaving more space available for the differences area. Clicking it again displays the panel back.

· “Show only changed elements” button: checkbox controls whether all items being compared are listed or only those that have real changes. Since the review is always comparing two set of revisions, it is possible that some items have not changed from one set to the other. This is a common case for instance when comparing the contents of two labels, where both of them have been applied to all the items of the workspace, but it is very unlikely that all the items change.

· Items list filter text box: a filter box similar to the one found in the rest of the views. If anything is typed, only those rows containing that text will be displayed in the list of items. Clearing the text in the box makes the view display all items again.

· List of items being compared: for each row, the following information is displayed in columns:

o Path: the full path to the item.

o Revision on the left: the full revision including branch and revision number inside the branch.

o Owner (left revision): the user that created the previous revision of the item.

o Revision on the right: this is the branch and revision number of the revision created. This one contains the changes made on the selected object that opened the reviewing tool.

o Owner (right revision): the user who made the change.

o Description: short text describing the type of change made. It can be any of:

§ “The revisions are different”: a change has been made on an existing item and the differences can be displayed clicking on the item.

§ “Only in <object> revision”: the item has been added in the object, so it is only present in the object.

§ “Only in previous revision”: the item has been deleted in the object being browsed so it was available in the previous revision but it does not in the object.

Changes made to the selected item: this area displays the differences to the current item. This is the same interface found in the differences tool and all the options available there can be used here as well.

Figure 92: Item differences in the review window

For more details on the options and usage, see the Differences Tool section of this guide.

5.3 Changeset walking

This window offers the ability to review changeset by changeset the changes that occurred on the branch. A sample of this view is displayed on “Figure 93: Changeset walking ”.

This is a simple and convenient way of reviewing the changes made on a feature or task branch. When a developer groups related changes together in changesets, this view will tell the story of the implementation of the feature or task.

Figure 93: Changeset walking window

This window is very similar to the normal review window described in the previous section, with the addition of a list of changesets on the left side. This list consists of a chronological list of the changesets checked into the branch. For each changeset, the number, date and comments are displayed. Clicking on a changeset in the list makes it the current changeset, and the items modified in it will be displayed in the adjacent area.

6 The 3D version tree

The 3D version tree is the Plastic SCM’s visual representation of the evolution of an item’s history. The history of an element can contain many branches and it can become overly complex viewing 2-dimensional representations of the version tree. In addition, merge links further complicated 2-dimensional views.

Plastic SCM has introduced a new method of representing a version with merge traceability by adding a 3^rd dimension to ease the visualization of the hierarchy and the links between revisions.

While the branch explorer represents a global view of the evolution of the whole code base, the version tree represents the particular history of a single item. If that item only has 2 revisions, then only 2 revisions will be displayed, independently of the number of branches in the repository or the revisions to other items.

The following sections describe the components of the 3D version tree and its operation.

6.1 Elements drawn in the tree

Figure 94: Basic elements in the version tree

The elements that can be found on the 3D version tree of an item are:

Branches: represented as blue rectangular boxes, larger than revision cubes, with the branch name printed on them. Revisions in the branch are drawn immediately below the branch header and follow a vertical axis.
Revisions: represented as blue cubes with their number indicated. A blue line joins a revision with its parent revision. The creation date of the revision is also drawn on its right side.

When a revision is clicked, it is drawn in yellow. Two revisions can be selected by clicking on one and then, holding the Control key (or Command in Mac OS X) and clicking on the second revision. This can be used to show the differences between two revisions, by clicking on ‘Diff. selected’ on the upper-left side of the window.

When the revision is clicked, information such as the changeset number, revision comment and additional details are printed at the bottom of the window.

If a revision is checked out, it is drawn in yellow instead of blue and its version number is replaced by CO (Checked Out). A sample of this state is shown in the following picture:

Figure 95: Sample checked out revision in the version tree

Merge links: green arrows represent when a revision has been merged from one branch to another. The arrow starts in the source revision and ends on the destination revision at the merge target branch. More information about this operation in the “Merge” chapter.
Labels: green text next to the revision to which they are applied. It is possible for a revision to be marked with more than one label and that is represented by showing all labels in columns in the line of the revision.

6.2 The toolbar

Figure 96: 3D version tree toolbar

The components of the version tree toolbar are:

Diff selected button: the differences between two versions can be launched by clicking on two revisions in the tree while holding the Control key (or Command on Mac OS X). When two revisions are selected, the “Diff selected” button is enabled and can be clicked which will launch the differences tool displaying the details of both revisions. More information about the differences tool in “The differences tool” section.
Go to revision box: when a revision is clicked in the tree, the “current revision” box is filled with the revision’s full version including branch and version number.

It is also possible to navigate to a specific revision by entering its full version specification and pressing enter or clicking the right arrow button. The version tree will automatically scroll to the specified revision.

Date filter: by default, the version tree does not load or draw all of the revision of the selected item. It displays only the revisions from the last 3 months (same default policy as the Branch Explorer). The filter can be modified to include a wider or narrower date range using the calendar controls and clicking on the right arrow button on the right side of the filter to redraw the tree.

6.3 3D Version Tree operation

The 3D version tree is operated with the mouse and some modifier keys. The options are:

Rotating the tree: drag the mouse using the left mouse button. This will rotate the tree about the center point of the window.
Panning the tree: drag the mouse with the left mouse button while holding the “Shift” key.
Zooming the tree: use the mouse wheel to zoom in or out. It is also possible to drag the mouse with the left button while holding the “Control” key.

7 Merge

The merge operation allows a user to mix changes done in a pair of revisions. The typical scenario is the integration of a branch into the main branch or when two users are working on the same files and both want to have the changes done by each other without missing their own changes.

Plastic SCM allows a user to mix changes done in changesets, branches, and labels, with the condition that the destination object must be a branch, because only a branch can contain checkouts.

7.1 The merge dialog box

The merge dialog box appears when a merge from branch or a merge from label operation is invoked. The merge dialog box also appears when a cherry pick or subtractive merge is performed. The following picture shows a sample merge dialog:

Figure 97: Sample merge dialog

The dialog contains an information area where the source of the merge is detailed. The source can be a branch, a changeset or a label. The source revisions will be merged with the revisions loaded in the current workspace.

Important: the merge destination is always a branch, which is the only object that can contain check outs. To work on a branch it is necessary to load it in the workspace, so, in the end, the destination of the merge is the contents loaded in the workspace. So, it is very important to have the workspace correctly updated before a merge operation, otherwise the merge candidates and / or the contents to merge could not be the correct ones, probably.

By default, Plastic SCM will try to automate the merge process without requiring user intervention, which simplifies the operation hugely. The merge process will use the merge tracking information in the repository (the green arrows shown in the 3D version tree, see “The 3D version tree”) to ensure that a merge case that was resolved in the past does not require resolution again. The automation attempts to minimize the number of conflicts that a user has to resolve manually.

It is possible to perform a merge from a branch and to also specify a label, meaning that only the revisions on the branch marked with the label will be processed to determine if they need to be merged.

Plastic SCM differentiates between text and binary files as well as directories to decide the best merge strategy to apply. Text files and directories can be processed line by line to reconcile the changes made, whereas binary files can only be merged as a whole.

When the merge process is launched, it calculates the items that will need to be merged, known as merge candidates. Those candidates are displayed in list form in the dialog. For each of the items to be merged, the following information is displayed:

Item name: full path name of the merge candidate.
Conflict type: type of merge that will be performed. It can be any of these types:

Copy-merge: the item has been created in the source of the merge, and will just be copied to the destination (the workspace).
Merge: the item already existed and has been changed in the source of the merge, the destination (the workspace) or both. This is detailed in the next column.

Contributors: who has modified the item, with any of the following possible values:

Source: the item has been modified only in the source of the merge. The changes will be applied automatically to the current content of the workspace.
Destination: the item has been modified only in the destination of the merge (i.e. what the workspace currently has).
Both: the item has been changed by both the source of the merge and the destination (the revisions in the workspace). The merge tool will be invoked with the revision involved to check if the changes can be merged (line by line if it is source code or with the binary merge tool in the case of binary files). The merge tool will automatically merge as many changes as possible and will appear only if there non-automatic conflicts. This behavior can be modified with the merge options panel described below.
None: this case happens when revisions with no changes have been created. So there are new revisions in the source and destination, but they have the same content as their most recent common ancestor (i.e., the base). This can be the case when a user rebases a child branch to get the latest changes from its parent and then that branch is merged up to its parent.

Actions available to complete the merge:

Merge all button: starts the process of merging all the merge candidates. This is the action normally used.
Merge button: merges only the selected items. It can be used to pick specific item and merge only those.
Search merges button: calculates the items that need to be merged. It is the same calculation that occurs when the merge dialog is shown. This can be useful if the options in the merge source panel have been changed.
Options button: makes the merge dialog grow to display a set of advanced options that control the merge. These options can be used to alter the default behavior of the automatic merge process to be less automatic for user reviewed. While the default settings will be appropriate for most cases, the user may want to change them to review a specific merge. The options are:

Figure 78: merged advanced options

o Select merge contributor section: this options controls how the changes from the contributors (source and destination) are handled to generate the merge result.

§ Take changes in the “merge from” branch (and discard changes in my workspace): the merge result will have only the changes from the merge source. If changes have been made on the destination on the same files, those will be discarded. This means that the changes on the source will be taken and no questions will be asked.

§ Take changes in my workspace (and discard changes in the “merge from” branch): the merge result will discard the changes of the source and keep the content of the current workspace (the destination).

§ Merge changes in my workspace with the changes in the “merge from” branch: the result of the merge will have the changes of the source and destination. This is the default option.

o Merge tracking section: this section is only enabled when performing a cherry pick merge.

§ Ignore merge tracking: this option covers the scenario where a changeset has been merged and then it has been de-integrated using a subtractive merge. If the change needs to be merged again, no candidate items will appear in the dialog, since they have been already merged before and the merge links were created.

Checking this option will ignore the previous merge links (i.e. the merge tracking) so that all the revisions in the changeset will be evaluated as merge candidates and can be merged again.

o Conflict resolution section:

§ Automatic merge if only one contributor changes: Plastic will automatically merge an item if it’s only changed on the source or destination, but if it has been changed in the source and destination, the merge tool will be displayed so the user can review the changes.

§ Automatic merge if only source changes: Plastic SCM will automatically merge the changes if come from the source. If there is any change on the destination, the merge tool will pop up and display those.

§ Automatic merge if only destination changes: Plastic SCM will automatically merge the changes if they are on the destination. If there is any change in the source, the merge tool will popup and display them.

§ Merge changes from both contributors: this is the default option since it performs the most automatic conflict resolution.

The merge candidates

Right clicking on merge candidates displays some operations to review the changes made on the merge candidates. These can be helpful in the process of solving a merge conflict.

Figure 98: items to merge operations

The options are:

View merge contributors: displays a new window with the specific revision numbers of the revisions involved in the merge (the source revision, the base and the destination).

Figure 99: item candidate contributor revisions

Diff current with source: displays a window with the differences between the current workspace revision (the destination of the merge) and the source revision for the selected item.
Diff current with ancestor: displays a window with the differences between the current workspace revision and the base revision (the nearest common ancestor of the source and the destination) for the selected item.
Diff source with ancestor: displays a window with the differences between the source and base revisions for the selected item.

More information about the differences tool in “The differences tool”.

Show version tree: this operation shows the 3D version of the selected item. Read chapter “The 3D version tree” to get more information about the 3D version tree.

Important: once the merge operation has been performed, the involved items are checked out. It is strongly recommended to review the merge results and verify that the result obtained is the expected one. Then, and only then, it is necessary to check in the changes in order to create the merge link and this way avoid that the items merged are not detected as merge candidates again.

7.2 The merge tool

When a conflict cannot be resolved automatically, the Plastic SCM merge tool will pop up, displaying the involved revisions and the result of the merge. The user will be able to navigate the changes made by the contributors and select the proper content to resolve any conflicting changes. This is a sample picture of the merge tool:

Figure 100: sample merge tool

The merge tool is divided several areas, as shown in the following figure:

Figure 101: Main areas of the merge tool

Navigation and options

The top toolbar is used to save the results of the merge as well as for controlling navigation through the changes and options.

Figure 102: toolbar in the merge tool

This is a detailed description of the available options:

Save and exit button: saves the result file as it is and closes the merge tool. This button is used when the conflicts have been resolved.
Save/Save as buttons: save the result file, with the default name or under a new name.
Change navigation buttons: navigate to the first, previous, next and last change in the files. The “Go” button sets the focus on the selected change, in case the view was scrolled with the mouse wheel or the vertical scrollbar.

Note: The selected change can be focused by clicking on it with mouse in the different text boxes.

Manual conflicts navigation buttons: navigate through the non-automatic conflicts and also print the count of pending unsolved non-automatic conflicts. A conflict will be removed from this count when it has been selected, even if the differences fragments are not changed (since the suggested merge solution can be the right one and may not need to be modified).
Versions involved in the merge process: this area has the full path and version specification of the revisions for the source, base and destination revisions. These are the versions displayed in the text boxes below.
Extra options menu: this menu allows adjusting settings for the merge tool:

Comparison method: controls handling of non-visible characters like spaces, tabs and ends of line when calculating the differences. These are the settings options:

Ignore EOL: ignore ends of line in the comparison.
Ignore whitespaces: ignore spaces and tab characters in the comparison.
Ignore EOL and whitespaces: ignore both.
Recognize all: do not ignore any characters, use all of them when computing differences. This is the default setting.

Syntax highlight: controls whether syntax highlight is used when displaying the contents of the source code files. The available languages are:

None
Java / C# / C

Encoding: the explicit encoding to read the files. It can be any of:

None: this setting means that the default setting of the underlying operating system will be used.
ASCII: interpret the files contents as ASCII characters.
Unicode: interpret the files contents as 16-bit Unicode
Unicode Big-Endian: interpret the files contents as 16-bit Unicode in big-endian byte order.
UTF7: interpret the files contents as UTF7 characters.
UTF8: interpret the files contents as UTF8 characters.

Tabs: the number of spaces used to represent a tab character.

4 spaces
8 spaces

Moved detection: opens the dialog to adjust the moved code detection parameters. This way it is possible to remove false conflicts that are actually refactors as a result of moving code from one place to other in the same file. The following dialog appears:

Figure 103: Moved code detection parameters

By editing these values it is possible to decide how similar have to be two code fragments to identify them as the same code moved, in percentage. The second parameter means the minimum number of lines that a fragment of code has to have to be taken into account in the moved code computation.

Source, base and destination

The three files on the top represent the source (left), base (center) and destination (right). These files are scrolled as a whole using the scrollbar on the right. When a change is detected between the versions, it is highlighted in a different color.

Figure 104: difference highlight in the merge tool

In the merge tool, the base revision is compared with the source and destination revisions. This means the base file box will highlight the differences with both files, while the source file box will only highlight the differences with the base (in the same way, the destination file box only highlights the differences with the base).

The source, base and destination boxes are read only and their contents cannot be edited.

The content of each of these boxes are:

Source: the revision of the item in the source of the merge (for instance, the “merge from” branch, changeset or label).
Base: closest common ancestor of the source and destination revisions. This revision is the last common parent of both revisions, so it is the revision with the minimum number of changes between them since they diverged as a consequence of branching.
Destination: the revision where the changes are applied. The destination is always the revision loaded in the workspace. Indeed, as part of the merge process, this revision gets checked out to receive the result of the merge (which is the textbox on the bottom of the merge tool). This revision will get the changes made in the result textbox.

Source and destination revisions are also known as contributors.

The navigation of these files together with the result file is controlled with the scrollbar on the right side. The scrollbar also displays gray and red areas, representing where the conflicting changes in the result file are.

Result of the merge

The result box in the bottom will contain the final result of the merge. The content of this box is saved with the “save” buttons on the toolbar. This text box can be edited, in contrast with the source, base and destination.

Automatic and non-automatic conflicts

A conflict is just a change made on one or more of the involved files in the merge. If the change has been made on the source and destination revisions affecting the same set of lines, this conflict needs user intervention to be resolved. These are marked in red.

Any other case where only the source or the destination revisions contain changes is a conflict that can be automatically resolved. This type is marked in gray. The following picture illustrates both types of conflicts:

Figure 105: automatic and non-automatic conflicts in the merge tool

Resolving a non-automatic conflict

In order to complete an item merge, it is normally necessary to resolve all the non-automatic conflicts. These can be navigated using the buttons in the toolbar:

Figure 106: non-automatic conflict navigation buttons in merge tool

Clicking the next/previous buttons scroll the files to focus on the conflicts. Non-automatic conflicts will involve a change in both the source and destination revisions, on the same set of lines.

To solve a non-automatic conflict, the user must decide between the changes on the source, on the destination or neither of them. By default, the result file will contain the three options together (the content of the source change, the original code from the base and the destination change). Use the contributor buttons to toggle the contents of that contributor in the result file.

Figure 107: a non-automatic conflict sample in merge-tool

Clicking on the source (blue) contributor button removes the content of the source in the result. The same applies for the base and destination contributors. To put a contributor back, click on the button of that contributor again. For instance, the example in the above figure had by default the three contributors selected. After clicking on the source and base buttons (on the top), these are removed from the result, as shown in the next picture:

Figure 108: the previous conflict sample, with base and source contributors deselected

When the result cannot be set to the right content simply by selecting and deselecting contributors, it is possible to manually edit the result file as a regular textbox.

Once all of the non-automatic conflicts have been resolved, click on the “Save and exit” button so that the merge result is saved and the merge process continues with the rest of the items.

Notes: the merge tool is available tool in the Plastic SCM client folder, or executing simply ‘mergetool’. This is very useful to resolve merges ‘offline’, that is, saving three revisions of a file (source, base and destination) and resolve the merge by using this tool.

XMerging files

Let’s suppose that the changes done in a file are not related to adding lines, removing lines or modifying lines but simply with lines of code that have been moved from one place to another, as a result of a refactor operation. The merge tool can detect that kind of situations using a powerful tool, the XMerge, that detects this way moved code so that the user can handle it and manage it easily.

When the merge tool detects a situation like the described above, it shows the following button in the results panel:

Figure 109: The XMerge button

If you click on that button it will appear a dialog in which this situation will be explained and after that the text detected as moved will be selected automatically in the results panel and it will be proposed as a conflict:

Figure 110: XMerge with this selection

When clicking on ‘XMerge with this selection’ the merge tool will open another merge tool window showing only the moved code. Now, the merge tool can detect conflicts inside the moved code block and the user can decide which contributor is the correct one. The conflicts are resolved, then, as explained in a previous section called “Resolving a non-automatic conflict”.

7.3 The differences tool

The merge tool is also used to display simple differences between two revisions. The differences tool is a simpler version of the merge tool, where only two revisions are compared.

Figure 111: sample differences window

The files are not editable in the differences tool. Options are the same as already described for the merge tool in the “Navigation and options” section of this guide.

Moved code detection

The differences tool can detect moved code, as the merge tool does. To do that, it is possible to configure the moved code detection parameters as explained in the section “The toolbar”.

If the differences tool detects moved code, it will show something like the following:

Figure 112: moved code detection on the differences tool

Clicking on the button with two boxes inside and the arrow between them will scroll and focus the corresponding moved code in the other contributor.

Clicking on the button with the window inside will open a new differences tool window that has only the moved code; this differences tool window can detect differences inside the moved code block.

7.4 The image diff tool

When displaying the differences between image items, the binary merge tool is used to present a special view for comparing images.

Figure 113: Binary merge tool comparing images side by side

The image diff tool can compare the two images by displaying them side by side or blended together. When blended together, the blending can be controlled with the slider on the top, making one image more visible than the other. The mode can be chosen with the buttons in the toolbar.

Figure 114: binary merge tool comparing images in blend mode

The user can zoom in and out, as well matching larger images to fit within the visible area of the window using the zoom controls of the toolbar.

7.5 The binary merge tool

For binary files, the regular merge tool is not suitable since it is designed to handle text files. There is a special tool to merge binary files. When a conflict arises merging branches with binary content, the binary merge tool is displayed.

Figure 115: Sample binary merge tool.

The result of the binary merge will be one of the files involved, i.e. the base, the source or the destination revision. To choose which of the contributors will be the result, simply click on the appropriate “Ancestor file”, “Source file” or “Destination file” buttons.

When the document to merge is an image file, a preview is displayed for each of the revisions on the binary merge tool.

Figure 116: sample bin merge tool with an image item

Since the binary merge tool only allows choosing one of the files as the merge result, some changes to the result file may be required to assure the correct merge result. First, finish the regular merge operation. When the binary file with the conflict arises, the binary merge tool will pop up. Choose the version that is closest to the desired result and “save and exit”. The merged files will be left checked out and those check-outs will now have the merge traceability. Modifications to the merged items can be made to achieve the final desired result.

8 Preferences dialog

The preference dialog box sets the configuration options the Plastic SCM GUI operation. Preferences are organized in several tabs with multiple options for each of the functional groups. Each option is described in detail in this section.

8.1 General options

The general options tab serves as the entry point to the client configuration wizard. Click on the logo button to launch the wizard. The steps in the wizard are described in the Plastic SCM Administrator’s Guide; please check the client installation section for details.

8.2 Differences and merge options

Figure 117: Differences and merge options in the preferences dialog

This tab configures the default differences and merging options. The options set here will be used for differences and merge tools operations. For a detailed explanation of each option, please see the “Navigation and options” section of this guide.

8.3 Comments options

Figure 118: Comments options in the preferences dialog

The options in this tab determine which operations should display the comments window. The default setting is only the check-in operation requests comments.

When the comments dialog box is displayed, it has a checkbox to determine future appearances. If it is unchecked in the dialog box, it can be restored in this tab.

The last option, ‘Show empty comments warning’ is used in the Commit view, when the user clicks on Check-in and there is no comment stated in the text area provided. See “The commit view” for more information.

A pre-filled comment created using the comment’s auto-text feature can be set. The values for comment auto-text are:

None: no auto-text in comments
User name: automatically write in the name of the user performing the operation.
Date: automatically add the date of the operation to the comment.
Custom: set a custom string with variable expansion. The possible variables to use are:

{0} the user name
{1} the date of the operation

Clicking on the question mark on the right displays a message box with the possible variables.

8.4 Other options

Figure 119: Other options in the preferences dialog

This tab offers a collection of options:

Auto-update workspace after changing the workspace selector: controls whether an update of the workspace is automatically launched after switching the workspace to a branch (or label) or changing the workspace selector.

Notes: It is recommended to mark this option when the user is a novice, since having the workspace correctly updated is essential before performing some operations (for instance, a merge).

Warn about permissions on move operations: when moving items from one folder to another with different security applied, the item being moved will still inherit its security ACLs from its original parent directory. This setting controls whether a warning message pops-up informing of this situation.
‘Update’ and ‘Check-in’ operations set files as read-only: by default, when Plastic SCM populates a workspace it sets the read-only attribute (on Windows platforms, on Unix/Mac it unsets the write permission). When a file is checked out, the read-only is removed so the file is writable.

When the setting is unchecked, the behavior changes so that files are always writable. When a file is changed without being checked out, it is marked as “changed” and can then be checked in as if it were checked out.

The setting is on by default meaning that files are set as read-only, since this is needed by some IDEs.

Compare files contents instead of using timestamp for ‘quick diffs’: controls how a file is identified as ‘changed’. The default setting is to use the timestamp of the file to check if it has been modified. It might be desirable to read the file’s content to really check if the file has changed. For those cases, turn this option on.

8.5 Integration with third party issue tracking tools

This tab configures the connection with a third party issue tracking tool. The details of this configuration are described in the Plastic SCM Extension Guide. Please refer to that guide for detailed information.

8.6 Replication profiles

This tab defines the list of server profiles to be used during a replication operation. For a detailed explanation of this tab, refer to the Plastic SCM Distributed System Guide, in the “Managing remote authentication” section.

9 Shell Extension for Windows

9.1 Introduction

Plastic SCM supports a Shell-Extension functionality that integrates powerful Plastic SCM functionalities directly into windows’ Shell by means of context menu options, which will add more flexibility to the work of the developer/normal user.

This chapter will explain how to use the GUI of Plastic SCM views and operations from the Shell Extension. To get further information about the different Plastic SCM views, please take a look at the previous chapters of this document.

9.2 Minimal requirements

To use the Shell-Extension the user is assumed to have successfully installed the Plastic SCM client.

The Plastic SCM Shell-Extension will successfully integrate into Windows Shell in the following versions of Windows:

· Windows XP

· Windows Vista

· Windows 7

· Windows 2003

· Windows 2008

For Plastic SCM installation instructions and requirements see the Admin-guide document.

9.3 The Plastic SCM shell extension context menu

After the user have installed the Plastic SCM client and successfully configured it to connect to the Plastic SCM server, many Plastic SCM operations will be accessible through a context menu by simply right-clicking on the Desktop window or inside any open windows file manager (Windows Explorer).

See Figure 120 and Figure 121:

Figure 120: Context menu from Desktop

Figure 121: Context menu Windows Explorer

9.4 Plastic SCM operation concepts

As in the Plastic SCM client GUI, when controlled file status are modified (check in, check out, etc.) a small icon within the file icon is updated to reflect the status of the file. See Figure 122:

Figure 122: File status icon

9.5 Plastic SCM operations through the context menu

In this section we will briefly discuss the accessible Plastic SCM operations from the context menu; please note that as any other modern context menu item, the Plastic SCM operations are accessible when the operation is logically enabled, otherwise it is inaccessible or grayed-out.

For instance, in Figure 121 a private file or in other words uncontrolled file will have the Add context menu item activated, but as soon the file is Added and Checked-in to Plastic SCM control, the Add item is grayed-out and a bunch of other operations are now available. See Figure 123:

Figure 123: Context menu after Add and Check in

Table 1 summarizes the functionality of each submenu in the Plastic SCM context menu.

	Create workspace: will open the new workspace creating window.
	Refresh status: will reload the status of every item shown in the explorer.
	Preferences: Will open the Plastic SCM preferences window.
	Disable extension: will disable the extension see next screen-dump.
	Enable extension: Will activate the Shell-extension.

Table 1: Context menu basic operations

From windows explorer and when the user right-mouse click a file/folder already controlled by Plastic SCM an extended context-menu is displayed as illustrated in Figure 123.

Table 2 summarizes the functionality of each submenu in the Plastic SCM context-menu.

	Add: Will add an uncontrolled or in Plastic SCM terminology “Private” file to the repository so that they are traced and their evolution is recorded. The option is grayed-out because the file is already added and checked in.
	Update: The Update operation downloads files and directories from the repository in the server to the workspace in the developer machine. Update forced: will force the download of the items indicated by the workspace selector, regardless of current workspace content.
	Diff with previous: Will compare the differences of the current file revision with the previous one.
	Checkin: will ‘check-in’ or commit the changes made to an item in the Plastic SCM server. Checkout: Will checkout an item making it modifiable. Undo checkout: will undo any changes made to a checked out item.
	Rename: Will change the name of the item. If it’s a controlled item, its parent directory is checked out since this option doesn’t really change the item itself but its containing folder. Move: Will move the selected item from its current folder to the specified folder. A folder selection dialog is displayed so the user can choose the destination folder. Remove: Will remove an item. The parent folder will be automatically checked out and the item removed from the folder. A dialog prompts if the item is to be removed also on disk or not.
	History: will open a new view with the temporal evolution of the selected item. Version Tree: will open a new dialog with the 3D version tree of the selected item.
	Permission: will display the permissions dialog for the selected items.
	Refresh status: will reload the status of every item shown in the explorer.

Table 2: Context menu extended operations

The following is the description of the context menu that appears when you right-click on a blank location within a workspace:

	Update: will update the workspace from the repository. It checks if the selected items contents need to be downloaded from the repository to match the configuration of the workspace. Pending changes: Will open the Pending Changes window, which indicates for instance, if some items are still not checked-in. Branch explorer: Will open the Branch explorer which will display the hierarchy of the branches.
	Branches: Will open the branches window, which will show detailed information of the branches, like which repository the branch belongs to, owner, child branches etc. Labels: Will open the Labels window, where you can view, create apply Labels to your workspace. Changesets: Will open the changeset window, showing the version groups of items in changesets. Attributes: Will open the Attribute window to view, create and apply attributes.
	Reviews: Will open the Code Review window, which will show the reviews that have been applied to the branches/changesets. Change Statistics: Will open the Change Statistics window which will present the user with graphical report representation of the number of changes performed on an item in the repository.
	Repositories: Will open the Repositories window, where you can view, create or delete a repository. Refresh status: will refresh the content of the current location. Preferences: Will open the Plastic SCM configuration wizard. You can also change many settings for the Plastic client. Disable extension: Will disable the extension. See Table 1 for screen-shots.

Table 3: Plastic Context menu within a workspace

For a detailed description regarding the menu items in the context menu, please see the GUI guide.

9.6 Using Plastic SCM context-menu

In this section, we will work through the process of starting a project, adding some files to it, adding the files to the Plastic SCM control ci, co etc. operations.

To start with we will create a workspace on the local computer, this is easily achieved by bringing the Plastic SCM context menu forward with a right-mouse click and choosing Create workspace; the New workspace window will pop-up. See Figure 124:

Figure 124: New workspace

Here we created a workspace called wksProject1 and the workspace path (or folder) is in C:\Projects\wks\ProjectShell. The repository server in this case we use the default repository on the local machine.

Now we can copy our project files to the workspace folder, be aware just copying the files to that folder will not mean that they are controlled; they need to be added to Plastic SCM version control. As soon the files are add to Plastic SCM and checked in with their first revision, the file icons will be tagged with a green mini-icon as previously illustrated in Figure 122.

Figure 125 shows a project file copied in the workspace, note the status of the file is private (not under Plastic SCM control).

Figure 126 shows the file in Windows Explorer as a normal file, with no change to its icon.

Figure 125: Private file in Plastic SCM GUI

Figure 126: Private file in Windows Explorer

From within Windows Explorer we can add the file and perform a check in operation, the file will be under Plastic SCM control and a first revision of the file will be saved into the repository. Figure 127 shows the controlled file with the green icon tag.

Figure 127: Controlled file in Windows Explorer

Remember to check in the parent directory, as it has been checked out when the file was added to Plastic Repository.

Figure 128 shows the directory before and after the check in.

Figure 128: Directory in Win-Explorer before and after check in

From now on, all the Plastic SCM operations on the controlled file are similar to the one performed from the Plastic SCM GUI.

Figure 129 illustrates the Checked-in file with at least two revisions, and we are performing from within Widows Explorer the Diff with previous and view version tree as shown in Table 2

Figure 129: Controlled file with multiple views