Plastic Intro

7/28/2019 Plastic Intro

1/108

Introduction

to Plastic SCM

Version 3.0 December 15, 2010
http://www.plasticscm.com/


2/108

ii

Table of Contents

Chapter 1 The World According to Plastic SCM ..................................................................................... 1

1.1 Plastic SCM Installations ............................................................................................................ 2

1.2 Users and Security ..................................................................................................................... 2

1.3 Repositories ............................................................................................................................... 3

1.4 Workspaces ............................................................................................................................... 4

1.5 Items .......................................................................................................................................... 5

1.6 Revisions and Changesets ......................................................................................................... 6

1.7 Branches and Labels .................................................................................................................. 7

1.8 Zooming In ............................................................................................................................. 8

Chapter 2 Basic Development with Plastic SCM .................................................................................... 9

2.1 Workspaces ............................................................................................................................... 9

2.1.1 Workspace Configuration and the Selector ............................................................... 11

2.2 Creating New Revisions ........................................................................................................... 13

2.2.1 Using the Checkout-Modify-Checkin Methodology ................................................... 13

Multiple Checkouts of the Same Revision .................................................................. 16

2.2.2 Using the Modify-Commit Methodology ................................................................... 16

Changing the Same Revision in Different Workspaces .............................................. 17

2.2.3 Private Files ................................................................................................................ 17

2.2.4 Pending Changes View ............................................................................................... 18

Checkouts All Users View ........................................................................................... 19

2.2.5 Revisions of Directories .............................................................................................. 19

2.2.6 Accessing Other Revisions of Items ............................................................................ 21

The History View ........................................................................................................ 21

The Revision Tree View .............................................................................................. 21

2.3 Plastic SCMs Flexibility in Day-to-Day Development .............................................................. 22

2.4 Incorporating Others Changes into Your Workspace: Update ............................................... 23

2.4.1 Tuning the Update Command by Cloaking Objects ................................................... 23

2.5 Detailed Monitoring of Changes: The Diff Tool ....................................................................... 24

2.5.1 Comparing Revisions of Text Files .............................................................................. 24

Advanced Detection of Moved/Modified Code ......................................................... 25

2.5.2 Comparing Revisions of Binary Files ........................................................................... 26


3/108

iii

2.5.3 Comparing Revisions of Directories ........................................................................... 26

2.6 Additional Tools for Detailed Monitoring of Changes ............................................................. 27

2.6.1 Annotation of Revisions ............................................................................................. 27

2.7 High-Level Monitoring of Changes: Changesets ...................................................................... 28

2.7.1 Viewing Changesets the Changesets and BranchExplorer Views ............................ 29

2.7.2 Comparing Changesets ............................................................................................... 30

2.7.3 Comparing All of a Branchs Changesets .................................................................... 32

2.7.4 Code Reviews for a Changeset ................................................................................... 33

2.8 Getting Started: Placing Objects under Source Control .......................................................... 35

2.8.1 Filtering Out Unwanted Objects with an Ignore File .................................................. 38

2.8.2 Adding Files to an Existing Repository ....................................................................... 39

Chapter 3 Parallel Development with Plastic SCM .............................................................................. 40

3.1 Establishing Development Baselines with Labels .................................................................... 40

3.2 Branches and Working on a Branch ..................................................................................... 41

3.2.1 Branches in an Item .................................................................................................... 41

3.2.2 Branches in a Repository ............................................................................................ 43

3.2.3 Working on the XXX Branch Theory ..................................................................... 44

SmartBranches ........................................................................................................... 45

3.2.4 Working on the XXX Branch Practice ................................................................... 45

Updating the Workspace ............................................................................................ 47

Shelving Checked-out revisions when Switching Branches ....................................... 47

3.2.5 Day-to-Day Parallel Development .............................................................................. 48

Surveying the Landscape and Getting Started ........................................................... 48

Creating New Revisions .............................................................................................. 49

Checking Your Status .................................................................................................. 49

3.2.6 Integrating the Changes from a Task Branch Merging ............................................ 50

3.2.7 The 3-Way Merge Algorithm ...................................................................................... 53

Merging of Directory Revisions .................................................................................. 54

Merging of Binary Files ............................................................................................... 54

Keeping Track of Merges with Merge Links ............................................................... 55

3.2.8 Merging Revisions with the Merge Tool .................................................................... 55

Merge Links in the BranchExplorer ............................................................................ 58

3.2.9 Merging from the Same Branch Again ....................................................................... 58

3.2.10 Rebasing a Smartbranch ............................................................................................. 60


4/108

iv

Rebasing at the Item Level ......................................................................................... 61

Rebasing in Practice ................................................................................................... 62

Chapter 4 Distributed Development with Plastic SCM ........................................................................ 64

4.1 Distributed Development Scenarios ....................................................................................... 654.1.1 Centralized Development ........................................................................................... 65

4.1.2 Multi-Site Development ............................................................................................. 65

4.1.3 Peer-to-Peer Distributed Development ..................................................................... 67

4.1.4 Hybrid Some or All of the Above ............................................................................. 67

4.2 Replication and Authentication ............................................................................................... 68

4.3 How Items Evolve in a Distributed Environment .................................................................... 68

4.3.1 Replicating Revisions: Restricted Branch Development ............................................ 68

4.3.2 Replicating Revisions: Unrestricted Branch Development ......................................... 70

Will the Real Revision #2 Please Stand Up .............................................................. 70

4.4 Replication in Practice ............................................................................................................. 71

4.4.1 Online vs. Offline Replication ..................................................................................... 73

Chapter 5 Security and Access Control ................................................................................................ 74

5.1 User Authentication ................................................................................................................ 75

5.2 The Security Hierarchy for Plastic SCM Objects ...................................................................... 75

5.3 An Objects Access Control List ............................................................................................... 76

5.4 Inheritance of Permissions through the Object Hierarchy...................................................... 77

5.4.1 Inheritance of Permissions through the Directory Hierarchy .................................... 78

5.5 The Inheritance Calculus ...................................................................................................... 79

5.6 Security Scenarios ................................................................................................................... 80

Chapter 6 Interfaces, Integrations, Extensibility .................................................................................. 82

6.1 The Graphical User Interface ................................................................................................... 82

6.1.1 The Top Level.............................................................................................................. 82

6.1.2 The Work Context ...................................................................................................... 83

6.1.3 A View Overview ........................................................................................................ 85

Customizing a View .................................................................................................... 86

6.2 The Command Line Interface .................................................................................................. 87

6.2.1 Command-Line Options and Help .............................................................................. 87

6.2.2 Specifying Repository Objects in Commands ............................................................. 88


5/108

v

6.2.3 Formatting Command Output .................................................................................... 88

6.3 Integrations with Issue Tracking Systems ............................................................................... 89

6.3.1 Configuring an Integration ......................................................................................... 89

6.3.2 Using an Integration ................................................................................................... 90

6.4 Integrations with Development Environments ....................................................................... 92

6.4.1 Developer IDE Integrations ........................................................................................ 92

Status of Source-Controlled Items ............................................................................. 94

And More ................................................................................................................ 94

6.4.2 Microsoft Office Integration ....................................................................................... 95

6.5 Extending Plastic SCM ............................................................................................................. 95

6.5.1 Placing Attributes on Repository Objects................................................................... 96

