Plastic SCM - Step by step Tutorial


Lesson 0 - Installation, configuration and concepts

This first lesson will teach you:

  • How to install Plastic SCM for Windows, Linux or Mac OS.
  • Set up Plastic SCM.
  • Review the fundamental concepts of Plastic SCM.

Download Plastic SCM

It's so easy! Just follow these steps:

  1. Visit the Plastic SCM download page.
  2. On the website, you can download the last release or select any other release exploring into the More installers, Previous releases or Labs downloads links.
  3. You can:
    • Download a 5 day free trial license.
    • Or sign up to get a 30 day free trial license for 5 users. You will receive an email with the download instructions.

These are the supported operating systems: Microsoft Windows, Linux, and Mac OS.


Installation Plastic SCM

Installing Plastic SCM is also an easy process. Here are the steps:

  1. Follow the Plastic Server and Client installation steps related to your operating system.
  2. In less than 1 minute, Plastic SCM will be installed on your computer.

Set up Plastic SCM

The Plastic SCM configuration process makes configuration very easy:

  1. Configure the Plastic SCM Server related to your operating system.
  2. Then, set up the Plastic SCM Client in your system.

These are some settings that you must configure:

  • The Plastic server port numbers where the server listens.
  • The user authentication mode.
  • The hostname and port where you Plastic SCM server is located.

Check the Quick-Start guide if you want to learn about Plastic SCM best practices.


Fundamental concepts of Plastic SCM

The goal of this section is to help you understand the terminology used to describe concepts in Plastic SCM. Since these terms will be used throughout this tutorial, it is important that you understand their meaning.

Here are a few concepts that you will need to know:

Repository

The storage. The repository will normally contain a project:

Repository
Workspace

The directory where your sources are stored:

Workspace

Items

The content of your workspace: files and directories:

Item

Branch

The place in the repository where you are currently working. You can create new branches then switch to them, compare their content, merge them, replicate them, and much more:

Branch

Changeset

The individual checkin you created:

Changeset

Label

The name assigned to a specific changeset. A label represents the state of your code at a specific branch and point in time.

Label

Lesson 1 - Adding the initial code

Welcome to the Plastic SCM world. This lesson uses a very simple scenario to walk you through setting up your project using Plastic SCM. The topics in this lesson include the following:

  • The basic structure of a repository and a workspace.
  • How to add your code to the version control, configure the ignored list and create your first label.

Create a repository

At this point, we need to create an empty repository to work with the codebase we just uncompressed.

Remember, the repository is the "database" where the changes will be stored.

To create a repository, simply click the Repositories menu option to display the repositories view:

Click on Repositories

Next, click the New repository button to start the process:

  • In Windows:

    Create new repository

  • In Mac OS:

    Create new repository

  • In Linux:

    Create new repository

When the New repository dialog is displayed, you will need to enter a name for the repository and specify the server. In this scenario (and most likely yours too), I'm using my local server running on my laptop, so these are the values that I will enter:

Dialog to create new Repository

Click OK to create the new repository.


Create a workspace

Once the repository is created, we need to create a workspace in the location where you uncompressed the files (remember, in this scenario it was C:\Users\maria\dokan_workspace).

To do this, go to the actions bar on the right and then click the Workspaces menu option:

Workspaces

Then, the Workspaces view displays, listing all the available workspaces on your machine. Click the Create new workspace button:

Create new workspace

When the New workspace dialog displays, you will need to:

  • Select a repository that the workspace will use.
  • Give the new workspace a name.
  • Select a path.
  • In Windows:

    Dialog to create new Workspaces

  • In Mac OS:

    Dialog to create new Workspaces

  • In Linux:

    Dialog to create new Workspaces

As you can see in the figure above, I selected the repository that I just created in the previous step. Automatically, Plastic choose dokannet as the name for the workspace and my workspaces path to store the data.

Once the workspace is created, the workspaces list will update. Double-click the dokannet one to open it:

Workspace created


Put the code in your workspace

Now, we're going to put some code in our workspace. We'll use a sample code uploaded to GitHub.

