Table of Contents

1      Introduction. 1

1.1       What is Plastic SCM? 1

1.2       Problems without version control 1

1.3       Components 2

2      Basic concepts. 4

2.1       Repository. 4

2.2       Item. 5

2.3       Revisions 5

2.4       Branch. 6

2.4.2      Version tree. 9

2.4.3      Branch explorer 11

2.5       Smart branches 12

2.6       Workspace. 13

2.7       Label (marker) 15

3      Plastic SCM operations. 16

3.1       Creating a repository. 17

3.2       Creating workspaces 17

3.2.2      Shared workspaces 18

3.3       Add. 19

3.3.1      Ignored items 19

3.4       Check in. 21

3.5       Update. 22

3.5.1      Modified items in the workspace. 23

3.5.2      Items marked as .unloaded. 23

3.5.3      Checkout shelving. 23

3.5.4      Parallel update. 24

3.5.5      Cloaked items 24

3.6       Check out 26

3.6.2      Internal Checkout details 27

3.7       Displaying pending checkins 27

3.8       Undo checkout 28

3.9       Revert to a previous revision. 29

3.10    Symbolic links 30

3.11    Creating a branch. 31

3.12    Editing branch properties 33

3.13    Merge (integration) 36

3.13.1    Merge conflict types 36

3.13.2    Contributors 37

3.13.3    Merges from the same branch. 38

3.13.4    Merging from different branches 39

3.13.5    Merging from a branch and a label 40

3.13.6    Merge from a label 41

3.13.7    Merging from a changeset 41

3.13.8    Merging from a revision. 42

3.13.9    Merging from the command line. 42

3.13.10 Cherry Picking or selective merge. 43

3.13.11 Cherry Picking from branch. 45

3.13.12 Merging an interval of changes 45

3.14    Subtractive merge (desintegration) 46

3.14.1    Subtracting a revision interval 50

3.14.2    Subtracting a changeset 52

3.15    Creating a label 52

3.16    Applying a label 53

3.17    Working with attributes 53

3.17.1    Creating an attribute. 54

3.17.2    Applying an attribute. 54

3.17.3    Editing an attribute value. 55

3.17.4    Deleting an attribute application. 56

3.17.5    Querying objects with attributes 56

4      Starting up a project 58

4.1       Creating a repository. 58

4.2       Creating workspaces 59

4.3       Performing a first code import 60

4.4       Starting to work 60

4.4.1      Update. 60

4.5       Checking out items to work with them. 61

4.6       Finding checked out files 61

5      Workspace selectors in depth. 62

5.1       Selector´s appearance. 62

5.2       Selector definition. 63

5.3       Path rules 65

5.4       The norecursive path rule option. 65

5.5       Specifying wildcards on the path selection rule. 66

5.6       Retrieving an item’s specific revision. 67

5.7       Smart branch rules 67

5.8       Using several repository servers 68

6      Object specifications. 70

6.1       Revision specifications 70

6.2       Branch specifications 71

6.3       Item specifications 71

6.4       Label specifications 71

6.5       Repository specifications 71

6.6       Workspace specifications 72

6.7       Repository server specifications 72

7      Managing projects with Plastic SCM.. 73

7.1       Working on the main branch. 73

7.2       Branch per developer 74

7.3       Branch per task 75

8      Simple Query System.. 77

8.1       Query Language. 77

8.2       Usage examples 81

8.3       Query language grammar 83

9      Advanced Query System (AQS). 84

9.1       Query Language. 84

9.2       Usage examples 88

Figures

Figure 1: Types of objects a repository can hold. 4

Figure 2: Sample items and private items 5

Figure 3: Relation between revisions and items 6

Figure 4: Sample item history. 6

Figure 5: Representation of the item history. 6

Figure 6: Item revisions contained in a branch. 7

Figure 7: Branch representation. 7

Figure 8: Branch inheritance representation. 8

Figure 9: How the workspace maps branch’s revisions 8

Figure 10: version tree in the repository structure. 9

Figure 11: hello.cpp item calculated by Plastic SCM. 10

Figure 12: Sample version tree. 11

Figure 13: Sample Branch Explorer 12

Figure 14. Smart branches define dynamic branch hierarchies 13

Figure 15: How revisions map to a workspace. 14

Figure 16: Each developer can have many workspaces 14

Figure 17: Labels applied to revisions 15

Figure 18: base version control operations 16

Figure 19: Repository creation dialog. 17

Figure 20: Creating a new workspace. 18

Figure 21: Items added from visual studio. 21

Figure 22: Checked out elements before update. 23

Figure 23: Check out protection. 24

Figure 24: Check out view. 24

Figure 25: Check out recovery. 24

Figure 26: Cloaked items example. 26

Figure 27: A revision is created in the checkout operation. 27

Figure 28: Pending checkouts view in the GUI tool 27

Figure 29: Undo checkout from the GUI tool 28

Figure 30. Revert operation. 29

Figure 31. Revert from GUI 30

Figure 32: Creating a child branch in the GUI tool 32

Figure 33: Smart branch creation dialog. 33

Figure 34: Editing smart branch properties 34

Figure 35: How smart branches evolve through time. 35

Figure 36: Two smart branches hierarchy samples 35

Figure 37: List of items to be merged. 36

Figure 38: Revisions included on a merge operation. 37

Figure 39: Merge from the same branch. 38

Figure 40: Basic merge, merge completed. 39

Figure 41: parallel development scenario. 39

Figure 42: Developers work on the item. 40

Figure 43: Both branches have been integrated. 40

Figure 44: Labeled revisions on the branch have been merged. 41

Figure 45: Regular Merge. 44

Figure 46: Cherry pick 44

Figure 47: Cherry pick from branch. 45

Figure 48: Subtractive merge, initial code. 46

Figure 49: Subtractive merge, first modification. 47

Figure 50: Subtractive merge, second modification. 47

Figure 51. Version tree after merging the first change. 48

Figure 52: Subtractive merge sample, file after the two changes 48

Figure 53: Substractive revision merge from the GUI 49

Figure 54: Subtractive merge showing the result of the file. 49

Figure 55: How subtractive merge works 50

Figure 56: Version tree after a subtractive merge showing the subtractive link 50

Figure 57: Subtractive merge of an interval 51

Figure 58: Subtractive merge from GUI 51

Figure 59: Creating a new label 52

Figure 60: Apply label to workspace content 53

Figure 61: Create new attribute. 54

Figure 62: How to apply an attribute. 55

Figure 63: Add attribute dialog. 55

Figure 64: Edit the attribute value. 56

Figure 65: Delete the attribute application. 56

Figure 66: Query objects with attributes 57

Figure 67: New Repository. 59

Figure 68: Creating a workspace. 59

Figure 69: Update operation. 60

Figure 70: Checked out revision list 61

Figure 71: Default selector appearance. 62

Figure 72: Selector definitions 64

Figure 73: Sample directory structure. 66

Figure 74: Smart branch scenario to study selector 67

Figure 75: All changes on the main branch. 73

Figure 76: Branch per developer pattern. 74

Figure 77: Branch per task pattern. 75

Figure 78: Query language grammar 83

 

 

 

Foreword

 

A Brief Introduction to Software Configuration Management

A Software Configuration Management solution often contains the following components:

• Configuration Identification, which means that you can tell which body of source code you are working with.
• Configuration Control, which involves controlling the release of a product and changes to it throughout its lifecycle so that you can create consistent baselines of that product.
• Status Accounting and Auditing, which means that you can record and report on the status of components and change requests to help you to measure some aspects of quality and change.
• Review, to validate the completeness of a product and to help you maintain consistency among the components.
• Build Management, to help you to create and maintain a repeatable construction process.
• Process Management, to ensure that the organization’s development processes are followed by those developing and releasing the software.

Having all of those pieces doesn’t mean that you have an effective SCM solution, however. To have an effective (which is not the same to complete) SCM solution you need to understand that there are many ways that one can have implement the set of items in the list, and the right way will be different for every organization. You also need to know that these items are focused on the macro level; for your SCM process to work the micro process: what happens each day in the developer’s workspace needs to be correct. It is also necessary to remember that the reason we have SCM processes and tools is communication and teamwork.

To create an appropriate and effective SCM process you need to understand that the SCM process works together with your architecture and organizational structure (and culture). An SCM process that works well for a 3-person startup building web applications will not work for a larger application development process distributed across countries. What these two types of organizations will share is that the process is simple to use and allows for repeatability. This is where good use of patterns comes in.

Some of the key things that your SCM process should allow for, but which you won’t often see on a list are the ability for developers to create a Private Workspace that contains the version of the application that they need to work with; the ability for developers to build the application before integrating with the rest of the team, and testing to verify that everyone is meeting each other’s expectations.

The theme that underlies all effective SCM processes is that SCM is there to facilitate communication. A good SCM tool will help your team work together.

 

Stephen P. Berczuk

October 2006

About this guide

This guide describes Plastic SCM’s regular use. It will introduce the features and techniques used to get the most out of the tool.

Audience

This guide is targeted to the average developer, assuming familiarity with operating system concepts, programming languages and integrated development environments (IDEs) like Microsoft Visual Studio or Eclipse.

Online documentation

Besides this document and the rest of the guides, Plastic SCM provides online reference throughout its different client frontends.