6.5.2 Automating Development Policies with Triggers ....................................................... 96

Communicating with a Trigger Program .................................................................... 97

6.5.3 Advanced Reporting with Queries ............................................................................. 97

SCM-Level Queries ..................................................................................................... 97

SQL-Level Queries....................................................................................................... 98


6/108

vi

List of Figures

Figure 1: Plastic SCM repositories ................................................................................................................. 3

Figure 2: Data flow in a workspace ............................................................................................................... 4

Figure 3: Items and private objects in a workspace ..................................................................................... 5

Figure 4: Revisions of an item ....................................................................................................................... 6

Figure 5: Branches in an item's revision tree ................................................................................................ 7

Figure 6: Labeling the source base to define a baseline ............................................................................... 8

Figure 7: Accessing workspaces .................................................................................................................. 10

Figure 8: Items view .................................................................................................................................... 11

Figure 9: Workspace configuration selecting item revisions ................................................................... 12

Figure 10: Checkout of items ...................................................................................................................... 14

Figure 11: Checked-out revision in the repository ..................................................................................... 14

Figure 12: Display of checked-out items in the Items view ........................................................................ 15

Figure 13: Checkin of new revisions ........................................................................................................... 15

Figure 14: Items view display of new revision ............................................................................................ 16

Figure 15: Two checkouts of the same revision .......................................................................................... 16

Figure 16: Changed items in the Items view ............................................................................................... 17

Figure 17: Items view display of private objects ......................................................................................... 18

Figure 18: Pending Changes view ............................................................................................................... 18

Figure 19: Checkouts All Users view ........................................................................................................... 19

Figure 20: Automatic checkout of a directory ............................................................................................ 20

Figure 21: History view ............................................................................................................................... 21

Figure 22: Revision Tree view ..................................................................................................................... 22

Figure 23: Diff Tool comparing revisions of a text file ............................................................................. 24Figure 24: Xdiff (cross-difference) capability .............................................................................................. 25

Figure 25: Diff tool comparing revisions of an image file ........................................................................ 26

Figure 26: Diff tool comparing revisions of a directory ........................................................................... 27

Figure 27: Annotate view of a revision ....................................................................................................... 28


7/108

vii

Figure 28: Changesets view ........................................................................................................................ 29

Figure 29: Changesets in the BranchExplorer ............................................................................................. 30

Figure 30: Viewing a changeset's individual items ..................................................................................... 30

Figure 31: What did a changeset change? .................................................................................................. 31

Figure 32: Comparing changesets ............................................................................................................... 32

Figure 33: Explore changesets in branch command ................................................................................... 33

Figure 34: Code review for a changeset ..................................................................................................... 34

Figure 35: Code reviews view ..................................................................................................................... 35

Figure 36: Creating a new repository .......................................................................................................... 36

Figure 37: Creating a new workspace ......................................................................................................... 37

Figure 38: Placing objects under source control ......................................................................................... 38

Figure 39: Defining a baseline with a label ................................................................................................. 41

Figure 40: Multiple branches in a revision tree .......................................................................................... 42

Figure 41: Items whose revision trees have different shapes .................................................................... 43

Figure 42: BranchExplorer with several branches ...................................................................................... 43

Figure 43: BranchExplorer showing "work on a branch" ............................................................................ 45

Figure 44: Creating a smartbranch ............................................................................................................. 46

Figure 45: Switching a workspace to a smartbranch .................................................................................. 46

Figure 46: Switching branches the shelve dialog ..................................................................................... 48

Figure 47: Using the Items view for parallel development ......................................................................... 49

Figure 48: Finding all the changes on a task branch ................................................................................... 50

Figure 49: Merging the changes from task branches ................................................................................. 51

Figure 50: Starting a branch-to-branch merge ........................................................................................... 52

Figure 51: 3-way merge: determining the common ancestor revision ...................................................... 53

Figure 52: Recording a merge with a merge link ........................................................................................ 55

Figure 53: Merging a text-file item in the Merge tool ................................................................................ 56

Figure 54: Resolving a conflict in the Merge tool ....................................................................................... 57

Figure 55: Xmerge (cross-merge) capability ............................................................................................... 57

Figure 56: Merge link in the BranchExplorer .............................................................................................. 58

Figure 57: Continued development on a branch ........................................................................................ 59


8/108

viii

Figure 58: Second merge from a branch, using a different base revision .................................................. 59

Figure 59: A smartbranch and its baseline.................................................................................................. 60

Figure 60: Merging to "realize" a rebase operation ................................................................................... 61

Figure 61: Moving a branch base link ......................................................................................................... 62

Figure 62: Merging out from a new baseline to the task branch ............................................................... 63

Figure 63: Centralized development ........................................................................................................... 65

Figure 64: Multi-site development ............................................................................................................. 66

Figure 65: Peer-to-peer distributed development...................................................................................... 67

Figure 66: Multi-site development on a branch (restricted) ...................................................................... 69

Figure 67: Multi-site development on a branch (unrestricted) .................................................................. 71

Figure 68: Replication menu in the BranchExplorer ................................................................................... 72

Figure 69: Specifying a replication operation ............................................................................................. 72

Figure 70: Merging a fetch branch .............................................................................................................. 73

Figure 71: Security Hierarchy for Plastic SCM Objects................................................................................ 75

Figure 72: The Permission window ............................................................................................................. 76

Figure 73: Inheritance of a permission ....................................................................................................... 78

Figure 74: Advanced settings on a directory item ...................................................................................... 79

Figure 75: Direct and inherited permission settings ................................................................................... 80

Figure 76: Top-level information in the GUI window ................................................................................. 83

Figure 77: A workspaces work context ...................................................................................................... 84

Figure 78: Change stats view ...................................................................................................................... 86

Figure 79: Customizing the query that creates a view ............................................................................... 87

Figure 80: Configuring an ITS integration ................................................................................................... 90

Figure 81: BranchExplorer display of issue record title .............................................................................. 91

Figure 82: Extended Information panel display .......................................................................................... 91

Figure 83: Opening an issue record from the BranchExplorer ................................................................... 92

Figure 84: Plastic SCM perspective in Eclipse IDE ....................................................................................... 93

Figure 85: Eclipse Team menu with Plastic SCM commands ...................................................................... 93

Figure 86: Plastic SCM entry on Eclipse main menu ................................................................................... 94

Figure 87: Indicating items' status .............................................................................................................. 94


9/108

ix

Figure 88: Plastic SCM command panel in Microsoft Office program ........................................................ 95


10/108

1

Chapter 1

The World According to Plastic SCM

By definition, all software configuration management (SCM) systems manage your source code. But

each system has its own way of organizing the development environment, along with its own

terminology. This chapter introduces Plastic SCMs architectural concepts and describes the data

structures it manages. There wont be any surprises: our terminology is quite consistent with that of

most other SCM systems. To prove it, heres a one-paragraph view from 10,000 feet of the Plastic SCM

landscape:

Each installation of Plastic SCM on a computer can provide both server and client software. The

Plastic SCM server manages any number ofrepositories, each of which stores the entire history of

a particular directory tree. Each item in the tree can have any number ofrevisions. To support

parallel development, revisions can be organized onto named branches. Working in a Plastic SCM