To do this:

  • In Windows:

    Go to the actions bar on the right and then click the Branch Explorer menu option:

    Branch Explorer

    In the Branch Explorer, right-click the main branch. Then, select the Sync with Git option in the Replication menu:

    Replicate some code

    Once the Sync with Git dialog appears, enter the following repository URL: https://github.com/PlasticSCM/dokannet:

    Replicate some code

    Then click the Sync button to start downloading (synchronizing) the code into your workspace:

    Replicate some code

    Once the synchronization finishes, close the dialog.

    Jump to the following steps.

  • In Mac OS:

    Run the following command in your terminal:

    cm sync dokannet@localhost:8087 git https://github.com/PlasticSCM/dokannet

    And you'll get something like the following:

    Replicate some code

    Jump to the following steps.

  • In Linux:

    Run the following command in your terminal:

    cm sync dokannet@localhost:8087 git https://github.com/PlasticSCM/dokannet

    And you'll get something like the following:

    Replicate some code

    Jump to the following steps.

Go to the Branch Explorer view and refresh it. Then you'll see a new changeset. Update the workspace with the downloaded code. To do this follow one of these steps:

  • Select the new changeset and right-click to run the Switch workspace to this changeset option.
  • Or, select the branch and run a Switch workspace to this branch option.

Replicate some code

Now, the Branch Explorer will look like this:

Branch Explorer updated

Take a look at the Items view in your workspace by clicking the Items view on the Main actions action bar:

Items View

And you'll see that your workspace will have the downloaded code:

Workspace updated

All files and directories are marked as Controlled. This means that they're under the Plastic SCM control.


Your first label

We can now go back to the Branch Explorer which will render the history of the repository graphically.

But what is the meaning of this graphic? What this means is that you have a branch and two changesets, one circle with a house on it (the current changeset loaded on your workspace) and the initial one (the solid circle on the left) which was the initial one created by Plastic SCM by default during the repository creation.

If you right click the changeset illustrated with the house, you will have the option to click the Label this changeset menu as shown in the figure below:

Click on label

Once you click the Label this changeset option, the New label dialog will display. Enter BL00 for the label name and enter a comment as shown in the figure below:

Create initial Label

Once the label is created, your Branch Explorer will look like this:

Initial label on Branch Explorer

Labels are used to mark stable releases in your project, so you can "save" a secure status that you can recover later if you need to by clicking the Switch workspace to this label option menu:

Switch workspace to this label


Lesson 2 - Modifying the code

Your code is always changing. Once you deploy your project you will continually be modifying files.

In this lesson, you will learn how to manage every change in your code under version control and how to see the differences with older versions of your files with the Plastic SCM GUI.


Checkout to edit

The checkout in Plastic SCM means:

  • The file is made writable (even if it was not by default).
  • Plastic SCM knows that the file has been modified (which is good for quickly locating changes).

To checkout an item, right-click it and select the Checkout menu option:

Checkout operation

As you can see below, after the checkout, the item is now marked as checked-out by Plastic SCM:

Item checked-out


Configuring the ignored files list

Once you open the DokanNet solution, in the Items view you'll notice that there are bin and obj subdirectories. We're not interested in these folders so we're going to add them to the ignored list.

To add these folders to the ignored list, simply right click the obj folder and click the Add to ignored list menu and select the obj option as shown in the figure below:

Add 'obj' to the ignored list

All obj folders in the current repository will be added to the ignored list. But, you can tell Plastic to add every obj folder in all your workspaces to the ignored list by selecting the Apply rules to all workspaces checkbox:

Add to the ignored list - All workspaces

Once the obj folders are added to the ignored list, all of the obj directories and their contents will be ignored. This means that Plastic SCM won't try to add them or try to find changes inside them.

If you repeat this process for the bin subdirectory, you'll see something like this:

All ignored files

You can add private items to the ignored list. An ignore.conf file will be created containing the ignored items.

If you add the ignore.conf file too to the ignored list, you'll avoid it to appear in the Pending changes view.


Modify a file

Let's start by performing a modification cycle on a file.

In this scenario we're going to modify the DokanNet.cs file, so let's run a checkout to edit the file as you've seen previously. Then, open it.