On the command line interface, both Windows and Linux, this reference can be obtained with the command:

For extended information on a specific command, type:

The graphical interface provides online reference through the Help menu.

Documentation errors

If you find any problem in this guide or any other part of the online reference, please report it using the following email address:

 

support@codicesoftware.com

 

1       Introduction

1.1    What is Plastic SCM?

Plastic SCM is a complete Software Configuration Management (SCM) platform, able to manage the evolution in time of source code and any development asset. It improves visibility and parallel development, ensuring optimum collaboration among teams and introducing new visualization formulas on a user-friendly interface.

1.2    Problems without version control

Development groups not using SCM are most likely familiar with the following topics:

• The current version of the source code is accidentally replaced by an older one.
• A critical update is wrongly discarded from a release to a client.
• Changes are made in an incorrect version of the system.
• Fixed bugs suddenly reappear.
• Difficulties to exactly know which versions of each file and directory go into a certain release. This problem can have different severity levels: from not exactly knowing the version of certain items to a complete information black hole in which there is no easy way to know which binaries are in production.
• Builds are not reproducible. There is no easy way to reconstruct an old release because sources and libraries are not correctly managed.
• Huge overhead when dealing with several releases in production. Is a very common scenario for a company, focusing on product development or on project development, to have more than one version of the same software released. Without the help of a proper SCM managing fixes, changes and upgrades can be a nightmare.
• No way to easily check changes made to the code or associated resources.
• Project managers can’t track progress.
• Poor team communication.

Almost all the described problems can be solved making a good usage of SCM tools. This guide will show how Plastic SCM can be a key to solve them.

1.3    Components

Plastic SCM has been designed around a Client / Server architecture.

• Server is responsible for project data storage, as well as managing clients’ access to that storage.
• Clients run on the developers’ machines, and are responsible for communicating user operations to the server. The supported clients are:
• Command Line Interface (CLI): gives access to Plastic SCM operations on the operating system shell. Very useful for task automation.
• Graphical User Interface (GUI): provides access to Plastic SCM operations using a window-oriented interface. It provides some graphical diagrams not available in the command line.
• Integrations with Integrated Development Environments:
• Visual Studio integration: provides access to commonly used operations like checkout / checkin from within Visual Studio, as well as full access to GUI views like Branch Explorer, labels and checkouts.
• Eclipse integration: provides access to the most used operations like checkout / checkin from within the Eclipse development environment.
• IntelliJ integration: provides access to the commonly used operations from the IDEA IDE.
• JDeveloper.
• Build Management tools integrations for the following products:
• Cruise Control
• Final Builder
• Integrations with task and issue management tools like:
• Atlassian Jira
• TechExcel DevTrack
• RallyDev
• Axosoft Ontime
• Version One
• Fog Creek’s FogBugz
• Trac
• Bugzilla
• Mantis

The following table shows the Operating Systems supported for the main system components:

 

2       Basic concepts

This chapter will detail the different elements that build the Plastic SCM platform and will set the basis for the descriptions of the system operations on later chapters.

2.1    Repository

The repository is the central storage area of Plastic SCM, where all revisions of both files and folders are saved, as well as their timestamps, who created them and the relations among them. Figure 2 shows all object types a repository can contain and that will be described further on.

Figure 1: Types of objects a repository can hold

A Plastic SCM server can manage as many repositories as needed, limited only by the available disk space.

At Plastic SCM server first boot, a default repository will be created if no databases are found from a previous installation. This repository will indeed be named ‘default’. This way, the user can start working immediately and create more repositories for different projects in the future.

For a complete reference on the operations that are available for repositories, as well as backup and restore procedures, check Plastic SCM Administrator’s guide.

2.2    Item

An item is any file or directory whose evolution in time will be managed by Plastic SCM. A software project is often composed of many files and directories. When this tree is located under version control, Plastic SCM calls those elements items, indicating that it will be possible to retrieve their change history and revert to a previous state. All information about the items, such as name, type, owner and the changes log, is stored in the repository.

Plastic SCM supports directory versioning the same way it versions files. This means that item renaming and moving is transparently supported and correctly propagated along the project evolution. This is especially important in order to rebuild the project state on a given time in the past.

However, not every file or directory in the project needs to be under version control. For instance, it is not usually a good practice to make items out of user-specific configuration files, since these are generated by the tools or contain settings specific to each developer that would disturb others when shared.

Plastic SCM calls ‘items’ the elements under version control, and ‘private elements’ or simply ‘privates’ the elements in the project tree but not under version control. These private elements are not considered by Plastic SCM, but can be useful for other tools like compilers and development environments. The following figure shows how private elements are related to items in the workspace:

Figure 2: Sample items and private items

2.3    Revisions

As items evolve in time, new revisions are created and it is usual that some items will undergo more changes than others throughout the development. Plastic SCM stores all the revisions of each item, so it is possible to revert to a previous state of these items in a given moment. A sample of this evolution is depicted on the following figure:

Figure 3: Relation between revisions and items

Revision creation is performed through the check-out and check-in operations. When a modification is being made to a file, it is checked-out and this is registered in Plastic SCM server. In order to create a new revision of the item, it must be checked-in, indicating the server to save the current file (or directory) content. This content is transparently compressed to reduce disk cost in the server.

Revisions are stored in the repository, saving revision date, revision creator, and other data. The set of revisions of an item is called ‘history’ or ‘log’ of the item. Following figure shows a sample item history:

Figure 4: Sample item history

2.4    Branch

Branches are a key element in Plastic SCM, and one of its most powerful design features. The previous section introduced the history of an item, which can be represented like the following figure:

Figure 5: Representation of the item history

This representation is implicitly employing the branch concept. A branch is a revision container, capable of storing the item’s evolution, as in the following figure:

Figure 6: Item revisions contained in a branch

When a new repository is created, it always contains a branch called ‘main’, so that every newly added item starts creating its revisions in this branch. Further sections will describe how to create more branches and create revisions on them.

Branches can contain revisions for more than one item. This is, indeed, the most common situation, and ‘main’ branch usually contains revisions for almost every item present in the repository. The following figure represents a sample ‘main’ branch container:

Figure 7: Branch representation

Figure 7 shows a branch represented as a container, with items (yellow cubes) and their revisions (white cubes) representing their evolution in time. It should be noted that different items have different number of revisions, meaning that they can evolve on their own. The history of the structure of the project is recorded in the history of its directories. In this way, when one item is moved, new revisions of the source and destination directories are created, but not a revision of the item itself.

In the sample on Figure 7, the item ‘master.cpp’ could be moved from ‘src’ directory to a different one, and it would preserve its three revisions. Thanks to this mechanism, Plastic SCM transparently supports code refactors, not losing the history of moved or renamed items.

2.4.1.1    Branch inheritance

One of the most important features in Plastic SCM is its support for defining a branch hierarchy, and the ability to precisely specify what content to select using it. This concept is called ‘branch inheritance’. The following figure represents two branches, and will be used to illustrate the feature:

 Figure 8: Branch inheritance representation

In Figure 7, a single branch was introduced. Now, in Figure 8, another branch (‘child1’) is added as a child branch of ‘main’. This new branch contains only revisions of two items (hello.cpp and master.cpp), indicating that only those two items have been modified on the branch.

All those pieces fit together when the developer tells the server what branches to use in a workspace. If the user wants to work on ‘/main/child1’ branch, the update operation will try to resolve what version to copy for each item. It will try to retrieve the latest revision on branch ‘child1’. If no revision is found there, it will then try with the ‘main’ branch, and pick that. A representation of how the revisions are mapped from the repository to a workspace selecting ‘/main/child1’ branch can be found in the following figure:

 

Figure 9: How the workspace maps branch’s revisions

The workspace needs to load one revision for each item, so the final content is resolved in these terms:

• master.cpp: revisions exist on ‘/main/child1’ so the latest in that branch is loaded.
• hello.h: revisions exist on ‘/main/child1’ so the latest in that branch is loaded.
• src: no revisions are found on ‘/main/child1’, then ‘/main’ is explored, and latest revision there is loaded.
• hello.cpp: no revisions are found on ‘/main/child1’, then ‘/main’ is explored, and latest revision there is loaded.

An item can have revisions on a more complex branch hierarchy, allowing for multiple inheritance levels, and several developers working on the same items on separate branches, so that they don’t interfere with each other. A further chapter will explain how to reconcile those branched items, resulting in contents being merged to produce stable project releases.

Creating a branch in Plastic SCM is a very easy operation as no content is replicated among branches. Only when items are modified, revisions are created on the branch, so branches don’t affect repository size by themselves, and are extremely efficient.

Although previous diagrams are useful to introduce the novel user to the concepts of Plastic SCM branching and how revisions are mapped to workspaces, different representations are used on the daily work, like the version tree of given item, or branch relations as represented in the branch explorer.

2.4.2 Version tree

The version tree is a graphical representation of the evolution of one single item. Figure 10 represents the pieces of repository information displayed in this diagram, continuing with the sample in this section. 

Figure 10: version tree in the repository structure

The following figure shows a real screenshot of how Plastic SCM displays that item:

Figure 11: hello.cpp item calculated by Plastic SCM