workspace, a useroften makes changes to several files at the same time, and enters a single

checkin command to create new revisions of them all. Plastic SCM records this group of revisions as

a changeset. Periodically, you mark the current state of development (designate a baseline or

release) by attaching a labelto the current revision of every item.

If that all seems familiar, great! Plastic SCM is designed to be straightforward. Also fast, easy, and

extremely good-looking everything you want in ... an SCM system.

The following sections in this chapter provide a bit more detail on the data structures mentioned above

(along with a few others we didnt squeeze into that paragraph). The remaining chapters of the manual

go even deeper, so that youll come out with a thorough understanding (and appreciation, we hope!) of

Plastic SCM.


11/108

2

1.1 Plastic SCM Installations

When you run a Plastic SCM installer on your computer (Windows, Linux, or MacOS see

http://www.plasticscm.com/download/login.aspx), you can have it install both client and server

software. Boring, youre thinking, yet another client-server system. But wait you dont have to use

Plastic SCM in a stodgy, old, 1990s manner. Here are some usage patterns:

Hermit developer youre a one-person shop with a need for revision control, because you tend to

code too fast. So you run the Plastic SCM server on your computer, managing one or more

repositories that are also located on your computer.

Member of the community youre part of an open-source team: you work alone, but periodically

exchange code with other team members, also running Plastic SCM. So you work like a hermit

developer (see above), but also push and pull changes from other installations. (Think

Git/Mercurial.)

Cog in the machine youre part of a development team, so you use the client software only,

accessing Plastic SCM installations in the same building, across the country, and/or around the

world.

Cog in the multiple-site machine your company has development groups distributed around the

world. Each one uses a local Plastic SCM server. The various servers periodically exchange data with

each other.

On-site firefighteryoure traveling to your companys biggest customer, in order to develop an

emergency fix. As youre packing your bags, you replicate (pull) the code you need from your

companys Plastic SCM installation to the installation on your computer. (You dont need to clone

entire repositories.) And you reconfigure the Plastic SCM client software to use your computers

standalone, unplugged installation. Upon your return to reality, you replicate (push) your

changes back to the company server.

These are examples of an essential aspect of the Plastic SCM system itsflexibility. Thats the meaning

of plastic, after all! Well be pointing the products flexibility repeatedly in this manual. Hope it doesnt

get too boring!

1.2 Users and Security

Plastic SCM has robust security features, all built around the concept that you must be authenticated

under a particular username to access the system. Plastic SCM can maintain its own

username/password database. Alternatively, you can configure it to use a network-based authenticationsystem, such as NIS+, LDAP, and Active Directory.

Plastic SCM has a fine-grained security system, consisting of access control lists (ACLs) for just about all

the entities managed by the system. The system is hierarchical, so its easy to grant or deny access to

large amounts of data (such as the entire installation) to small amounts (such as an individual files, or

even an individual revision of a file). Here are just a few of the operations that the ACL system can grant

or deny to particular usernames:
http://www.plasticscm.com/download/login.aspxhttp://www.plasticscm.com/download/login.aspxhttp://www.plasticscm.com/download/login.aspx


12/108

3

reading the contents of a file

reading the contents of any file in a particular repository

seeing whether a particular repository exists

creating a new revision of a file

attaching labels to any revision of file

creating a new branch

seeing the contents of a branch

1.3 Repositories

Each Plastic SCM installation can handle any number of repositories, of any size (limited only by the

available disk space). Each repository stores a complete directory tree one particular directory along

with all the files and subdirectories it contains. The repository also stores the entire development history

of the directory tree. This includes all the old revisions (back to the beginning of time!), along with a

mass ofmetadata: revision numbers, branch structures, labels that define baselines, and a whole lot

more.

Should repositories be big or small? Its your choice Plastic SCM is flexible! An important point is that

theres no need to maintain a single, giant repository just because your software build process needs to

access all files as a single directory hierarchy. You can (in effect) assemble any number of repositories

together into the desired tree structure.

No matter how many repositories there are at an installation, a single Plastic SCM repository server

process handles them all. (Take that, ClearCase!) You can rename a repository easily, without causing

the walls to come crashing down important in an environment with lots of repositories.

Figure 1: Plastic SCM repositories

At the heart of each repository is a relational database (RDMS). This enables Plastic SCM to leverage

essential features of RDMS technology, such as atomic transactions. And it supports seamless scalability:

your organization might start with a zero-administration RDMS, such as the built-in SQLite or Firebird;

when you need more power, speed, and tunability (or to comply with directives from your IT

department), you can move up to MySQL or to one the big boys, SQL Server or Oracle.


13/108

4

1.4 Workspaces

Users dont access repositories directly; only the Plastic SCM server process does. That makes sense: a

repository contains allthe revisions of a particular file, but at any given moment, you want to work with

just one revision (often, the most recently created one). Like many SCM systems, Plastic SCM handles

this situation by maintaining one or more workspaces for each user. A workspace is just a directorytree on your computer, with a two-way data path to a repository.

Whenever you execute an Update command, Plastic SCM makes sure that one revision of each source-

controlled file from the repository is loaded into the workspace. (These operations work very much like

Subversions checkoutcommand.) When youve edited one or more files and want to preserve your

changes as official revisions, you execute a Checkin command (like a Subversion commit).

Figure 2: Data flow in a workspace

As you might suspect, the above description is an oversimplification. For example, when we said, one

revision of each source-controlled file, you might have thought, well, which revision?. You can specify

your own answer to that question, because workspaces are configurable. Here are some simple

workspace configurations:

the most recent revisions in development of the next product release

the revisions that are labeled RLS_1.2 (the ones that were used to build Release 1.2 of the product)

Another oversimplification: we implied that a workspace is married to a single repository. But in fact,

you can switch a workspace back and forth among any number of repositories. (Many developers find

this practice to cause brain cramps and also a lot of unnecessary data transfers during Updates.)

Even better, it is workspace configurability that enables you to, in effect, assemble several repositories

into a single directory hierarchy.


14/108

5

To achieve fancy configurations, you can edit a workspaces selector, using a special configuration

language (similar to ClearCases config spec language). But youll find that most of the time even

when youre developing on branches a simple dialog box in the Plastic SCM GUI is all you need to

change a workspaces configuration.

For ease-of-use, each workspace has a simple name, such as mary_asterproj, as well as a location in thefile system, such as E:\user_workspaces\mary\current\asterproj. For flexibility and ease-of-

maintenance, you can change a workspaces simple name or its file system location.

1.5 Items

A directory is sort of like a home for files. And like many homes, directories can get messy. If you look

inside a typical development directory, of course youll find source files. But youll probably find a lot of

other stuff, too. Some of the files (and subdirectories) might be necessary, such as artifacts created by

IDEs and other development tools. And other files would more like junk: editor backup files and

temporary files, excerpts from email messages, to-do lists, and so on.

Recognizing this reality, Plastic SCM distinguishes between two kinds of file system objects in a

workspace:

Items files, directories, and symbolic links that are under source control that is, whose changes

are to be monitored by Plastic SCM, and whose revisions are to be preserved in a repository. If you

want Plastic SCM to track an object, you must say so, using the Add-to-source-control command.

Private objects files, directories, and symbolic links that are notunder source control. These

objects are allowed to peacefully coexist with the workspaces source-controlled items. Plastic

SCM can locate and report on these objects, but they never get copied to the repository. This

category also includes various other kinds of objects that might find their way into a workspace:

hard links, device files, named pipes, and so on.

Figure 3: Items and private objects in a workspace


15/108

6

Plastic SCM offers flexibility in this area, too. You can specify filename patterns (such as *.bak) for the

Add-to-source-control command to ignore, so that you dont mistakenly load a whole bunch of junk

from a new workspace into the repository. But if you do, its easy to remove such items.

You might have some very large, rarely modified files under source control (third-party libraries come to

mind). Or maybe there are files that are not required for the work youre currently doing (say, giantbitmaps). You can cloaksuch items, reducing administrative overhead and saving download time. For

example, the Update command wont waste time copying cloaked files from the repository to your

workspace; it wont even waste time determining whether such a copy is needed.

The ignore and cloak features are implemented through configuration files, ignore.confand

cloaked.conf, which can be located either centrally or in particular workspaces.

1.6 Revisions and Changesets

As you work on source files in your workspace, using a text editor or an IDE, you probably execute the

Save command many times a day. It wouldnt make sense for Plastic SCM to create a new revision in the

repository each time you did so the repository would be littered with intermediate revisions that no

one cares about. Instead, a new revision of an item is recorded only when you specify the item in Plastic

SCMs Checkin command.

You can create any number of revisions, which Plastic SCM automatically assigns integer

revision numbers, starting with zero. So many items start out looking like this, conceptually.

(Note to ClearCase users: youre used to version 0 meaning empty or no change from

parent branch. Thats not the case with Plastic SCM; revision 0 can have as much content, or

as many changes, as any other revision.)

Figure 4: Revisions of an item

If youve been using source control systems for a while, you might be thinking, Aha, the command is

called Checkin, so Plastic SCM must use the checkout-modify-checkin paradigm, not the simpler modify-

commitparadigm. Or something like that. But having read this far, you shouldnt be surprised with our

comeback: you can work using eitherof those revision-creation paradigms, because Plastic SCM is

flexible! There is a Checkoutcommand, which tells the server that you intend to create a new revision of

an item (or a group of items) at some point in the future. After youve made changes to the item(s), you

follow through on your intention by executing one or more Checkin commands.


16/108

7

But you dont have to work this way. Instead, you can use the CVS/Subversion/Git/Mercurial method:

just make changes to the items in your workspace, and use Checkin to send the changes to the

repository. The only new thing to teach your fingers is clicking (or typing) checkin instead of commit!

Each time you Checkin a set of new revisions, whether its a single file or an entire source tree, Plastic

SCM records the entire set of revisions as a changeset. (Git and Mercurial call them commits.) Likerevisions, changesets are automatically assigned integer changeset numbers, starting with zero.

This is certainly a convenience its a lot easier to remember a number like 5613, instead of a

timestamp like Nov 11 2010 4:36 PM EST, when youre trying to retrace your recent (mis)steps. But

changesets are much more than a nice history-tracking mechanism. They are first-class citizens in the

world of Plastic SCM, enabling such sophisticated operations as:

undoing the changes in a changeset

merging (or cherry-picking) the changes from each revision in a changeset

basing a new branch on a changeset (because you forgot to label the source base last week)

Oops, were getting a little ahead of ourselves there. In the remaining chapters of this manual, well

explain all those operations.

1.7 Branches and Labels

Well conclude this overview chapter by introducing a few more of the data structures that play

important roles in a Plastic SCM development environment.

Figure 4above shows the evolution of a source-controlled file system object (that is, an item) as a kind

of timeline: revision 0 followed by revision 1 followed by revision 2, and so on. Well, time might be

restricted to a single dimension (as far as we know!), but software development knows no such bounds.Most organizations need to perform several coding tasks on the same source base at the same time:

working on the next release, fixing bugs in the last release, finally getting around to replacing the

database engine the list goes on. This means that a given item must be able to evolve in multiple

dimensions at the same time. Like many SCM systems, Plastic SCM supports this parallel development

or concurrent development practice with branches in the evolution of items.

Heres how the revisions of an item might be organized into three branches.

Maybe new development is taking place on the blue branch, bugfixing on the

red branch, and database reworking on the green branch. Plastic SCM does not

color-code branches (interesting idea, come to think of it ); instead, each branch

has a user-assigned name.

Any branch can have sub-branches, which can have sub-sub-branches, and so on

creating a hierarchy of branches. An items complete set of revisions, organized in

a branch hierarchy is called its revision tree.

Figure 5: Branches in an item's revision tree


17/108

8

Many SCM systems support branch-based development, but the Plastic SCM implementation with the

cool brand name smartbranch is particularly powerful and (of course) flexible. Each smartbranch has

a designated parent branch, from which it can inherit revisions (of items that dont have any revisions

on the smartbranch itself). Smartbranches make it easy to configure a workspace to work on a branch

no getting caught in what ClearCase users call config spec hell. It just takes a few clicks in a dialog

box.

Like branches, labels are a feature of many SCM

systems. A label is a user-defined name that can be

attached to a revision. Thats nice names are easier to

remember than revision numbers. But the big payoff is

when you define a baseline by attaching the same

label, say RLS3.5, to the current revision of every item in

your workspace (just after your boss gives final

confirmation that the latest build really will go out as

WonderWidgets Release 3.5). Thereafter next week,next year, whenever you can use the label RLS3.5 to

have Plastic SCM identify or retrieve the exact set of

revisions that went into the release.

Figure 6: Labeling the source base to define a baseline

How do Plastic SCM labels compare with your average SCM systems labels? Theyre pretty much the

same, really. Unlike some systems, Plastic SCM allows you tochange a labels name for example, when

the Marketing Dept. decides that Release 3.5 should really be called Release 4.0.

1.8 Zooming In This concludes our view from 10,000 feet of the Plastic SCM landscape. In the remainder of this

manual, well zoom in, giving you a more complete look at all the features we seen so far. Youll get to

see some additional features, too (some of which complained loudly about not making it into this

chapter), including:

comparing revisions and merging revisions from branch to branch

replicating revisions between multiple Plastic SCM installations

revision annotation and code reviews

trigger-based automation of SCM policies and procedures

integrations with third-party IDEs and other development tools

Plastic SCMs killer graphical user interface (GUI)


18/108

9

Chapter 2

Basic Development with Plastic SCM

This chapter describes a very simple scenario of Plastic SCM usage: a small team of developers, working

together on the same project. No subprojects, no branching, just everyone working on the same set of

source files. The team relies on the SCM system to keep things organized, and to prevent code from

getting lost or overwritten. If your own development scenario is more complex, dont worry well

address your needs in later chapters!

Whats more, were going to start in the middle, with the teams code base already under Plastic SCMsource control.

2.1 Workspaces

The source code base is safely stored in a Plastic SCM repository, but as a developer, you never access

the repository directly. Instead, you create a workspace and use the Update command to load source

files into it. The Plastic SCM GUI makes it very easy to keep track of your workspaces, switch back and

forth among them, and create new ones.


19/108

10

Figure 7: Accessing workspaces

A workspace is simply a directory more precisely, a directory tree on your machine, or maybe on

some network server that your machine can access. The only thing that makes a directory special is a

hidden subdirectory, named .plastic. On Linux systems, its hidden from many commands by virtue of

that initial dot character in the name; on Windows systems, the directorys hidden attribute is set.

Plastic SCM uses the files in this subdirectory to establish the workspaces identity (plastic.workspace)

and to determine which revisions of source-controlled items should be loaded into the workspace

(plastic.selectorandplastic.wktree). You never need to access these housekeeping files directly.

Because a workspace is just a standard directory on your machine, you can use all your regular tools toaccess it: file managers such as Windows Explorer, IDEs such as Eclipse and Visual Studio, and so on.

Plastic SCM has its own Explorer-like tool, called the Items view:


20/108

11

Figure 8: Items view

The Items view has standard file-manager columns, including an items name, its size, and its timestamp.

It also has SCM-related columns Status, Type, and so on. The Revision column in the figure above

shows that the workspace contains a particular revision of each item. In this example, its revision #23 of

filefracbars.pwy, a checked-out revision offracbars_help.py, revision #2 ofwood_ruler.png, revision #2

of directory doc, and so on. In keeping with our simple development scenario, all these revisions are

on the/main branch.

Why those particular revisions? Its time to discuss the way in which revisions find their way into a

workspace.

2.1.1 Workspace Configuration and the Selector

The repository contains allthe revisions ofallthe source-controlled items. Each workspace contains a

configuration of revisions just one revision (at most) of each item. Heres a conceptual picture for our

example scenario:


21/108

12

Figure 9: Workspace configuration selecting item revisions

A workspaces configuration is determined by its selector, a set of rules for selecting one revision of

each item. In our simple scenario, the selector looks like this:

r eposi t or y "REPOSITORY_NAME"

pat h "/ "

br " / mai n"

co "/ mai n"

These four lines constitute a single, simple rule:

In the repository named REPOSITORY_NAME, for all items at or below the root directory (pat h "/ " ),

select the most recent revision on branch/main (br "/ mai n" ); create new revisions of the item on

that same branch (co " / mai n" ).

All of the developers on the team use this same selector in their workspaces. This enables development

to proceed as follows:


22/108

13

Each developer uses the Update command to bring the most recent revision on branch /main into

his or her workspace. At this point, all three developers (Mary, Eduardo, and you) have the same

configuration of revisions in their workspaces, the one illustrated inFigure 9.

Mary creates a new revision, #7, of itemfracbars_help.py. Eduardo creates a new revision, #15, of

itemfracbars_utils.py.

Youre the third developer, but you havent gotten around to writing any new code yet. When

youre ready to go, you Update your workspace again. Plastic SCM sees that your workspace

currently contains revision #6 offracbars_help.py, but your workspaces selector indicates that the

latest revision on the /main branch is #7. Likewise, it sees thatfracbars_utils.pyneeds to be updated

to revision #15. Accordingly, the Update causes these two new revisions to be copied from the

repository to your workspace.

Its all quite simple. Too simple, youre probably thinking. Fair enough well introduce some

complexities in the next section, where we describe the ways in which developers actually go about

creating new revisions. And even more in the next chapter, where we discuss parallel development.

Youll see that Plastic SCM handles the complexities simply, effectively, and flexibly.

2.2 Creating New Revisions

Over the years, most SCM systems have chosen one side in the great debate over how to go about

making changes to the repository. Plastic SCM doesnt make you choose sides you can proceed in

either of these ways:

Checkout-Modify-Checkin You declare your intention to create a new revision of an item with a

checkoutcommand. Plastic SCM records this in the repository, so that other developers (or

managers) can tell what youre doing. It might also prevent other developers from performing a

checkout of the same revision. After modifying the item, you use a checkin command to create the

actual revision in the repository.

Modify-Commit You dont need to declare your intention, but simply proceed to make a

modification in your workspace. Then, you use a commitcommand to send the change to the

repository, creating a new revision there.

Both methodologies have both advantages and disadvantages. For example, checkout-modify-checkin

works better with huge source bases, so that the SCM system doesnt have to engage in a lengthy hunt

for modified files. And the shelving feature works only with checkout-modify-checkin (see section

Shelving Checked-out revisions when Switching Branches). But many developers have gotten used to the

convenience of never having to issue a checkout command. Lets see how both methodologies work in

Plastic SCM.

2.2.1 Using the Checkout-Modify-Checkin Methodology

In the Items view, the Checkout-for-editcommand appears in the context menu of current selection,

which can be a single item or an arbitrary set of items:


23/108

14

Figure 10: Checkout of items

Checking out an item creates a checked-out revision sort of a temporary revision in

the repository. No data gets copied from the repository by this operation (unlike, say, with

a Subversion checkout). But there mightbe a change in your workspace: Part of Plastic

SCMs per-user configuration is the option to maintain items as read-only in your

workspace until theyre checked-out. (Its in the Preferences dialog, on theOther options

tab.) If your configuration uses this option, then the Checkoutcommand changes each

items status from read-only to read-write.

This feature is intended to make accidents less likely, not make them impossible. After all,

most developers know how to get rid of a files read-only status. Plastic SCM has very

robust security features, but theyre focused on the repository, not the workspace.

Figure 11: Checked-out revision in the repository

In the Items view, a checked-out item appearance is distinguished in several ways:

In the Item column, the icon decoration changes from a green checkmark (meaning under source

control, but not checked-out in this workspace) to a red dot (checked-out in this workspace).

The Status column indicator changes from Controlledto Controlled/Checked out.

The Revision column shows the checked-out revision, in which the keyword CO appears instead of a

revision number.


24/108

15

Figure 12: Display of checked-out items in the Items view

As you make changes to a checked-out item (for example, with a text editor), the Items view display

doesnt change the items status remains checked-out. To see what changes youve made, you can use

the Diff tool, described later in this chapter.

When youre done making changes, you use the Checkin command to replace the checked-out

temporary revision with a permanent, official revision.

Figure 13: Checkin of new revisions

The Plastic SCM GUI makes it easy to enter a comment string, to be associated with the newly created

revision(s) anything from a single word to multiple paragraphs. Its also easy to reuse (and revise)

comment strings that you entered for recent Checkin commands.

In the Items view, the icon decoration and Status indicator revert to their not-checked-out states. In the

Revision column, the CO keyword is replaced by the revision number of the newly created revision.


25/108

16

Figure 14: Items view display of new revision

Multiple Checkouts of the Same Revision

Remember your project colleagues, Mary and Eduardo? What happens

if one or both of the want to Checkoutthe same item(s) as you? With

Plastic SCM, its not a problem. Any number of checked-out revisions

can be created for a revision, as long as each one is in a different

workspace.

Figure 15: Two checkouts of the same revision

Now, the race is on! In this example, if Eduardo performs a Checkin first, you dont exactly lose. But you

must perform a merge operation, combining Eduardos changes with your own, before Plastic SCM will

allow you to Checkin the item. This is very similar to what occurs in a parallel development environment,

which the next chapter explores. And in fact, you and Eduardo are engaging in parallel development on

this item, even though there are no subbranches involved!

Some organizations might want to discourage developers from racing to be the first to Checkin. In this

case, you start the checkout-modify-checkin cycle by invoking the command Checkout exclusive instead

ofCheckout for edit. Everything looks exactly the same in the Items view when this exclusive checkout

feature is in use. And it works the same, too, except that an error occurs in Mary, Eduardo, or anyone

else attempts to Checkoutthe same item in their workspace. The race is over before it starts youve

grabbed the exclusive right to create the next revision of that item.

We discourage use of exclusive checkouts, because theres really no need to restrict developers from

working. Let them work now, and merge later!

2.2.2 Using the Modify-Commit Methodology

To use this methodology, you first make sure notto configure Plastic SCM to maintain items in a read-

only state. Then, you just go ahead and make your changes, without invoking Checkout. Items that you

modify show up in the Items view as having Changedstatus (instead ofChecked out), and their icon

decoration turns blue (instead of green). Typically, you must refresh the Items view to have it notice

that certain items have been changed.


26/108

17

Figure 16: Changed items in the Items view

When youre done making changes, you use the Checkin command to create new revisions of the

modified items. (There is no commit command in Plastic SCM we just wanted to make this

description sound familiar to users of the many other SCM systems that do use a commit command to

implement this methodology.)

Changing the Same Revision in Different Workspaces

If you, Mary, and Eduardo use the modify-commit methodology on your project, there will inevitably

come a time when two or more of you work on the same file at the same time. This is perfectly fine, but

there are no checked-out revisions in the repository, and so no way for Plastic SCM to inform team

members that they might be getting in each others way. Still, Plastic SCM keeps things organized:

anyone can Checkin a new revision. Other developers wishing to Checkin must first perform a merge

with the latest checked-in revision. (This is pretty much the same as the protocol described in section

Multiple Checkouts of the Same Revision above.)

2.2.3 Private Files

In the preceding sections, we saw how items go through several kinds ofControlledstatus as you modify

them:

Controlled

Controlled / Checked out

Controlled / Changed

Theres one more status to discuss: none of the above that is, Private. A workspace is a space in

which you do development work, so it tends to accumulate lots of files (and even directories) that

shouldnt be placed under source control. This can include editor backup and temporary files, compiler


27/108

18

output files, email messages, screen shots, little scripts that you would never show to anyone else, and

so on.

The Items view displays private files and directories with no icon decoration and no entry in the Revision

column. For your convenience, Private objects are grouped together, separate from the various kinds of

source-controlled items.

Figure 17: Items view display of private objects

2.2.4 Pending Changes View

One of Plastic SCMs most useful tools in the Pending Changes view. It helps you to answer the

questions, what items have I changed? and how does my workspace differ from the repository?

Using checkboxes, you can have this view search through your entire workspace for one or more of the

categories introduced in the preceding sections: Checked outitems, Changeditems, and Private objects.

Figure 18: Pending Changes view

A couple of fine-tuning controls in this view are particularly useful for handling large sets of files:


28/108

19

The listing of Private objects can include or exclude the ones that you have no intention of placing

under source control. Such ignored objects are described in sectionFiltering Out Unwanted

Objects with an Ignore File below.

Typing a character string in the Filterfield instantly restricts the listing to the subset of names that

contain the string.Once youve located the objects that have changes, you can take steps to synchronize the workspace

with the repository: Checkin items that are checked-out (or cancel the checkouts), place private objects

under source control. Before doing so, you might want to examine the actual changes in the modified

objects. But the Pending Changes view simply lists names of objects; to drill down into the objects, you

need Plastic SCMs graphical Diff tool. This is a great tool, fully deserving of its own section. See section

Detailed Monitoring of Changes: The Diff Tool below.

Checkouts All Users View

The Pending Changes view can show the checked-out items for one workspace only. If you want to see

what your colleagues are doing, or what youre doing in other workspaces, use the Checkouts All Users

view.

Figure 19: Checkouts All Users view

Like its cousin, this view has a Filterfield, helpful in wrangling large sets of checked-out items.

2.2.5 Revisions of Directories

Chances are that (almost) every time weve referred to a revision of an item in this chapter, youve

thought revision of a file. Many people get a little dizzy when confronting the idea of directory

versioning, and many SCM tools dont even try to address this area (or they do, but do it badly). But the

ability of an SCM tool to track directory-level changes (and the freedom of developers to refactor

without fear of breaking the tools) is very important to keeping a source base healthy.

Besides, its really not all that difficult.

Consider what the contents of a source-controlled item are:

For a file item, the contents are a series of text characters (text file) or a series of byte values (binary

file).


29/108

20

For a directory item, the contents are a set of names names of files that live in the directory, and

names of subdirectories.

Now consider what constitutes a change to a source-controlled item, a change that can be preserved in

the repository as a new revision of the item:

For a file item, its any change addition, deletion, moving from one point to another in the seriesof characters or bytes.

For a directory item, its any change to the list of names. This includes renaming an existing file or

subdirectory, deleting an existing file or subdirectory, creating a new file or subdirectory, or moving

a file or subdirectory to another location in the directory hierarchy.

In practice, developers are quite happy to have an SCM system track directory-level (or namespace)

changes. But they tend to get annoyed when making those changes, because a directory must be

checked-out before it can be modified. This is true even if youre using the modify-commit methodology

instead of checkout-modify-checkin when working with file items. (If I had a dime for every time I forgot

to checkout the current directory before placing a newly created file under ClearCase source control, )Fortunately, the Items view takes care of the checkout for you.

Figure 20: Automatic checkout of a directory

CLI users and script writers: our condolences, youll have to perform the directory checkouts yourselves.

Pop quiz: what happens if you cancel the checkout of the src directory at this point? Answer: the

renamed item reverts to its old name,fracbars.pyw. Renaming is a directory-level change, and you just

threw away the change. And the fact that renaming an item is not a change to the item itself explains


30/108

21

why the revision identifier/main#23 never changed in this example. This is the aspect of directory

versioning that is most likely to make peoples heads explode!)