I'm going to modify line 119 and replace the DOKAN string with the DOKAN-NET one:

Modify file


Check the difference in the Pending changes view

We can go to the Pending changes view and see what we have modified so far:

Plastic SCM 'Pending Changes' view

As you can see, the Pending changes view lists the files you previously checked out. You can see a changed item too - the one that our IDE modified when we opened the solution.

If you click the Show diffs button, you'll see the line you previously modified:

Plastic SCM 'Diff' view

This action allows you to inspect the differences in every item prior to checking them in.


Making a checkin

If you agree with the changes made, you can now perform a checkin to confirm them. To do this, first enter a comment and then click the Checkin button. For example:

Plastic SCM 'Pending Changes' checkin


Show the Diff

If we go to the Branch Explorer to see the current state of the repository, you will see something like this:

Branch Explorer

In the branch, there are now three changesets:

  • The initial changeset.
  • One with the label Baseline00 on it.
  • The current changeset loaded on your workspace.

Now, right-click the current changeset.

  • In Windows:

    Click the Diff changeset action as shown in the figure below:

    Branch Explorer

  • In Mac OS:

    Click the Diff with previous action as shown in the figure below:

    Branch Explorer

  • In Linux:
  • Click the Diff with previous action as shown in the figure below:

    Branch Explorer

Once the option is clicked, you will see a comparison of the previous content with the current one in a new window. This window has three sections of information as shown in the figure below:

  • At the top - Information about the changeset and its author, and the comment you wrote upon checkin.
  • In the middle - The list of items being compared.
  • At the bottom - The diffs between the current changeset (number 2 or cs:2) and the previous (number 1 or cs:1) one.

Diff View


Lesson 3 - Moving, deleting and renaming

This lesson will teach you about file operations such as moving, renaming and deleting a file.

The goal of this lesson is to learn how Plastic SCM performs these common file operations and how it reverts to a previous revision using undo a change.


Moving a file

Let's take a look at how this simple operation is performed on files under the Plastic SCM control.

We will start with moving the file license.txt. To do this, right click the license.txt file and select the Cut option in the context menu:

Moving a file

We want to move the license.txt file to the \sample directory. To do this, we just paste the license.txt file in that directory using the Paste context menu option. After you perform this operation, this is how your Items view will look:

Items View

The Pending changes view shows what we've modified so far:

Pending changes View

The picture above explains the move you just performed: source and destination of the move plus the status sets moved.

You can now checkin the move. But, don't forget to write a comment to document what you did. For example, license.txt file moved to 'sample' directory.


Deleting a file

The next simple operation will be deleting a file that is under the Plastic SCM control.

To do that, simply right click the readme.txt file and select the Delete menu option as shown in the figure below:

Deleting a file

After clicking Delete, a dialog will display to enable you to choose whether you want to keep the file on disk or not:

  • In Windows:

    Delete confirmation

    If you just want to remove something from version control but you want to keep it in your disk (like a temporary file that you mistakenly added), select the Do not delete items on disk option.

    For this scenario, we will choose that option.

  • In Mac OS:

    Delete confirmation

    If you just want to remove something from version control but you want to keep it in your disk (like a temporary file that you mistakenly added), select the Remove item(s) from version control option.

    For this scenario, we will choose that option.

  • In Linux:

    Delete confirmation

    If you just want to remove something from version control but you want to keep it in your disk (like a temporary file that you mistakenly added), select the Remove item(s) from version control option.

    For this scenario, we will choose that option.

The Pending changes view will look like the figure below.

Pending changes View

Note that the file is listed twice:

  • One instance is Added - The status is Private (we decided to keep the file on disk).
  • Second instance is Deleted - The status is Removed (removed from version control).

If we now go back to the Items view, we will see that the status of the deleted file is Private as we've seen before. This means that the file is not under source control anymore and it is displayed without a customize icon and no entry in the Type, Branch or Changeset columns:

Items View

If you switch to the Pending changes view, you can now Checkin the deleted item. And don't forget to enter a comment to document what you did:

Checkin


Renaming a file

Renaming a file is actually equivalent to moving the file as you did previously. But a rename operation is just a move inside the same directory.

