Chapter 1
Introduction to the
Graphical User Interface
The Plastic SCM graphical user interface (GUI) provides easy-to-use, powerful tools that cover virtually all of the product’s client functionality.
1.1 Launching the Plastic SCM GUI
· Windows: On the Start menu, go to the Plastic SCM program group and execute program Plastic SCM.
· Linux: On the main menu of the distribution you are using, select Applications and then Development. You can type plastic in a shell window, also.
· Mac OS X: Go to the Plastic SCM folder within the Applications folder, and execute program Plastic SCM client.
You can launch the GUI from a command processor by executing the program plastic or plastic.exe. This program is located under the Plastic SCM installation directory, in the client subdirectory. (You probably won’t need to switch to this directory, because the installer typically adds the directory to your program search path.)
1.2 How the GUI Window is Organized
The Plastic SCM GUI window is structured around the fact that you can have any number of workspaces, but you work with only one workspace at a time. This is called the active workspace – it’s like the current working directory in a command processor.
Figure 1: active workspace in the GUI
Near the top of the GUI window is the workspaces tabstrip, which provides quick access to all your workspaces. Clicking on a workspace’s tab instantly makes it the active workspace. Overall information on the active workspace appears just below the tabstrip.
Figure 2: The GUI window
The main portion of the GUI window is a region that displays the active workspace’s work context. It can include any number of tabbed windows, called views. When you switch the active workspace (for example, using the workspaces tabstrip), the GUI preserves the current state of the work context. If you switch back to the original workspace – in the same GUI session or in a subsequent one – its work context is restored exactly as you left it. Each time a view is open using the buttons in the left panel a new tab is created for it, or the existing tab is activated if it was previously open.
1.2.1 Refreshing a View
Each view has a Refresh button, which “recalculates” the view’s contents. There’s also a Refresh button for the workspace’s overall-information area. Refreshing is useful for synchronizing your GUI session with changes that have been made in other windows and/or by other users.
Figure 3: workspace and view refresh buttons
1.3 Tables
Many of the GUI’s views are tables (or include a table along with other elements). Each row of the table represents one SCM object: an item, a revision, a branch, and so on. The columns of the table contain values of the objects’ fields: Name, Status, Creation Date, and so on.
The following sections describe table-manipulation features common to all tables in the Plastic SCM GUI.
1.3.1 Selecting Objects/Rows
The GUI recognizes the “standard” single-selection and multiple-selection gestures supported by many graphical interfaces.
Mouse Gestures
Left Click
Select a single row, which represents a single SCM object.
Ctrl – Left Click
Toggle the membership of the clicked row in the set of selected rows.
Select the block of consecutive rows that extends from the row you clicked most recently (the “anchor” row) to the row you are clicking now (the “free” row).
If there is already a block of consecutive rows selected this way, extend (or invert) the selection by keeping the same “anchor” row but changing the “free” row.
If the current selection set consists of a non-consecutive set of rows, that selection set is discarded.
Keyboard Gestures
Up-Arrow
Down-Arrow
Discard the current selection set, if any, and move the selection highlight upward or downward.
Shift – Up-Arrow
Shift – Down-Arrow
Similar to Shift – Left Click: modify the current block by moving the “free” row upward or downward.
1.3.2 Adjusting Column Widths
You can drag the right-hand separator line of any column to adjust the column width – all the way down to nothing, if you want!
Double-clicking a right-hand separator line resizes the column to the width of the largest element.
Figure 4: Resizing Columns in a Table
1.3.3 Sorting
Clicking a column header sorts the rows on that column. Clicking it again, reverses the sort order. There are exceptions in certain tables. For example, in the Items view, sorting on the Item column doesn’t disturb the directory hierarchy; it sorts the entries in each directory separately.
1.3.4 Exporting the table contents to a text file
The “Export view data” button opens a new window that configures how to export the content of the current table view to a text file in CSV (Comma Separated Values) or XML format, as seen on the following figure:
Figure 5: exporting the view content to a text file
1.3.5 Filtering the Rows of a Table
The toolbar for some views contains a Filter field. As you type characters in this field, the table is instantly “filtered down” to the rows that contain the filter character string, in any column.
Figure 6: Filtering the rows of a table
To restore the original set of rows, just empty the Filter field.
1.3.6 Advanced Mode: Revising the Query that Produces a Table
Most of the tables in the GUI’s various views are produced using Plastic SCM’s SCM-level query facility. Some views feature an Advanced mode, in which you can view the query that produced the table. Moreover, you can customize the query to produce more finely tuned results.
Figure 7: Advanced mode queries
The query input field is also a drop-down box, providing access to standard queries and ones that you’ve previously used. In addition to Execute, these commands are available:
Reset query
Return to using the standard Plastic SCM query for this view.
Clear history
Empty all queries from the drop-down box, except for the current one.
Set as default query
Make the current query the one that gets executed whenever this kind of view is opened.
1.4 Executing Commands
In any table, you can right-click on a selection of one or more objects (that is, rows) to bring up a context menu of commands that operate on the selection.
Figure 8: Context menu in a table
On many context menus, there is a default command that appears in boldface type. You can invoke an object’s default command by double-clicking the object with the left mouse button. (The context menu does not appear at all in this case.) If a context-menu command has a keyboard equivalent (“accelerator”), it is listed in the menu.
Many views also have one or more command buttons in their toolbars. The commands may or may not process the currently selected object(s).
Figure 9: Command buttons in a view's toolbar
Chapter 2
The Items View
The Items view is Plastic SCM’s version of the Windows Explorer or a Linux file manager. It displays the contents of the active workspace as a table, either one directory at a time, or all at once using tree control. Buttons in the view’s toolbar control the display mode:
Figure 10: Items view -- "flat" and "tree" display modes
The Items view shows both items (file and directories under source control) and private objects (not under source control).
2.1 Columns in the Items View
Most columns in the table display SCM-level metadata: revision identifier, changeset membership, status (checked-in / checked-out), and more. There are also a couple of columns that display standard operating system metadata: Size and Date.
The leaf name of the object, along with an icon that shows the object’s type and its current status. See section Icons and Icon Decorations.
Exception: the full pathname is listed for the root directory of the workspace.
One or more indicators of the object’s SCM status. The first indicator for an item is always Controlled; the first indicator for a private object is always Private. Additional indicators can be:
For private objects: Ignored indicates that the object is specified in the workspace-local or user-global ignore file. Attempts to execute the Add to source control command on the object will be ignored.
For items:
· Checked out indicates that the file has been processed by the Checkout command. The object loses its Checked out status when you execute a Checkin or Undo checkout command on it.
· Changed (files only) indicates that the item has been modified without first being checked-out. (The user preference Compare files contents instead timestamps controls how Plastic SCM determines that a file has been modified.).
· Not on disk indicates that the object has been deleted from the file system by a program other than Plastic SCM. You can use the Update command to restore such a file to the workspace.
· Cloaked indicates that the item is specified in the workspace-local or user-global cloak file. An Update command bypasses the item (unless you explicitly selected it when issuing the update).
An item’s icon has as icon decoration that indicates its current status. See section Icons and Icon Decorations.
Size
(files only) The size of the file as it currently exists in the workspace.
Type
(items only) Either Directory, Text, Binary, xlink or wxlink. You can change a file item’s type between Text and Binary using the Change revision type command. Plastic SCM uses different algorithms to compare and merge Text and Binary files. See section How Differences are Displayed.
Branch
The branch of the revision loaded into the workspace.
The changeset that contains the revision loaded into the workspace.
Created by
The user who created the revision loaded into the workspace.
A timestamp, indicating either:
· When the revision was created in the repository, or
· When the object was most recently changed in the workspace, either by the Update command or by your modifying it.
See the user preference ‘Update’ operation sets repository file dates on disk.
The repository in which the item and its revisions are stored. (You can configure a workspace to combine items from multiple repositories.)
2.2 Icons and Icon Decorations
The Items column displays an icon for each file system object, indicating its type. These icons are the same found in the operating system. Examples include:
|
|
text file (including program source code) |
|
|
executable program |
|
|
binary file (including Java class files and C object modules) |
|
|
image file (BMP, JPG, PNG shown here) |
|
|
directory (folder) |
Table 1: Icons for file system objects
Unless it’s a private object, an object’s icon has an icon decoration that indicates its current Plastic SCM status. The following table shows some of the ways a text-file icon can be decorated:
|
(none) |
Private |
|
|
Ignored (private objects only) |
|
|
Controlled |
|
|
Checked out |
|
|
Changed |
|
|
Cloaked |
|
|
Not on disk |
Table 2: Icon decorations
This table is not exhaustive, because more than one decoration can appear on the same icon – for example, as with the cloaked file in the table.
2.3 Navigating the Directory Hierarchy
When the Items view is in tree mode:
·
Expand a directory by double-clicking it or by
clicking its 
control.
·
Collapse a directory by double-clicking it or by
clicking its 
control.
When the Items view is in flat mode:
· Drill down into a directory by double-clicking it.
·
Pop up to the parent directory by clicking the 
toolbar button.
2.4 Commands for Source-Controlled Items
Add directory tree to source control
(only for directories) For each selected directory, search for all private objects within the directory tree and convert each one into a source-controlled item. An initial revision is created in the repository for each new item – typically, it’s revision 0 on the /main branch.
Each selected directory is also converted to an item, if it isn’t already under source control. At one or more levels up the directory hierarchy, parent directories are either placed under source control or have new revisions created.
This command does not process private objects that are specified in a workspace-local or user-global ignore file.
For each selected file item and for the entire subtree of each selected directory item, copy the item’s currently configured revision from the repository to the workspace. This normally means bringing the latest changes from the repository to the workspace.
The standard use of Update is to incorporate the changes made by other users whose workspaces are configured the same way as yours. You can also use it to restore files that were inadvertently deleted from your workspace or populate your workspace right after it is created.
You can use Update forced to switch a workspace’s files from read-only to read-write, or vice-versa, after changing the related user preference. See The Other Options Tab.
If an Update operation finds any problem (for instance, a file could not be written because it was blocked by some program), an “Update Report” dialog is displayed at the end of the operation. This dialog lets the user retry the Update, maybe after solving the issue that was causing the trouble.
If there are any pending changes in the workspace when the Update command is performed, an error message is shown indicating that the changes need to be either checked in or undone.
Open
(only for files) Launch the program that the operating system associates with this object.
Open with ...
(only for files) Launch a program that you specify interactively.
Open in Windows Explorer
(Windows only) Open a Windows Explorer window on the selected directory, or on the parent directory of the selected file.
Diff with previous
Open a Diff view, showing the changes you’ve made to the selected file or directory in your workspace. For an item that you have not modified or checked-out, compares the workspace’s revision with its immediate predecessor in the revision tree.
Display a dialog in which you choose two revisions of the selected item, then open a Diff view to compare those revisions. By default, one of revisions is the item as it exists in your workspace. See Figure 48.
Opens the branches, branch explorer, changesets or labels views for the repository of the selected item. These are the same options available in The Repository Browser View context menu of a repository.
This is useful when there are xlinked repositories, since the buttons on the left panel open those views for the main repository (the one where the root directory is in).
Checkout
Items are checked out to signal Plastic SCM that they are being edited. No change occurs to the contents of the item in your workspace. The checked-out revision’s properties include:
· The revision you checked it out from.
· The branch on which a subsequent Checkin will create a permanent new revision.
The item’s status changes to Checked out. You can see the checked out items in the The Pending Changes View.
Create a new changeset containing the changes of each selected checked out of changed item. You are not required to Checkout an item before modifying it in order to check it in. Items that have been modified without having been checked-out have Changed status and can be checked in the same as checked out items.
The set of item revisions created by an invocation of the Checkin command are grouped into a new changeset. Typically, a Pending Changes view dialog box appears, in which you can specify a comment string to be associated with the changeset and all its individual revisions.
This option is provided here for convenience. However, the preferred way to check in items to the repository is to use The Pending Changes View, instead of right clicking on each of them in the items view and creating separate changesets every time you checkin. That view is explicitly designed to check in changes to the repository and is better suited for the job, displaying all the pending changes and letting the user review them with ease before checking in.
If an item has been checked out but has no changes, its state is set back to Controlled (not checked out), but no new revision for that item is created in the repository.
If a user checked in some items in the repository after you started your changes, a dialog will appear asking whether you want to merge the new changes before checking in, or to create branch and checkin your changes there, thus letting you continue working and merge later.
Figure 11: somebody else checked in changes in your branch
More details about this dialog can be found in The Pending Changes View section.
(checked-out items only) For each selected item, discard the checked-out revision in the workspace and download the content it had before the changes from the repository. Since this operation can overwrite changes that are not preserved anywhere else, a confirmation box appears.
To undo your changes to an item with Changed status, perform an Update forced command on it. In The Pending Changes View this is done for you automatically using the “undo changes” button.
Remove from cloaked list
Through a submenu, these options offer to modify a cloaked list, by adding or removing an entry for each selected item. Cloaked items are items that the update operation won’t download by default from the repository to the workspace. Download can be forced using the update forced operation instead. This is convenient in some scenarios, for instance when there are big files in the repository that are updated often, but you don’t really work with them, so you prefer to skip downloading those cloaked files every time you switch the workspace to a different branch or do an update of the workspace.
Cloaked items are defined as entries in file named cloaked.conf. The submenu adds or removes those entries to the cloaked.conf file based on the item that right clicked on.
The entry can be:
· the item’s leaf name: meaning that any file or directory matching that name (inside any directory) will be cloaked.
· the item’s pathname relative to the workspace’s root directory: meaning that the cloaked item is exactly this one.
By default, this command modifies the workspace-specific configuration file cloaked.conf located in the active workspace’s root directory. This file affects the active workspace only.
If you check Apply rules to all workspaces in the confirmation dialog that appears, this command modifies the cloaked.conf file in the plastic subdirectory within your operating system home directory instead. This one affects all your workspaces.
Add to hidden changes list
Remove from hidden changes list
Through a submenu, these options offer to modify the Hidden changes list, by adding or removing an entry for each selected item.
Items in this list are controlled items that can be changed but the user doesn’t want them to appear by default on the Pending Changes view (this is customized in a setting). IT can be the case for libraries that are under source control, but overwritten every time they are compiled and the user doesn’t usually want to the check them in.
Change the leaf name of the selected object, without changing its directory location. This is change to the parent directory, not to the renamed item itself. Accordingly, when you rename an item, a Checkout command is automatically performed on the parent directory (if necessary). However, if you go to The Pending Changes View, the renamed item will appear in the “Moved and renamed items” section.
No checkout occurs when you rename a private object.
Performing an Undo checkout command on the parent directory from the items view has the effect of undoing Renames and Moves within it. In The Pending Changes View, you can just mark the moved item and then click on the “Undo changes” button.
For each selected item, change the directory in which the item resides, without changing its leaf name. A “Select destination” window appears, in which you can navigate through the repository’s directory hierarchy and choose a new parent directory for the item(s). This is a change to both the “from” and “to” directories, but not to the moved item(s). A Checkout command is automatically performed on each directory, if necessary.
To undo a Move, just perform an Undo checkout command on the parent directories involved. As with renamed items, in The Pending Changes View, you can just mark the moved item and then click on the “Undo changes” button.
Deletes the selected objects, which can be private objects and/or source-controlled items.
For a private object: delete the selected objects from the disk.
For an item: perform a Checkout of the parent directory, if necessary, and remove the item’s name from the directory. In the confirmation popup dialog, you also have the option to remove the file or directory from your workspace -- that is, delete it from disk storage.
In the pending changes view you will see the item itself listed as deleted, rather than its parent directory.
The item is not removed from the repository. Rather, its name no longer appears in the checked-out revision of its parent directory. The deletion is “solidified” on your workspace’s branch when you Checkin the parent directory (if using the items view) or select the deleted item in The Pending Changes View and click “Check in”.
At that point, you can still access the item in the previous changesets where it existed. You can propagate the deletion of an item to other branches, just like other changes you make, using the various forms of the Merge command.
You cannot Delete a directory if there is a checked-out item anywhere in its subtree.
To undo a Delete of an item, just perform an Undo checkout command on the parent directory.
Change revision type ... Binary
Change revision type ... Text
Change the revision type of each selected item, to binary or text. The type of an item controls how it is handled by the Diff and Merge tools.
New Folder
(only for directories) Create a new, empty file or subdirectory in the selected directory. The new object has Private status.
Annotate
Open an Annotate view for the selected item.
Open a History view for the selected item, showing its revisions in a table.
Search ... Changed items
Search ... Private items
(only for directories) Run a query to find all the items in the selected directory’s subtree with Changed or Private status. The results are displayed in a new view as a table.
Open a Permissions window for the selected object.
2.5 Commands for Private Objects
Add directory tree to source control
Convert each selected file, and the entire subtree of each selected directory, into source-controlled items. An initial revision is created in the repository for each new item – typically, it’s revision 0 on the /main branch.
At one or more levels up the directory hierarchy, parent directories are either placed under source control or have new revisions created.
Open submenu
Open
(only for files) Launch the program that the operating system associates with this object.
Open with ...
(only for files) Launch a program that you specify interactively.
Open in Windows Explorer
(Windows only) Open a Windows Explorer window on the selected directory, or on the parent directory of the selected file.
Remove from ignored list
Through a submenu, offers to modify an ignored list, by adding or removing an entry for each selected item. The entry can be:
· the item’s leaf name
· the item’s pathname relative to the workspace’s root directory
· the item’s suffix
By default, this command modifies the workspace-specific configuration file ignored.conf located in the workspace’s root directory. This file affects this particular workspace only.
If you check Apply rules to all workspaces in the confirmation dialog that appears, this command modifies the ignored.conf file in the plastic subdirectory within your operating system home directory instead. This file affects all your workspaces.
Rename
Change the name of the selected file or directory. Since the object is Private, this has no effect on the repository.
Delete
Remove the selected file, or the selected directory and its subtree, from disk storage. Since the object(s) are Private, this has no effect on the repository.
New File
New Folder
(only for directories) Create a new, empty file or subdirectory in the selected directory. The new object has Private status.
Chapter 3
The
Pending Changes View
The Pending Changes view shows what changes you have made to the files and directories in the active workspace and lets you review and check them in efficiently.
This view is essentially a “diff” between the workspace and the repository. This view makes it easy to follow through on the changes, either by creating new revisions (Checkin) or by discarding your work (Undo checkout). You can also use this view to convert private objects into source-controlled items.
This view is the central hub where all the changes happening in the workspace are listed together and is the recommended tool to check in changes to the repository. It lists items that have been changed explicitly in Plastic SCM (for instance, an item has been renamed in the Plastic SCM GUI client) and items that have been changed outside (for instance, an items that has been renamed in the Windows Explorer). The later changes are normally considered “local”, since they have not been “applied” yet and Plastic SCM has to detect them.
Figure 12: Pending changes view with different types of changes
You can see in the figure above that your changes are grouped in four categories: changed files, added and private, deleted and moved items.
· Changed files: this is the list of files whose content has changed. It includes checked out files and changed files. By default, the items in this category are selected.
o When checking in items in this category, they will be checked out and then checked in automatically. If an error occurs during the checkin process, the items will be left in checked out state, instead of changed.
o Undoing the changes for this items means that the check outs and changed files
· Added and private: this is the list of files that have been added explicitly to the repository but have not been checked in yet and any private files that have not been added to ignored list.
o By default, the items in this category are not selected. Any item that you select in this group will be added to the repository.
o Out of the box, the GUI checks the items in when they are added (in the items view), but this behavior can be changed in the “preferences” windows by unmarking the option “Checkin files and directories when adding them to source control”.
o Undoing the changes on private items has no effect.
o Undoing the changes on added items makes them private again.
· Deleted items: this is the list of deleted items, either explicitly deleted in Plastic SCM (using the delete command on the items view) or deleted in the workspace (moved locally).
o When checking in the items in this category, they are removed from the current branch. They are still available in the older changesets.
o Undoing the changes on this category means that the items are downloaded back from the repository.
· Moved items: this is the list of items that have been moved or renamed on the workspace.
3.1 Changing the Set of Displayed Revisions
The “Options” button lets you configure what happens when the pending changes view is open or refreshed. A set of checkboxes provides a filtering capability. Use the checkboxes to include/exclude categories of objects from the Pending Changes listing.
Figure 13: the pending changes options window
Show checked-out items
Include items that have been Checked out. An item gets this status through the Checkout command.
Show changed items
Include revisions that have Changed status. A file item gets this status when you modify it in the workspace without having executed the Checkout command on it.
A directory item never has Changed status. For example, if you rename a file from myfile.txt to newname.txt outside of Plastic SCM, its parent directory’s status does not change. Instead, Plastic SCM sees that item myfile.txt is missing from the workspace, and a new Private file, newname.txt, has been created. Then it can be detected as moved / renamed.
Show private items
Include objects that have Private status. These are files and directories that have not been placed under source control. You can use the Checkin or Add to source control command in this view to place such objects under source control.
Show ignored objects
Refine the display of Private-status objects:
· If checked: include files and directories that are matched by the ignored list that applies to this workspace.
· If cleared: exclude such files and directories from the listing.
Show hidden changed objects
Include controlled items that have been added to the “Hidden changes list” in the Items view.
Show manually deleted items
Include items that have been deleted outside Plastic SCM. These are controlled files or directories that have been deleted from the workspace.
Show manually renamed / moved items
Include items that have been moved or renamed outside Plastic SCM. These are controlled files or directories that have been moved or renamed on the workspace.
Plastic SCM uses a matching algorithm to detect when a controlled file or directory has been moved (or renamed) inside the workspace, even if its content have modified as well.
3.1.1 Options and performance
The list of checked out items is stored in the workspace information directory (.plastic) locally in the disk, so retrieving it is very fast.
Since detecting changed, added, deleted and moved items requires scanning the workspace directory tree, it can be convenient to configure the extent of this scan in some scenarios (i.e. when the workspace has hundreds of thousands of items, or there are many added and deleted items, or the disk is busy for instance performing a build, it can take some time to complete this scan).
If only the “Show checked-out items” option is marked, the pending changes view will not traverse the workspace directory tree when it is refreshed. So when the workspace has many items and the disk not very fast, you may want to unselect the other options and checkout your files when you modify them so that they appear in the pending changes view and they can be easily checked in.
3.2 Columns in the Pending Changes View
This view contains a subset of the Items view columns: Item, Type, Branch and Repository. It also includes an Extension column, which lists the suffix (if any) of the item’s leaf name.
The Status column has different values from those seen in the Items view. Here is a detailed description of the possible values in the Pending changes view:
· Changed files:
o Checked-out: when a controlled item has been changed in the workspace (edited) and Plastic SCM has been told about it (i.e. the item has been checked out in the items view or any of the third party integrations).
o Changed: the controlled item has been changed in the workspace, but Plastic SCM has not been told about it.
· Added and private:
o Added: the item has been added explicitly to Plastic SCM, but is checked in yet.
§ Note that out the box, the Plastic SCM GUI will automatically check in items when they are added using from the items view, so they don’t appear here.
§ Items appear here if they have been added with a “cm add” command in the command line interface or if adding them through the items view when the preference “Check in files and directories when adding them to source control” has been deselected in the “preferences - other options” window.
o Private: the item is not added to the source control and not fitting any of the ignored patterns (unless the “show ignored items” option has been set in the pending view options as described in Changing the Set of Displayed Revisions.
· Deleted items:
o Removed: the controlled item has been deleted from the workspace using the delete command in the items view (or any of the third party integrations).
o Removed locally: the controlled item has been deleted in the workspace outside Plastic SCM (for instance, in the Windows Explorer).
· Moved items:
o Moved: the controlled item has been moved or renamed in the workspace using the “Move” or “Rename” commands in the items view (or any of the third party integrations).
o Moved locally: a controlled item has been moved or renamed outside Plastic SCM. The pending changes view checks the items that are no longer available and tries to match them with the private items to determine if it’s the same item. A similarity algorithm is used for matching, so that items that have been moved and changed are still detected as the same item.
§ The similarity value is displayed of the “Similarity” column. Only locally moved items have a value in this column.
3.3 Commands in the Pending Changes View
3.3.1 Toolbar Commands
The toolbar in this view contains command buttons that act on the set of items with checks in the Item-column checkboxes (independent of the standard row-selection mechanisms):
Figure 14: the pending changes view toolbar
Refresh
Refresh the content of the view filtering according to the options as described on Changing the Set of Displayed Revisions.
Checkin
Perform a Checkin command on all checked items, including changed, added, moved and deleted. Behavior has been described at the beginning of this chapter.
This button has expanded options letting the user use a checkin variant: “Checkin changes to other branch”.
Figure 15: Checkin alternate operations
In this case, a new window appears to select the branch to where the changeset created on checkin will go, as shown in Figure 16.
Figure 16: checking in changes to other branch
When “Create new branch” is selected, several things happen:
· The new branch is created
· The workspace is switched to the new branch
· The checkin changeset is created in the new branch.
When “Select an existing branch” is selected, keep in mind that it has to be an empty branch and its base (starting changeset) will be changed to be the current changeset of the workspace.
Undo changes
This button undoes the changes of the selected items. A dialog is displayed asking for confirmation, since undone changes cannot be recovered.
This button has an additional option as shown in Figure 17: “Undo unchanged”. This option will remove from the list any checked out items or items detected as changed when they have no real changes in their content.
Figure 17: Undo changes extended options
Options
Opens the pending changes view filter options as described in Changing the Set of Displayed Revisions.
Show diffs
Toggles display of the differences panel at the bottom. The differences panel shows the differences of content of the selected item with its previous version.
Clear / Check all
Select or deselect all the items in the pending changes view.
3.3.2 Context Menu Commands
The commands available right-clicking on an item in the pending changes view vary slightly depending on the category of the item.
Figure 18: context menu of items in the pending changes view categories
Open
Same as the “Open” submenu in the items view.
Diff
Same as the “Diff” submenu in the items view.
Search matches
When a file is moved in the workspace out of Plastic SCM control and then heavily changed, Plastic SCM may fail to recognize the item as moved and detects it as one added item and another deleted item. This is the case when the similarity percentage is below the threshold set for moved items detection (default 90%).
The search matches option lets the user match the added item with the deleted item to tell Plastic SCM that they are actually the same item and the history of the original item is preserved. It’s the way to tell Plastic SCM that the items it is detecting as added + deleted are actually one single moved or renamed item.
Figure 19: match added item with deleted to identify a move or rename
The similarity threshold can be adjusted for this specific item using the “Min similarity accepted” slider. As you move the slider to the left, the deleted items that match are shown in the list. Once the item is manually selected and the “Accept the selected match” button is clicked, the item appears in the “Moved items” category.
Apply local change
For local operations, make Plastic SCM aware of the change, or apply the change to the workspace. See “The Pending Changes View” at the beginning of this chapter for more details on local operations.
Delete
Delete the item from the workspace, same as the “Delete” command in the items view.
Add to hidden changes list
PENDING
Add to ignored list
Add the selected item to the ignored filter. See “Commands for Private Objects” in the items view for more details.
Change revision type
Change the type of the selected item to either text or binary. See “Commands for Source-Controlled Items” in the items view for more details.
Annotate
Launch a new view of the selected item with line by line annotations about the author, changeset and branch that last modified it.
View history
Display the reversion history of the selected item as described in The History View.
3.4 Merge in the pending changes view
When a branch or changeset is merged, the items are left in checked state. The pending changes view will display these items and also provide information about the merge operations that have been performed and are pending to be checked in. This is depicted in Figure 20.
Figure 20: merge link information in the pending changes view
Chapter 4
The BranchExplorer View
The BranchExplorer view provides an interactive diagram of a repository’s development activity. It shows:
· The repository’s branch hierarchy, showing the branches’ inheritance relationships.
· The development that has taken place on branches, as recorded in the individual changesets created by Checkin commands.
· The merge operations that have been performed to integrate different branches’ development work.
· The labels that are applied on changesets.
Figure 21: BranchExplorer view
The BranchExplorer makes it easy to “drill down” from the highest level (the repository and its branches) to the lowest level (changes to individual code statements in revisions).
In addition to viewing past activity, you can use the BranchExplorer to perform new development operations: switching the active workspace to another branch, creating branches, merging from one branch (or changeset) to another, diff the changes made in branches and changesets and more.
4.1 Components of the BranchExplorer Diagram
The BranchExplorer diagram is 2-dimensional:
· The vertical dimension is structural – the /main branch appears at the very top; higher-level branches appear toward the top of the diagram; lower-level branches toward the bottom. The hierarchical connections among the branches are indicated by branch base links: each branch is connected to its parent branch by such a link.
· The horizontal dimension is temporal –whenever a Checkin creates a new changeset on a branch, it is represented in the diagram as a new rounded-corners rectangle (almost a circle, actually) within the branch. Thus, a branch grows rightward over time as development takes place on it. To help you map development changes to the calendar, shading bands divide the horizontal dimension into separate days.
By default, the BranchExplorer displays development activity for the previous three months only. See The Display Options Tab below.
The BranchExplorer displays these kinds of Plastic SCM objects: branch, changeset, label, branch base link, and merge link. Figure 21 at the beginning of this chapter shows these elements in the diagram. Here are the details:
· branch – a branch is represented as a gray rounded rectangle that grows rightward as changesets are checked-in into it.
· changeset – each changeset is created on a particular branch. It records the creation of new revisions in the repository (Add to source control or Checkin).
Changesets are joined together with a link arrow that always goes from a changeset to its parent. This is true even for changesets in different branches: the first changeset on a new branch will be linked to its parent changeset on the other branch.
· label – the BranchExplorer indicates that a label has been applied to a changeset with a green circle around it. If more than one label has been applied to a given changeset, the circle is split in up to four sectors to give a visual clue of how many labels are applied.
o Commands for all the labels are available with right clicking on the green circle.
· branch base link – the branch base link is just a changeset parent link. The only difference is that it goes to a parent changeset in a different branch.
o When a branch has been just created, no changesets are inside it. The empty branch has a branch base line pointing to the changeset or label that has been used as base.
· merge link – when you merge two branches using the Merge from this branch command, the BranchExplorer indicates the merge by drawing a green arrow; it connects a changeset on the source branch (typically, the latest of the branch) to the changeset on the destination branch that records the Checkin of the merge results.
o There are more merge links for special types of merge like cherry picks or subtractive merges. A reference panel about these types can be shown anytime clicking the “Legend” button on the Branch Explorer toolbar like the one shown in Figure 22.
Figure 22: legend panel in Branch Explorer
4.2 Navigating the Diagram
Plastic SCM makes using branches easy, so it’s likely that a given repository has a large number of them. Accordingly, the BranchExplorer provides numerous facilities for navigating the branch hierarchy, so that you can concentrate on the ones you care about right now (and ignore the ones you don’t):
· Scroll bars – scroll bars are located at the bottom and right edges of the BranchExplorer diagram. The size of the draggable bar indicates how much of the horizontal or vertical dimension is currently visible.
· Dragging the diagram – Using the left mouse button, you can click-and-drag anywhere in the diagram to move it in any direction.
· Navigator panel – Click the Show navigator button in the BranchExplorer toolbar to open a navigator panel below the diagram. This panel uses a tinted “viewport” highlight to indicate which portion of the entire branch-hierarchy diagram is currently visible. You can drag this highlight to scroll the display, or click anywhere in the navigator panel to center the viewport there.
Figure 23: Navigator panel
· Search for objects – The BranchExplorer toolbar includes a search box that will highlight and let the user navigate through all the objects that contain the entered string. The search includes branch and label names as well as changeset numbers.
o Once you have entered the string to search for, hit enter to highlight the matching objects in the diagram and use the “Next” and “Previous” buttons to navigate through the results. The diagram will scroll to make the highlighted search result visible.
Figure 24: Search for and highlight branches
· Use the “Clear highlights” to remove the temporary highlighting applied to search results.
4.3 Commands in the BranchExplorer View
4.3.1 Toolbar Commands
Figure 25: Branch Explorer toolbar
Zoom in
Make the diagram larger.
Zoom out
Make the diagram smaller.
Navigator
Toggle the display of the Navigator panel. (Note that the Navigator and Stats panels cannot both be visible at the same time.) See section Navigating the Diagram above.
Statistics
Toggle the display of the Stats panel. (Note that the Navigator and Stats panels cannot both be visible at the same time.) This panel displays a bar graph, showing the number of changesets created each day during the interval that the BranchExplorer is currently displaying. You can configure this interval in The Extended Options Panel.
Options
Toggle the display of The Extended Options Panel.
Legend
Toggle the display of the legend panel.
Keyboard shortcuts
Open a window with a summary of the keyboard shortcuts for the Branch Explorer.
Figure 26: Branch Explorer keyboard shortcuts
4.3.2 Context Menu Commands
The Branch Explorer is a fully interactive diagram in which most of the objects can be operated. The user can right-click on branches, changesets, labels and merge links to get the context menu of an object and launch any command. The context menu for each of those objects is the same found in the specific views. For instance, the Changeset context menu found in the Branch Explorer is the same as the one in the Changesets view. Only the Branch context menu adds a “Branch Explorer” submenu, with options specific to the Branch Explorer.
4.3.3 Branch Context menu commands
Create a child branch of the selected branch (which becomes the “parent” of the new branch). A New Branch dialog appears, in which you enter specifications for the new child branch.
Figure 27: new branch dialog
· Branch name – Enter a simple (“leaf”) name only. The new branch’s complete name includes the “path” of parent branches. For example, specifying task123 as the branch name might create a branch whose complete name is /main/integration/task123.
· Comments – Optional comment string, which will be displayed in a Branches view column.
· Starting point – Where this branch starts from. This is always a changeset, but it can be specified through several choices:
Label – (recommended SCM “best practice”) Use the changeset pointed by a label as the branch base. Note that if the label is moved to another changeset, the branch will still have use the old changeset as base.
Changeset – Specify one of the changesets on the parent branch. A dialog appears, in which you choose a changeset (Figure 28). This dialog is similar to The Changesets View, only difference being that by default it is set to filter changesets from the last month on the parent branch. The user can adjust this filter using the “Advanced” button.
Figure 28: Select changeset window
Last changeset on parent branch – Same as the preceding choice, but automatically select the changeset that was most recently created on the parent branch. This changeset remains fixed as the branch base, even if additional changesets are subsequently created on the parent branch.
Switch workspace to this branch – As a convenience, the dialog offers the possibility of directly switching the workspace to the new branch created.
Switch workspace to this branch
Change the workspace’s configuration to use the selected branch. This modifies the workspace’s configuration to point to the selected branch and then performs an Update to make the workspace’s actual contents match the contents of the branch.
Plastic SCM first checks whether there are any pending changes and if so, prevents the user from continuing the switch operation by displaying an error window (Figure 29).
Figure 29: Error dialog shown when changes are pending before switching to a branch
In this case, the user should go to The Pending Changes View and either check in or undo any pending changes before switching to the branch. If needed, it is possible to checkin any pending changes in a new branch from The Pending Changes View. This operation will also switch the workspace to that new branch automatically.
Advanced merge > Cherry pick from this branch
Open a Merge Organizer window, with an entry for each item that has revisions on the selected branch. Using the Merge Organizer window, you can perform a standard merge or a cherry-pick merge for some or all the items. For each item, the contributors to the merge are:
· source: the last revision on the selected branch
· destination: the item as it exists in your workspace
Diff branch
Open a SuperDiff window (as described in The SuperDiff Window) to compare the items changed in the branch. This command will compare the latest versions of the items in the branch with the revisions in the branch base changeset.
Figure 30: Diff branch command
Diff >
Diff with label
Diff > Diff with other branch
Open a SuperDiff window (as described in The SuperDiff Window) to compare the latest revisions in the selected branch with the revisions in a label or another branch.
View > View changesets in branch
Open a Changesets view, listing all the changesets created on the selected branch. The listing is created by a query in this form:
find changeset where branch='branch-spec' on repository 'repository-spec'
Using the Advanced mode in this view, you can modify the query and re-execute it any number of times.
View > Explore changesets in branch
Open a Branch Changes window, enabling you to browse though all of the selected branch’s changesets (the same collection of changesets displayed by View changesets in branch), drilling down to individual items and individual changes in those items.
View > Browse repository on this branch
Open a Repository Browser view, configured with the selected branch. This is a virtual view into the repository; no data is transferred to the workspace. This command is useful when you are working on one branch, and you wish to see how the source base would look if you were working on another branch.
Note: the replication commands described below can use your day-to-day user profile (see The General Preferences Wizard) or an alternative profile (see The Profiles Tab). With all these commands, you enter replication specifications in a pop-up dialog box. See section The Replication Dialog. For a complete description of Plastic SCM’s replication facility, see the Plastic SCM Distributed System Guide.
Replication > Push this branch
Send all revisions on the selected branch, along with associated metadata, to a repository at another Plastic SCM site. You choose the remote Plastic SCM server and repository in a popup dialog.
Replication > Pull this branch
Bring all revisions on the selected branch in a repository at another Plastic SCM site, along with associated metadata, into the workspace’s repository. You choose the remote Plastic SCM server and repository in a popup dialog.
Replication > Pull remote branch
Same as above, except that you choose the remote repository’s branch in a popup dialog.
Replication > Create replication package from this branch
“Offline” version of Push this branch: instead of sending the data to a specified remote site immediately via the network, store the data in a replication package file. This file can subsequently be imported at any Plastic SCM site(s).
Replication > Create replication package
Same as above, except that you specify the source (Plastic SCM server, repository, branch) in the dialog box, along with the replication package file.
Replication > Import replication package
Complete a replication data transfer by incorporating the data in a specified replication package file into a repository at your site.
Branch Explorer submenu
The Branch Explorer submenu is only available in the Branch Explorer view and offers filtering and navigation commands specific to this view.
Branch Explorer > Go to branch base
Scroll the diagram to the branch base changeset of the selected branch.
Branch Explorer > Show selected branches in a new diagram
Open a new filtered Branch Explorer view that only contains the selected branches.
Branch Explorer > Show selected and related branches in a new diagram
Open a new filtered Branch Explorer view that only contains the selected branches plus those connected to them through changeset parent links or merge links.
Branch Explorer > Show pending merges for selected branches in new diagram
Open a new filtered Branch Explorer view that contains the branches whose base changesets are on the selected branches and have changes that have not been merged yet.
Branch Explorer > Show custom diagram of the selected branches
Open a new filtered Branch Explorer view that contains the branches matching the criteria selected in the dialog that pops up.
Figure 31: Custom Branch Explorer options
Rename
Change the name of the selected branch. This does not automatically modify the selector of the active workspace or any other workspace.
Delete
Permanently remove the selected branch from the repository. This is allowed only if no item has a revision on the branch.
New code review for this branch
Create a code review for the selected branch, and optionally open it in a Code Review window. You specify the code review’s title, initial status, and initial assignee in a popup dialog.
Create top-level branch
Create a branch that is not a child (or grandchild, etc.) of any other branch. This only affects the name assigned to the branch. To all effects, a top level branch behaves exactly as a child branch.
Properties
Open a Branch Properties view, in which you can view and/or modify the branch’s name, its comment string, and the branch history.
Permissions
Open a Permissions window for the selected object.
4.3.4 Changeset context menu commands
The commands available when a changeset is right clicked are the same described in the “Commands in the Changesets View” commands.
4.3.5 Label context menu commands
Labels are represented in the Branch Explorer as circles around the changeset they are applied to and, of course, several labels can be applied to the same changeset. When it happens, a right clicking on the labels circle shows a top level menu with all the labels. And the commands for each of them are defined as submenus. This situation is depicted in Figure 32.
Figure 32: Multiple labels in changeset in Branch Explorer
The commands available for labels are the same described in the “The Labels View” section. Please check that section for more details.
4.4 The Extended Options Panel
Visibility of the BranchExplorer view’s extended information panel is toggled by the “Options” button in the toolbar. The panel includes several tabs, stacked vertically.
4.4.1 The Properties Tab
This tab displays information on the selected object – the same information that is displayed in the Branches, Changesets or Labels view, along with information on replication.
4.4.2 The Display Options Tab
The “Display Options” tab controls the appearance of the Branch Explorer diagram. Checkboxes of the top set what objects are shown.
Figure 33: Branch Explorer display options
The options in the panel are detailed below:
· Display branches: toggles the display of branches in the diagram.
· Display merge links: toggles the display of merge links in the diagram
· Display cross-branch changeset links: toggles the display of branch base links between changesets in the diagram.
· Display labels: toggle the display of labels in the diagram.
· Display branch’s task info: toggle the display of task info when integration with an Issue Tracking System has been setup.
· Display only relevant changesets: toggles the display of changesets that don’t have merge or branch base links on them. When changesets are hidden by this mode, the changeset parent link becomes dashed.
Figure 34: show only relevant changesets mode enabled in Branch Explorer
· Display branch levels: this setting controls how many branch levels are displayed in the diagram. The level of a branch is determined by how many parent branches it has. Figure 35 depicts this.
Figure 35: branch level
· Date filter: by default the Branch Explorer view displays the last three months of activity in the repository. The data filter lets you set the data range that is displayed in the diagram.
Figure 36: Branch Explorer date filter
·
Enter visibility mode: the visibility mode lets the user hide or show branches in the
diagram. The hidden branches are not displayed across session of the Plastic
SCM GUI. The hidden branches list is local to the client machine, so if a user
hides a branches, it’s not visible for her but is visible for the other users.
To hide a branch and all its children, double click it. Use Shift + double
click on a branch to hide it but not its children.
Once the visibility is set, click the “Exit visibility mode” button confirm the
visibility changes.
Figure 37: Display options - visibility edition mode
Enter re-layout mode: the re-layout mode lets the user set the vertical order of branches, so it is easy to have the most relevant branches at the top, for instance. Click on a branch to select it and then the cursor keys up and down to move it to the desired location. Only the vertical position can be changed, since the horizontal scale is time and changesets have a specific date so it doesn’t make sense to move them. When a branch has been explicitly relocated, its color changes to yellow.
Figure 38: Branch Explorer re-layout mode
It is also possible to reset the diagram to its default layout clicking the “clear all the re-layout data” in the panel, as well as the setting for any specific branch.
4.4.3 The Conditional Format Tab
Using this tab, you can color-code the rounded rectangles that represent branches, but setting one or more “format rules”. If a branch is selected by one of the rules, the BranchExplorer will display it with the background color you configure. (If multiple rules match, the first one “wins”.)
Here’s a procedure for using this tab:
1. Click the Add Format Rule link, then select the kind of rule to add:
· Non-integrated branches – a predefined rule that selects all branches that contain one or more changesets that have not yet been merged to any other branch.
· Branches used in the workspace –a predefined rule that selects all branches that are explicitly mentioned in the workspace’s selector. Typically, it selects the one branch that is the workspace’s active branch.
· Simple query rule –a custom rule, in which you can enter any SCM-level query that yields a set of branches as its result. You must omit the initial find branches where part of the query. Examples:
owner is "mary"
parent = "/main"
An error occurs if you enter a query that yields an empty result. For more details on the queries supported, refer to the Plastic SCM Reference Guide.
2. (optional) Double-click the rule’s color swatch to open a color-selection dialog. Use this dialog to change the rule’s color from the one that Plastic SCM has assigned automatically.
3. Click the Apply button.
A common use of the conditional format is to highlight branches with specific attributes applied to them. For instance, a user may define a “Status” attribute and apply values such as “Pending”, “In Progress” or “Completed” to different feature branches. Then, define 3 conditional format rules to apply a red color for “Pending” branches, orange for “In progress” and green for “Completed” ones.
Figure 39: sample conditional format usage in Branch Explorer
For more details on attributes and how to define and apply them, refer to The Attributes View section.
4.4.4 The replication sources tab
A replication source is a remote repository from which branches have been replicated to the current repository at some point.
By default, changesets that have been replicated from remote repositories are drawn with a different color in the diagram. This tab controls that color coding and it also lets the user connect to those remote repositories to explore their contents.
Note: the color coding only indicates that the changesets came from a replication operation, but they are actually in the current repository. They are replicated from the other repository, so they exist in both places.
Figure 40: replication sources in Branch Explorer
Customizing the replication sources
The replication sources tab can customize the appearance of changesets. Figure 41 summarizes what can be customized for each source.
Figure 41: customizing the replication source display
Exploring remote repositories
When a replication source is online after activating the “Show remote data” checkbox, the branches and changesets in that remote repository are displayed with dashed lines (Figure 42). Right clicking on these changesets, it is possible to diff the changes, browse the repository as is it on those changesets or compare them with any other local changeset.
Figure 42: changesets from remote repositories in the Branch Explorer.
4.4.5 The Issue Tracking System Extension Tab
This tab appears only if you’ve configured an integration between Plastic SCM and an issue tracking system (ITS). (See The Issue Tracking Tab.) The tab displays certain fields from the record that corresponds to the currently selected branch.
For more information, see the Plastic SCM Integrations manual.
4.5 The Replication Dialog
The pop-up dialog that appears for each replication command enables you to enter the specifications for transferring data from one site to another. Depending on the operation, this can include the identifier of a remote repository server, the name of a local repository and a branch within it, and a pathname for storing a replication package file.
When you’ve entered all the specifications, click the Replicate button to perform the operation.
Note: the replication operations are extensively described in the Plastic SCM Distributed System guide.
Figure 43: Replication window
4.5.1 The Replication Advanced Options Dialog
The Advanced Options button opens another dialog, in which you can specify options related to user identities:
Remote server configuration profile
By default, the replication operation will be performed at the remote site under the same user identity that you’re currently using at the local site. However, it is possible to define connection profiles for different servers.
If a different identity must be used at the remote site, or if a different user-authentication scheme is employed at that site, specify a replication profile here. You can create such a profile in the Preferences window – see section The Profiles Tab.
User translation mode
This option specifies how the user identities recorded in repository database records at the sending site are to be interpreted at the receiving site. This is useful when the source and destination Plastic SCM servers are configured to use different authentication methods, or the credentials used to connect to the remote server are not the same as those used in the local one. These are the possible values:
· Copy – User identities are simply copied into the new database records at the receiving site. This method is valid only if both sites employ the same user-authentication scheme and have the same user database.
· By name – The user identity in a database record is sent to the receiving site as a name; it is converted there to a local user identity– either by the repository server itself or by another process (for example, an LDAP server). This is correct when the same user name is available to both source and destination Plastic SCM servers.
· Use translation table –Similar to By name, but an incoming user name at the receiving site is first translated to another name before it is converted into a local user identity. You specify a file containing a simple table to drive the name-translation process. Each line of the table is in this form:
sending-site-name ; receiving-site-name
Here’s an example, in which short names at the sending site are converted into corresponding long names at the receiving site:
rafa;rafael.nadal
rog;roger.federer
arod;andy.roddick
4.6 Commands for Changesets
The commands that you can execute on one or more selected changesets in this view are the same as in the Changesets view.
4.7 Persistence of BranchExplorer Settings
When an instance of the BranchExplorer closes, Plastic SCM saves the current state of its Navigator, Stats, and Extended Information panels in file branchexplorer.cfg, located in the plastic subdirectory within your operating system home directory. Both the panel’s current visibility and their various options settings are preserved. Likewise, the zoom level of the branch-hierarchy diagram is saved in the configuration file.
All these settings are restored the next time you open a BranchExplorer for the same workspace.
Chapter 5
The Branches View
The Branches view lists all the branches that have been created for the workspace’s repository(s). (The BranchExplorer view provides an alternative, showing the branches in a diagram instead of a table.)
5.1 Columns in the Branches View
Name
The branch’s name.
Repository
The repository in which the branch was created.
Owner
The user who created the branch.
Creation date
A timestamp indicating when the branch was created.
Comment
The comment string associated with the branch.
5.1.1 The Extended Information Panel
The Show extended information toolbar button opens the Branches view’s extended information panel, which has two panes.
The Properties pane repeats the main table’s information on the selected branch, and also adds information on replication and more room to display the comment. It’s interesting to note that the object comment can be edited here by clicking on the “Comments” text box. As soon as a key is pressed to edit, a “Save” button appears to persist the changes.
The Attributes pane lists the attributes that are currently applied to the selected branch. You can use this pane to revise an attribute’s value or unapply the attribute from this branch. You can also click the Add attributes button to apply additional attributes to the branch.
5.2 Commands in the Branches View
5.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
5.2.2 Advanced
Toggles the toolbar’s Advanced mode, in which you can view and customize the query that produced this view’s table. See section Advanced Mode: Revising the Query that Produces a Table.
Display the view’s extended information panel (see above). To close the panel, use its “x” button.
5.2.3 Context Menu Commands
A branch has the same context menu in the Branches view as in the BranchExplorer view. See section Commands in the BranchExplorer View.
Chapter 6
The Changesets View
The Changesets view lists some or all of the changesets created by Add to source control and Checkin commands in a particular repository.
· When you open a Changesets view using the Changesets button, only changesets created in the past 30 days are listed.
· Similarly, when you open a Changesets view using the View changesets command in the Repositories view, only changesets created in the past 30 days are initially listed.
· When you open a Changesets view using a branch’s View changesets in branch command, all of the branch’s changesets are listed.
Subsequently, you can use the toolbar’s Advanced mode to modify a time constraint or otherwise revise the query that produced the changeset listing. See section Toolbar Commands below.
6.1 Columns in the Changesets View
Name
The integer sequence number that uniquely identifies the changeset within its repository, at a particular site. (In a distributed development environment, the collection of changesets in a repository varies from site to site.)
Comment
The comment string entered during the Add to source control or Checkin command that created the changeset.
Creation date
A timestamp indicating when the changeset was created.
Branch
The branch on which the changeset’s revision(s) were created.
Created by
The user who invoked the command that created the changeset.
Repository
Guid
The Globally Unique Identifier of the changeset. This alphanumeric string identifies a changeset uniquely among different repositories. Since replicated changesets may have a different number than they had in the repository they were replicated from, this GUID helps to unequivocally identify the changes in different repositories. A GUID is a 128 bits value represented in hexadecimal notation.
6.1.1 The Extended Information Panel
The Show extended information toolbar button opens the Changesets view’s extended information panel, which has two panes. It’s interesting to note that the object comment can be edited here by clicking on the “Comments” text box. As soon as a key is pressed to edit, a “Save” button appears to persist the changes.
The Properties pane repeats the main table’s information on the selected changeset, and also adds information on replication.
The Attributes pane lists the attributes that are currently applied to the selected changeset. You can use this pane to revise an attribute’s value or unapply the attribute from this changeset. You can also click the Add attributes button to apply additional attributes to the changeset.
6.2 Commands in the Changesets View
6.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Display the view’s extended information panel (see above). To close the panel, use its “x” button.
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
6.2.2 Advanced
Toggles the toolbar’s Advanced mode, in which you can view and customize the query that produced this view’s table. See section Advanced Mode: Revising the Query that Produces a Table.
6.2.3 Context Menu Commands
Open a SuperDiff window, loaded with all the items in the selected changeset and comparing these revisions:
· the revision in the changeset
· the immediate predecessor of that revision in the item’s revision tree
Create branch from this changeset
Perform a Create child branch command, with the selected changeset as the new branch’s branch base.
Create a new label and apply it to the selected changeset. See Commands in the Labels View for more details on the new label dialog window.
Merge from this changeset
Open a merge organizer window. This option is the same as merging the branch where the changeset is located, except that instead of merging the full content of the branch, the merge operation considers changes in the branch up to the selected changeset.
Advanced merge > Subtractive merge from this changeset
Open a Merge Organizer window, with an entry for each item in the selected changeset. Using the Merge Organizer window, you can perform a subtractive merge for some or all the items. This will effectively remove the changes that were introduced by this particular changeset from the current revisions loaded in the workspace.
Cherry pick from this changeset
Open a Merge Organizer window, with an entry for each item in the selected changeset. These items are the same listed using the “diff changeset” command above. For each item, the contributors to the merge are:
· source: the revision in the selected changeset
· destination: the item as it exists in your workspace
Diff with other changeset
Open a SuperDiff window, comparing the revisions in the selected changeset with the revisions in another changeset. You choose the other changeset in a popup dialog.
Browse repository on this changeset
Open a Repository Browser view, configured with the selected changeset. This is a virtual view into the repository; no data is transferred to the workspace. For example, you might use this command to “turn back the clock” to a point earlier in the evolution of the branch you’re working on as see how the revisions as they were back at that point.
New code review for this changeset
Create a code review for the selected changeset, and optionally open it in a Code Review window. You specify the code review’s title, initial status, and initial assignee in a popup dialog.
Chapter 7
The History View
The History view displays all the revisions of an item – the initial revision created by Add to source control, and all the subsequent revisions created by Checkin.
This view also contains an entry for each namespace change -- Delete, Rename, or Move -- involving the item (even though such a change is recorded as a new revision of the parent directory, not of the item itself).
7.1 Columns in the History View
The changeset the revision is part of. Since the history view can display namespace changes, the changeset number listed can have these values:
·
Content change: the changeset number is the changeset identifier of this revision of the item.
·
Namespace change: the changeset number is the changeset identifier
of the parent directory’s revision that records the removal, renaming, or
moving to another directory of the item.
Branch
The branch of the changeset
Comment
The comment string of the changeset described above.
Creation date
The timestamp of the changeset described above.
Markers
The labels that are applied to the changeset described above.
Owner
The user who created the changeset described above.
Description of task on this branch
Information from the issue tracking system (ITS) record associated with the branch containing this revision. A value appears in this column only if the GUI is configured to integrate with an ITS and the connection is currently active. (See section The Issue Tracking Tab.)
7.2 Commands in the History View
7.2.1 Toolbar Commands
The toolbar includes the following control:
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
7.2.2 Context Menu Commands
A selected revision’s context menu contains these commands:
Open submenu
Open
(only for files) Launch the program that the operating system associates with this object.
Open with ...
(only for files) Launch a program that you specify interactively.
Save this revision as
(only for files) Save the selected revision as a file on disk. A standard operating system choose-pathname window appears.
Diff with previous
Open a Diff view, comparing the selected revision with its immediate predecessor in the revision tree.
Differences with other revision...
Display a dialog in which you choose two revisions – by default, the selected revision and the item as it exists in your workspace. Then open a Diff view to compare those revisions.
Revert to this revision
Create a new revision of the item, using the contents of the selected revision. You are prompted to specify a Checkin comment for the new revision.
Diff revision’s branch contents
Open a SuperDiff window that compares the changes in the branch on which the revision is contained.
Diff revision’s changeset contents
Open a SuperDiff window that compares the changes in the changeset on which the revision is contained.
Permissions
Open a Permissions window for the selected object.
Chapter 8
The Labels View
The Labels view lists all the labels defined for the workspace’s repository(s). You can use this view to create new labels and to rename or delete existing ones. You can also execute a number of commands, such as applying a selected label to all the revisions currently in the workspace.
8.1 Columns in the Labels View
Name
The label’s name.
Changeset
The changeset on which the label was applied to.
Repository
The repository in which the label was created.
Owner
The user who created the label.
Creation date
A timestamp indicating when the label was created.
Comment
The comment string associated with the label.
8.1.1 The Extended Information Panel
The Show extended information toolbar button opens the Labels view’s extended information panel, which has two panes. It’s interesting to note that the object comment can be edited here by clicking on the “Comments” text box. As soon as a key is pressed to edit, a “Save” button appears to persist the changes.
The Properties pane repeats the main table’s information on the selected label, and also adds information on replication.
The Attributes pane lists the attributes that are currently applied to the selected label. You can use this pane to revise an attribute’s value or unapply the attribute from this label. You can also click the Add attributes button to apply additional attributes to the label.
8.2 Commands in the Labels View
8.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Display the view’s extended information panel (see above). To close the panel, use its “x” button.
Create new label
Open a New Label dialog, in which you can define the name and comment of the new label, as well as the changeset to apply it on. By default, the changeset field is filled in with the value of the current changeset loaded in the workspace.
Figure 44: create new label dialog
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
8.2.2 Advanced
Toggles the toolbar’s Advanced mode, in which you can view and customize the query that produced this view’s table. See section Advanced Mode: Revising the Query that Produces a Table.
8.2.3 Context Menu Commands
The context menu of a selected label includes the following commands:
Apply label to workspace contents
Apply the selected label to the changeset currently in the workspace. The command will display an error if there are any pending changes in the workspace.
Switch workspace to this label
Change the configuration of the workspace to load the revisions as they were when the label was applied. A message noting that this is a read-only configuration is displayed.
Browse repository on this label
Open a Repository Browser view, configured to view all the revisions that the selected label is applied to. This is a virtual view into the repository; no data is transferred to the workspace. If you wish to actually load the labeled revisions into the workspace, use the Switch workspace to this label command.
Merge from this label
Open a Merge Organizer window to merge the changeset to which the label is pointing to with the current content of the workspace. This operation has the same effect as “Merge from this changeset” described in section Commands in the Changesets View.
Create branch from this label
Create a new branch using this label as the branch base. See “Create a child branch” command in section Commands in the Branches View for more details on the “New branch window”.
Rename
Change the name of the selected label. This change is automatically reflected in the Labels column of a History view. But it is not automatically applied to the any workspace that is configured with the label (see Switch workspace to this label).
Delete
Permanently remove the selected label(s) from the repository. This also removes all the applications of the label(s) to item revisions.
Open a SuperDiff window, comparing each item’s revision that has the selected label with its revision that has another label. You choose the other label in a popup dialog.
Permissions
Open a Permissions window for the selected object.
Chapter 9
The Attributes View
Attributes are user-defined properties that can be applied to Labels, Branches and Changesets. Attributes are created in the Attributes view and then they can be applied to objects with a specific value, different in each case.
For instance, the user can define an attribute called “Task Status” and apply values like “New”, “In progress” or “Completed” to the branches used to implement each task. Combined with the Branch Explorer conditional format and the filtering capabilities available through the Advanced button in several views, attributes let the user build custom intelligence into the Plastic SCM repository.
The Attributes view lists all the attributes defined for the workspace’s repository(s). You can use this view to create new attributes and to rename or delete existing ones.
To apply an attribute/value pair to a label, branch, or changeset, use the Extended Information panel in the Labels, Branches, or Changesets view.
9.1 Columns in the Attributes View
Name
The attribute’s name.
Repository
The repository in which the attribute was created.
Owner
The user who created the attribute.
Creation date
A timestamp indicating when the attribute was created.
Comment
The comment string associated with the attribute.
9.2 Commands in the Attributes View
9.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Create new attribute
Open a dialog where you can define the “Name” and “Comment” of the new attribute.
Figure 45: new attribute dialog
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
9.2.2 Advanced
Toggles the toolbar’s Advanced mode, in which you can view and customize the query that produced this view’s table. See section Advanced Mode: Revising the Query that Produces a Table.
9.2.3 Context menu Commands
The context menu of a selected attribute includes the following commands:
Rename
Change the name of the selected attribute. This change is automatically reflected in the Attributes tab of an Extended Information panel of a Labels, Branches, or Changesets view.
Delete
Permanently remove the selected attribute(s) from the repository. This also removes all the applications of the attribute(s) to repository objects.
Permissions
Open a Permissions window for the selected object.
Chapter 10
The Repository Browser View
The Repository Browser view shows all the revisions in a particular configuration of the repository, as specified by one of these commands:
· Browse repository on this label
· Browse repository on this branch
· Browse repository ion this changeset
This is a “virtual” view into the repository itself, independent of all workspaces. Opening the view does not transfer any data to your workspace. Accordingly, a Repository browser view:
· Does not include any private objects.
· Is not affected by changes that you make to a cloak list. Such changes only affect the downloading of revisions to workspace directories.
10.1 Columns in the Repository Browser View
The column setup for this view is almost the same as that for the Items view. The only difference is the lack of a Status column, which applies only to objects in a workspace.
10.2 Commands in the Repository Browser View
10.2.1 Toolbar Commands
The Repository Browser toolbar includes two controls beyond those in the Items view:
·
The 
View/edit
selector button opens a dialog in which you can
view and modify the rules that determine what set of revisions is loaded in the
browser.
· The Jump to directory field appears in flat mode only. Enter a pathname within the repository’s directory hierarchy to jump directly to that directory. (Use the forward slash (/) character to indicate the repository’s root directory and as a directory separator.)
Figure 46: Repository Browser "Jump to directory" control
10.2.2 Context Menu Commands
The context menu for a selection of one or more items is the same as in the Items view. But many of the commands (for example, Checkout) are disabled, because they apply only to revisions in a workspace.
Chapter 11
The
Diff View
The Diff view compares two text files, side by side. It is used by numerous commands to compare two revisions of an item. The diff view is also embedded in the SuperDiff window, which compares revisions of multiple items, and in the Branch Changes window, which you can use to browse through all the changes made on a branch.
You can configure Diff to appear as a standard view in the GUI window’s work context or as a separate top-level window on the desktop (see section The Diff tools Tab in the Preferences dialog). Whether it’s an embedded view or a standalone window, we call it the “Diff view” in this manual.
The main components of the Diff view are:
Figure 47: Diff view
· Two file panes, labeled “left file” and “right file”, which display the contents of the two files/revisions.
· A separator bar between the panes. This bar is wide, enabling it to display “tubes” that indicate the various kinds of differences: insertions, deletions, changes, and moves. The separator bar is adjustable; you can also remove it temporarily, so that only the “left file” or “right file” is displayed.
· A control panel at the top, providing navigation controls and text-comparison options.
· A find panel at the bottom (which toggles in and out of view), supporting simple text searches within either file pane.
11.1 The Diff Revisions Dialog
Sometimes, the two revisions of an item to be compared are not set when you invoke the “diff” command (for example, Diff revisions ... in the Items view). Instead, a dialog appears in which you specify the revisions.
Figure 48: Diff Revisions dialog
For both the “left file” and “right file”, the specifications are:
Name
The item’s (or private object’s) full
pathname in the active workspace. The “diff” command fills in this field with the
selected item’s pathname, but you can change it – either by typing a pathname
or by clicking the 
control and selecting a
file in the pop-up dialog that appears.
If you specify a private file, the Revision radio buttons become irrelevant, and so are disabled.
Revision
One of these choices:
· Workspace revision – the item’s current contents in your workspace. If the item’s status is Checked out or Changed, the contents don’t correspond to any “official” revision in the repository.
·
Latest revision on
branch – the most recent revision on a
particular branch. You can enter a branch identifier manually (for example, br:/main/task476) or click the 
control to select a branch in a pop-up dialog.
·
Other – a revision that you specify by entering a revision identifier
manually (for example, /main/task476#12) or by
click the control and selecting a revision in a pop-up dialog.
In many cases, the “right file” is set to Workspace revision when the Diff Revisions dialog first appears.
11.2 How Differences are Displayed
The Diff tool analyzes the two files/revisions on a line-by-line basis, seeing how they differ. (The definition of “differ” is configurable. See section File-Comparison Options below.) It identifies and displays several kinds of difference blocks:
· insertion – one or more lines exist in the right file, but not in the left file.
· deletion – one or more lines exist in the left file, but not in the right file.
· change – a series of lines in the left file differs from a series (not necessarily the same number of lines) in the right file.
· move – a series of lines exists in both files, but at different locations. The moved block does not need to be identical at both locations – see Moved detection in section File-Comparison Options below.
(The names “insertion” and “deletion” are based on the assumption that the left and right files represent the “before” and “after” states of editing a file.)
The left and right sides of a difference block are displayed with tinted backgrounds, and are connected by “tubes” in the wide separator bar:
Figure 49: Difference block display
The tinted background colors are configurable -- see Configure colors in section File-Comparison Options below.
Figure 49 shows an insertion, a deletion, and a change. But what about moved blocks? They’re special, and so deserve their own section!
11.2.1 The XDiff Capability
There are many SCM systems available, and even more standalone “diff” programs. But very few even try to detect when a block of text has been moved from one part of a file to another – and possibly edited, too. But that happens all the time – it’s what refactoring is all about!
Plastic SCM has a robust capability for detecting, displaying, and comparing such moved blocks. We call it Xdiff (“cross-difference”). The Diff view indicates a moved block as follows:
Figure 50: Xdiff -- displaying a moved block
· In one pane, the block is marked as an insertion; in the other pane, as a deletion. This counts as two blocks in the tally of difference blocks (see Figure 54).
· A purple “ribbon” in the wide separator bar connects the two sides of the block.
· Control buttons float over each side of the block:
·
(Go to) Click this button in one side to scroll the
display, making the other side visible. This does not change the Diff view’s current difference block – see section Navigating the Difference Blocks.
·
(Show differences) Click this button
to open a sub-diff window, comparing the two
sides of the moved block side-by-side. This is especially useful when a block
has been moved “far away”, making it difficult or impossible to bring both
sides into view by simple scrolling. The sub-diff window provides its own
difference count (within the moved block) and its own navigation controls.
The sub-diff window is modal: you must close it before returning to work in the original Diff view.
Because Xdiff’s job is to detect blocks that have been both moved and modified, its work is not an exact science. (“Is Block B a modified version of Block A, or are they unrelated?”) Accordingly, you can tune the Xdiff algorithm – see Moved detection in section File-Comparison Options below.
11.2.2 Comparing Binary Files
The Diff view can compare image files/revisions in JPEG, PNG, GIF, or BMP format. It displays the two images side-by-side or blended together (you control the blending with a slider).
Figure 51: Comparing images
(If you have a tool that compares other kinds of binary files, such as sound files, you can configure the Plastic SCM GUI to use it. See section The Diff tools Tab.)
When comparing images, the Diff view’s toolbar includes these buttons and controls:
Side by side
Blend
Select the method of displaying the two images.
Zoom in
Make the image larger.
Zoom out
Make the image smaller.
Zoom one to one
Make the image its original size.
Zoom to fit
Zoom the images to fit the current size of the Diff window.
Blend level
A slider that spans the full width of the Diff window appears at the bottom of the control panel. Moving the slider leftward “fades in” the left image and “fades out” the right image.
11.2.3 Comparing Revisions of a Directory
The Diff view’s comparison of directory revisions appears similar to its comparison of simple text files. The left-side directory revision’s contents are displayed an alphabetized list of file and subdirectory names. An item’s name in the other directory revision appears directly across, on the right side. Thus:
· A simple renaming of a file or subdirectory appears like a one-line change to a text file:
· If an item has been deleted or moved to another directory, the change appears like deleted text. (Multiple such changes that are alphabetically consecutive appear as a single deletion block.)
· If a new item has been created or an existing item moved from another directory, the change appears like inserted text. (Multiple such changes that are alphabetically consecutive appear as a single insertion block.)
Figure 52: Comparing revisions of a directory
11.3 The Diff View Toolbar
The toolbar includes the following indicators and controls:
Left File / Right File
Descriptions and revision identifiers of both revisions that are being compared.
Options
A menu of options that control file comparison. See File-Comparison Options below.
Difference block navigation controls
First, Previous, Next, and Last buttons support browsing through all the difference blocks. The Current: NN/TT indicator identifies the current difference block and the total number of difference blocks.
Open a search panel at the bottom of the view.
Figure 53: Finding text in the Diff view
This provides a simple facility for searching through the entire text (not just the difference blocks) The Match Case checkbox provides for case-sensitive/insensitive searching. The Search Forward and Search Backward buttons search within a single pane only; to switch the search to the other pane, just click anywhere within that pane.
11.4 Navigating the Difference Blocks
At any moment, one of the difference blocks is the current difference block, as indicated by dull-red tinting of both side’s line numbers:
Figure 54: Indicating the current difference block
Notes:
· This figure shows that for insertion and deletion blocks, the tinting on one side spans zero text lines, and so appears as a line instead of a rectangle.
· For a moved block, dull-red tinting appears on one side only – and that side is considered to have the current difference block.
To keep yourself oriented, use the indicator in the Diff view toolbar:
Figure 55: Current difference block indicator and navigation buttons
Use these facilities to navigate among the difference blocks – and more generally, within the files/revisions being compared:
· Scroll bar – The scroll bar at the right side of the Diff view works in the standard manner. The left and right panes scroll somewhat independently, in order to keep both sides of each difference block visible. (This can cause the “tubes” to change shape a bit. Hours of fun to be had there ...)
Clicking anywhere in the empty region of the scroll bar centers the draggable “elevator” control at that spot (to the extent possible). The scroll bar’s background shows the locations of the difference blocks with tinting. Thus, you can click a difference block’s tint in this “scroll bar map” to bring the block into view. But this does not affect the current-difference-block setting.
· Mouse – Click anywhere within the tinted area of a difference block to make it the current difference block.
· Navigation buttons in the toolbar – Buttons in the Diff view toolbar (see Figure 55) support browsing through all the difference blocks. Clicking a button sets the current difference block and scrolls the display to bring it into view.
11.5 Text Operations
The Diff view is not a text editor – you cannot change the contents of either pane. But right-clicking in either pane opens a context menu, providing for limited text operations:
Copy the selected text to the operating system clipboard.
Select the entire contents of the current pane.
Find
Same as clicking the Find toolbar button.
If the search panel is already open, perform a Search Forward. If the search panel is not already open, simply open it.
11.6 File-Comparison Options
The following options control how the contents of files/revisions are compared in the Diff view:
Comparison method
· Ignore EOL – Ignore line-endings. This is helpful, for example, if one revision being compared was created on a Linux system (text lines end with NL) and the other was created on a Windows system (text lines end with CR-LF).
· Ignore white space – Within a single line, treat any consecutive string of SPACE and/or TAB characters as equivalent to a single SPACE.
· Ignore EOL and white space – both of the above.
· Recognize all – neither of the above.
Syntax highlight
· None – don’t perform any syntax highlighting
· Java / C# / C – if the text is Java code, C# code, or C code, highlight it accordingly.
Encoding
The way in which each file/revision’s contents are to be interpreted as text characters:
· None – interpret the contents using the operating system or development framework default.
· ASCII -- interpret the contents as ASCII characters.
· Unicode -- interpret the contents as UTF-16LE characters.
· Unicode Big-endian -- interpret the contents as UTF-16BE characters.
· UTF7 -- interpret the contents as UTF-7 characters.
· UTF8 -- interpret the contents as UTF-8 characters.
Tabs
· 4 spaces – establish tab stops every 4 columns.
· 8 spaces – establish tab stops every 8 columns.
Open a dialog in which you can adjust two parameters used by both the Xdiff (“cross-difference”) and Xmerge (“cross-merge”) capabilities, which detect moved text sections – see The XDiff Capability and The Xmerge Capability.
· Move detection ratio – the threshold at which two text sections are determined to be “the same section, but edited”. Choose a higher value if you are getting “false positives”; at 100%, two sections must be truly identical to be judged the same section. Choose a lower value if Xdiff/Xmerge is failing to recognize an insertion/deletion pair as being the same section.
· Minimum lines in difference -- the minimum number of lines that each section must contain to trigger Xdiff/Xmerge processing. Below this threshold, the two sections are always treated as a separate insertion and deletion.
Configure colors
Open a dialog in which you choose the background colors for difference blocks (Diff) and change blocks (Merge).
Chapter 12
The SuperDiff Window
The Diff View compares two revisions of an individual item. The SuperDiff window “bumps it up” a level, comparing two sets of item revisions. A set of revisions can be a complete configuration of the repository – for example, the set of revisions to which a given label is applied. Or it can be more limited – for example, the set of revisions in a given changeset or the set of latest revisions on a given branch.
A SuperDiff window includes two panes:
· The top pane is a table of items, with a control panel that provides browsing and filtering tools.
· The bottom pane is a complete, fully-functional Diff view, with its own control panel.
As you browse through items in the top pane, the Diff view automatically compares the revisions of that item in the two specified sets. If the item has a revision in only one set, the Diff view is replaced by a simple display of that revision.
The Plastic SCM GUI also includes tools that embed an entire SuperDiff window inside a window with additional functionality:
· New code review for this branch
· New code review for this changeset
· Explore changesets in branch
12.1 Columns in the Items Table
The items table is divided in categories for Changed, Added, Moved and Deleted items, much like The Pending Changes View. The columns found in this panel are:
· A Path column, containing the repository pathname of them item.
· A Repository column, containing the repository in which the revision is contained.
Figure 56: SuperDiff window
Chapter 13
The Branch Changes Window
The Branch Changes window is opened by the Explore changesets in branch command. It enables you to get both high-level and detail-level perspectives on the changes that have been made on a selected branch:
· The left pane is a scrollable listing of all of the branch’s changesets, with their timestamps and comment strings.
(The initial changeset and any others that establish or change the branch’s branch base link are not included in this listing.)
· The right pane is an embedded SuperDiff window, which “recalculates” automatically as you browse through the changesets.
Selecting a changeset in the left pane executes a Diff changeset contents command on that changeset, displaying the results in the right pane.
Figure 57: Branch Changes window
You can use both the mouse and the standard keyboard navigation keys to browse through the changesets in the left pane. See the SuperDiff and Diff View descriptions for help using the right pane to “drill down” from the changeset level to individual line edits.
Chapter 14
The Merge Organizer Window
The Merge Organizer window is a dispatch center, in which you initiate the merging of branches and changesets. For more details about the merge operation, refer to the Plastic SCM Introduction Guide.
In most cases, the revisions to be merged come from two specified sets – for example, the set of revisions (inside changesets) on one branch, and the set of revisions (inside changesets) on another branch. In all cases, merging two of an item’s revisions is a directional operation:
· One revision is the source – it remains unchanged by the merge operation. This is the revision that comes from the branch or changeset that is being merged.
· The other revision is the destination – it is always the revision in your workspace – typically, the last revision on the workspace’s active branch. The merge operation performs a Checkout on this revision (if necessary) and replaces its contents with the merge results.
When the view is loaded, it presents a summary of the operations that will happen during merge. This summary is the list of items that need to be merged, grouped in categories according to the type of merge conflicts between the source and the destination revisions.
Figure 58: merge categories
This is a list of all the possible categories:
· Changed on both the source and destination might require manual merge: these items have been changed on the source and the destination. Plastic SCM will try to merge them automatically, but if both revisions have changes on overlapping lines, the user needs to solve them manually. In this case, The Merge Window described below is used.
· Changed only on source, automatic merge: The item only has changes in the source, so the changes will be merged automatically to the destination in the workspace.
· Added, automatic merge: The item has been added in the source branch or changeset; it will be added as well in the destination (the workspace).
· Moved, automatic merge: The item has been moved in the source branch or changeset; it will be moved as well in the destination (the workspace).
· Deleted, automatic merge: The item has been deleted in the source branch or changeset; it will be deleted as well in the destination (the workspace).
14.1 Columns in the Merge Organizer Window
Item name
The item’s full pathname in the active workspace.
Remarks
A short description of the conflict for each item.
Contributors
Prints the action that will be run when the “Process all merges” button is clicked. This can be set in The Merge Options , to force the merge to take all the changes from a specific contributor or try to merge them.
14.2 Commands in the Merge Organizer Window
14.2.1 Toolbar Commands
The Merge Organizer has a set of buttons on the top of the view and a some more at the bottom.
Figure 59: Commands in the Merge Organizer
Process all merges
Initiates the merge operation. If Directory conflicts are still unresolved, a message will appear warning that the directory conflicts need to be resolved before continuing with the merge.
Open a new Branch Explorer with the merge contributors
Opens a new Branch Explorer window with a filtered diagram that displays the base, source and destination changesets used in the merge calculation.
Figure 60: Merge contributors in Branch Explorer
Recalculate merge
Refreshes the Merge Organizer view to perform the merge calculation considering the latest changes of the workspace.
Merge options
Opens a new window with the options that govern the merge operation. This dialog is described in its own section below.
14.2.2 Context Menu Commands
A selected item’s context menu includes these commands:
View merge contributors
Open a pop-up window, showing the revision identifiers of the source, destination, and common ancestor revisions.
Diff current with source
Diff current with ancestor
Diff source with ancestor
Open a Diff view, comparing any two of the three revisions involved in the merge.
14.3 Directory conflicts
If directory merge conflicts are found, an additional panel is shown on the top of the Merge Organizer window. The directory conflicts need to be solved before the merge of files can continue.
Figure 61: merge window with directory conflicts
These are the possible types of directory conflicts (“Conflict column”):
· Add / Move conflict: An item has been added on the source and other item has been moved on the destination to the same location.
· Move / Add conflict: An item has been moved on the source and a item with the same name has been added on the destination on the same location.
· Change / delete conflict: An item has been added or modified on the source, and the destination has deleted the item or its parent.
· Cycle move conflict: Two items have been moved on source and destination and collide because they create a cycle.
· Delete / Change conflict: An item has been deleted on the source and the destination has changed it.
· Delete / Move conflict: An item has been deleted on the source and it was moved on the destination.
· Move / Delete conflict: An item has been moved on the source and the destination has deleted it or its parent.
· Divergent move conflict: An item was moved on source and destination to two different locations.
· Evil twin conflict: An item has been added on the source and on the destination with the same name, and they are different items.
· Loaded twice conflict: Two items have been added on source and destination and collide because they are the same item.
· Moved evil twin conflict: Two different items with the same name have been moved to the same location on source and destination.
· Xlink conflict: An Xlink has been changed on source and destination.
· Writable Xlink conflict: The Xlinked repository doesn't know the ancestor changeset to calculate merge. The user must specify the ancestor changeset manually.
To solve the directory conflicts, the user needs to click on the “Choose…” clickable link in the “Resolution method” column. This will pop up a new dialog with the choices for the specific type of conflict.
Once a directory conflict is resolved, the “Status” column will change from “Unresolved conflict” to “Solved conflict”.
14.4 The Merge Options window
The Options panel (opened with the Merge options button) enables you to customize the merge operation.
Figure 62: Merge options dialog
· “Select merge contributor” section: in this section it is possible to override the default merge behavior of combining changes from source and destination together and instead force the merge to take all the changes from one of the contributors. This option only affects items in the “Changed on both the source and destination might require manual merge” category.
o Merge your changes with the source contributor’s changes: the merge operation will try to merge the changes in content from both the source and destination. The Merge Window may appear to solve non-automatic content conflicts. This is the default option.
o Preserve changes in your workspace (discarding the source contributor’s changes): for items that have content conflicts, override the default merge behavior and take always the changes from the workspace (the destination).
o Preserve changes in the source contributor (discarding your changes): for items that have content conflicts, override the default behavior and take always the changes from the source.
· 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. - 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.
Chapter 15
The
Merge Window
The Merge window is an interactive tool for performing a 3-way merge, involving three revisions of an item:
· the source contributor revision
· the destination contributor revision
· the closest common ancestor revision of the two contributors (also called the base revision)
The destination contributor is always the revision in your workspace – typically, the last revision on the workspace’s active branch. During a merge operation, Plastic SCM performs a Checkout on this revision (if necessary) and replaces its contents with the merge results.
Plastic SCM takes into account previous merges of the same item when determining the closest common ancestor. This means that you don’t need to merge the same section over and over again when you perform multiple merges on an item.
The Merge window doesn’t appear immediately when you issue one of Plastic SCM’s many “merge” commands. Instead, a Merge Organizer window appears. Invoking the “Process all merges” command in that window opens the Merge window as many times as necessary to perform a merge for each specified item, but only when user intervention is needed to solve a non-automatic conflict.
Initially, Plastic SCM is set to perform merges as automatically as possible: a Merge window appears only when there are one or more conflicts (see below) between the contributors, requiring manual intervention to resolve. You can modify this setting in the Preferences window -- see section The Diff and Merge Tab.
15.1 Organization of the Merge Window
The Merge window has quite a few panes:
· A control panel at the top, with buttons for controlling the merge process and for navigation.
· A row of three read-only contributor panes, side by side, displaying the contents of the source contributor, base (common ancestor), and destination contributor. Adjustable wide vertical separators define these panes.
· An editable merge results pane at the bottom. The contents of this pane changes according to choices you make in the control panel. You can also edit the contents of this pane directly. There’s an adjustable, wide horizontal separator between this pane and the row of panes above it.
· A scroll bar at the right side scrolls all the panes, and also provides a “map” of the changes found in the contributors. It works the same way as the Diff view’s scroll bar, described above.
Figure 63: Merge window
15.2 Change Blocks and Conflict Blocks
Much like The Diff View. the Merge window partitions the three revisions’ text into color-coded sections, called change blocks. And as with Diff, there are options for controlling the way in which change blocks are identified and displayed -- see Merge Options below.
Figure 64: automatic versus non-automatic conflicts in the merge window
For the following simple kinds of change blocks, Merge always merges the sections automatically:
· Blocks in which only the source contributor differs from the common ancestor.
· Blocks in which only the destination contributor differs from the common ancestor.
Figure 65: Change blocks -- automatic merging
For more complex change blocks, in which both contributors differ from the common ancestor, Merge merges the sections automatically in some cases, but requires you to guide it (“manual intervention”) in other cases:
· conflict block -- a change block in which one or more lines in the common ancestor have been modified by both contributors, in different ways. This is where manual intervention is required -- see Resolving a Conflict below.
Figure 66: Conflict blocks -- manual intervention required
· identical twins -- a change block in which one or more lines in the common ancestor have been modified or deleted by both contributors, in exactly the same way. Since the contributors agree with each other, Merge accepts their decision, automatically placing the agreed-upon change in the merge results.
For a modification, Merge indicates this case in the contributor panes by using the source contributor’s color-coding for both identical sections.
Figure 67: Identical twin changes
· parallel insertions – a new section has been inserted in both contributors at the same location in the common ancestor:
· If both insertions are the same, this is another “identical twins” case. Merge automatically places the inserted text in the merge results.
· If the insertions are sufficiently similar, Merge automatically combines the sections into a single insertion in the merge results. It indicates this case in the merge results pane by using a blending of the source and destination contributors’ color-coding. See Working with a Parallel Insertion below.
· If the insertions are not sufficiently similar, Merge treats this as a conflict block, initially placing both contributors’ sections in the merge results. See Resolving a Conflict below.
And there’s more ... like Diff, Merge can determine when sections of text have been moved within the file -- see The Xmerge Capability below.
In all cases – both automatic and non-automatic -- you can undo or modify Merge’s work in a change/conflict block, using the techniques described in Resolving a Conflict below.
15.3 The Merge Window Toolbar
The toolbar includes the following indicators and controls:
Save & Exit
Save the current contents of the merge results (bottom) pane as a checked-out revision of the item, on the destination branch. Then, close the Merge window.
If any conflicts have not yet been resolved, you must specify how to proceed in a pop-up dialog:
· Save & Exit – Continue with the save operation. The work you’ve done in this window is preserved, but Plastic SCM does not consider this item’s revisions to have been merged. (It does not create a merge link for this item.)
· Exit without saving – Close the Merge window without saving the work you’ve done. Plastic SCM does not consider this item’s revisions to have been merged.
· Cancel – Go back to working in the Merge window.
The same pop-up dialog appears if you try to close the Merge window with the “x” control in its window banner.
Options
A menu of options related to merging. See Merge Options below.
Change block navigation controls
First, Previous, Next, and Last buttons support browsing through all the change blocks, including the conflict blocks. The NN/NN indicator identifies the current change block and the total number of change blocks. See Navigating through the Change and Conflict Blocks below.
Conflict block navigation controls
Previous and Next buttons support browsing through all the conflict blocks. The Pending non-automatic: NN/NN indicator shows your progress in resolving the conflicts: the first number indicates which conflict is current; the second number indicates the total number of conflicts to be resolved in this item. See Navigating through the Change and Conflict Blocks below.
Current conflict type:
A status indicator for the current change block:
· Automatic. No user intervention needed – Merge has automatically merged the contributors.
· Non-automatic. User intervention needed – This is a conflict block; Merge has placed text sections from the source contributor, common ancestor, and destination contributor in the merge results pane.
· Non-automatic. Reviewed by the user – This is a conflict block that you have already resolved.
In any kind of change block (conflict block or not), you can undo or modify Merge’s work, using the techniques described in Resolving a Conflict below.
Mark as unresolved
Manually toggles whether the Merge tool considers the current conflict to be resolved. Normally a non-automatic conflict is marked as resolved as soon as the user clicks on any of the buttons to select or deselect a contributor (see below), but in some cases, the solution that the Merge Window suggests by default may be the right answer. In that case, click “Mark as resolved” and the non-automatic conflict is no longer pending.
Conflict block select/deselect buttons
A toggle button is located above each contributor pane. The buttons include/exclude a revision’s contribution to the merge results. When you restore a section that has been toggled off, it is placed at the end of the change block (not necessarily at its original position).
Figure 68: conflict block selection buttons
You can use these buttons in any change block – not just conflict blocks. This provides a way to modify or undo the Merge tool’s automated merge decisions.
Caution: toggling a section off also obliterates manual changes that you’ve made to it.
See Resolving a Conflict below.
15.4 Navigating through the Change and Conflict Blocks
At any moment, one of the change blocks is the current change block:
· If it’s a non-conflict change block (no user intervention required -- for example, where only the source contributor differs from the common ancestor), the block’s line numbers are tinted gray, as are the “tubes” in the separator bars:
Figure 69: Displaying a change block for which no user intervention required
· If it’s a conflict block (user intervention required), the block’s line numbers are tinted dull red, and the “tubes” are a brighter red.
Figure 70: Displaying a conflict block -- user intervention required
Use these facilities to navigate among the change blocks – and more generally, within the files/revisions involved in the merge:
· Scroll bar and mouse – these work in much the same way as in the Diff window, as described above. In the Merge window, the “map” in the scroll bar’s background is color-coded: conflict block locations are red; non-conflict change block locations are gray.
· Navigation buttons -- there’s one set of navigation buttons in the control panel for browsing through all the change blocks (including the conflict blocks), and another set of buttons for browsing through the conflict blocks only. Clicking a button sets the current change block and scrolls the display to bring it into view.
Figure 71: Navigation buttons in the Merge window
15.5 Resolving a Conflict
In the upper part of the Merge window, a conflict block appears as the contributing sections – from the source contributor, common ancestor, and destination contributor -- displayed side by side and connected by “tubes”.
Figure 72: Display of a conflict block’s sections in the contributor panes
Before you resolve the conflict, the merge results pane displays the three sections stacked vertically. Color-coding makes it easy to distinguish them.
Figure 73: Display of a conflict block’s sections in the merge results pane
Deleted lines are included in this display, indicated by strike-through, to help you fully understand the contents of all three sections. (Don’t worry – those lines won’t be included when you save the merge results!)
The Merge tool is satisfied that you’ve resolved the conflict in that particular block when you do any of the following:
· Click any of the Deselect buttons located above the contributor panes (see above). These buttons toggle the inclusion of that contributor’s section in the merge results.
You can toggle a section an many times as you like. In particular, a deselect/select sequence moves a section to the end of the conflict block. But be careful: toggling a section obliterates manual changes that you’ve made to it.
· Manually change the contents of any section within the conflict block, by typing or by using the Paste context-menu command.
· Click the Mark as resolved button in the toolbar.
Clicking Mark as unresolved tells the Merge tool that the conflict is not resolved, after all. But it doesn’t change the contents of the merge results pane.
15.5.1 Working with a Parallel Insertion
Merge sometimes treats a parallel insertion (described above) as a conflict block requiring manual intervention, and at other times processes it automatically. In particular, if you don’t approve of the way Merge has combined the two contributors’ sections into a single insertion, you can use any combination of these techniques:
· The Deselect result button in the separator bar above the merge results pane toggles the inclusion of the combined text insertion.
· The Select Source and Select Destination buttons above the contributors’ columns work as described in the preceding section.
· Manually change the merge results pane, as described in the preceding section.
Figure 74: Working with a parallel insertion
15.5.2 The Xmerge Capability
Xmerge (“cross-merge”) is Plastic SCM’s procedure for resolving a particular subset of conflicts:
· Contributor A (either the source or the destination) has modified a section, but not deleted it.
· Contributor B (the other one) has moved the same section to another location in the file -- and perhaps modified it, also.
Detecting this situation is a heuristic procedure. Merge automatically enables Xmerge for any conflict block in which it appears that the above conditions might hold true: that is, one contributor’s section is modified from the common ancestor, and the other contributor’s section is completely missing at that location. It also makes Xmerge available though the Xmerge context-menu choice, which is enabled in all conflict blocks – because what appears to be a “normal” conflict block might actually be an Xmerge situation.
Figure 75: Invoking Xmerge
(Exception: Xmerge is not modified for a parallel insertion in which the two contributors’ sections are not combined – see above.)
The Xmerge Procedure
After displaying an initial message box (“Xmerge – merge moved code”), Xmerge tries to locate the missing text section in “Contributor B”. Its search algorithm is configurable – see the Moved Detection option in section Merge Options.
· If it finds a candidate section, Xmerge highlights it in the merge results pane. (At this point, the section will appear to be a separate “inserted text” change block, made by Contributor B.) It displays a dialog asking for your approval. You can correct Xmerge’s guess by highlighting another section in the merge results pane.
Figure 76: Xmerge highlighting the moved text section
· If it does not find a candidate section, Xmerge invites you to identify the missing text section yourself, by highlighting it in the merge results pane.
When you click Xmerge with this selection in the dialog, work in the current Merge window is suspended, and a sub-merge window opens. It’s another full-featured instance of the Merge window, but limited to the current conflict block:
· Contributor A’s modified section.
· The common ancestor’s original section.
· Contributor B’s moved, and perhaps modified, section – the one you just (highlighted and) confirmed.
Figure 77: Xmerge conflict sub-merge window
Resolve the conflict(s) in the sub-merge window, using the techniques described in Resolving a Conflict. You can finish your work in this window in either of these ways:
· Click Save & Exit – The current contents of the sub-diff window’s merge results pane are placed in the merge results pane of the original Merge window. Contributor B’s move of the text block to a new location is preserved.
In addition, the conflict block is marked as resolved.
· Close the window with the “x” control in the window banner – No change is made to the original Merge window. The conflict block remains unresolved.
15.5.3 Text Operations
In the contributor panes (read-only) and the merge results pane (read-write), you can use context menus to operate on a selected text string:
Cut
(merge results only) Remove the text string from the merge results pane, and place it on the operating system clipboard.
Copy
Copy the selected text to the operating system clipboard.
(merge results only) Insert the contents of the operating system clipboard.
Delete
Remove the text string from the merge results pane.
Select All
Select the entire contents of the current pane.
(enabled for conflict blocks only) Launch the Xmerge procedure for this conflict block, even though it does not meet Merge’s criteria for a moved text section. See section The Xmerge Capability above.
Find
Same as the Diff view’s Find command.
Find next
If the search panel is already open, perform a Search Forward. If the search panel is not already open, simply open it.
15.6 Merge Options
Comparison method
Syntax highlight
Encoding
Tabs
Configure fonts and colors
These options are the same as those in the The Diff View view. See section File-Comparison Options above.
Moved detection
Open a dialog in which you can adjust two parameters used by both the Xdiff (“cross-difference”) and Xmerge (“cross-merge”) capabilities, which detect moved text sections – see The XDiff Capability and The Xmerge Capability.
· Move detection ratio – the threshold at which two text sections are determined to be “the same section, but edited”. Choose a higher value if you are getting “false positives”; at 100%, two sections must be truly identical to be judged the same section. Choose a lower value if Xdiff/Xmerge is failing to recognize an insertion/deletion pair as being the same section.
· Minimum lines in difference -- the minimum number of lines that each section must contain to trigger Xdiff/Xmerge processing. Below this threshold, the two sections are always treated as a separate insertion and deletion.
Split conflict blocks
Wherever possible, split a conflict block into a smaller contiguous change blocks. For example, if the source contributor and base share some code that does not occur in the destination contributor, a conflict block requiring manual intervention can be converted into two or more changes blocks that are merged automatically.
Figure 78: Splitting a conflict block
Chapter 16
The Workspaces View
The Workspaces view lists all your workspaces on the local machine. It provides a command button for creating a new workspace.
16.1 Columns in the Workspaces View
Name
The name of the workspace.
Path
The full pathname of the workspace’s root directory.
16.2 Commands in the Workspaces View
16.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Create new workspace
Open a dialog in which you create a new workspace and set its selector. The dialog includes these fields:
· Workspace name -- a simple name for the new workspace. SPACE characters are allowed, but not at-sign (@), pound-sign (#), slash (/) or colon (:). This name identifies the workspace in the tab bar at the top of the GUI window, and in the banner at the top of the work context area.
· Path on disk -- the full pathname of a disk location that will become the new workspace’s root directory. You can specify an existing location, in order to “convert” an ordinary directory into a Plastic SCM workspace. But you cannot specify a location within an existing Plastic SCM workspace. (That is, you cannot nest workspaces.)
· Default repository -- Use this field to specify which repository should be loaded in the workspace. By default, the “/main” branch will be used. In case the /main branch has been renamed in that repository, the new name given to it will be used instead.
Figure 79: New workspace window
It is also possible to create a new repository with the “New…” button on the right of the default workspace repository.
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
16.2.2 Context Menu Commands
Set selector
(active workspace only) Open a Selector dialog, in which you can view and modify the selected workspace’s selector. If you modify the selector, you’ll probably want to leave the Update workspace checkbox checked, to guarantee that the workspace’s contents correspond to its selector. The workspace selector is a set of advanced rules that determine what is loaded in the workspace. For more details on the Workspace Selector, please check the Plastic SCM Reference Guide.
Make active workspace
Set the selected workspace as the GUI’s active workspace. The views that are currently open in the work context of the newly activated workspace appear, replacing the views belonging to the workspace that was previously active.
This action is the same as clicking the workspace tab at the top of the GUI window.
Rename
Change the name of the selected workspace. This does not change the workspace’s location in disk storage.
Delete
Permanently remove the selected workspace from Plastic SCM. (This does not remove the workspace’s directory tree from disk storage.) You cannot remove the active workspace. To prevent data loss, you cannot remove a workspace that contains items with Checked out status (but you can remove a workspace with Changed items).
Chapter 17
The Repositories View
The Repositories view lists all the repositories managed by the repository servers that your client software is configured to use. By default, your client software uses the Plastic SCM repository server on the local machine. You can configure any number of repository servers in The Profiles Tab in the Preferences window. When the connection type is set to “Automatic” on the connection profile, the repositories view will connect to this server and list its repositories together with other servers.
The Repositories view also provides a command button for creating a new repository on any server whose repositories are listed.
17.1 Columns in the Repositories View
Name
The name of the repository.
Server
The repository server (hostname:portnumber) that manages this repository.
17.2 Commands in the Repositories View
17.2.1 Toolbar Commands
The toolbar includes the following buttons and controls:
Create new repository
Open a dialog in which you create a new repository. The dialog includes these fields:
· Name of new repository --a simple name for the new repository. SPACE characters are allowed, but not at-sign (@), pound-sign (#), slash (/) or colon (:).
· Server -- the name (in hostname : portnumber format) of the Plastic SCM repository server process that is to manage the new repository.
Figure 80: New repository window
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
17.2.2 Context Menu Commands
The context menu for a selection of one or more repositories includes these commands:
View branches
Open a Branches view for each selected repository.
View labels
Open a Labels view for each selected repository.
Open a Changesets view for each selected repository.
View BranchExplorer
Open a BranchExplorer view for each selected repository.
View attributes
Open an Attributes view for each selected repository.
Rename
Change the name of the selected repository. This does not change the selector of the active workspace or any other workspace. If the renamed repository is used by any workspace(s), you must revise the workspace(s)’ selector(s) manually.
Delete
Permanently remove the selected repository. Be careful! Plastic SCM does not check whether any workspace (even the active workspace) is using the repository.
Permissions
Open a Permissions window for the selected object.
Repository server permissions
Open a Permissions window for the repository server, which is the top-level object in the ACL inheritance hierarchy. Any permission set at this level is inherited by all repositories that haven’t explicitly broken the permission inheritance.
Moreover, the owner (user or group) of the repository server becomes the superuser of the system, having no security restrictions. It is a good practice to set this superuser when setting up Plastic SCM.
Note that by default this owner is set to ALL_USERS, so has no effect until a specific user or group is set.
Chapter 18
The Change Statistics View
The Change Statistics view displays two bar charts that provide a high-level perspective on how a repository’s items have been changed by developers over a particular interval (default: one month):
· The Changed Items chart includes a bar for each item that has new revisions, showing the number of changesets that contain a new revision of that item.
· The Users chart includes a bar for each user, showing the number of changesets created by that user.
Figure 81: Change Statistics view
In both charts, selecting a bar provides more detailed information on the changes it represents. There are sorting and filtering controls, and you can customize the query that provides the raw data that goes into the charts.
18.1 Detailed Information on Changes
As you hover the mouse over an item’s bar in the Changed Items chart, the status pane at the bottom of the view displays the item’s pathname and its total number of changesets.
Similarly, as you hover the mouse over a user’s bar in the Users chart, the status pane at the bottom of the view displays the user’s name and the total number of changesets created by that user.
In either chart, selecting a bar partitions it into multiple alternating color bands, and also partitions the bars in the other chart. The color bands represent a “drill down” to provide more detail on the changes.
When you select an item’s bar in the Changed Items chart:
· The item’s pathname appears in the status pane at the bottom of the view.
· Alternating color bands in the selected item’s bar indicate the number of changesets created by individual users. Hovering the mouse over a color band displays the user-specific details in the status pane.
· All bars in the Users chart are two-way partitioned: the lower band depicts the user’s changesets that contain the selected item; the upper band depicts the user’s other changesets. Hovering the mouse over the lower band displays its details in the status pane.
Figure 82: Detailed information on an item
When you select a user’s bar in the Users chart:
· The user name appears in the status pane at the bottom of the view.
· Alternating color bands in the selected user’s bar indicate the individual items that the user has changed. Hovering the mouse over a color band displays the item-specific details in the status pane.
· All bars in the Changed Items chart are two-way partitioned: the left band depicts the changesets created by that user; the right band depicts the changesets created by all other users. Hovering the mouse over the left band displays its details in the status pane.
 |
Figure 83: Detailed information on a user
18.2 Modifying the Charts
These controls enable you to modify the Changed Items chart:
Minimum changes / item
An integer value that defines a filter: an item will be included in the chart only if its number of changesets equals or exceeds this value.
Sort order
The order in which the bars are displayed: Order by name sorts the bars by item pathname (ascending); Order by changes sorts the bars by size (largest number of changes first).
This control enables you to modify the Users chart:
Sort order
The order in which the bars are displayed: Order by name sorts the bars by user name (ascending); Order by changes sorts the bars by size (largest number of changes first).
In the Change Statistics view’s toolbar, you can revise the SCM-level query that yields a set of revisions, providing the raw data for the charts. Clicking the Execute button runs the revised query and regenerates both charts.
Figure 84: Revising the Change Statistics query
The initial query yields all the revisions created during the preceding month in the active workspace’s repository:
find revisions where date > "month-ago-date" on repository "repository-spec"
(If the active workspace combines items from multiple repositories, you are prompted to choose one of them.)
Following are typical revised queries:
· All revisions created during the year 2010 in the active workspace’s repository:
find revisions where date between "1/1/2010" and "12/31/2010"
· All revisions you created in repository fracrepo:
find revisions where owner = "ME" on repository "fracrepo"
· All revisions made on branch /main/task398 before December 2010:
find revisions where branch = "/main" and date < "12/1/2010"
Chapter 19
The Code Reviews View
The Code Reviews view contains a table that lists some or all of the code reviews that users have created, using the command New code review for this branch or New code review for this changeset from the branch and changeset context menus respectively. You can use this table to locate a particular code review and open it. Plastic SCM uses a separate window, the Code Review window, to display the contents of an individual code review.
19.1 Columns in the Code Reviews View
Title
The name of the code review.
Status
One of these values: Pending, Approved, Discarded.
Reviewed object
The name of the branch, or the number of the changeset, for which the code review was created.
Assignee
The user or group to whom the code review is currently assigned. This field can be empty, indicating that the code review is not currently assigned to anyone.
A code review’s assignee can be changed in its Properties window.
Owner
The user who created the code review.
Creation date
A timestamp indicating when the code review was created.
19.2 Commands in the Code Reviews View
19.2.1 Toolbar Commands
Standard filters list
This view provides the following standard filters that can be selected in the dropdown list:
· All code reviews – Display all code reviews
· Pending reviews – Display all code reviews whose status is Pending.
· My reviews – Display all code reviews that you created.
· Assigned to me – Display all code reviews that are currently assigned to you personally. (Do not include code reviews that are assigned to groups that you belong to.)
Export view data
This button is used to export the current content of the table in the view to a text file, either CSV or XML. See Exporting the table contents to a text file section for more details.
Filter
You can use this field to reduce the table to a subset of its rows. See section Filtering the Rows of a Table.
19.2.2 Advanced
Toggles the toolbar’s Advanced mode, in which you can view and customize the query that produced this view’s table. See section Advanced Mode: Revising the Query that Produces a Table.
19.2.3 Context Menu Commands
Open
Open a Code Review window, showing the contents of the selected code review. You can use this window to browse existing review comments and add new ones.
Open a dialog in which you can view and modify the settings of the selected code review.
Delete
Permanently remove the selected code review. Be careful! There is no way to recover the comments in a code review that has been removed.
Chapter 20
The Code Review Window
The Code Review window is a SuperDiff window with some extra functionality: developers can add one or more comments to any line of any text-file revision that the window displays. All the comments appear in a separate, scrollable pane at the bottom of the window. Indicators on individual lines make it easy to see which ones have comments, and to display a particular line’s comments. Separator bars adjust the allocation of space among the Code Review window’s three panes.
Figure 85: Code Review window
These commands create code reviews:
· New code review for this branch – creates a code review with all the revisions modified on the branch, even if they are contained on more than one changeset.
· New code review for this changeset – creates a code review with all the revisions checked in together as part of the selected changeset.
20.1 Viewing Existing Comments
The right side of the Diff display contains the “revision of interest” – that is, the revision in the branch or changeset for which the code review was created. The left side contains the immediate predecessor revision. Accordingly, comments apply to the right-side revision only.
20.1.1 Using the Comments Pane
The comments pane at the bottom of the window shows all the comments for all the revisions in the code review’s branch or changeset, ordered chronologically (oldest one first). Each comment is annotated with the name of the user who created it, how long ago it was created, and line-number/pathname information to identify the target of the comment. (The revision identifier is listed in the items table at the top of the window.)
Selecting a
comment reveals Edit and Delete controls for it. The 
(Refresh) button recalculates all the
“XXXX ago” values and includes any changes to the comment set that have been
made recently by other users.
Figure 86: Comments pane in the Code Review window
20.1.2 Viewing the Comments for a Single Line
If a line in the right-side Diff pane has one or more existing comments, a blue button appears over its line number:
·
A “single” blue arrow button indicates that the line has one
comment.
·
A “stack” blue arrow button indicates that the line has more than
one comment.
Clicking the button opens a window containing all of that line’s comments:
Figure 87: Viewing a line’s existing comments
Selecting a comment reveals Edit and Delete
controls for it. The (Refresh) button recalculates all the
“XXXX ago” values and includes any changes to the comment set that have been
made recently by other users. The Reply button opens a window in which you can enter an
additional comment for this line.
20.2 Adding New Comments for a Line
As you hover the mouse over the lines numbers in the right-side revision, a gray button appears over each line number. Clicking this button opens a window in which you can enter a comment for this line. If the line already has one or more comments, the gray button “peeks out” from behind the blue button indicating the line’s current comments.
Figure 88: Creating a comment for a line
Chapter 21
The Synchronization view
The Sync Replication view lets the user configure replication relationships between repositories so they can be easily synchronized with one click. Replication relationships automate branch replication operations so that entire repositories can be kept in sync with little effort.
This view is divided in two main areas, as depicted on Figure 89.
Figure 89: The Sync Replication view
The top pane, called “User defined sync views” contains the list of defined relationships (or Sync views). This is a table that will list the list of relations created. Relations are just containers that assign a name to a set of repositories configured to synchronize with each other. Each relation, later, will have a number of source repositories each configured to synchronize with one or more destination repositories.
Note: Source and destination is just a naming convention, actually the synchronization can happen in both directions.
Once a Sync view is created and selected in the top pane, the bottom pane lets the user configure the repositories to synchronize.
Figure 90: Details of replication relationship in the Sync replication view
Replications relationships are configured defining one or more source repositories and, for each of them, one or more destination repositories. When the relations are expanded, the source repository server connects to the destination repository server to get a list of the changesets that need to be synchronized.
21.1 Commands on the Sync replication view
21.1.1 Commands on the “User defined sync view” pane (top)
Use the buttons in the toolbar to add a new relationship (or Sync view) or delete the selected one in the table, as shown in Figure 91. When a new Sync view is created, a dialog appears to prompt for the new name.
Figure 91: Commands to manage relationships in the Sync replication view
21.1.2 Commands in the Sync View details pane (bottom)
Configuring a relation involves adding first one or more source repositories. Each of these repositories will be synchronized on demand with one or more destination repositories. These actions are depicted in Figure 92.
Figure 92: Command in the Sync view details pane
Add source repository
Adds a new repository to the relationship definition. A dialog appears to choose the server repository and the repository itself, as seen in the following figure:
Figure 93: repository selection dialog in Sync View
The list of servers in the dropdown list is the made of the default server plus any servers defined in The Profiles Tab in the Preferences dialog.
Delete selected source repository
This command removes the selected source repository from the selected Sync view. Note that this does not affect the repository itself in any way.
Add target repository
This command lets the user select a destination repository. The selection mechanism is the same the one used for the source repository described above.
Delete target repository
Deletes the selected destination repository from the source repository in the relation. Note that this doesn’t affect the repository itself in any way.
21.1.3 Commands in the details view (context menus)
Each type of object in the Sync view details table has a different set of available actions. Figure 94 summarizes the actions associated to each object that will be described below.
Figure 94: context menus in the Sync view details table
Source repository menu
Add target repository
Same as the “add target repository” command described above.
Delete selected repository source
Same as the “Delete selected source repository” described above
Refresh
Reloads the list of pending changes of the repositories underneath.
Target repository menu
Synchronize all
Initiates a synchronization of all the pending changes, replicating all the branches listed in the outgoing and incoming sections for the selected repository. A summary window appears so the user can review the actions that will be done and confirm that the operation can proceed as depicted in Figure 95.
Figure 95: Sync view "Synchronize all" summary window
Push all outgoing changes
Instead of performing a full replication, only the outgoing changes (from source to destination) are replicated. A summary window appears so the user can review the actions that will be done and confirm that the operation can proceed as depicted in Figure 95.
Pull all incoming changes
Same as the previous option, but the other way around: only pull from the destination to the source.
Delete selected target repository
Same as the “Delete target repository” command described above.
Refresh
Reload the list of pending changes for the selected relationship.
Outgoing / incoming changes menu
Push / Pull all changes
Initiates a replication operation that includes all the outgoing or incoming changes.
Branch menu
Push / Pull branch
Depending if the branch is listed under outgoing or incoming changes, this action is “Push” or “Pull” respectively. The command initiates a replication operation on the selected branch.
Changeset menu
Diff changeset
The content of the selected changeset can be reviewed before replicating it as part of the synchronization process. A SuperDiff window appears with the content of the changeset.
Chapter 22
The Permissions Window
The Permissions window is the control panel for an object’s access control list (ACL). Whenever a user invokes a Plastic SCM command through the client software, the repository server first consults the ACL of one or more objects to determine whether that user has permission to execute the command.
An object’s ACL consists of permissions, each of which states that a particular user or group (possibly the special user OWNER or the special group ALL USERS) either is Allowed or Denied the right to perform a particular Plastic SCM operation on this object.
(Each object has an owner – initially, the user who created it. The ownership of some objects can be changed, using the Change owner command in this window. For an overview of this aspect (and all others) of Plastic SCM’s access control facility, see the Plastic SCM Security manual.)
The Permissions window’s Advanced tab displays an individual permission like this:
Figure 96: Display of an individual permission
This permission says that group “All users” is allowed (not denied) the right to apply labels to revisions, and that this is a direct permission (an explicit setting on this particular object), not an inherited permission (from a higher-level object).
The inheritance scheme means that an object can be affected by a large number of individual permissions:
· Some objects (for example, items) inherit from the file system hierarchy.
· Others (for example, branches) inherit from the repository object hierarchy.
· Still others (for example, revisions) inherit from both hierarchies.
For each operation, the Assigned Permissions tab shows the result of combining the object’s direct permissions with its inherited permissions to answer the question, “does this user have the right to perform this operation on this object?”. (The Plastic SCM Security manual details the algorithm that combines the permissions.) But note that this answer might not be the “final answer”. Many operations involve multiple repository objects – for example, applying a label to a revision involves both a label object and a revision object. Thus, the Permissions window for each individual object sometimes tells just a part of the story for a given operation.
22.1 The Permissions Window Display
An object’s Permissions window has two tabs, described in the following sections.
22.1.1 The Assigned Permissions Tab
This tab displays the “net effect” of the object’s individual permissions. The upper pane lists all the users and groups for which permissions on this object (both direct and inherited) have been defined. Selecting a particular user or group in this pane causes the lower pane to display that user/group’s “effective permissions” for the object.
Figure 97: Permissions window -- Assigned Permissions tab
Each row indicates the “effective permission” for one Plastic SCM operation as two checkboxes – one for Allowed and one for Denied. Each checkbox can have one of these states:
empty
For this user/group and this Plastic SCM operation, the object has no direct or inherited permission of this kind (Allowed or Denied).
black checkmark
For this user/group and this Plastic SCM operation, the object has a direct permission of this kind (Allowed or Denied), but no inherited permissions. You can clear this setting with a mouse click.
gray checkmark
For this user/group and this Plastic SCM operation, the object has one or more inherited permissions of this kind (Allowed or Denied). It is also possible that the object has a direct permission of the same kind. You can determine the details on the Advanced tab – for example, which higher-level object the permission is inherited from.
You cannot clear this setting with a simple mouse click, but see section Clearing an Inherited Permission below.
These checkbox settings determine the effective permission as follows:
· If the Allowed checkbox is checked (black or gray) and the Denied checkbox is cleared, then the user/group has the right to perform the operation on this object.
· Otherwise, the user/group cannot perform the operation on this object.
Clearing an Inherited Permission
You cannot clear an inherited permission, indicated by a gray checkmark, with a simple mouse click. Instead, open a Permissions window on the higher-level object from which the setting is inherited, and clear the direct setting there. (If the lower-level object has multiple inherited permissions for this user/group for the same operation of this kind (Allowed or Denied), clear the setting on each of the higher-level objects.)
When you reopen a Permissions window on this lower-level object, you’ll see:
· An empty checkbox, if there was no corresponding direct permission -- for this user/group, for the same operation, and of the same kind (Allowed or Denied).
· A black checkmark, if there was a corresponding direct permission. In this case, the direct permission has now “emerged from the shadow” of the inherited permission(s) that you just removed from the higher-level object.
22.1.2 The Advanced Tab
The upper pane displays a table of all the object’s individual permissions – both direct and inherited -- for all users and groups.
Figure 98: Permissions window -- Advanced tab
The columns of this table are:
User/Group
The name of the user or group (possibly the special user OWNER or the special group ALL USERS) to which this permission applies.
Permission
The Plastic SCM operation that is affected by this permission.
Allowed
Yes or No, indicating whether this permission grants the right to perform this operation.
Denied
Yes or No, indicating whether this permission denies the right to perform this operation.
Inherited
The identifier of the object from which the permission is inherited. Dashes (--) indicate a direct permission (not inherited).
22.2 Commands in the Permissions Window
There are command buttons and checkboxes on both tabs in this window. No change that you make takes effect immediately – instead, the following buttons operate on the changes you’ve made on either tab:
Apply
Save any new permissions, changes to existing permissions, and ownership changes that you’ve made on the Assigned Permissions tab; save any inheritance changes that you’ve indicated by the checkboxes on the Advanced tab.
Ok
Perform the Apply command, then close the Permissions window.
Cancel
Close the Permissions window without saving any of the changes that you’ve made since the most recent Apply command.
22.2.1 Commands on the Assigned Permissions Tab
Add
Create a set of direct permissions for a user or group. You select the user or group from a pop-up dialog.
Remove
Delete all the direct permissions for the selected user or group.
Change the object’s owner to another user or group. You select the user or group from a pop-up dialog.
22.2.2 Commands on the Advanced Tab
By default, an object inherits permissions from its parent (which may, in turn, inherit permissions from its parent, and so on). On this tab, you can invoke one or both of these kinds of commands:
· A command that changes how this object inherits permissions from higher-level objects.
· A command that changes how this object’s permissions are inherited by lower-level objects.
The following four commands are mutually exclusive – you can check only one checkbox at a time:
Break inheritance, copying inherited permissions
Convert all of the object’s inherited permissions to direct permissions. You can think of this command in either of these ways:
· On the Assigned Permissions tab, for all users/groups: change all the gray checkmarks to black checkmarks.
· On the Advanced tab, change each object identifier in the Inherited column to “--”.
Break inheritance, without copying inherited permissions
Remove all of the object’s inherited permissions, leaving the direct permissions unchanged.
WARNING! This command can render the object completely inaccessible. Before invoking this command, make sure that the object has some direct permissions -- for example, chgperm, view, and read --that will provide at least minimal access after the inherited permissions are removed.
Add inheritance from parent directory item
(items only) Undo a previous Break inheritance command, by reestablishing permission inheritance from the item’s parent directory. This command removes the object’s direct permissions, if any.
Add inheritance from a specified object
Have this object inherit the direct permissions that are defined for a specified other object. This adds to the existing settings – it does not change or delete any existing direct or inherited permission.
You can invoke the following command by itself, or in combination with one of the above:
Extend inheritance
(directory items only) This command does not affect this directory object; instead, it affects all the file system objects in the subtree below this directory. In effect, an Add inheritance from parent directory item command is performed on each file and directory in the subtree. This removes direct permissions throughout the entire subtree.
Chapter 23
The Preferences Window
The Preferences window manages your user profile, which controls many aspects of your day-to-day usage of the Plastic SCM client software. Your user profile is stored in an XML-format file, client.conf, located in a subdirectory (subfolder) under your home directory.
23.1 The General Preferences Wizard
This wizard (launched by clicking the large gears button) configures several basic usage parameters. This is the connection information used for the default Plastic SCM server that you want to connect to.
Figure 99: General preferences
· the language to be used in both GUI and CLI client programs
· the Plastic SCM repository server to which client program requests will be directed
· (optional) a proxy repository server, which handles “read” (but not “write”) requests, accelerating performance by caching data
· the user-authentication scheme to be used in establishing your identity to the repository server (and, depending of the scheme selected, a username/password combination to be sent with each client request)
In addition, you can create any number of named profiles on the Preferences window’s Profiles tab. Each profile can have different settings for the user and repository server parameters. Profiles are meant to connect to different servers, especially on distributed scenarios.
You can launch this wizard from a command processor, without having to start the Plastic SCM GUI:
· The command plastic --configure launches the same graphical wizard as this Preferences tab.
· The command clconfigureclient launches a console version of the wizard.
23.2 The Diff and Merge Tab
The settings on this tab configure the defaults to be used by the The Diff View and Merge tools. You can override the defaults in instances of these tools.
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.
Encoding
The encoding used to convert text files’ contents to screen characters in the merge and diff tools. For more details, refer to section The Merge Options window.
Merge contributor handling
The default way in which the two contributors to a text-file merge operation are to be handled. For more details, refer to section The Merge Options window.
23.3 The Diff tools Tab
This tab enables you to configure and customize the behavior of the Diff tool when it compares revisions of items. It contains a sequence of patterns (in the Type/Suffix column), which Plastic SCM matches, one after another, with an item’s file type or its filename. When it finds a match, the Plastic SCM invokes the corresponding command in the Tool column.
This tab is initialized with two special patterns that are matched against an item’s type, as reported in the Type column of the Items view:
$text
Matches all items whose type is Text.
$binary
Matches all items whose type is Binary.
You can create additional entries for filename extensions, such as .docx, .cs, and so on. In each entry, the command corresponding to the pattern is one of the following:
Embedded diff viewer
(indicated by the keyword $internal_tool) The GUI’s built-in file-comparison routine will be invoked, creating a view in the active workspace’s work context area.
Plastic SCM diff tool
A standard mergetool command line will be invoked for files of type Text and for files with a matched filename extension. A standard binmergetool command line will be invoked for files of type Binary. This creates a separate top-level window on your desktop.
External diff tool
A command line to invoke any file-comparison program. You use the following keywords to incorporate information about the revisions being compared into the command line:
Figure 100: Keywords for invoking an external diff tool
23.4 The Merge tools Tab
This tab enables you to configure and customize the behavior of the Merge tool when it performs a 3-way merge of two contributor revisions and a common ancestor (base) revision. It contains a sequence of patterns (in the Extension column), which Plastic SCM matches, one after another, with an item’s file type or its filename. When it finds a match, Plastic SCM invokes the corresponding command in the Tool column.
This tab is initialized with two special patterns that are matched against an item’s type, as reported in the Type column of the Items view:
$text
Matches all items whose type is Text.
$binary
Matches all items whose type is Binary.
You can create additional entries for filename extensions, such as .docx, .cs, and so on. In each entry, the command corresponding to the pattern is one of the following:
Plastic SCM merge tool
A standard mergetool command line will be invoked for files of type Text and for files with a matched filename extension. A standard binmergetool command line will be invoked for files of type Binary. This creates a separate top-level window on your desktop.
External merge tool
A command line to invoke any file-merge program. You use the following keywords to incorporate information about the revisions being merged into the command line:
Figure 101: Keywords for invoking an external merge tool
23.5 The Comments Tab
This tab provides some control over when and how Plastic SCM displays the Comments dialog. You use this dialog to a comment string to be associated with one or more new revisions.
Maximum number of recent comments
The maximum capacity of the list of your previously specified comment strings, which appears when you click the Recent comments button in a Comments dialog or in a Pending Changes view. When the capacity is reached, new comments are pushed onto the top of the list, and old comments fall off the bottom.
Show comments dialog in Add command
If this option is set, a dialog box will appear when adding items to the repository in order to enter the comments associated to the operation. This is normally useful since the added items are by default checked in directly, so if this option is not set, that changeset will have an empty comment. (Note that the changeset comment can be edited later in the extended options panel, in the changesets view).
Warn about empty comment in Pending Changes view
Display a warning message when checking in from The Pending Changes View if the comment is left empty.
Comments auto-text
Specifies the text, if any, which is automatically entered into each instance of the Comments dialog. Plastic SCM can automatically fill in the user name that performed the operation and the date they were performed. Keep in mind, however, that this information is also recorded in the Plastic SCM repository even if not detailed in the comment.
23.6 The Other Options Tab
Check for pending changes when switching workspace to a branch or label
Controls whether a warning box appears if you are about to change a workspace’s configuration and one or more items are checked-out.
Warn about permissions on Move operations
Controls whether a warning box appears when moving an item between directories whose ACLs differ; the moved item will still inherit its permissions from its original parent directory.
‘Update’ and ‘Checkin’ operations set files as read-only
Check this checkbox to use the checkout-modify-checkin methodology to work with source-controlled files. Files remain read-only until they are checked-out. (Some IDEs require this methodology.)
Clear this checkbox to use the modify-commit methodology to work with source-controlled files. Files are writable at all times.
If you change this setting, you can use the Update forced command to change the writability of the workspace’s source-controlled files. Before using this command, use the Pending Changes view to resolve the status of all files with Checked out or Changed status.
Compare files contents instead timestamps when determining “Changed” status
Controls how Plastic SCM determines whether a source-controlled file has Changed status. When this option is not set, Plastic SCM uses the timestamps of the files. When the option is set, the content of the files that have a changed timestamp is hashed to see if has really changed. The latter option is slower but completely accurate, while the first is faster but may mark a file as changed when it actually is not.
‘Update’ operation sets repository file dates on disk
When Update creates a file in the workspace by copying a revision from the repository:
· If this option is set, the file’s timestamp is set to the revision’s creation time.
· If this option is not set, the file’s timestamp is set to the current time.
Try to run quick update (Do not update if the workspace changeset is up to date)
Controls the behavior of the Update Workspace command.
· If this option is set, the update command will check the current changeset in the workspace and compare it to the changeset that should be loaded in the workspace (according to the workspace configuration). Only the changed items are downloaded from the repository. The workspace directory is not read, so If any file is locally deleted, it won’t be downloaded from the repository.
· If this option is not set, the Update command behaves as described above, but in addition it will traverse the workspace directory to see if any file has been deleted locally and then download it so that the workspace contains the same configuration as the changeset it is pointing to. This is the default behavior.
While the first option (quick update) is faster, there are some cases where the workspace might not be left in consistent state and the user has to be aware of that. The default behavior is to have this option unset, so that the Update command leaves the workspace in a consistent state, although is a bit slower.
Checkin files and directories when adding them to source control
When this option is set (default) the “Add to source control” commands also checkin the items. When it is not set, the added items are left in “Added” state and have to be checked in using the Checkin command on the Pending Changes view or the Item’s view context menu.
Display error for same file with different case (from Unix filesystems) on Windows
If this option is set, an error is displayed in the Update report when two files with the same name but different case are present on the same directory. This is supported in case-sensitive file systems, commonly found on Unix platforms, but it is not supported in Windows file systems. It is possible to add items with same name and different case in Linux and Update a workspace in Windows to download those files. However, in Windows only one of the files will be downloaded. When this option is set, the Update operation will warn about this. If it is not set, the case is ignored, but only one file is downloaded anyway.
23.7 The Issue Tracking Tab
This tab configures an integration between Plastic SCM and an issue tracking system (ITS).
Figure 102: Configuring an ITS integration
For details on individual ITS integrations, see the Plastic SCM Integrations manual.
23.8 The Profiles Tab
This tab manages any number of named connection profiles, which can be used in replication operations instead of your day-to-day user profile.
Each replication profile specifies a remote repository server, a user-authentication mode, and in some cases a username-password combination. You enter the specifications using a wizard that is essentially the same as The General Preferences Wizard.
Figure 103: Connection profiles
The first page of the wizard presents a new option, however. The connection type determines the availability of the server whose connection profile is being defined.
Figure 104: new profile window
· On demand: the server is not always reachable from this client and Plastic SCM will not try to connect to it unless explicitly told so (for instance, from the Branch Explorer replication sources “Show remote data” checkbox, or from the “List repositories” button on the replication dialog. Maybe you are configuring Plastic SCM on a Laptop and when you leave the office, this server is not reachable but you still want to connect to it when you get back.
· Automatic: the server is always online (maybe on the same local network, when connecting from a desktop machine). For instance, the repositories view will try to connect to this server when displaying the list of repositories if the connection type is set to “Automatic”.
If a server is set as “Automatic” and for some reason it is not reachable, Plastic SCM may show a delay in some operations. This is because it has to wait until the network timeout is reached (normally between 20 seconds and several minutes).