2.2.6 Accessing Other Revisions of Items

Your workspace contains one revision of an item, but all the other revisions are safely stored in the

repository, ready to be accessed. Plastic SCM provides a couple of tools for working with these other

revisions.

The History View

The History view displays a table that contains all the revisions of one item. The columns in this table

provide overview information on each revision: the revision identifier, timestamp, user who performed

the Checkin, the checkin comment string, and the labels (if any) attached to the revision.

Figure 21: History view

Its pretty easy to figure out how the revision identifierworks: / mai n#5 means revision 5 on the main

branch. These identifiers will get more interesting in the next chapter, when we discuss the branch

hierarchies that arise in parallel development environments.

You can use the History view to examine the contents of any revision, to revertyour workspace to an

old revision (because everything youve done since is brain-dead), and a variety of more advanced

operations. Its likely that youll use this view chiefly to compare an old revision with the one in your

workspace. Another popular operation is comparing a revision with its immediatepredecessor, to

determine what changes were made in that particular revision. Comparing revisions is described in

sectionDetailed Monitoring of Changes: The Diff Tool.

In addition to providing a way to drill down into revisions, the History view enables you to rise up

into the context where a particular revision was created. That is, you can jump from a revision to the

changeset that includes the revision. SeeHigh-Level Monitoring of Changes: Changesets.

