The Plastic SCM GUI

What's a workspace? What's a repository?

Ok, so you already know Plastic is made of servers and clients, but you'd like to know what a repository and workspace are. Let's go!

When you code, you have a copy of your sources in a certain directory, right? You make changes there, build your project, test it, run unit tests, and so on. That's your workspace. A workspace is just a directory where your sources are. As simple as that, with one slight qualification: this directory is under version control with Plastic SCM. When you modify something, Plastic will know. When you add something, Plastic will know. Plastic knows the version of every file and every directory you have in your workspace.  Directory versioning allows for this to happen.  Directory versioning is powerful and few SCM tools support this capability.

So what's a repository? Remember that the Plastic server stores all your files, directories, and their modifications on databases. Each of these databases is a repository and each of them will normally contain a project. We can argue later about different alternatives, but in order to get started, simply assume every software project you work on will be stored in a different repository.

Your files and directories and their changes are not stored on the server like zip files (as you probably did when you were not using an SCM tool! :-P) but in a relational format. The server and the client have to work together to extract data efficiently from the repository (database) and create a directory structure with files you can work on, AKA your workspace.

So, let's do a really simple experiment, and let me introduce you to some of the most basic actions on the Plastic command line interface before jumping into the GUI. Go to a directory where you have some code and type:

cm makerepository myrepository
cm makeworkspace myworkspace .
cm switchtobranch /main@myrepository
cm add -R *
cm checkin

Which means:

  • Create a new repository to store this project (myrepository)
  • Create a workspace called "myworkspace" here.
  • Switch the workspace to the main branch of the repository "myrepository".
  • Add everything inside.
  • Check in everything inside.

All these commands have short versions to avoid typing toovdfgs much (i.e. makerepository --> mkrep, switchtobranch --> stb, etc.). We used the spelled-out versions here, for clarity.

Note: Once you create your workspace, check that your directory now has a hidden directory named .plastic. This is where Plastic will store workspace-associated information, the workspace tree (which shows revisions of every file and directory you've loaded), and other internal stuff.

Now try the following: delete everything (except the .plastic hidden dir!) inside your working directory! Don't hesitate, just do it.

Well, now you've lost your code. Hope it was not too terribly important!

I'm kidding! Your code is now safe on the server, in the repository you've created during installation. Go to your workspace directory and type:

cm update .

And you'll see how your beloved code quickly comes back to your directory. What happened here?

Simple: you uploaded your code to the repository, and then you downloaded it back. The Plastic client and server will work together to make this copy as efficient as possible, and will only download the necessary files. Okay, this particular time, you removed the entire thing, so everything will be re-downloaded, but normally you'll just be switching from one version to the next one. That makes this a fast and efficient operation.

Geek point!!! We've worked hard to optimize the client so it will do as few disk reads and disk writes as possible while also taking advantage of your multi-core CPU to speed up the download process, the check-in, and so on. That's why Plastic is faster than other SCMs out there.

The Plastic SCM GUI

When you start up the Plastic GUI (plastic.exe for Windows users, and simply 'plastic' for Mac OS X and Linux) you'll find something like this:

Let's take a detailed look at each of the areas of the GUI. Once you learn what they are about, you'll find it easy to do even the most complicated and sophisticated operations.

First you find the workspaces tab area: it's just a list of the workspaces you have on your machine. You can switch from one to another just by clicking on the names (that's why we do names for workspaces!). Remember the current one will be highlighted in white.  A blue rectangle screenshot below highlights the area I'm talking about.  In my case I have 3 workspaces.  When you open Plastic for the first time you'll only have one (you'll be prompted to create one during the first run of the tool).

Just below the previous area you'll find the active workspace info panel in the image above. It is just an area to display information about the current workspace, the one selected on the workspaces tab area. This area renders the workspace name, then it loads the branch and the path where your workspace is located on the disk.

On the left of the screen in the image below, we find the view buttons. This is a panel with buttons that opens Plastic SCM "views". A view is just a window with information about one or more of the objects Plastic can deal with, like files, directories, labels, branches, changesets, and so on. You can display the famous Branch Explorer from the view buttons panel too.

Then we enter the biggest zone on the window: the views area. Here's where the different views are located. You can open multiple views and switch between them using the tabs on the top, similar to what you would do in a web browser. By default, when you open Plastic SCM, the items view will show up. It's the view showing you the content of your workspace, the files and directories you have there.

Common actions

Now you have a basic understanding about how the Plastic graphical user interface is organized. The next step is taking a look into the different views. In the left panel, they are organized into sections:

  • Main Actions:
    • Items: You'll see the content of your workspace here, which files and directories you've loaded, and which revision of each one. From here, you can perform basic actions like check in, check out, update the workspace, delete items, add items, run differences, and show version history. Get familiar with it, since it's going to be one of your key tools.
    • Pending Changes: This is the view you'll normally use to check in changes. Here, you can list all your check-outs (files and directories you've marked to be modified), see files you've directly modified (overwriting and changing their contents), new files you've created, and files that have been moved, renamed or deleted.
    • Branches: This is the list of the branches you have in the repository you're working on. From here, you can create new branches, switch to them (to work on them), compare their content, merge them, replicate them, and much more. It's another key view.
    • Branch Explorer: Our unique Branch Explorer provides the main view related to parallel development. It's equivalent to the branches view, but this time in a graphical way. It's probably the view you'll be using most of the time. From here you can complete an entire branch and merge cycle.
    • Changesets: This lists the individual check-ins (changesets) you've created. You can review them from this list. It's a very useful tool to gain another overall perspective.
  • Review & Stats:
    • Reviews: This is a list of the code reviews. You can run entire code reviews within Plastic SCM, out of the box.  More importantly, users can comment on them.
    • Change Stats: If you need a visual way to see who's doing more changes and where, this is where you go.
  • Other actions:
    • Labels: See a list of the labels you've created. Use this view to go back to a label and rebuild a previous version of your software, to view its contents, or simply to create and apply new labels. Remember: first you create the label and then you apply it to your workspace to create a snapshot of the current situation.
    • Attributes: Here, you can add customizable metadata to objects. Powerful for advanced users and adopted by most sophisticated development shops.
    • Sync Replication: This is a special view that lets you configure automated replications between different repositories (even on different servers). Once the relations between repositories are set up, a simple click keeps them in sync.