You can select a file and right-click to open up the context menu and select the Rename option as shown in the figure below:

Renaming a file

After clicking Rename, a dialog will display to enable you to introduce a new name for the selected item. For example, we can enter lic.txt as the new name:

Windows Dialog

Once the operation completes, the Pending changes view will look like this:

Pending Changes View

Please note that the status of the file is now moved. Plastic SCM knows the file was renamed as well.

You can now Checkin the moved item. And don't forget to enter a comment to document what you did:

Checkin


Undoing changes

At any stage, you may want to undo something. In this scenario, we are going to show you how to undo the changes you've made in your workspace.

We will start by modifying the file DokanNet\DokanNet.cs. First, checkout the file and edit it by doing the following:

Modifying a file

Now, save the changes and go to the Pending changes view to review what you have modified so far. You can click the Show diffs button to compare the previous content with current one. The diffs will look like this:

Show Diffs

After viewing the comparison, you noticed that you made a mistake editing the file and you need to un-edit it. With Plastic SCM, this is an easy step.

  • In Windows:

    To do this, perform any of the following actions:

    • In the Text diff view, you can go to every change you want to undo and click its "undo button" Undo every change. Don't forget to click the Save or Discard buttons to confirm or not the undo.
    • Or you can click the Undo changes button, in the toolbar, to undo all the changes done on every selected item. After clicking the Undo changes button, a dialog will open to Confirm the undoing changes:

      Confirm undoing changes

  • In Mac OS:

    Click the Undo changes button, in the toolbar, to undo all the changes done on every selected item. After clicking the Undo changes button, a dialog will open to Confirm the undoing changes:

    Confirm undoing changes

  • In Linux:

    Click the Undo button, in the toolbar, to undo all the changes done on every selected item. After clicking the Undo changes button, a dialog will open to Confirm the undoing changes:

    Confirm undoing changes


Lesson 4 - Transparent SCM

In this lesson, you will learn all about the Transparent Version Control Plastic SCM feature.

The Transparent feature eliminates the worry associated when moving or renaming files and losing the synchronization with the version control. With Plastic SCM, you can work with your files, change them, move them around, create new ones or even remove them if you want.

When you are ready to checkin your changes, just go to the Pending changes view. Plastic SCM detects all those actions and records them to the repository with a single click.


Intro to Transparent SCM

In the previous lesson, we've followed the checkout-edit-checkin workflow. Using this workflow you have to tell Plastic SCM that you are going to perform a specific operation on a file.

In these scenarios, we're going to use the very extended edit-checkin workflow, which was made popular by most open source version controls (SVN, CVS, Git and many others).

In Plastic SCM, we know it as transparent working mode because, as you'll see, Plastic SCM is able to detect everything you've done in your workspace and propose it for checkin.


Finding changes

Let's open the DokanNet\DokanNet.cs and DokanNet\DokanOperation.cs files in our IDE tool, but don't check them out.

Modify the DokanNet\DokanNet.cs file by deleting line 149:

Modifying a file

And modify the DokanNet\DokanOperation.cs file by uncommenting the range from line 43 to line 49 as follows:

Modifying other file

Go to the Pending changes view to check what we have modified. As you can see, the Pending changes view is detecting the files you've modified. Because we didn't check them out prior to edit, you can see that the status value is Changed instead of Checked-out:

  • In Windows:

    Pending Changes View

  • In Mac OS:

    Pending Changes View

  • In Linux:

    Pending Changes View

Checkin the changed files. And don't forget to enter a comment.


Move a file and let Plastic SCM detect it for you

The next operation we will perform is moving a file in your workspace and let Plastic SCM detect it.

We're going to move the lic.txt file from the sample\ folder to the root one. Let's do this operation outside of Plastic SCM, for example, using the Windows Explorer. Remember that this operation involves both the move and rename operations.

Now, open the Pending changes view. You can see how the move you have just done is detected by Plastic SCM and the status is Moved locally. Please note the Similarity column. This column shows the percentage of similarity. Plastic SCM tries to match moved items with private items to determine if it's the same item. Only locally moved items have value in this column:

Move a file and detect it