The Revision Tree View


31/108

22

The Revision Tree view provides an alternative way

to view an items revisions. Instead of displaying a

table, this view presents an interactive 3D drawing,

showing how all the versions are organized into a

hierarchical tree. Heres an example, following this

chapters scenario: all revisions are created on a

single branch, called/main.

Figure 22: Revision Tree view

You can rotate the view in three dimensions, zoom in and out, and jump to a particular revision. If an

item has many revisions, you might choose to restrict the view to those revisions created in a particular

time interval.

2.3 Plastic SCMs Flexibility in Day-to-Day Development

As you go about your day-to-day development work, there will be plenty of occasions when you change

your mind or just plain make a mistake. Plastic SCM is flexible enough to handle many of these situations

easily. This section introduces a few of these features.

Often, you intend to work on a particular file, and so perform a Checkout, but then change your mind.

(Or your boss changes your mind for you.) Or maybe you mistakenly included a particular file in a group

of files you submitted to the Checkoutcommand. No problem just use the Undo checkoutcommand.

Ever have one of those weeks when every good idea you have turns out to be a bad idea? Youve

created revisions 13, 14, and 15 of a file, and now nothing works. Again, no problem just use the

Revertcommand to reinstate revision 12. Those evil revisions remain in the repository (just in case there

were some good ideas in there), but they wont break your builds anymore!