Under "Repositories & workspaces", you'll find the buttons to open the list of workspaces on the current machine and the list of repositories in the server.

The preferences button launches the preferences dialog. This lets you configure a number of Plastic options: from comment behavior to update options, from language preferences and connection to the server (running the configuration wizard) to issue tracking integration.

Add code under source control.

Once you've created a workspace, the first thing you'll need to do to start working is to add some code under source control. There are several ways to get this done:

  • From the command line using the "cm add" command (as was described earlier).
  • From one of the integrations: Visual Studio, Eclipse, IntelliJ, etc. The wizard will guide you through the process of adding code and will take care of skipping private files that shouldn't be added.
  • From the GUI.  This merits a little further explanation.

Add code from the GUI

First, copy some code into your workspace.  For this simple example, Windows Explorer will suffice.

Once you've copied the code, if you'd like to get the entire tree under source control, simply right-click on the root of the workspace and select "Add directory tree to source control". This is the same thing you did at the beginning of this chapter with command line "cm add -R ." plus "cm ci". It adds your code and checks it in for you in one step.

If you go to the branch explorer, now you'll see how you have a new changeset created. This is the one you've just created when you added your code.

Selecting what to add: ignoring files and directories

Let's go back to the first step.  Suppose you have contents on your directory that you simply want to skip.  For instance, you don't want to add your "bin" directory under source control. How can you do that? Check the following screenshot. It explains how to ignore a directory. The same can be applied for files too.

Please note that there are two options:

  • The first one just says "bin" which means: ignore any "bin" directory. So if you want to ignore all of them in your tree, that's the one to use.
  • The second one means: just ignore this EXACT "bin" directory (the one on the root of the workspace according to the screenshot). Any other "bin" down in the code tree won't be ignored.

Note: By doing this, you're actually editing the ignored.conf configuration file, which is always local. Don't worry if you set up something weird, it will only affect your machine, not the repository.