Due to the fact that the version tree can grow across many branches, Plastic SCM offers a 3D representation for it, allowing for better manipulation and visualization. The following figure shows a bigger tree than the previous trivial sample:

Figure 12: Sample version tree

2.4.3 Branch explorer

The Brach Explorer offers a timely view of the evolution of branches and their relations. It gives a global overview of the project evolution, as opposed to the much more localized view of the version tree, which only displays the history of a single item.

The Branch Explorer draws a representation of all branches on a given repository, displaying when they were created and their lifetime, understood as the period for which revisions are present in the branch. The following figure shows a sample of this diagram:

Figure 13: Sample Branch Explorer

In the diagram branches are represented as horizontal bars. Columns are specific dates in which some event happened, like branch creation, last day in branch lifetime, or a merge. Parent relations are drawn as straight lines from the parent to the beginning of child branches. Merge lines appear as curved lines. In order to help determining merge direction, merge curves always start horizontal from the source, and end vertical on the destination with a little circle.

When a branch is selected, it is highlighted together with its relations to help identification.

2.5    Smart branches

Smart branch support extends basic Plastic SCM branch inheritance capabilities introducing the ability to dynamically define branch hierarchies.

Basic branch inheritance is heavily tied to the workspace selector, so depending on the way a selector is configured, branch inheritance will behave differently.

When branch inheritance was introduced above it was said that when the developer is working on a specific branch and a revision is not in the branch, Plastic will load it from the parent branch. The question here is: which revision of the item will be used? The question is answered by the developer when he chooses a label as the base of the branch on his workspace through the workspace selector. But smart branches introduce a simpler solution: during branch creation the user can specify which one will be the point (label, changeset or branch) to use as base for the newly created branch, so that each time Plastic needs to locate a revision from a given item on the branch hierarchy, it will go to the right place.

Smart branches are actually a step ahead in Plastic branch inheritance and enhance branches in such a way they’re able to remember which specific branch, changeset or label is its parent at a certain instant (changeset).

Figure 14 depicts a sample smart branch scenario in which a branch has different bases or inheritance points as it evolves through time.

The branch actually remembers each of the configurations so it is possible to go back to a given changeset and entirely rebuild the desired configuration.

Figure 14. Smart branches define dynamic branch hierarchies

2.6    Workspace

To perform any operation on revisions and items from a given repository or set of repositories, a workspace is needed.

The workspace is a directory in the user’s file system in which repository contents are downloaded. This is the location that will be used to edit, compile and work with development projects.

The workspace gets a certain set of revisions from the repository into the user’s file system. To actually select which revisions of items must be retrieved, the workspace has a selector. A selector is a set of rules that tells the server which revisions should be obtained.

Figure 15 illustrates the workspace concept and the selector. In figure you can observe that there are several items available, and each of them has different revisions. To map the repository into a file system, at most one revision from each item can be obtained. The selector contains the rules to choose between the available revisions. This way a workspace, created in a client machine, is able to download specific revisions from the server.

Workspaces act as an interface to the repository that development tools (IDEs, compilers, debuggers, documentation generators…) use to operate transparently as if the versioned assets were regular elements on a file system.

Developers can create as many workspaces as they need to. Normally a developer will have several workspaces, as Figure 16 depicts.

Figure 15: How revisions map to a workspace

Figure 16: Each developer can have many workspaces

In Plastic, workspaces are stored locally in the client machine, in a hidden folder named .plastic and placed in the root of the workspace. This folder contains the following files:

• plastic.selector, which stores the current selector text.
• plastic.workspace, which stores the name of the workspace and its GUID (Global Unique Identifier).
• plastic.wktree, a binary file which states the revisions that must be loaded in the workspace in this moment.

Furthermore, in the local user folder (in Windows XP: Documents and Settings\<user>\Local Settings\Application Data\plastic) a plastic.workspaces file is stored which contains information related with the workspaces handled by the Plastic client. This is a sample file:

 

Each line contains the workspace GUID, name and path on the disk, separated by tabs.

2.7    Label (marker)

A label is a way to mark specific revisions so that they are grouped together on a given criteria, meaningful to the user. When a label is applied, a snapshot of the items’ state is created. Later on, that snapshot can be easily referenced in order to identify a specific moment in time. A label or marker is, finally, an easy to remember name given to specific set of item revisions.

Labels are always applied to revisions currently present in the workspace and can be applied to one or more items depending on the needs. It is quite frequent to apply labels to all the items in the workspace.

Figure 17 shows two labels, ‘Label0’ and ‘Label1’. Both labels are being applied to different items. ‘Label0’ is only applied to revision 0 of the first item. However ‘Label1’ is grouping together several revisions of different items.

Figure 17: Labels applied to revisions

In order to use a label, the first step is creating it, indicating in which repository it is going to be created and its name.

Labels are used for many different reasons. They can be applied to some revisions just to highlight them, or they can be used to manage the development process, helping in the path to mark releases and baselines.

3       Plastic SCM operations

This chapter will describe main Plastic SCM operations. Being familiar with other version control systems, most of the operations will be already known, with some differences.

Figure 18: base version control operations

For each operation, several sample command line usages are shown. It is possible to get more detailed command information through the ‘help’ command:

3.1    Creating a repository

A repository called default is created during the first server boot. Using this repository, users can easily start working, as they only need to create their workspace. In this chapter, a new repository will be created and used instead of the default one, in order to illustrate how to work with different repositories.

3.1.1.1    From the GUI tool

1. Menu Repository.
2. Click on “Create New Repository”.
3. Give a name to the new repository, and the server that will hold it.

Figure 19: Repository creation dialog

3.1.1.2    From the command line

3.2    Creating workspaces

The first time a developer runs the Plastic GUI tool, no workspaces are detected, so it will display the workspace selection dialog, allowing for creation of a new one, as shown on Figure 20. By default, workspaces point to branch ‘/main’ of the repository ‘default’.

3.2.1.1    From the GUI tool

1. Menu Workspace.
2. Click on “Create new workspace”.
3. Enter a name for the new workspace, its path and the server that will manage it.

Figure 20: Creating a new workspace

3.2.1.2    From the command line

3.2.2 Shared workspaces

It is possible to share a workspace by creating it in a shared folder or directory, mounting a virtual disk unit or using symlinks (UNIX based systems).

This way, the user will be able to manage his loaded revisions from any machine that can connect to that machine and use that shared resources.

To use this functionality, you simply have to create a shared resource (folder in Windows terminology, directory in Linux terminology) and create a workspace on it. Then, from another machine, mount or create a share for accessing that shared resource and try to create a workspace on it. Plastic will detect automatically that the workspace already exists and it simply will connect with that workspace. Every change you do in the shared workspace from any location will be seen from any other location.

 

3.3    Add

Once a repository has been created (as a reminder, a repository called “default” is always created by the server), the first thing to do is adding files and directories to it so that they are traced and their evolution is recorded. This is done with the ‘Add’ operation, which is responsible for creating the needed data and structures in the repository to hold the new items.

When an ‘add’ operation is started, all items are added to the current branch being used in the workspace. After the operation is completed, all items are kept checked-out (both files and directories), meaning that no item content actually travels to the server and only the metadata is created in this step.

3.3.1 Ignored items

Plastic SCM can ignore item patterns on the add command. You can define some patterns in an ignore.conf file and the files/directories that match any pattern defined in that file won’t be added to the repository. You can place this file either on a workspace root folder in order to apply the ignore rules to that workspace, or on the Plastic client configuration directory in order to apply rules to all workspaces of the user. The user configuration folder, on Windows systems (prior to windows Vista), can be found on:

Since Windows Vista, this folder is:

On non-windows systems:

Note that the ignore.conf file itself can be added to the repository. Doing so, the ignore rules are applied to all users of the repository, since they will get the file when updating their workspaces.

The file must contain one pattern per line. Patterns can be specified with wildcards (? and *) with the same meaning that the command line. If a line starts with # character, this line will be assumed as a comment.

Each line pattern is interpreted as a full path to a file inside the repository. The wildcard ‘*’ can be used, meaning any number of characters in the position it’s found. Additionally, it is possible to include exceptions to the ignore rules. Exception rules start with an exclamation sign (!) and comment start with ‘#’.

This is an example of the ignore.conf file:

3.3.1.1    Item types (bin/txt)

Plastic SCM recognizes the most popular file types as text or binary automatically, reading its extension. Some unrecognized extensions can be incorrectly assumed as binary when they are really text. The user can define custom file types (binary/text) in a filetypes.conf file, placed also in the client configuration directory.