Please note the Similarity value is 100%, so it is the same file.


Move a modified file

What if we now decide to move one file previously modified? Will Plastic SCM be able to detect it?

First, we're going to modify the DokanNet\DokanNet.cs by adding a new line. But, as we did before, we're not going to check it out:

Change a file

Let's see what happens when we move the changed DokanNet\DokanNet.cs file to the DokanNet\Properties directory. To do that, we just open a Windows Explorer and move the file. Once the move is done, this is what the Pending changes view will look like:

Move a modified file

Here is an explanation of the move you just performed:

  • Status is set to moved locally.
  • Similarity is set to 99,49% because you modified the file previous to moving it. And Plastic SCM is able to detect it as the same file because the content matched at 99%.

Delete a file

What happens when you delete a file?

Let's see what happens when we delete the DokanNet\Proxy.cs file. After you open Windows Explorer and delete the file, the Pending changes view will look like this:

Delete a file

Now, look at the status column. You'll see that it is now set to Removed locally which means that the controlled file was deleted from the workspace outside Plastic SCM (as we have done).


Detecting moved directories

We are now going to move a directory. For example, let's try moving the RegistoryFS folder from the sample directory to the DokanNet one. To do that, open Windows Explorer and move the directory. The Pending changes view shows what we've modified:

Moved Directory

Here is an explanation of the move you just performed:

  • Status is set up to Moved locally.
  • Similarity column contains 100%.

As you can see, Plastic SCM identifies and displays only the directory that was moved instead of displaying all files inside as moved.


Check in

At this point, you can now checkin all the changes, but don't forget to include a comment when you checkin all items (deleted and moved) to document what you did:

Check in


Check the differences

Let's go to the Branch Explorer to see the current state of the repository:

Branch Explorer

Go ahead and right-click the current changeset.

  • In Windows:

    Click the Diff changeset button as shown in the figure below:

    Diff Changeset

  • In Mac OS:

    Click the Diff with previous button as shown in the figure below:

    Diff Changeset

  • In Linux:

    Click the Diff with previous button as shown in the figure below:

    Diff Changeset

Once the button is clicked, you will see a comparison of the previous content with the current one. And, the diff will look like this:

Diff View

As you can see, there are several diffs and you can show each of them by clicking the arrows.


Lesson 5 - Working on branches

In this lesson, you will learn all about branches. Branches offer a way to isolate different lines of development from each other, often called Parallel Development.


Why should I create branches?

There is a concept that is very fundamental to source control and it is called branching.

The basic concept of a branch is a line of development that exists independently of another line and shares a common history. A branch always begins its life as a copy of something and moves on from there generating its own history.

Branching is a very efficient process. You can easily work with feature branches or go even further and use task branches, the model that Plastic SCM recommends.

Plastic SCM implements task-driven development very efficiently through the well-known branch per task pattern. You can read more at the following links:


Creating a "baseline"

What's a baseline? Very simply it is a label. Do you remember? We've seen at the beginning of this tutorial.

It's a snapshot of your code at a given point in time. It's a mark, a tag that you can use to rebuild this status later if you need to.

To create a label, open the Labels view in the Other actions left action bar:

Creating a baseline

Your Labels view will look like this:

Labels view

  • In Windows:

    Click the Create new label button.

  • In Mac OS:

    Right-click the Labels view and select the Create new label option:

    New label action

    In Linux:

    Right-click the Labels view and select the Create new label option:

    New label action

After clicking it, a dialog will appear to enable you to enter the name for the new label. In this example, I'll enter Baseline01 for the name and a comment as shown in the figure below:

New label

Please note the Changeset to label field. It tells Plastic SCM where the label is applied. The default value is the current changeset loaded in the workspace. In my case, the changeset is number 7.

Now, we've got another label to mark a stable release in our project. Once the label is created, our Branch Explorer will look like this:

Branch Explorer


Your first branch

Now, let's go to the Branch Explorer to create our first branch.

Remember that the current changeset loaded in your workspace is represented with a house on it. Right click this changeset and click the Create branch from this changeset action as shown in the figure below:

Creating a branch