32/108

23

Sometimes, your zeal to place all your work under source control goes a little too far. For example, you

might have created source-controlled items from backup files and compiler object modules. TheDelete

command comes to the rescue, creating a new revision of the parent directory that excludes the item.

You can delete the file(s) from your disk, as well, or leave them in your workspace as private objects.

(The command-line interface includes an obliterate command, which removes an item from the

repository altogether. By default, permission to use this command is not granted to any user!)

2.4 Incorporating Others Changes into Your Workspace: Update

Your workspace provides isolation from the changes that your colleagues are making to the source base.

This can be a good thing. But all the changes will eventually need to be integrated with each other. The

conventional wisdom is that the longer you wait, the more difficult the integration will be! Thus, it

makes sense to integrate on a regular basis, bringing your colleagues changes which theyve made in

their own workspaces and then sent to the repository with Checkin commands into your workspace on

a regular basis.

The Update command is your everyday tool for incorporating others changes into your workspace. As

described in sectionWorkspace Configuration and the Selector above, this command determines that

your workspace wants the most recent revision of each item and, if necessary, downloads the newest

revision from the repository into your workspace. Typically, the new revision was created by another

user, but it might be a revision that you created in a different workspace.

If you have a particular file checked-out in your workspace, and another user has created a new revision

in the repository, the Update command wont overwrite your file. In fact, Plastic SCM bends over

