View
222
Download
0
Category
Preview:
Citation preview
7/28/2019 Plastic Intro
1/108
Introduction
to Plastic SCM
Version 3.0 December 15, 2010
http://www.plasticscm.com/7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
9/108
ix
Figure 88: Plastic SCM command panel in Microsoft Office program ........................................................ 95
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.aspx7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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)
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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).
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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!
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
40/108
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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.
7/28/2019 Plastic Intro
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).
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
45/108
36
Figure 36: Creating a new repository
Next, you create a workspace connected to the new repository again, an easy task:
7/28/2019 Plastic Intro
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:
7/28/2019 Plastic Intro
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
*.
Recommended