Once the action is clicked, a New branch dialog will display. Enter scm001 for the branch name and a comment as shown in the figure below:

New branch

The Plastic SCM team works with the Branch per task model. This means that every development task is a new branch.

At the bottom of the window there is a checkbox called Switch workspace to this branch. Select this checkbox to start development in the new branch.


Making some changes in the branch

Now, let's go to the Branch Explorer and check the current state:

Current state

Select the new branch and then click the Options button in the toolbar. On the right side, you will see the properties of the branch as shown in the figure below:

Properties of the branch

Let's now make some changes to the branch.

Let's go to the Items view where we are going to add the readme.txt file. To do this, right-click the file and then select the Add to source control option:

Add a file

The file is now added and checked out:

Items View

Go to the Pending changes view and checkin the change to confirm the added file:

Items View

Now, let's modify the readme.txt file by adding a line at the beginning. First, you checkout the file and then you open it, by double-clicking it or by right-clicking the file and selecting the Open action.

Let's now go to the Pending changes view and check what we have modified:

Pending Changes

You can now enter a comment and checkin the change.

Let's go to the Branch Explorer to check our new branch. As you can see in the picture below, we have two changesets in the scm001 branch: the first one we created when we added the readme.txt file, and the second one with the latest change:

Current Branch

Now, we are going to do a new change in the branch. Let's go to the Items view, checkout the lic.txt file, and open it to modify it by deleting the lines 10 and 11:

Modifying the file

Now, let's go back to the Branch Explorer. What is that on the graphic? Can you can see a "house" with a dashed circle outline? This is the icon for the checked-out changeset:

Branch Explorer

The house with dashed circle means:

  • It will be the next changeset.
  • It is pending to checkin.

Now, go to the Pending changes view to see what we modified. Write a comment and run a Checkin:

Pending Changes

If we go back to the Branch Explorer, we can see the current state of the current scm001 branch:

Branch Explorer

What have I done? Well, I performed several checkins in the scm001 branch to hold all the changes. If you checkin often, it will be easy for you to understand all the changes. This means that you are self-documenting the code.

In the traditional model, you must write documentation. And good documentation is hard to find. That's why it's so great to see that this documentation is generated as I go along.

You can read more about it at the Self documented development through inch-pebble checkins blog post.


Lesson 6 - Merging the changes

We all fear and, at the same time, love merging which is an essential process that a good version control expert must master.

In Lesson 5 we covered how to work on a main branch, how to create new branches, switch to them, and make changes to them.

Now, you are ready to merge them and this lesson will show you how the merge process works.


Creating another branch

Let's go to the Branch Explorer and check the current status. We are in scm001 branch but let's go back to the main branch. To do that, right-click the main branch and click the Switch workspace to this branch as shown in the figure below:

Switch workspace to this changeset

After you confirm the operation, you will see something like this:

Current changeset at main branch

The current changeset has come back to the main branch.

Now, we're going to create another branch from the last changeset on the main branch. These are the steps to complete:

  • Right click the current changeset, and click Create branch from this changeset.
  • Write a branch name, for example:scm002 (for task002).
  • Click OK.

Now, your Branch Explorer will look like this:

Branch Explorer

Now, let's go to the Items view. We are going to modify the lic.txt file by adding a new line at the top. So we're going to checkout the file and add the new line. In the Pending changes view, you can see this modification:

Pending Changes

Now write a comment (for example, Added new line) and run a Checkin.

We can now go back to the Branch Explorer to see the current state of the workspace:

Pending Changes


First merge

First, let's return to the main branch. To do this, right-click the branch and then select the Switch workspace to this branch options as shown in the figure below:

Switch workspace

Now, let's merge the scm001 branch back to the main one. The Branch Explorer before the merge will look like this:

Branch explorer

Now, right-click the scm001 branch and select the Merge from this branch option. You will see something similar to following:

Merge from this branch...

Once the action is performed, the Merge from this branch view will look like this:

Merge view

Please note the column marked:

  • Changes only in source contributor - There are changes only in the source contributor. This means that these changes are only in the scm001 branch.
  • Added on source - The item was added in the scm001 branch.