backwards neverto overwrite changes that have not been preserved in the repository, unless you

approve such clobbering. In this case, youll eventually need to perform a merge, as described in

sectionMultiple Checkouts of the Same Revision above.

2.4.1 Tuning the Update Command by Cloaking Objects

In a large development organization and/or with a source base involving very large files and/or in a slow

networking environment, the Update command can take a long time to accomplish its work of

determining which objects need to be updated in your workspace, and then downloading the actual

data. To address this potential problem, Plastic SCM enables you to designate individual files or entire

directory subtrees as being cloakedfrom the Update command (and, less importantly, from the

Checkoutcommand, too). Perhaps youre working on real-time graphics performance, so you dont care

about the tweaks to the database-query engine or to the online help system. You can cloak the

directories containing these subsystems, to make your updates proceed more quickly.

The cloaked.confconfiguration file controls cloaking. It can be located under your home directory, for

use in all workspaces, or in the root directory of individual workspaces.


33/108

24

2.5 Detailed Monitoring of Changes: The Diff Tool

Its time (finally!) to take a look at Plastic SCMs graphical Diff tool. A tool that shows differences

between revisions of a source-controlled object is obviously an essential part of any SCM system. Its

one thing to see that lots of revisions exist, using the History tool or Revision Tree tool; its quite another

to be able to see, and understand, how the revisions differ how an item has evolved over time.

The Diff tool is simple to use and powerful able to show differences in text files, image files, and

directories. And we think its beautiful, too! In keeping with Plastic SCMs flexibility, you can configure

the GUI to use alternative difference tools, as well.

2.5.1 Comparing Revisions of Text Files

The Diff tool displays two revisions side-by-side, using colors and shading to clarify exactly where

differences occur, down to the individual character. The fat separator bar between the left and right

panes makes it particularly easy to see how blocks of code have changed in size, have been deleted

altogether, or have been newly inserted. Arrow buttons and a search facility make navigation through

large files easy. And the Options menu provides a great deal of flexibility in handling whitespace, line-

endings, and character encodings.

Figure 23: Diff Tool comparing revisions of a text file


34/108

25

Advanced Detection of Moved/Modified Code

Perhaps the most powerful feature of the Diff tool is its cross-difference capability, which we spell

Xdiff. The Diff tool can recognize that code blocks have been moved from one part of the file to

another. It can even detect that such blocks have been revised as well as moved, and can launch a sub-

diff windowthat zooms in on just those revisions.

Figure 24: Xdiff (cross-difference) capability


35/108

26

2.5.2 Comparing Revisions of Binary Files

Binary file comparison is something that many SCM systems dont even attempt. The Diff tool doesnt

work miracles, but does its best to enable you to compare revisions of an image file (PNG, JPG, GIF, and

so on). The two revisions images are displayed side-by-side, so that you can determine the differences

by inspection.

Figure 25: Diff tool comparing revisions of an image file

Alternatively, you can have the images superimposed and blended together (with a slider to control the

blending), which sometimes make it easier to perform the visual comparison.

2.5.3 Comparing Revisions of Directories

The Diff tool is just as good at comparing directory revisions as file revisions and it compares them in

much the same way. Creation and deletion of files and subdirectories appear in exactly the same way as

insertion and deletion of lines from a text file. Renaming of an object appears similarly to making a one-

line edit in a text file.


36/108

27

Figure 26: Diff tool comparing revisions of a directory

The moving of an object from one directory to another shows up as two changes: a deletion in the

from parent directory, and an insertion in the to parent directory.

2.6 Additional Tools for Detailed Monitoring of Changes

The Diff tool does an excellent job of showing whathas changed in the contents of an item. Sometimes,

though, an organization needs to know the who, when, and whyof a change. Whats the need? Well, the

command name git blame might provide a hint. Plastic SCMs corresponding command doesnt have a

snarky name; we just call it annotate.

2.6.1 Annotation of Revisions

The Annotate view displays the complete contents of a revision, with annotations automatically

displayed for each text line: the name of the user who added (or last revised) the line, along with the

changeset and revision identifier to pinpoint when the line was added (or last revised). In a parallel

development environment, where changes can get propagated from branch to branch to branch, the

Annotate view takes care to identify the originalsource of each change.

The annotations are colored and shaded, making it easy to scan a revision for recent changes or old

ones. (For flexibility, the shading colors are configurable.) Selecting a line reveals the changesets

timestamp and comment string in a properties pane at the bottom of the view.


37/108

28

Figure 27: Annotate view of a revision

In addition to automatic annotation of text files on a line-by-line basis, Plastic SCM provides for manualannotations, in the form of code reviews. Well defer discussing this feature until the next section,

because its closely related to another feature: changesets.

2.7 High-Level Monitoring of Changes: Changesets

In the preceding sections, weve concentrated on individual file system items in describing how changes