This is an example of the filetypes.conf file. (The # character is a comment):

The ‘add’ operation can be run on the command line, on the GUI tool or from the IDE integrations. This last case presents the advantage of the IDE accounting for the items that need to be added, leaving build products and user-specific configuration files as private elements. The following figure shows several items added from within Visual Studio. Items with a red dot have been added to the repository, while the others have been left as private. When those items are checked-in, they will get a green tick.

Figure 21: Items added from visual studio

3.3.1.2    Adding items from the command line

In order to import a project from the command line, copy the contents of the project in the workspace directory, cleaning compilation results or user-specific files. Once the project tree contains only the files that need to be under source control, the following command will add the contents of all files and directories recursively in the current directory. Remember to check-out the current directory before adding items.

To add an isolated item, type

To add an item, automatically checking-out the parent:

3.4    Check in

The ‘check-in’ operation stores changes made to an item in the Plastic SCM server. Check-in always needs a previous Check-out or add operation. Before a check-in is performed, the system ensures that changes have been performed by comparing with the previous revision of the item. If no change has been made, usually there is no point in creating a new revision and that is the reason why the system performs this check. However, it is possible to override this behavior using the ‘forced check-in’ option.

The check-in operation stores the revision in the same branch as the previous item check-out happened and it is an atomic operation, so if an error occurs, no item will be checked-in, even those that could be successful. This ensures that either all specified checkouts will be checked-in, or none will. When the check-in is successfully completed, the revisions created share a ‘changeset number’, which is printed at the end of the check-in operation in the command line client, and it is a convenient way to group related changes that Plastic SCM provides, together with branches and labels.

It is possible to get a list of the items that belong to a changeset through the query system, described later on this document.

3.4.1.1    Checking-in items from the GUI

Any checked-out item can be checked-in using its context menu and selecting check-in.

3.4.1.2    Checking-in items from the command line

To check-in an item that is checked out from the command line, use the ‘ci’ command:

It is possible to recursively check-in a whole directory and its contents, although the operation the operation will show a warning for those items not checked-out or private.

To check-in a checked-out item, overriding the content check:

Finally, to list the items contained on a changeset:

3.5    Update

The Update operation downloads files and directories from the repository in the server to the workspace in the developer machine. When a workspace is created for the first time, an explicit update is needed in order to populate its contents. In normal conditions, an update is performed to bring the latest revisions of the configured branches to the workspace or when the workspace configuration is changed, for instance after a ‘switch to branch’.

The Update operation traverses the given directory looking for changes against the current workspace configuration, checking if different (normally newer) revisions from those currently loaded need to be copied from the repository.  For instance, if two developers are working on the same branch and creating new revisions on their respective workspaces, they will need to update in order to get the changes from each other.

There are two modes for the update operation. Regular update will check the current workspace contents against different revisions available on the server for the current workspace selector. Only those revisions that are different will be downloaded. The other mode is called ‘update forced’, and it will force the download of the items indicated by the workspace selector, regardless of current workspace content. From the command line, this is signaled through the --forced argument.

3.5.1 Modified items in the workspace

Sometimes, an update operation can print a message like:

This happens because the contents of the item or its timestamp have been modified without telling Plastic SCM to check-out the file, and the update operation avoids overwriting the file so the changes made are not lost.

The developer can directly check-in the item to create a new revision of the file on the repository. If the file content has not been modified, it normally means that the timestamp has been modified for some reason. The user can perform an update forced on the item and the timestamp will be synchronized in the repository.

3.5.2 Items marked as .unloaded

As a consequence of the new revisions brought by the update operation, some files or directories could have been unloaded from the system. In this case, Plastic SCM follows the rule of never deleting anything, so instead of removing the elements that would otherwise be lost, they are renamed with the extension .unloaded and became private elements. This way the contents are preserved in case there was something important inside, but having a different name, they will not conflict with other tools.

3.5.3 Checkout shelving

Plastic SCM is capable of storing the current content of a checked-out item in the repository, without actually creating a full revision like one created by the check-in operation. Following again the rule of never deleting anything, when an update operation would be forced to overwrite a checked-out file, their contents are first stored in the server, and then the file is overwritten. But this stored checkout can be later retrieved.

This mechanism will run when the user switches the workspace to a different branch and one or more items were checked-out. If, as a consequence of this update any checked-out item needs to be overwritten, it will be first saved to the repository. When switching back to the old branch, the checked-out content will be restored to the workspace.

Imagine you are working on branch ‘/main/task001’, and some items are checked out as you can see on Figure 22

Figure 22: Checked out elements before update

If you switch to the branch ‘/main/task006’, update will store your checkouts from ‘/main/task004’, and bring the revisions in ‘/main/task006’. This operation can be seen in the log.

Figure 23: Check out protection

Plastic SCM will preserve the checked-out contents while you are working on ‘/main/task6’. You can check that your checkouts are still there in the checkouts view. They will appear with an orange icon, meaning that the items are checked-out, and are not in the workspace.

Figure 24: Check out view

When you switch back to ‘/main/task4’, update operation will download your checked-out content. In the checkouts view, they will appear as a green icon with a red dot, meaning they are in the workspace and checked out.

Figure 25: Check out recovery

The user can manually shelve a checked out item through the using the shelve command:

 

3.5.4 Parallel update

The update operation by default uses several threads to communicate with the server. While this mode improves performance on most scenarios, a few cases can benefit from using a single thread for instance, to reduce the number of connections on low bandwidth connections. To perform an update operation on a single thread, use this command:

3.5.5 Cloaked items

You can specify that you don’t want to update some files every time you change your workspace configuration. You may have several reasons to do this:

• Files which are modified few times;
• Files which are very big in size and take long time to download;
• Files which are not affected by the regular development process and don’t receive changes. They can be downloaded once and stay untouched in the workspace.

Examples: testing programs, 3^rd party libraries, binary files used for different purposes…

This way you can decrease the update time considerably and therefore you can work in a more comfortable way.

To indicate which files/folders Plastic should cloak, a cloaked.conf file has to be created. The syntax of that file is very similar to the ignore.conf file (see the Add section in this manual):

The cloaked.conf file can be placed in the user local directory (that is, /home/<user>/.plastic directory in Linux or C:\Documents and Settings\<user>\ Local Settings\Application Data \plastic in Windows XP or C:\Users\<user>\AppData\Local\plastic in Vista/Win7) or in the root directory of the workspace. In the first location it will be applied to every workspace; in the second one it will be applied only to the workspace where the file is placed on.

Now, when you open the Plastic GUI, you will see the cloaked items identified by its own state; if you perform an update of your workspace, your cloaked items will be ignored; when you perform a recursive checkout in a directory which contains cloaked items, those items will be skipped.

Figure 26: Cloaked items example

3.6    Check out

The checkout operation tells the system that the given items are being modified. Files are checked-out when their content is being altered, and directories are checked-out when items are added, renamed, moved or deleted inside them.

When an item is checked-out, it is marked as ‘CO’ on the command line, and it is marked with a red dot in the GUI tool. If the workspace is pointing to a child branch that didn’t contain a revision of the item being checked-out, the check-out operation will create the first revision (in check-out state) in that branch, from the current revision in the workspace. In the following sample the items Form1.cs and Form1.Designer.cs, originally on branch ‘/main’ have been checked-out with the workspace pointing to the branch ‘/main/branch4’.

When a file is checked-out, the read-only attribute is removed, so that the user is able to write on the file. This attribute is later restored when the revision is checked-in, so that the file is not editable. Although it is possible to manually set this attribute on any item, letting Plastic SCM manage them is an easy way to prevent accidental manipulation of the items.

The 3D version tree displays checkouts as purple cubes, while regular revisions are drawn in blue.

3.6.1.1    Checking-out items from the command line

To checkout any given item

Checkout all items read from standard input:

3.6.2 Internal Checkout details

Internally, checking out an item has the effect of creating a new special and empty revision in the repository. Figure 27 shows how this revision is created from the revision loaded in the workspace. When the check-in operation is performed later, that check-out revision will become a regular revision and content will be uploaded to the repository.

Figure 27: A revision is created in the checkout operation

This mechanism makes it possible to manage checkouts of every developer in a centralized fashion and serves as the basis for the checkout shelving described previously in the update section.

3.7    Displaying pending checkins

Plastic SCM controls what items have been checked out by every user on every workspace, and it is possible to list them from the different clients.

3.7.1.1    From the GUI tool

 

Figure 28: Pending checkouts view in the GUI tool

3.7.1.2    From the command line

To get a list of the pending the checkouts in the current workspace:

To get a list of all checkouts in all workspaces:

Obtain a list of checkouts in current workspace displaying just the item name:

3.8    Undo checkout

Once an item has been checked out, it is possible to undo that checkout, effectively reverting the item to the state it had before it was checked out. If the item is a file, its contents are reverted to the previous state. If the item is a directory, the behavior is the same, however here just the names of the items in the directory are updated, and any added or deleted items are downloaded.

3.8.1.1    From the GUI tool

Figure 29: Undo checkout from the GUI tool

3.8.1.2    Undo check out from the command line

To undo the check out of any given item:

To undo check out of all pending check-ins in the current workspace:

The ‘findcheckouts’ command (abbreviated ‘fco’) prints the information of the workspace checkouts. The --format modifier alters the way results are printed on screen. In this case, {4} instructs the command to print only the item name. This is fed to the undo command through a regular shell pipe.

3.9    Revert to a previous revision

The ‘revert’ operation creates a new revision with the contents of a previous revision. This way, unwanted changes can be discarded recovering previous valid revisions.

Figure 30 explains how the ‘revert’ operation works.

Figure 30. Revert operation

The revert operation is available from the revision history view on the GUI as the Figure 31 shows.

Figure 31. Revert from GUI

The operation is also available from the command line using the cm revert command.

3.10Symbolic links

Plastic supports symbolic links versioning for UNIX users; symbolic links are treated as any other item with some special features.

There is a command line modifier called “--symlink” which can be used to refer the command action to the symbolic link file instead of its target. You can use the modifier with these commands:

• Checkin
• Checkout
• Uncheckout
• Ls
• Tree
• History

If you use these commands without the “--symlink” modifier it implies that the action of the command is applied to the target of the symbolic link, i.e. to the item that the symbolic link points to, instead of the symbolic link itself.

On the other hand, with the rest of commands the action is automatically applied to the symbolic link file and not to its target, so the “--symlink” is not needed. Below there is an example that shows the same command used with and without the modifier:

Without the modifier the “ls” command shows the info about the symlink target’s data.

With the modifier you can see the symbolic link info instead of its target.

3.11Creating a branch

As mentioned earlier, Plastic SCM always creates a branch called ‘main’ on every new repository. In order to use other branches, they need to be created first.

3.11.1.1                 From the GUI tool

Plastic SCM will always create smart branches when a new branch is created from the GUI. Smart branches are an enhancement of regular Plastic SCM branches and they will actually remember the starting point from which they were created, which eases further use.

In the branches view, select the branch from which you want to create a child one, right click on it and choose the option ‘Create child branch’, as Figure 32 shows.

Figure 32: Creating a child branch in the GUI tool

A smart branch creation dialog will pop up, like the one at Figure 33. The dialog will let the developer introduce both the new branch name plus its comments and then choose the branch base.

There are three different branch base possibilities for any given new branch base: use a given label as the starting point, use a given changeset on the parent branch or just choose to dynamically inherit from the latest on the parent branch (which was the default option prior to the introduction of smart branches).

 

Figure 33: Smart branch creation dialog

3.11.1.2                 Creating a branch from the command line

Branches are created with the ‘mkbranch’ command. This sample creates a branch called ‘task1’ as a child of the ‘main’ branch.

Slashes ‘/’ separate the different levels of the branch hierarchy. A branch can only have one parent branch, and any number of child branches.

When a new branch is created from the command line it isn’t automatically converted to a smart branch. To do so the setbranchbase command is used.

Running the following command will make the newly created branch task1 inherit from the revisions on main labeled as BL010.

3.12Editing branch properties

Smart branches have the ability to evolve their inheritance through time, so branch bases can be modified after being set or even after some development occurred on the branch.

After a branch is created you can edit its properties accessing the properties option on the branch context menu.

Figure 34 shows the smart branch properties dialog. The dialog shows the current branch base of the smart branch, and enables the developer to run the following operations:

• Rename the branch: editing the name textbox.
• Change the branch comments.
• Change the branch base.

Figure 34: Editing smart branch properties

It is very important to understand how changing a branch base works. Each time a new base is set to a smart branch a new base link (also known as parent link) is created. So the base is not actually edited but a new one is created. This allows developers returning to previous configurations choosing the right branch changeset in their workspace selectors.

Figure 35 shows a sample smart branch evolution and how its bases are changed over time.

Smart branches introduce a whole new way to create and maintain branch hierarchies which is very convenient in a number of development scenarios. Using smart branches and their corresponding bases it is possible to define different hierarchies in which the developers exactly specify what has to be included or excluded from a certain branch, as the Figure 36 defines.

Figure 35: How smart branches evolve through time

Figure 36: Two smart branches hierarchy samples

Smart branches can evolve due to many different reasons:

• A task branch which has to be rebased to a newly created baseline
• A maintenance branch which moves to a new release
• A feature branch which has to include newly created common functionalities

3.13Merge (integration)

The merge operation is in charge of reconciling the contents of items that diverged among branches, for instance when two developers perform changes to the same item in separate branches to work in parallel, and the changes need to be merged back together; or when two developers work on the same branch but have separately modified the same file and their changes have to be merged.

The merge operation is traditionally, one of the most complex operations on version control systems. But Plastic SCM tries to reduce its complexity, solving automatically as many conflicts as possible.

A merge operation will check the differences between a branch (called source branch) and the current workspace content (destination).  If the merge source is a branch, the latest revision of the items included on that branch will be taken in order to see if they need to be merged. In order to carry out a merge operation, a source must be chosen, and it is compared to the current workspace content, called destination. Within Plastic SCM, destination is always the workspace content.

Plastic SCM determines which items have been modified from origin to source, and will list them. The following figure shows an example list of the items to be merged:

Figure 37: List of items to be merged

It lists both files and folders to be merged, the type of conflict and their contributors. Next topics will explain in detail each of these issues.

3.13.1             Merge conflict types

The aim of a merge operation is integrating the changes done on the code base on different ways. Two types of conflicts can be given:

• Copy merge: the item has been added for the first time to the source code control so the merge only has to copy the content to the destination.
• Merge: the item already existed both on the source and destination and those changes have to be integrated. In this case, the system checks where the changes come from, and this is indicated in the ‘Contributors’ column.

3.13.2             Contributors

The contributors are the item revisions included on the merge. There would always be a merge source, which is the revision of the branch to be integrated; a destination, which is the revision located on the current workspace; and a baseline, which is the parent revision to the other two. The following figure shows where each revision is coming from:

Figure 38: Revisions included on a merge operation

In the sample, the user workspace is pointing to branch br:/main, and the content of branch br:/main/child1 will be integrated there. The contributors would be:

• Source: /main/child1#1
• Destination: /main#5
• Baseline: /main#4

Figure 38 also shows that the merge result will be creating a new revision /main#6 once the merge is done and the result saved.

Keeping these concepts in mind, the column ‘Contributors’ on the merge dialog could show the following values:

• Source: changes are just coming from the source. There are no new revisions on destination after the base revision. This type is automatically solved by applying every source change to the destination.
• Destination: changes are just coming from the destination. This is the opposite case as the one above and it is also automatically solved.
• Both: there have been new revisions both on the source and destination branch. This type of merge can be automatic or manually, depending on the following:
• If it is a text file, conflicts will be automatically solved whenever changes have been done on different lines. In the case that the same lines have been changed, a graphic merge tool will be shown, allowing integrating the changes. This tool will be described beyond.
• If it is a binary file, the binary merge tool will be shown, choosing which revision to keep as merge result. It is possible to define merge tools associated to different file extensions on each client configuration.
• In the case of a directory, the system will try to integrate the changes done on both source and destination revisions. This integration is usually automatic, even though there are four options requiring a tool to integrate changes. Every merge will be automatic except in the following cases:
• Two items have been renamed the same both on source and origin
• An item has been differently renamed on source and destination
• Two new items have been added with the same name on source and destination
• An item has been renamed with the same name as another one added on origin and destination.

3.13.3             Merges from the same branch

A merge could be needed to be done using the same branch as source and destination. This happens when a file has been changed from two different workspaces pointing to the same branch.

Figure 39: Merge from the same branch

In this case, ‘developer2’ would first integrate his changes with the ones on the branch introduced by ‘developer1’.

Figure 40: Basic merge, merge completed

Once ‘developer2’ has finished merging the items, he can check in his changes keeping the integrity of the base code.

3.13.4             Merging from different branches

The usual merge scenario is the one on which the source branch is different from the destination branch (that where the workspace is pointing to). Following figure shows a possible scenario, in which two developers created separate branches to work in parallel (/main/branc001 and /main/branch002) starting from the same point on the main branch (revision /main#1). Figure 41displays one single item (boo.c), however a regular branch will contain several items.

 

Figure 41: parallel development scenario

 

Figure 42 shows how the developers work separately on their respective branches, making changes on the item without interfering each other. They can make as many intermediate checkouts as desired, as their check-ins are on the private branch.

Figure 42: Developers work on the item

When a developer finishes working, the changes are ready to be integrated on the /main branch, so they will become visible to the rest of the developers.

In order to perform the integration, the workspace is pointing to ‘br:/main’ (remember that the merge destination is always the workspace content), and branches are integrated one at a time, making it possible to integrate as many as needed. The result for item ‘boo.c’ is showed on the following figure.

Figure 43: Both branches have been integrated

In this sample, no check-in was performed after each integration, so all the merge links point to the /main#2 revision.

3.13.5             Merging from a branch and a label

Even though the most common merge case is that on which different branches participate (shown above), it describes that the last changes on source branch are included on the workspace.

Sometimes it may not be necessary to merge the last content of the branch but the last labeled content. This will happen when we want to include the changes made a branch on which we are still working and the content we need is a stable one labeled before.

In order to get this content we can set that branches merge so that instead of including the last revision of each item it will include a certain revision which is labeled on the branch.

The following figure only shows a certain item (boo.c), on which we have kept on working on the branch and we want to get that item’s labeled revision.

Figure 44: Labeled revisions on the branch have been merged

The revision included on the merge is not the last revision on the branch, as it happened on the case of merging from different branches, it is the labeled revision.

3.13.6             Merge from a label

We have explained how to include changes from a branch on the workspace. We could have the situation on which the changes to be included are the previously labeled ones regardless the branch on which they are contained. The difference between merging from a label and merging both from a branch and a label is that on the former case the items were labeled on a certain branch and on this case we merge every item with the same label, wherever branch they belong to.

This option can be very useful for creating a new release if working with multiple branches. When a new release is created, it should be labeled so the user can always go back to a stable product. Once a release is done, tested and labeled, the developers should include those new changes on their branch, for this they must merge from the release label.

3.13.7             Merging from a changeset

On the check in operation explanation you could see that a group of items that were checked in together were grouped in a changeset and it was given a unique number. Through this changeset number you can refer to the group of items that created a change.

As a certain change can be identified by its changeset it can be merged by merging that changeset. As well as on the case of merging from a label, we do not depend on the branch on which the changeset is located.

3.13.8             Merging from a revision

The cases explained so far had a merge source containing more than one item. It’s also possible to merge one single revision of an item.

The difference with the previous methods is that only the revision indicated by the user will be included, so the user will decide which item has to be merged, instead of the system looking for the items based on any given criteria (changeset, branch…)

If the merge includes more than one item, either the previous methods need to be used or an individual merge is done for each item. So, in order to merge two items from specific revisions, two merges would be needed. Unless a merge is going to include one item or a small number of items, or the items to be merged have no relation between them whatsoever, this method will not be the most adequate.

3.13.9             Merging from the command line

The destination of the merge operation always is the current content of the workspace, so it is normally desired to do an update operation before merging in order to ensure that workspace contents are what they are supposed to be. The update is performed with the command of the same name, on the root of the workspace for it to be complete:

The mergebranch command takes as its main argument a branch specification, following this syntax:

Object specifications are described in more detail on a later chapter. To get a list of the items that will need to be merged from the ‘/main/child1’ branch to the current workspace content, a command like this could be used:

The mergebranch command with just the branch spec simply prints the items to be merged, but it doesn’t perform the actual merge. In order to do the merge, the ‘--merge’ modifier needs to be added:

Merge operation leaves all merged items checked out, so they can be reviewed and the integration verified. The user will later check them in, with the following command, which checks in every checkout on the workspace:

3.13.10         Cherry Picking or selective merge

Cherry picking is a merge on which a change on an item’s content and only that change is applied to the workspace. In this case there is no merge of the source item’s content but of the changes included on a revision which did not belong to the previous one.

It’s different from the regular merge because this will bring all changes since the versions diverged, while cherry picking will bring only the changes of the selected revision, changeset or branch, without taking into account any previous versions.

On the following example the difference can be easily understood:

• You have a file on which a method has been added as part of a new functionality that is being developed. Then on that same file one of the existing methods is modified to correct an error.
• If a merge from this file is done the result will include that correction but it will also include the new functionality developed. 
• If instead of a regular merge you do a cherry pick merge, only that correction will be included, but not the new functionality.

These are the supported sources for cherry picking:

• A revision. In order to merge a change from a revision in a single item, you would do a cherry pick from that revision.
• A changeset. On the previous case the change only affected one item but on most occasions more than one item must be modified. For example, if a function’s parameters are modified you would need to modify both the file on which they are defined as the files containing a call to that function. If every modified item of this change is checked in at the same time we can use that changeset to refer to the change. So, in order to incorporate that change you would only have to do a cherry picking of that changeset.

You have to be aware that cherry picking is just a type or merge. In order to do a cherry picking from the command line the command merge will be used, including the modifier –-cherrypicking.

Example of the command to do a cherry picking from changeset 50:

Figure 45 shows a regular merge process, on which every change made on revisions from branch001 is merged into revision 2 on /main, on the Cherry pick, as shown on Figure 46, only the required revision is merged, in this case revision 4 on branch 001 is merged into main, but the user can choose any revisions he needs.

3.13.11         Cherry Picking from branch

 

The cherry picking from branch is a bit special, since it changes the idea of “bring contents of the last changeset or last revision” to “bring contents introduced in the last branch”.

Let’s suppose the following:

Figure 47: Cherry pick from branch

In this case we have a main branch, a Fix branch which starts from a certain point of that main branch, and finally a task branch (task001) which starts from that Fix branch.

If we perform a merge from task001 to the main branch, we integrate all changes done in the task001 branch and those changes introduced in the Fix branch, indeed.

But if we use a cherry picking from task001 to the main branch, only the changes introduced in that task001 will be integrated in the main branch. The changes done in the Fix branch will be rejected. The concept is quite similar, but adapted to the special circumstances of branches.

To execute this operation in Plastic, type a command like this:

Where <branch_from> means the source branch of the cherry picking.

When using the GUI, right-click on the source branch of the cherry picking and select the option ‘Cherry pick from this branch’.

3.13.12         Merging an interval of changes

Cherry picking allows including a change on the workspace. But as explained on cherry picking, a modification may not have been done by a single change but by an interval of changes. In this case you will not need to merge the last change included but all of them.

Merging an interval allows integrating every change from two given revisions. You would be merging from one revision but taking only the changes included from the previous revision.

As in cherry picking, including changes done between two revisions on the workspace is another special type of merge.

If you have branch br:/main/fix and you want to include the changes done on file “test” from revision 5 to 15, the merge command used would be the following one:

If we are using the “branch per task” pattern, this type of merge is not useful.

3.14Subtractive merge (desintegration)

A subtractive merge is able to undo a previously introduced change, creating a new revision which doesn’t have the change.

To better illustrate the operation a step by step sample will be explained. The first step will be creating a file under source control with the content shown on Figure 48.

Figure 48: Subtractive merge, initial code

Then two developers will start making modifications in parallel. The first developer will start working on a branch named /main/task001 and will modify the file on the branch as shown on Figure 49.

Figure 49: Subtractive merge, first modification

Later on, a second developer modifies the same file on the main branch, starting from the contents at Figure 48. He modifies the file as follows:

Figure 50: Subtractive merge, second modification

After the two changes have been done, the first developer decides to merge his modifications into the /main branch. Figure 51 shows the version tree of the item after this merge.

The results of comparing revision 2 of the file against the revision 0 of the file on /main will be are shown on Figure 52.

Subtractive merge will get rid of one of the modifications performed on the branch. For example, in order to remove the last change made on the file (revision 1 on /main), we can perform a subtractive merge of that revision. This will remove only the changes introduced by that revision, and create a new checked out version of the item without the subtracted changes.

Figure 51. Version tree after merging the first change

 

Figure 52: Subtractive merge sample, file after the two changes

 

There are several types of subtractive merge supported ranging from subtracting a given revision, a certain interval of revisions or a specific changeset.

For the sake of simplicity the sample will substract the change introduced in revision 1 on /main.

Figure 53 shows how the revision 1 is selected on the file’s history and the subtract operation is invoked.

Figure 53: Substractive revision merge from the GUI

In order to do the same from the command line the user will use the cm substractivmerge (or cm sm) command:

Both the command and the GUI will invoke the subtractive merge process, which will identify the modifications introduced on revision 1, and create a new revision without these changes.

After the subtractive merge is invoked, the new revision looks like the file on the right in Figure 54. The change introduced on revision 1 of the file has been removed, as the diff shows:

Figure 54: Subtractive merge showing the result of the file

Figure 55 explains how the subtractive merge works in a simple example. The revision created after the subtractive merge is run (revision 4) contains all the previous changes except the subtracted one.

Figure 55: How subtractive merge works

Plastic will create a link between the revisions participating on a subtractive merge in order to keep track of all the operation executed on the revisions as Figure 56 shows:

Figure 56: Version tree after a subtractive merge showing the subtractive link

3.14.1             Subtracting a revision interval

It is also possible to select both from the GUI and the CLI a revision interval instead of a single revision to run a subtractive merge. If an interval is selected, the changes to remove will be the changes made between revisions included in the interval, as the Figure 57 shows.

Figure 57: Subtractive merge of an interval

The subtractive merge from an interval can be run from the history view of an item on the GUI as the Figure 58 shows.

Figure 58: Subtractive merge from GUI

Finally in order to run the subtractive merge from the command line consider the following sample:

3.14.2             Subtracting a changeset

One of the easiest ways of subtracting a given change (for instance, the result of a merge) is removing a complete changeset. This way, instead of having to specify revisions one by one, all the revisions modified in the changeset will be selected by Plastic.

Changeset subtractive merge can be invoked from the changeset view on the GUI or from the command line using a changeset spec.

3.15Creating a label

3.15.1.1                 From the command line

Before using a label, it must be created. The following sample creates a label called ‘rel1.0’:

3.15.1.2                 From the GUI

Go to the labels view and click on the button Create new label to display the dialog showed at Figure 59

Figure 59: Creating a new label

3.16Applying a label

3.16.1.1                 From the command line

Applying a label means specifying the label to apply and the revision on which to apply it. This sample shows how to apply the label ‘rel1.0’ to the revision currently loaded in the workspace of the item hello.cpp:

‘lb:rel1.0’ is label specification. For more details on object specifications, check below the specific section on the subject. It is rather usual to apply a label to many items, so the ‘label’ command supports the use of wildcards and the –R modifier to recursively process items. The following command labels all items under current directory (including the directory itself) with label ‘rel1.0’.

It is also possible to apply a label to a specific revision, different from that on the workspace, passing the revision spec as an additional argument. This command will apply label ‘rel1.0’ to revision 4 of the element hello.cpp on branch ‘/main/child1’

3.16.1.2                 From the GUI

Figure 60: Apply label to workspace content

3.17Working with attributes

An attribute is a property that can be applied to the repository objects. When you create an attribute, you are creating a property that is identified by its name. Then, this attribute can be applied to a repository object with a value. For example, you can create an attribute called "Branch Status" and apply it to your repository branches with several values: In progress when you are working on it, Closed when you have finished your work on that branch, Integrated when you have integrated that branch on main branch…

Later, the query system allows you to search branches with a specified attribute value (For example: You want to see all branches with status Closed, which means Integration pending).

The first step is creating the attribute (Branch Status). The second step is applying the attribute to the repository objects and using the query system to filter objects with attributes. The following sections explain how to do all the actions.

3.17.1             Creating an attribute

3.17.1.1                 From the command line

You can create an attribute from the command line with the following command using the mkatt command. The first parameter is the attribute name.

3.17.1.2                 From the GUI

Go to the attributes view and click on the button Create new attribute to display the dialog showed at Figure 61: Create new attribute

Figure 61: Create new attribute

3.17.2             Applying an attribute

3.17.2.1                 From the command line

To apply an attribute from the command line you have to use the setattribute command. The first parameter is the attribute that you want to apply. The second parameter is the object which the attribute will be applied (it is an object specification). The third parameter is the attribute value. Note: In order to understand first and second parameters, see Chapter 6: Object Specifications.

3.17.2.2                 From the GUI

The attributes on the GUI are managed through the objects view (branches, labels, etc). First, left click on the object that you want to apply an attribute, in order to select it. Once the object is selected in the view, display its properties by clicking on the “Show extended information” button on the taskbar’s view. A right pane will be opened in the view. Select the option attributes, and click the button “Add attributes”:

Note: Plastic SCM supports applying an attribute value for a multiple object selection.

Figure 62: How to apply an attribute

You will see the following window. Then select the attribute, write an attribute value and click Ok.

Figure 63: Add attribute dialog

3.17.3             Editing an attribute value

3.17.3.1                 From the command line

In order to modify an attribute value from the command line, you can use again the setattribute command:

3.17.3.2                 From the GUI

You can later change the attribute value for an object. For example, if you want to mark a branch as “closed”, you have to modify the attribute value on the “Extended info” right task pane, and click the button with the green tick. This button is disabled by default. When you change the text on the attribute value field, the button will be enabled.

Note: Plastic SCM supports changing the attribute value for a multiple object selection.

Figure 64: Edit the attribute value

 

3.17.4             Deleting an attribute application

3.17.4.1                 From the command line

In order to delete an attribute from the command line, you can the removeattributerealization command:

3.17.4.2                 From the GUI

You can delete the attribute application for an object. You have to click the red button on the “Extended info” right task pane.

Note: Plastic SCM supports deleting an attribute value for a multiple object selection.

Figure 65: Delete the attribute application

3.17.5             Querying objects with attributes

Here there is a sample of query object using the attributes.

3.17.5.1                 From the command line

3.17.5.2                 From the GUI

Open the advanced query view, and type the previous query:

Figure 66: Query objects with attributes

 

 

4       Starting up a project

Plastic SCM has been designed to allow you start using it fast and easiy. This topic will show the steps to start adding a project to the version control both from the GUI and the command line.

Only the needed steps to complete the operations will be shown. Most operations have already been described in detail on previous topics.

The user must have already properly installed and configured the authentication method to be used.

4.1    Creating a repository

A repository called “default” is created during the first server start up. By using this repository, users can start working easily; they would only need to have a workspace created.

A new repository is created and used for the example:

4.1.1.1    From the GUI

1. Menu Actions / Create new repository
2. Introduce a descriptive name and the repository server.

Figure 67: New Repository

4.1.1.2    From the command line

4.2    Creating workspaces

When a developer opens the GUI tool for the first time, and if it does not detect a workspace, a dialog as shown on Figure 68 will appear.

By default workspaces point to the default repository, and to main branch. This could be changed depending on the branching pattern to be used.

4.2.1.1    From the GUI

1. Menu Workspace / Create workspace
2. Introduce a descriptive name and the server’s

Figure 68: Creating a workspace

4.2.1.2    From the command line

4.3    Performing a first code import

Copy the project’s files and directories to the newly created workspace (c:\projects\view1\). The project can be added from the GUI, the command line or the available IDE integrations.

4.3.1.1    From the GUI

1. From the workspace root, right click, menu option “Add recursively”.
2. Check outs menu.
3. Select every item with Ctrl-A.
4. Right click and press on the button “Checkin”.

4.3.1.2    From the command line

4.4    Starting to work

Once the code has been added to the repository, the rest of the developers can obtain a local copy on their workspace.

 

4.4.1 Update

4.4.1.1    From the GUI

1. Button “Update” on the tool bar.

Figure 69: Update operation

4.4.1.2    From the command line

4.5    Checking out items to work with them

In order to change any item under the version control, it has to be checked out.

4.5.1.1    From the GUI

1. Select the item to be checked out.
2. Right click, menu, option “Check out”.

4.5.1.2    From the command line

To check out any item:

To recursively check out a file and its content

Check out every read item from the standard input:

4.6    Finding checked out files

4.6.1.1    From the GUI

Figure 70: Checked out revision list

4.6.1.2    From the command line

4.6.1.3    From Visual Studio Plug In

Visual Studio shows the items to be checked in by right clicking on a checked out item and selecting “Show pending check ins”.

5       Workspace selectors in depth

Selectors are the workspaces’ center piece. By configuring the selector users can exactly work on the specific revisions they need.

This topic will describe how to create and configure selectors. Understanding how selectors work allows users to take full advantage of the Plastic SCM system.

5.1    Selector´s appearance

A selector is a specification of which elements’ revisions will be downloaded to its associated disk location and in which branch checkouts (new revisions), will be placed.

A very common selector will look like the one on Figure 71. First a selector must indicate in which repository the revisions to be downloaded are stored. This is done by means of the repository selection rule.

Figure 71: Default selector appearance

The next step is exactly specifying what to download. InFigure 71, the path selection rule specifies that it will download everything under the root directory.

A selector must always specify a way to download the root directory; otherwise Plastic SCM server will raise an exception, notifying you have to write this kind of rule. To download files and directories to the workspace, the system needs to solve the paths from the root downwards, and so it needs to be able to find appropriate rules for each one.

Inside the path selection rule there will be another kind of specification telling which is the branch to retrieve revisions from, and in which branch the check outs will go.

5.2    Selector definition

The next figure shows the full definition of the selector. There are many possibilities available to exactly define the revisions to be downloaded.

A selector consists of one or many repository load rules, each of them defining one or more paths to download, and where to find the elements (branches, labels, changesets or revision numbers).

Figure 72: Selector definitions

5.3    Path rules

Path rules define what to download for a certain path. They are executed in order, meaning that if a path rule is able to download a certain item, the next rules won’t be processed.

The following sample shows how path rules work.

The sample above specifies that: whatever is inside path /01nerva/doc will be taken from branch /main/SCM0841 and checked out on the same branch. Everything else, including the root directory, will be directly downloaded from the main branch.

But, what would happen with the following selector?

The path rules have been changed on the above  selector sample. Now the path rule “/” will be evaluated first, and as all items can be solved with this rule, this time the rule path “01nerva/doc” won’t be executed.

5.4    The norecursive path rule option

The norecursive option means that the rule will be applied to the directory you are specifying, but it won’t be applied to the items below.

Suppose we have the directory structure shown in Figure 73, we just want to work with the items on the path /01nerva/doc, so we are not interested in downloading the rest of the directory structure.

Figure 73: Sample directory structure

To achieve this behavior the following selector will be required:

The selector will just download revisions from items inside the requested path, taking them from label BL034.

5.5    Specifying wildcards on the path selection rule

In some situations only certain file types have to be downloaded to the workspace. Let’s take again the previous sample and suppose we just want to download .doc files:

5.6    Retrieving an item’s specific revision

If you need to download a specific revision of a certain item, the revno option of the branch selection rule has to be used. Revno can be a number or the special names LAST or FIRST.

LAST indicates the last revision on the branch, and FIRST the initial one.

Let’s take again the sample and create a selector that downloads a specific revision of the file manual.doc inside the /01nerva/doc directory:

5.7    Smart branch rules

Selectors can also be used to work with smart branches. Normally to work with a smart branch the generated selector will be like the one on the following sample:

Which means the workspace will work on the smart branch “/main/task001”.

Consider a smart branch scenario like the one described at Figure 74.

Figure 74: Smart branch scenario to study selector

If the developer sets a selector like the previous one, the smart branch task001 will be used from last which means it will take cset204 at /main as base.

If the developer sets a selector like:

Then the label 01 will be taken as branch base, and a totally different configuration will be used to work.

5.8    Using several repository servers

In order to configure your workspace to use several repository servers, they can be registered. To do this, you need to create a file named plastic.servers in your plastic folder of your user local folder (that is, /home/<user>/.plastic directory in Linux or C:\Documents and Settings\<user>\Local Settings\Application Data\plastic in Windows XP or C:\Users\<user>\AppData\Local\plastic in Vista/Win7). The following is an example of the contents that this file may contain:

The file contains a server:port entry per line. This way, you will be able to use those repositories in your workspace. Now, when you create a workspace, you can select repositories on those servers from the list.

You can also specify a repository using its server in the workspace selector. Take a look at this example:

In the example we state that we’ll use three repositories: our local repository ‘mylocalrep’ and furthermore two remote repositories: ‘remote_rep1’, located in a registered repository server and ‘default’, located in the ‘remote_machine2’ host.

To specify ‘remote_rep1’ we have used simply the alias of the remote repository, but to specify the ‘default’ remote repository placed in ‘remote_machine2’ we have used its complete specification. Why?

If we have two repositories with the same name, Plastic will decide to use the repository server indicated by the client.conf file. In order to use repositories with the same name placed in different repository servers, we need to write their full repository specification.

6       Object specifications

In Plastic SCM every object can be referenced with an object specification. Having to use object specs is not very common using the GUI tool, but it is interesting to have a background on how the system is able to reference objects.

6.1    Revision specifications

To reference a specific revision of an item, one of the following formats can be used:

For instance, it is possible to reference revision 23 of file /src/main.java on branch main using the following syntax:

Another possibility would be accessing a labeled revision using:

6.2    Branch specifications

Branch specs are used during the merge process, or setting selectors. A branch spec has the following syntax:

Example:

6.3    Item specifications

An item spec has the following syntax:

Example:

6.4    Label specifications

A label spec has the following syntax:

Example:

6.5    Repository specifications

A repository specification has the following syntax:

Example:

6.6    Workspace specifications

To reference a given workspace, the needed syntax is the following:

Example:

6.7    Repository server specifications

The repository server specification has the following syntax:

Example:

 

7       Managing projects with Plastic SCM

Having a SCM system is not enough to properly manage a project. Knowledge about how to structure work is also required.

This topic will introduce different ways of working, strictly related to branching patterns

7.1    Working on the main branch

This is a very common way of working with many version control systems such as Subversion, CVS or SourceSafe. It is very simple to set up, but has many drawbacks.

Figure 75 illustrates the process. Each developer works in his workspace. He can check out as many files and directories as he needs to, but then when he checks in, changes go directly to the br:/main branch. Developers, therefore, must be very careful with their check outs.

Figure 75: All changes on the main branch

 

If a developer checks his changes in (either files or directories) and another developer updates his workspace, he will receive the recently submitted changes. If there was something wrong, the error will propagate to the second developer.

The main problem with this pattern is that there are no intermediate locations on which the changes are stored before going into the main line. This means that check ins are less frequent, and the code is often under the source control. The developers are not using their SCM as a tool to ease their daily work but just to submit work. We discourage using this way of working.

7.1.1.1    How to work on the main branch with Plastic SCM

In order to use this patter, developers should use the following selector:

7.2    Branch per developer

Using this pattern developers enjoy a higher isolation. They can do as many check ins as they feel to, without compromising the br:/main integrity.

Figure 76 shows the pattern.

Figure 76: Branch per developer pattern

Work can be divided into tasks, controlled by a bug tracking or issue tracking system. Then each developer will work on his assigned tasks, implementing all of them in his own branch.

After some tasks have been completed, depending on the available number of developers, a new release will be created, integrating all the branches on the main line. Integration can be done by each developer or by an integrator.

Once the integration is finished (done by merge operations from each branch), a new baseline will be created, labeling the new included changes.

After the new release has been created (a new baseline), developers will rebase from the br:/main branch.

 

7.2.1.1    How to follow the branch per task pattern with Plastic SCM

To implement this way of working, each developer will have a selector like the following:

Where developerbranch will be replaced by the developer´s name or identifier following the name convention structure.

In order to integrate changes into main, either the developer or the integrator will use the following selector:

7.3    Branch per task

Branch per task model will create a new branch for each task assigned to a developer.

This pattern offers wider isolation and control but it requires the SCM to support a strong branching method.

Plastic SCM implements this pattern without an impact on the system’s performance or integrity, which is not so easily handled with other SCMs.

Developers will work on a branch, then switch to a new one when the work is finished.

An integrator will create new baselines on a fixed frequency, integrating the branches containing finished and tested tasks.

Branch per task allows maximum developer isolation and the project’s stability can be kept through its main line. It improves the developer’s productivity allowing them to use the SCM for their daily work. Figure 77 shows the pattern.

Figure 77: Branch per task pattern

7.3.1.1    How to follow the branch per developer pattern with Plastic SCM

To implement this way of working, each developer will have a selector like the following:

Where taskXXX will be replaced by the task number.

ere is also another way to simplify the selector:

The integrator will work on the main branch with the following selector:

8       Simple Query System

Plastic SCM provides a query and report system creating the starting point to implement a wide variety of development statistics. It is a simple query mechanism which allows recovering information from the repository objects, being able to set different filters and their combinations.

Plastic SCM would answer, through its Query System the following kind of queries:

• Which items included on label xx are not included on label yy? (or, what is the difference between these two labels?)
• Which revisions have been created by user ‘xx’ on branch ‘rr’ during the last week?
• Which are the revisions included on changeset xx?

Furthermore, it is possible to export any query on XML format, which provide diverse integration possibilities with third party’s tools.

8.1    Query Language

Plastic SCM provides its own query language in order to specify the type of objects to be offered as result as well as these object’s filtered parameters. Every query is done through ‘find’ command.

The available object types are the following ones:

 

Queries can only be done on one object type at a time, although it is possible to search on different repositories at the same time.

The query conditions would be specified by where command.

It is possible to group different conditions through and and or, and the values must be given between brackets when used to specify filters. For example: obtaining every revision included on branch ‘/main/child1’:

Each entity has different attributes to be used in order to specify the filter conditions as well as the output format. The following attributes are shared by every entity system, except user, wkrepository and workspace types:

For every object the owner ‘ME’ can be specified and the query will search the objects created by the user logged into the system.

The following sections describe the specified attributes for each object type mentioned above.

Attribute

Attributetype

Branch

Changeset

Link

Linktype

Marker

Merge

 

Moved

Removed

 

Revision

User

Wkrepository:

Workspace:

8.2    Usage examples

Revisions from a given label:

Revisions created by a given user on a certain period of time and on the main branch:

History of an item on a given branch:

Revisions which have changed from label ‘excel2’ to label ‘excel3’:

Binary revisions larger than 1MB on a given changeset:

Checked out revisions on different branches:

Markers applied to a certain revision:

 ‘/main’ child branches belonging to a certain owner:

Deactivated users on different repositories:

Branches integrated by the user:

Workspaces created by the user at his machine (my computer)

Branches containing the “open” attribute:

Merges done from branch ‘/main/task001’ to branch ‘/main’

Revisions created on ‘/main’ as a result of integrating a branch on changeset 5

Moved items ‘doc’ on branch ‘/main’

Removed items to create revision ‘.#br:/main#4’

8.3    Query language grammar

Figure 78: Query language grammar

 

9       Advanced Query System (AQS)

Apart from a query system, Plastic also provides an advanced query system available through the command line interface, through the cm query command, which allows objects recovery from one or several magnitudes at the same time following several search criteria. It allows the user to do any kind of query.

The differences between both available systems is that the simple one passes the queries on the system entities and only on one at a time, but the advanced system does it on the server data bases and it can be done on one or several entities at the same time; so with this system we can get more information, but in case of a query which can be solved with any of the systems, we recommend the simple system as the query is more simple.

In the examples you can find a query on both systems. Even though some entities are the same for both systems, some of them are different and there is a higher amount on the AQS.

Through the query system Plastic SCM is able to answer to questions such as:

• In which branches are located an item’s revisions?
• Which revisions have been merged into main on a certain date?

9.1    Query Language

Command cm query uses SQL syntax to execute queries on the server database. It uses every SQL option; even the most advanced Plastic functionalities are using AQS.

 

AQS is totally integrated with Plastic and does not impose any additional restriction on the system’s operation. It works of any of the operative systems supported by PlasticSCM.

In order to execute this kind of query the user should have advanced query system permit on the repository.

The queries can be done on one entity or several at the same time.

The following list shows the entities on which queries can be done:

Every entity has a different set of attributes which allow defining search criteria and limiting the number of objects recovered from each identity. The following attributes are common to every system entity:

The following attributes belong to each of the entities mentioned above.

Items

Revisions

Checkouts

Branches

Labels

LabeledRevisions

Links

Linkedobjects

Attributes

Objectswithatributes

Changesets

In order to manage path solutions and users’ queries, two predefined solution functions will be introduced. These are the following ones:

In order to show the queries result in a transparent way to the user, the query interpreter can be given the following options:

Several column names can be specified, divided by comas.

In order to explain the usage of predefined functions and query options and understand why both must be used when launching a query, you can see the following examples:

Current repository revisions:

Current item repository revisions whose item, used by Plastic, corresponds to the specified path c:\workspace. The function solves the specified disc path to the item identifier used by Plastic.

The same result is obtained but now the itemid column does no longer contain the item id but the disc path corresponding to that identifier, in this case c:\workspace.

Current item repository revisions whose user item, used by Plastic, corresponds to the users specified to the function.

The same result is obtained but now the owner column does no longer contain the user id used by Plastic but the user name.

9.2    Usage examples

Repository check outs.

Current repository branches that were created by the specified user.

Branches on which there are revisions of item c:\workspace\file.txt.

Revisions merged into main branch on a given date.