Click the Process all merges button at the top of the toolbar and the merge will be processed as shown in the figure below:

Process all merges

So, we did our first merge. There aren't any merge conflicts. And now, the main branch contains the changes made on the scm001 branch.

Now, let's go to the Branch Explorer to see the current status of the workspace:

Branch Explorer after merging

In the figure above there are two new things to note:

  • Checked-out changeset - The changeset with the "house" and the dashed circle outline.
  • Pending merge link - The dashed green line with an arrow at the end.

So, what does it mean? We did a merge from the scm001 branch to the main branch so a new changeset is going to be created after the checkin action. Now let's go to the Pending changes view:

Pending Changes

As you can see in the figure above:

  • The branch, where you are going to checkin, is the main branch.
  • The status is Replaced (we modified an existing file) and Copied (new) (we added a new file).
  • Both changes come from changeset 10.
  • It reminds you that there is a pending merge to checkin.

You can now Checkin the changes from the merge. Don't forget to write a comment like: Merge from scm001 branch to main branch to document what you did.


Merge back to "main"

Now, let's go to the Branch Explorer to see the current status of the repository:

Branch Explorer

Now, let's perform a merge from scm002 branch to main branch. Right-click the scm002 branch and select the Merge from this branch option:

Merge from this branch

Once the action is done, you'll see how the merge from the scm002 branch to the main one is. Let's see the Merge from branch view:

Merge Branch View

As you can see, there are two columns marked:

  • Remarks - Shows a short description of the conflict for each item. In this case, there are changes in both source and destination contributors.
  • Contributor - Displays the actions that will be run when the Process all merges button is clicked.

If you want to dig deeper to learn more about the merge, click the Explain merge button at the top in the toolbar. The Merge explanation view will look like the following:

Merge Explanation

From the information provided by the figure you can really see how the merge works. There are 3 important terms:

  • Source (src) - Shows the revision you are merging from (scm002 in this case).
  • Base - It's the initial revision (Baseline01 in this case).
  • Destination (dst) - Shows what you have right now in your workspace. A new changeset will be created on the main branch. It will contain the merge result.

Return to the Merge from branch... view and click the Process all merges button to start the process. Once the merging completes, the Branch Explorer will look like this:

Branch Explorer

There is a new changeset pending to checkin so let's go to the Pending changes view and check what we have modified.

As you can see, the Pending changes view lists the file you previously merged. If you click the Show diffs button, you'll see the line you've modified:

Pending Changes

You can inspect the difference prior to the checkin merge operation to ensure that the code has been correctly merged.

Then, enter a comment (for example, Merge from scm002 branch to main branch) and then click the Checkin button.


Test in baseline

Now, let's go to the Branch Explorer to create a new baseline. Right-click the current changeset and click the Label this changeset action and the New label dialog will appear. Enter Baseline02 for the label name and enter a comment:

Create a Label

Once the label is created, your Branch Explorer will look like this:

Merge + Label

Baseline is defined as a line that forms the base for any construction, comparisons or calculations. The objective of a baseline is to reduce a project's vulnerability to uncontrolled change by fixing and formalizing change by controlling critical points in the development life cycle.

You're now in the right place. Baseline02 is where you would make up the Unit Tests that can help you ensure the code quality.


3-way merge: Manual conflicts

Let's now go to modify exactly the same section of code in the same file.

We're going to create two new branches.

Go to the Branch Explorer and right-click the current changeset. Then, select the Create branch from this changeset option and enter scm003 as the branch name and add a comment:

New branch

You'll get the same result if you right-click the main branch and select the Create child branch.

Now, we're going to modify the DokanNet\Properties\DokanNet.cs file by adding new lines at line 117. First, checkout the file.

Let's go to the Pending changes view and check what we have modified:

Modifying a file

You can now run a Checkin action. But don't forget to write a comment (for example, Adding new conditions on DokanNet.cs file to document what you did.

Now, let's go to the Branch Explorer to see the current status of the repository:

Branch Explorer

Then, return to the main branch. To do that, right-click the main branch and select the Switch workspace to this branch action as shown in the figure below:

Switch workspace to this branch

And now, we are going to create the second new branch from the Baseline02 label.