are made (by you) and tracked (by Plastic SCM). But in practice, you probably spend most of your time

implementing changes that affect groups of items, rather than individual ones. (I need to add a

parameter to the AdjustFrammis function, and also fix all the routines that call this function.) Recent

SCM systems, such as Git and Mercurial, have recognized this truth and have deemphasized individual-

file changes, stressing instead changesets that can affect any number of files.

Well, with Plastic SCM, you can have it both ways. To get the big picture, you can work with changesets.

(In fact, you can get an even bigger picture, by working with sets of changesets!) When you need to, you

can drill down to the individual items involved, to determine line-by-line differences, using the Diff

tool.


38/108

29

Each time a Checkin command is invoked on a group of items, Plastic SCM creates a new revision of each

item; it also creates a changesetobject, which lists all the newly created revisions. Each repository has

its own collection of changesets, numbered sequentially: 0, 1, 2, 3, and so on. (Changeset 0 is always the

big bang that places the repositorys root directory under source control, creating revision/main#0.)

A changeset also represents an atomic transaction, thanks to the SQL database technology upon whichPlastic SCM is built. If you submit 1000 items to Checkin, the resulting changeset is guaranteed to

contain all 1000 new revisions if it is created at all. If the Checkin is interrupted, on purpose or by

accident, the repository remains unchanged no new revisions, no new changeset.

2.7.1 Viewing Changesets the Changesets and BranchExplorer Views

Plastic SCM provides multiple changeset-related tools for getting the big picture that we alluded to

above. This section describes the two basic tools: the Changesets view and the BranchExplorer view.

The Changesets view displays a table of recently created changesets for the current repository. Actually,

thats just the default; you can modify the query that produced the table, to refine its contents by

various criteria timestamp, username, and so on. (Like this flexibility? See sectionAdvanced Reporting

with Queries.)

Figure 28: Changesets view

The BranchExplorer view provides a graphical alternative to the Changesets view. It shows a repositorys

branches along a timeline, with squares representing the branchs changesets. (EachCheckin command

produces a changeset consisting of revisions on one particular branch.) In keeping with this chapters

scenario, the example below shows development work taking place on the/main branch only. Selecting

a changeset displays overall information in the Properties pane, such as the changeset number,

timestamp, and Checkin comment string.


39/108

30

Figure 29: Changesets in the BranchExplorer

In either the Changesets view or BranchExplorer view, double-clicking a changeset opens a view that

lists its individual revisions.

Figure 30: Viewing a changeset's individual items

Using this view, you can drill down further, viewing the contents of individual revisions, comparing

revisions with the Diff tool, and so on.

2.7.2 Comparing Changesets

The Changesets and BranchExplorer views are very valuable, but they dont precisely answer the

question, just what did this changeset actually change, at the content level?. To get the answer to that

question, you need to compare each revision in the changeset with its immediate predecessor revision

in the repository. Thats just what the Diff changeset contentcommand does. Its available in both the

Changesets and BranchExplorer views.


40/108


41/108

32

Figure 32: Comparing changesets

Again, the comparison is presented in two panes. The upper pane lists the items with a revision in either

changeset, or only the items that have a revision in both changesets. When you select an item, the

appropriate drill down automatically appears in the lower pane: the contents of the one revision, or aDiff-tool comparison of the two revisions.

2.7.3 Comparing All of a Branchs Changesets

The Diff changeset contentcommand, described in the preceding section, provides insight into one set

of changes that were recorded on a branch. Now, think bigger think about scrolling through an entire

sequence ofDiff changeset contentdisplays, one for each changeset on a branch. That would play the

movie of all the changes on the branch, organized by changeset. In an environment that uses the

branch-per-task methodology, that movie would tell the entire story of the work that went into a

particular task.

The movie is not just a Hollywood fantasy its the view produced by the Explore changesets in branch

command. The right hand side contains a two-pane Diff changeset contentdisplay. Along the left edge

are the movie frames that is, the branchs changesets.


42/108

33

Figure 33: Explore changesets in branch command

(You might think of this views movie frames as blowups of the boxes that represent changesets in the

BranchExplorer.)

2.7.4 Code Reviews for a Changeset

A code reviewfor a changeset is a cooperative document, with contributions from any number of

Plastic SCM users. It has a title, a status, an assignee (the user responsible for conducting the review),

and an owner (the user who created it). The initial content of a code review is the view produced by the

Diff changeset contentcommand. In the lower pane, where the Diff tool shows the differences between

a revision in the changeset and its immediate predecessor, users can click on any line to add comments

of any length to the line. Existing comments are displayed in a third pane at the bottom of the window.


43/108

34

Figure 34: Code review for a changeset

The Code reviews view displays all of the teams code reviews. You can also restrict the display to just

those reviews retrieved by standard queries (Filters), by queries you customize, or whose titles match

a filter string you enter. Team members can use this view to monitor the code reviews, reassign them,and transition their statuses (Pending, Approved, or Discarded).


44/108

35

Figure 35: Code reviews view

2.8 Getting Started: Placing Objects under Source Control

Why is a getting started section near the end of a chapter? We decided to describe the operations you

perform most often first. After all, you start a project only once; you work on the project every day

thereafter. Well assume that the project files to be placed under source control are all in one location.

They might be in a ZIP or TAR archive, or maybe theyre just sitting in a directory on your disk.

First, you need to decide whether to create a new repository. A project that has its own identity (which

often means its own development schedule and perhaps its own set of developers) typically should have

its own repository. The Plastic SCM GUI makes repository creation easy:


45/108

36

Figure 36: Creating a new repository

Next, you create a workspace connected to the new repository again, an easy task:


46/108

37

Figure 37: Creating a new workspace

Depending on how youve packaged your project files, you can create the workspace in either of these

ways:

Bringing the data to the workspace if the project files are in a ZIP or TAR archive, create the

workspace as a new directory in disk storage. Then, unpack the archive into the newly created

workspace directory.

Bringing the workspace to the data if the project files are sitting in a directory, just designate that

directory as the location of the new workspace.

At this point, your project files are in the workspace, but are not yet under source control. That is, they

are private objects. So the next (and last!) step is to convert this entire collection of private objects into

source-controlled items, using theAdd to source controlcommand in the Items view:


47/108

38

Figure 38: Placing objects under source control

2.8.1 Filtering Out Unwanted Objects with an Ignore FileSometimes, your package of project files turns out to contain some junk: backup files, excerpts from

email messages, and so on. You certainly dont want the junk cluttering up your repository, but whats

the best way to handle this? Here are a couple of acceptable alternatives:

Clean up the package before getting started with Plastic SCM, take time to remove the junk files

from the ZIP or TAR archive, or remove them from the directory tree containing the project files.

Clean up the repository after placing the project files under source control, go back and use the

Delete command to get rid of the junk files and directories that were converted to source-

controlled items.

But Plastic SCM offers another alternative, which often turns out to be the cleanest solution: during

execution of theAdd to source controlcommand, filter out the junk automatically. You accomplish this

using an ignore file, a simple configuration file that specifies filename patterns. Heres a simple

example:

# i gnor e al l bi n and bui l d di r ect or i es

*/ bi n*

*/ bui l d*

# i gnor e t ext - edi t or backup f i l es and emai l messages

*. bak

*.

Documents

Plastic Intro