First, we go to the Branch Explorer, right-click the current changeset and select the Create branch from this changeset option. Enter scm004 as the branch name and add a comment:

New branch

We're going to modify the same DokanNet\Properties\DokanNet.cs file by adding new lines also at line 117. First, checkout the file and add the lines.

Now, let's go to the Pending changes view and check what we have modified:

Pending Changes View

Don't forget to write a comment (for example, Adding new lines on DokanNet.cs file) and run a Checkin operation.

Now, let's go to the Branch Explorer to see the current state of the workspace:

Branch Explorer

Let's return to the main branch by right-clicking the main branch and then selecting the Switch workspace to this branch action as we did before. So, the current state of the repository will be something like the following:

Main Branch

Remember, that we modified exactly the same section of code in the same file. This action makes the merge much more complicated.

To perform this merge, we are first going to make the merge from the scm003 branch to the main one. And then, we are going to merge from the scm004 branch to the main branch.

Let's start by going to the Branch Explorer and right-clicking on the scm003 branch and then clicking on the Merge from this branch option. Once this action is done, the Merge from branch... view will show something like this:

Process all merges

As you can see, there are changes only in the source contributor. We can click the Process all merges button and merge will run automatically.

Go back to the Branch Explorer to check the current state of the workspace:

Switch workspace

There is a new pending merge link so let's go to the Pending changes view. Don't forget to write a comment (for example, Merging from scm003 to main) before running a Checkin action:

Pending changes

Let's go to the Branch Explorer to see the current state of the workspace:

Branch Explorer

As you can see, the scm003 branch is merged.

Now, we're going to follow the same steps to merge the scm004 branch.

In the Branch Explorer, right-click the scm004 branch and select the Merge from this branch action. Once this action is done, the Merge from branch... view displays. At this point, click the Process all merges button and the Mergetool window will appear:

Mergetool

In the figure above, you can learn more about how the merge works by referring to these four important terms:

  • Source (src) - Shows the revision you are merging from.
  • Base - It's the initial revision.
  • Destination (dst) - Shows what you have right now on your workspace.
  • Result - Displays how the revision on your workspace will be once you finish the merge.

Each one of them has different color to help you better understand the merge process.

On the left side, you can see the code I added in the scm003 branch (source). On the right side, you can see the code I added in the scm004 branch (destination). At the bottom, you will see the final result with both contributors.

Under these circumstances, the tool will always prompt the user. It will still save you precious time because it directly focuses you on the problem, but you'll have to make the decision yourself.

In my case, I agree with Destination. So click Deselect Source, and you'll see something like the following:

Merge tool: destination, source...

As you can see, the result file has a background in green like the Destination code selected and the non-automatic conflict has been reviewed by you.

If you agree with the result, click the Save and Exit button at the top of the toolbar.

Now, let's go to the Branch Explorer to see the current state of the workspace:

Branch Explorer: pending merge

In the Pending changes view, we can check what we modified. Remember to write a comment before you perform a Checkin:

Pending changes

You can now compare the two merges we have performed:

  • If only one contributor changed the code, it's an automatic conflict.
  • If both contributors changed the code, it's not trivial and merge tool will ask you.

3-way merge vs 2-way merge

What's 3-way and 2-way merge?

In the last scenario, we saw a 3-way merge. This involved modifying the same file in the same place in two different branches. The result file is the one created after the changes are combined, and you decided which would be the final code.

A 2-way merge is easier to explain because it doesn't consider the base file (also known as common ancestor) to calculate the merge.

So, let's go back to the DokanNet\DokanOperations.cs and make a couple of very simple changes then we will try to merge the code with a 2-way merge tool. Check out the results in the figure below:

2-way Merge

  • The 2-way merge doesn't know whether I added the line or you removed it so it cannot make a decision on how to solve this conflict automatically.
  • A 3-way merge tool however would automatically solve the conflict because it knows what the original file was based on (the base file). That is why Plastic SCM only uses the 3-way merge tool.

Learn more about merge by reading the following documentation:


Last updated

Jun 01, 2016
  • Now you can read the updated Step-by-step tutorial.