Plastic SCM - Gluon guide


Introduction

Gluon is a tool designed for users who typically work on a single branch with files that can't be merged (typically, binaries such as images, animations, or documents). These users usually coordinate teamwork collaboration by locking file access. Repositories are normally huge and include very large binaries.

The typical users of the tool are artists involved with game development teams. However, the tool is not restricted to only game teams.

Here are a few scenarios that might help you decide whether Gluon is a good fit for you and your team:

  • As a user, I will select the files I will work on, make changes, and quickly submit them. I don't ever want to deal with merging or branching files either. Those functions should happen automatically in the background.
  • As a user, I want to lock files so nobody can work on them simultaneously as me.
  • As a user, I don't want to be forced to download a file repository containing tons of huge files to access the one or two files that I need to work on. I should be able to select only the files I want to work on and download those.

Plastic Gluon


Configuring Gluon

Important!

Before running Gluon, you must configure the locking system function. To do that, the server file, lock.conf must be correctly set up. The lock.conf file allows you to lock files upon checkout, preventing others from modifying those files while you are working on them. By controlling file access in this way, you avoid merging files that can't be merged.

For additional information, read how to create and configure the server lock.conf.

To use Gluon for the first time, you must create your first workspace by configuring the Plastic SCM server (IP address or Name). If you need help with this setup, we recommend that you consult with your sysadmin.

This server configuration step usually only takes a few minutes to complete:

Configuring Gluon

Once you have secured the IP address and port for the server by asking the sysadmin or scanning the network, click Connect. The server will then detect the user-authentication mode and begin the process of connecting you to the server by prompting you to enter the following information:

  1. Verify that your username is correct, then enter your password (if applicable). If your username is incorrect, click Check, and the server will allow you to choose your username from a list.
  2. Enter a repository name or use the Choose button to select one from a list.
  3. Once you select a repository, a location for the working directory (workspace) will be automatically displayed. You can enter another location, or use the Choose button to select one from a list.
  4. Once all information is entered, click Apply.

The configuration is now complete, and you are now ready to start working with Gluon.


Configuring the workspace

A workspace is your working directory that will contain the project files you create, modify, delete, and so on. To start configuring your workspace:

  1. Click Open in the Workspace Switcher view:

    Workspace Switcher view

    You will see an empty folder/directory like the one below (with 0 bytes size):

    Explore workspace

    You can now select the files you want to work on by selecting them from the repository.

  2. Click the Configure button. In the Configuration Mode view window, you can view all the items in the repository stored on the server:

    Configuration mode view

    This is a super cool feature because the Configuration Mode view allows you to select (load) or deselect (unload) the files or directories (items) that you want to work with so that you don't have to load the whole repository. You can also see the size for every file/directory.

  3. To select the items you need, check the boxes of those items, and they will be loaded into your workspace:

    Configuration mode view - Load items

    In this example, we will select only the blue + 256 files inside the Tanks and Soldiers folders as well as the complete Enemies and Misc folders.

    • Use the Search files dialog to select files and group of files. Open the Search files dialog, enter the file name or a pattern (*.jpg, *.psd, etc) in the search text box and then toggle (load/unload) all the search results:
      Configuration mode view - Load items
    • Pro tip: Use Ctrl+A/Cmd+A to select all the nodes in the tree, and then use the space bar to toggle the load/unload status.
  4. Once those items are checked, click the Apply button to load these items into the workspace:

    Workspace - loaded items

If you prefer, you can use the command line to configure your workspace. For our example above, run the cm partial configure command with the following notation:

cm partial configure +/Enemies +/Misc +/Soldiers/soldier_blue_01_256.png +/Tanks/tank_blue_01_256.png

This example will load the complete Enemies and Misc folders and the blue_01_256.png soldier and tank pictures.

You can change the configuration at any point by downloading new items or unloading them from the workspace by clicking Configure again.

All of the loaded items have the Controlled status, which means that they are under version control.

For each selected item in the workspace window, you can:

  • Preview the file
  • View the file details
  • View the file history.

You can configure the maximum file size to generate at the preview of a file when that file is not loaded in the workspace (Configuration mode). To do so, add the following key to your client.conf file:

<MaxPreviewFileSize>1048576</MaxPreviewFileSize>

The default value is 1 MiB (1048576 bytes). This means that if the selected, non-loaded file size is more than 1 MiB, it won't be downloaded to generate its preview. But, you will still be able to see its icon, if any, its size, and its attributes.


Workspace view modes

You can configure the Workspace view to show your loaded items in two different ways:

  • Tree mode.
  • List mode.

By default, the Workspace view appears in a directory tree mode.

To change the view mode, right-click anywhere on the workspace view and select the View as a list option:

Gluon - Workspace - View as a list

And you will see something like this:

Gluon - Workspace - List view

To go back to the tree mode, right-click again and select the View as a tree option.


Manual and Automatic modes

Gluon has two modes, depending on whether you specify files within the parent folder or select the complete parent folder.

However, when you select some of the files (children) in a parent folder, Gluon identifies the folder as Manual Mode. When you select the complete parent folder, Gluon identifies the folder as Automatic Mode.

As we'll see later, the Manual and Automatic modes will determine how Gluon treats the folder during updates.


Unloading items

As you saw in the example, Gluon lets you configure your workspace any time by enabling you to load and unload items with a simple mouse click.

If you don't need the Misc folder for your current project, unload it from the workspace. This will reduce the number of files in your workspace. Open the Configuration Mode view so that you can choose the repository items that you want to remove from your workspace:

Configuration Mode - Unload items

As you can see in the above image, the Misc folder is loaded as seen by the black square in its checkbox; a black triangle indicates that the folder is partially loaded.

To unload a loaded folder, you must complete two simple steps:

  1. Uncheck the Misc checkbox to remove the black square. A red square will replace the black square, and the folder name text will turn red, and the word unload will appear next to the folder name:

    Unload items

  2. Execute the unload action by clicking Apply. Your workspace will refresh, and the Misc folder will be removed from the folder list:

    Workspace - unloaded folder

Or, you can run the following CLI command to unload the Misc folder:

cm partial configure -/Misc
Important!

If you unload a folder that contains private or ignored items, Gluon won't delete them.
This is for a security reason: We can't remove items outside Gluon's control.


Workspace information

Options in the directory sizes

As you've seen in the previous screenshots, you can see the directory sizes both in the Explore workspace and the Configure views.

In the Explore workspace, you can choose whether to exclude or include the private items when calculating the directory sizes:

Explore workspace - Exclude/Include private items from directory size

If private items are excluded, the size of the private files will still appear in the Workspace Explorer view. However, the private directory sizes will not be calculated, and all private items will be discarded when calculating controlled directory sizes.

The update report

The Show update report button lets you see a list with all the updated items. For update or partial update operations, the report contains all the changed, added, deleted and moved items. For apply configuration operations, loaded and unloaded items are listed. This report looks like:

Explore workspace - Update report

The Show update report button appears for the first time when an Update or apply configuration operation is performed. You can clean this report or hide it.


Locking your files using Checkout

By this point, you have loaded all of the files that you will need in your workspace. Now, it's time to modify them.

To ensure that other users will not edit the same files as you, Gluon provides the Checkout feature. By checking out the file, it is locked so that only the person that checked out the file can edit it, and it is not available to others until it is checked back in. Once you have selected the files that you want to checkout, right-click any one of them and select the Checkout option from the submenu:

Checkout files

The files you select will lock and nobody can edit them until you check them back in. Once you have checked out the files, those files are marked with a new icon, the Last edited field will change from root to your user name (in this case Maria), and the status of the file will change to Checked-out (unchanged):

Checked-out files

The new Checked-out (unchanged) status visually indicates that the file has been checked out or locked by you, but no changes have been made yet.

You can also checkout or lock the selected files by running the following command:

cm partial checkout c:\Users\maria\wks\battlegame\Enemies\enemyGreen1.png c:\Users\maria\wks\battlegame\Tanks\tank_blue_01_256.png The selected items are about to be checked out. Please wait ... Item c:\Users\maria\wks\battlegame\Enemies\enemyGreen1.png was correctly checked out Item c:\Users\maria\wks\battlegame\Tanks\tank_blue_01_256.png was correctly checked out

You are now ready to edit the files by dragging and dropping them into an external editing tool. The files are locked, so nobody but you can edit them.


Force the lock and checkout

To force the lock before the checkout, you can use the Lock and checkout option:

Lock and checkout

This option ensures that an appropriate lock rule for the selected file exists in the server for the repository.

If it doesn't, and you want to lock and checkout a controlled file, a new dialog displays. There, you can add the new lock rule that will be added to the repository in the server:

Add lock rule and checkout


Checkout recursively

If you need to lock all of the files in a folder, select the folder, right-click it and then select the Checkout recursively option from the submenu:

Checked-out recursively

You can also run the recursive checkout from the command line:

cm partial checkout -R c:\Users\maria\wks\battlegame\Soldiers

All the items in the folder are checked out (locked), so you don't have to select each file. The result is the same as we saw before; Every file has a new icon, the Last edited field for every file in the folder changes from root to your user name (in this case, Maria), and the status of every file in the folder changes to Checked-out (unchanged):

Checked-out recursively


Saving your changes to the server

When you're done editing your files using the external tool, after refreshing the workspace view, notice the status of the edited files has changed from Checked-out (unchanged) to Checked-out (changed):

Checkout (changed) files

This means that your locked files were edited, and those changes were saved locally but not on the server.

To save the changes to the server (add the changes to the repository in version control), click the Checkin changes tab. In this new window, you'll see the files you've changed, and by default, all of them are marked to be checked-in. Now, write a comment to identify the changes associated with those files and click Checkin:

Checkin changes

Once the Checkin operation is complete, you can go back to the workspace view (by clicking the Explore workspace tab). You'll see that the status of the checked-in files is now Controlled, indicating that the files were checked in successfully. Also, the history view displays the new changeset:

Checkin changes successfully

You can also perform a checkin operation from the Workspace view. To do this, select the required items, right-click them, and select the Checkin option. This option will open the Checkin changes view on the right side of the view.

And, of course, you can checkin your changes from the command line by running one of the following:

  • Specify every item you want to checkin: cm partial checkin c:\Users\maria\wks\battlegame\Enemies\enemyGreen1.png c:\Users\maria\wks\battlegame\Tanks\tank_blue_01_256.png -c="Edited pictures."
  • Or, checkin all the pending changes in the workspace: cm partial checkin -c="Edited pictures." --applychanged

You've done your first changes, and they are now saved on the server.

You may have noticed a panel below the History view where you can always read the comment that was entered during the checkin process. The comment shown corresponds to the comment of the selected revision in the History view. If no selection is performed, the comment for the loaded revision is shown. With this panel, you don't have to scroll through the History view horizontally to read the comment.

The Checkin Changes view includes a Checkin comments button that allows you to quickly fill the checkin comments text box with the previous changesets' comments:

Checkin comments button


But are the files really locked?

Maria has made changes and checked them in, but she realizes that she forgot to add one change to the tank_blue_01_256.png file. So, she checks it out again, and, at the same time, her teammate John wants to check it out as well.

Maria get there first so her workspace looks like this:

Maria's workspace - Checkout file

Let's go to John's workspace. He loads the folder HQ and some files from the Tanks folder. One of the files is the tank_blue_01_256.png picture. In the History view, John can see that the picture was modified a few hours ago by Maria and was checked in; so as far as he knows, the file can be edited:

John workspace

John goes ahead and tries to initiate a checkout, but he gets an error message indicating that Maria has checked out the file:

Error - file is locked

If John tries to run the checkout from the command line, he will get the same message:

cm partial co /Tanks/tank_blue_01_256.png The selected items are about to be checked out. Please wait ... These items are exclusively checked out by: /Tanks/tank_blue_01_256.png (wk:battlegame owner: maria)

Gluon prevents John from editing the file while Maria is working on it. Upon closer inspection, John can see that the file status is Locked by 'maria'.

Note: Gluon always shows you the current status of every item (file or directory). Use the Refresh button.

Maria decides to keep the file locked for the rest of the day because she has some additional changes to apply. She can save the changes to the server and keep the file locked by simply selecting the Keep items locked option.

She makes the changes, adds a comment, selects Keep items locked, and clicks Checkin to save her changes while John finds something else to work on:

Keep items locked

You can also keep an item locked from the command line. Just run a checkin command and add the --keeplock option:

cm partial checkin -c="Lighter shadow" --applychanged --keeplock

After the checkin operation is performed, you can see the latest changes saved to the server. And in the History view, you will see that Maria created a new changeset. Because she selected the Keep items locked option, the file still has a checked-out (now unchanged) status. This ensures that the file remains locked until Maria no longer needs it:

Keep items locked - New changeset

So now John, after doing a Refresh to his workspace, will see that the file is still locked and that it is Out of date, so he will wait patiently until the file is unlocked:

Out of date - Locked by

After a couple of days, Maria is finally ready to checkin the file and unlock it (by deselecting the Keep items locked option). This way, other users can make their changes. But the file status was Out of date, so let's look at what that means in the next section.


Working with the latest stuff

Before performing a Checkout action on a file or a group of files, you must ensure you have the latest revisions in your workspace.

John has been waiting patiently to make changes to the tank_blue_01_256.png file. It is unlocked, but it hasn't been updated yet in John's workspace.

Here is what John's workspace looks like right now. If he refreshes the Explore Workspace view, he will see that the file he needs to modify is out of date:

John's workspace - Out of date

The reason it is outdated is that Maria made some changes to it. By the time John can work on it, the file displays in John's History view as the old one that was loaded in his workspace previously (changeset 3). So John has to get the latest version of this file into his workspace by running the Update option from the submenu:

John's workspace - Update out of date

You can also run the update option from the command line:

cm partial update c:\Users\john\wks\battlegame\Tanks\tank_blue_01_256.png

By performing the update, John loads the latest revisions of the file into his workspace (check the History view). Now that the file is updated (status is Controlled and the latest changeset is loaded), he can now do a checkout:

John's workspace - Updated


Can an out-of-date item be checked out before it is updated?

The short answer is NO. And John does not have to worry about it. If he tries to checkout an out-of-date item, Gluon will display an error message indicating that the file is not up to date in his workspace.

Let's look at an example.

John wants to modify and check in the enemyGreen1.png file to the server. But, he first must load it into his workspace as we saw previously:

John's workspace - Loaded file

Remember how to load the item from the command line:

cm partial configure +/Enemies/enemyGreen1.png

John can now check out the file and make the modification (add a grey center point). After completing this change, he checks in the file, which results in a new changeset (changeset 6), as you can see in the History view:

John's workspace - New changeset

Maria now realizes that she has to make a change to the same file. So, she tries to perform a checkout, but receives an error message indicating that the file is not up-to-date in her workspace:

Error when checking out an out-of-date file

Maria will see the same error if she runs the checkout from the command line:

cm partial co c:\Users\maria\wks\battlegame\Enemies\enemyGreen1.png The selected items are about to be checked out. Please wait ... The file '/Enemies/enemyGreen1.png' requires exclusive checkout, but it is not up-to-date in your workspace. To avoid merge conflicts, please update your workspace and try again.

If Maria had looked at the History view, she would have seen a newer revision of the file, updated by John. She forgot to update the file in her workspace, so she received the error. If she clicks the Refresh button, she will see that the file in her workspace is out-of-date:

File out of date

Note: Remember always to check the status of the file. If it is out of date, you must get the latest version before checking out a file.


You can update only what you need

After Maria changed the enemyGreen1.png file in her workspace, she also made some changes to the tank_blue_01_256.png image. She checked-in these changes, so newer versions of both files were created.

John has decided to edit the enemyGreen1.png file, but as you can see in his workspace, the file is out-of-date because Maria just checked it in after making her changes:

Files out of date

Since John is only concerned with the enemyGreen1.png file, he will need to perform an update (by selecting Update from the submenu) to checkout the file. After he performs the update, his workspace now shows that the enemyGreen1.png file is updated and loaded, however, the tank_blue_01_256.png picture still is out-of-date:

Updated and out of date files

John can now perform a checkout on the enemyGreen1.png file and make the changes he wants. Once he is finished, he has to check in the changes and save them to the server (repository):

Checkin updated file

After saving the changes to the file, John's workspace updates, but the tank_blue_01_256.png file is still out-of-date. As you can see, Gluon enabled John to perform a checkin of the changed files even though there were files that were not updated in the workspace:

Checked-in and out of date files


How do you update the whole workspace?

You may have noticed that there is an Update workspace button in your Explore workspace view:

Update workspace button

Clicking this button delivers the same result as selecting Update from the submenu but, instead of updating a specific file, the complete workspace (all files) will update so that none will be out-of-date.

You can perform an update workspace operation from the command line by running the following:

cm partial update

Manual and Automatic modes - Update

As we learned previously, folders loaded into the Gluon Configuration Mode view are identified as either Manual Mode or Automatic Mode.

The mode assigned to each folder determines whether new files added to the folder will download into your workspace or not.

  • If a folder is identified as Manual Mode in your Configuration Mode view, it means you selected some of the files in the folder. When new files are added by someone else, the new files will not automatically download into your workspace during an Update action.
  • If a folder is identified as Automatic Mode in your Configuration Mode view, it means you selected the complete folder. When new files and directories are added by someone else, the new files and directories will automatically download into your workspace during an Update action.

Undoing the checkout

If John performs a checkout to add new changes to the enemyGreen1.png file, the status of the file becomes Checked-out (unchanged):

Remember how to checkout the file from the command line:

cm partial checkout c:\Users\john\wks\battlegame\Enemies\enemyGreen1.png

John's checkout

If he opens the file using his favorite editor, modifies it, and saves the changes, he needs to click the Refresh button to see the status updated to Checked-out (changed):

John's file - checked out and changed

Unfortunately, John realizes too late that he was not supposed to make the change because he did not get the actual requirement from the Project Manager. So now he needs to undo what he did. Luckily, Gluon makes this very easy.

All John must do is right-click the file that he needs to undo, and the following submenu will open:

John's workspace - Undoing checkout

By selecting the Undo checkout option, Gluon displays a warning message indicating that all the changes done on the file will be discarded. By clicking the Yes button, the undo operation will remove John's changes, and the file will restore as if nothing was ever done to it:

John's workspace - Undoing checkout

Run the following command to undo checkout from the command line:

cm partial undocheckout c:\Users\john\wks\battlegame\Enemies\enemyGreen1.png

This operation can also be performed from the Checkin changes view by first selecting the files you want to undo and then clicking Undo:

John's workspace - Undoing checkout

And you can get the same result by running the following command:

cm undochange Enemies\enemyGreen1.png

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.


Undoing the changes

John can change the files by editing them using his favorite image editor and without performing a checkout action.

If John changes the file without checking it out, the file will have a new status, Changed:

John's file - changed

Gluon offers John the Undo changes action to go back and discard the changes he applied:

John's file - Undo changes

John can run the following command to undo the changes:

cm undochange Enemies\enemyGreen1.png

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.


Find the image differences

The team's Project Manager sent Maria the new design requirements to implement in the soldier_blue_04_256.png file. After loading the file in her workspace, she can perform the changes.

After completing her updates, she wants to show her colleagues the changes she made to the image. To do this, she can explain all these changes by, for example, reading the comments added on every check in action she performed. But, she thinks it might be better to show them graphically, which is a function supported by Gluon. So, let's take a look.

In the History view, she can see all of the changes that were made to the file.

  • If she only wants to see the differences between the revision loaded on her workspace and the previous one, she will follow one of these actions:
    • In the Workspace view, right-click the changed file and select the option Diff with previous revision from the submenu.
    • In the History view, right-click the last change and select the option Diff with previous revision from the submenu:

      Diff with previous revision

    Or, she can run the following command:

    cm diff Soldiers\soldier_blue_04_256.png

    Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.

    When she selected the option Diff with previous revision, a Side-by-side Diff Tool window opened and displayed the two images. In this window, she can see the differences between the images of the two selected revisions (changesets). On the right, it is the last revision. And on the left side, it is the previous revision. The changeset version will display in the caption above each image. She can also display the properties of each image so that she can see the differences between the last and the previous revision:

    Side-by-side Diff Tool

  • Now, Maria wants to show her colleagues how the first revision compares to the latest one. So, she selects both revisions from the History view, right-clicks, and selects the Diff selected revisions from the submenu:

    Diff selected revisions

    Or, she can run the following command:

    cm diff Soldiers\soldier_blue_04_256.png#cs:1 Soldiers\soldier_blue_04_256.png#cs:10

    Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.

    Gluon will then launch the Side-by-side Diff Tool and display the differences. Maria's colleagues can now see how the first revision looked compared to the last revision. By choosing the Swipe option, she can use the scrolling action to clearly show the differences in a split view:

    Side-by-side Diff Tool - Swipe

Find information about the Side-by-side Diff Tool and binary files. As you can imagine, the Side-by-side Diff Tool will launch too if you want to see the differences between two text files. Read how the Side-by-side Diff Tool can help you.

The Side-by-side Diff Tool is helpful to find out what every user did in every change.

Gluon lets you also see the differences between your workspace content and the changes you are performing. Select one of these actions:

  • In the Explore workspace view, right-click the file you are changing and select the Diff with previous revision option.
  • Or, go to the Checkin changes view, right-click the changed file and select the Diff workspace contents option.

Let's imagine that Maria has checked out the soldier_blue_03_256.png file. Then, she opened it with her favorite editor and saved some changes. If she wants to see the differences between these changes and the workspace content, she can run the following command:

cm diff Soldiers\soldier_blue_03_256.png

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.


Save a specific revision

Maria can also save a given revision of a file to her computer.

This option is available both in the Workspace Explorer and Configuration views.
  1. She selects an item.
  2. In the History view, she right-clicks the revision.
  3. Now, she selects the Save this revision as... option.
  4. Save revision

She can also save a specific revision from the command line using the following command:

cm cat Enemies\enemyGreen1.png#cs:1 --file=Enemies\enemyGreen1.png#1.png

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.


Revert to a specific revision

Looking back on the last two changes that Maria made to the soldier_blue_04_256.png file, the team decided that the image still does not have the design they are looking for. They want to keep the original color and add some contrast. To do this, Maria could checkout the file and apply colors and actions to recover the original blue color. But, it might be quicker and easier to go back to a previous revision, which is a function supported by Gluon. So, let's take a look.

The first step is for Maria to go to the History view and locate the revision that she wants to go back to, in this case, changeset 1. Then, she right-clicks it and selects the Revert to this revision option:

Revert to this revision

Or, she can run the following command:

cm revert Soldiers\soldier_blue_04_256.png#cs:1

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.

when selecting Revert to this revision, a dialog box opens asking Maria to confirm the revert operation:

Revert to this revision - Message

As a result of Maria's revert confirmation, the following actions took place in the workspace:

  1. The selected revision loads into Maria's workspace.
  2. The reverted item is locked (checked-out).
  3. The reverted item has a new status - Checked-out (unchanged)|Replaced.

Reverted revision - Message

Once Maria adds the contrast and saves the change, she must perform a checkin operation. In the Checkin changes view, you will see a new status assigned to this item: Replaced/Checked-out:

New status - Replaced/Checked-out


Recover a deleted revision

Maria has decided to delete all the "red enemies" items that she doesn't need anymore. She knows that this operation will remove these items from the server. So, she selects the items to remove and right-clicks the Delete option:

Gluon - Delete items

A new message will appear asking her to confirm the deletion. Maria has to select if she also wants to remove the items on the disk or only delete them from the server. She wants to keep them on the disk. So, she selects the right option and clicks OK:

Gluon - Confirm deletion

Now, she must checkin the changes to save them into the server. As you can see, the items appear as Private because Maria decided to keep them on the disk:

Gluon - Checkin deleted items

After the checkin action, Maria will see these items in her workspace as Private items:

Gluon - Workspace after deletion

Maria can remove these items (and keep them on disk) from the command line by running the following:

  1. First, the remove command: cm partial remove c:\Users\maria\wks\battlegame\Enemies\enemyRed*.png --nodisk
  2. And then, the checkin one: cm partial checkin -c="Delete 'red enemies'" --applychanged

But, where can John see how many deleted revisions there are? Is there a way to recover them?

If John opens the Checkin changes view, he'll see the Undelete button. John clicks this button and a list of the deleted revisions displays. The list can be filtered by owner and by date:

Gluon - Deleted revisions

To recover or undelete a deleted revision, he right-clicks a revision and selects one of the following options:

  • Undelete revision - To recover the deleted revision in its original location.
  • Undelete revision to this path - To recover the deleted revision to a new location.

Run the following to undelete a revision from the command line:

cm undelete serverpath:/Enemies/enemyRed5.png#cs:27 Enemies\enemyRed5.png

As you can see, John will undelete the changeset 27 related to the enemyRed5.png, and he is going to place it in the Enemies folder. The changeset 28 was created when those "red enemies" were deleted, so there is no revision linked to those files (no changes were made while deleting files).

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.


Uploading new items into the repository

The Project Manager has some new requirements for Maria to do, including adding new figures related to the background textures in the story game. First, Maria needs to create a new folder called Textures. She can do this from the explorer, but this is also a function supported by Gluon. So, let's take a look.

Gluon enables Maria to create new folders and new files as needed. A submenu opens by right-clicking the parent folder, and Maria selects the New option, which opens another submenu. From here, Maria selects the Directory option so that she can create a new directory:

New option

She then enters the name of the new directory and clicks OK:

New directory

This action creates a new folder called Textures with a Private status, which means that it is in Maria's computer, but it's not under version control. Since the repository on the server does not control it, no one can access it:

Private directory

Maria used her design tool to create a new figure called text_wall_01.png which she saved in the new Textures folder. If she does a refresh on the Explore Workspace view, she sees the following:

Private file

As you saw previously, with a new folder, this new file is private as well. You should also note that there were no revisions in the history view because it isn't under version control. So, the server does not know anything about the file.

Once Maria creates the file, she needs to save it into the server repository. Gluon provides two methods for accomplishing this. So, let's take a look.

Note: If you compare both the Explore workspace view method with the Checkin changes view one, you will see some differences in the status and icons associated with the selected items. Both methods will result in saving the items selected to the server.


From the Explore workspace view

If Maria selects the new folder and right-clicks it, she will be able to choose the option Add directory tree to source control from the submenu:

Add directory tree to source control

This action marks the new folder and all its associated files to be added to the repository. Each of the files to be added is marked as checked-out. Upon closer inspection, the file size is zero. This is not a problem because the file is not yet under source control:

Added directory tree to source control

Maria can also add the directory tree to the repository by running the add action from the command line in the following way:

cm partial add -R Textures

To complete the operation, Maria must run a checkin operation on those items. In the Checkin changes view, Maria sees the new items selected and under the Added and private category with status Added and marked with the Checked-out icon. Maria now must enter a comment and click Checkin to save the new items to the server:

Checkin added items

And let's remember how to save all the items from the command line:

cm partial checkin -c="Added textures" --applychanged

From the Checkin changes view

By clicking the Checkin changes tab, Maria sees the new items under the Added and private category:

Add from Checkin changes view

Using this method, Maria must complete the following steps to save the new items to the server:

  1. Select the item(s) she wants to upload to the repository (or select the checkbox near the Added and private category to select all of them).
  2. Enter a comment.
  3. Click Checkin.

The steps above match the commands that we saw in the previous method. This means that you have to run both commands:

  1. Add the directory tree to source control: cm partial add -R Textures
  2. And then, run the checkin to save them into the server: cm partial checkin -c="Added textures" --applychanged

Manual and Automatic modes in action

Now that you are familiar with adding new items to the repository, let's look at how the Manual and Automatic modes work when someone else adds a new item.

John received new requirements from his Project Manager, which means that he must create new yellow figures related to the enemies and tanks design.

To create them, John uses his design tool and then saves his changed files to the Enemies and Tanks folders. As you can see, these files have the status Private:

Private - new files

Once John completes his changes, he must add the files to the repository using the Checkin changes view method to perform this action:

Checkin new files

Once these new files are added to the repository, their status changes to Controlled:

Added new files

As a reminder, previously, Maria loaded the complete Enemies folder (Automatic mode) and several files in the Tanks folder (Manual mode), so this is what her workspace looks like now:

Maria's workspace

As you can see, Maria doesn't have the new yellow files in her workspace because they are in the repository, and she hasn't performed an update yet. You will also notice that the enemyGreen1.png file is out-of-date, but after Maria performs the Update workspace action, her workspace now looks like this:

Maria's updated workspace

Let's take a look at what happened when Maria performed the Update workspace action:

  1. The enemyGreen1.png file updated (it was out-of-date).
  2. The enemyYellow.png file loaded because Maria loaded the whole Enemies folder into her workspace (Automatic mode).
  3. The tank_yellow_01_256.png file wasn't loaded because Maria only performed a partial load of specific files from the Tanks folder into her workspace (Manual mode).

Changeset contents

Gluon creates a new changeset every time you run a checkin action and the involved files change.

The Checkin changes view shows a warning message if no changeset was created after a checkin operation. This can happen when one or more files are just checked-out and then checked-in without any actual change in those files:

Checkin - Warning message when no changeset created

Since you can perform a checkin with one or several items, a typical changeset will involve one or more changes.

At any point along the way, you can review the changes done in every changeset by comparing one with a previous one. The History view shows all the changesets for every item. Let's take a look at how this works.

The enemyGreen1.png file has several changesets associated with it. Maria sees in the History view that she created changeset 3 as well as others. To view the contents of changeset 3, she right-clicks the changeset 3 in the History view and selects the Diff changeset option from the submenu:

Diff changeset

Maria can run the following command to get the contents of changeset 3:

cm diff cs:3 --format="{status} {path} {owner} {date}" C "Enemies\enemyGreen1.png" "maria" "3/10/2015 1:49:16 PM" C "Tanks\tank_blue_01_256.png" "maria" "3/10/2015 1:49:16 PM"

You can see that Maria changed the files enemyGreen1.png and tank_blue_01_256.png where changed (C) on that changeset.

Note: This command doesn't require the partial option because it is not a Gluon-exclusive command; it's also used in Plastic SCM.

This will open a Diff Window that displays the "content" for the changeset 3. The Diff Window has two sections:

Diff Window - changeset 3

  1. The top section shows you:
    • Information about the changeset like who and when the changeset was created.
    • The comment entered when the user runs the checkin to save the changes. You can edit this comment by clicking the Edit comment button.
    • A menu bar where you can run some actions.

      For example, if Analyze differences is clicked, two new columns (Status and SLOC) appear in the top section and display information about the text lines if the selected file is a text file.

    • And all the items in the changeset are grouped by the type of change done (changed, added, moved).
  2. The lower section shows the differences for the selected item in the top section with the current changeset on the right side and the previous changeset on the left side.
Read more about the Diff Window.

If a Diff changeset action is performed on the changeset 12, the result displays the items uploaded (added) by Maria in the previous chapter:

Diff Window - changeset 12


The Changesets view

By this point, you understand that each time you run a Checkin action, a new changeset is created. Each item in your workspace is associated with one or more changesets displayed in the History view:

History view

Gluon lets you see all the changesets created in the repository you're working on. Click the Changesets tab, and you will see the Changesets view:

Changesets view

There are several options you can run when right-clicking on a specific changeset:

  • Diff changeset lets you see the changes made in the selected changeset. We've seen this previously, when using the submenu in the History view.
  • Switch workspace to this changeset allows you to switch the workspace to a specified changeset. This allows artists to ensure their entire workspace is consistent and in the correct changeset.
  • External tools lets you configure custom actions. Every action will be a new menu item under External tools.

    If you haven't use this feature with Plastic, let's see how to configure:

    1. Add a new configuration file externaltools.conf. (Read here where to place this externaltools.conf file.). It allows you to specify external applications and arguments to pass to them.
    2. Edit the file by adding a line for each external tool you want to configure. This is the syntax to follow:
      changeset | <toolName> | <pathToExecutable> | <args>

      where:

      • toolName - The name of the tool to be displayed in the context menu.
      • pathToExecutable - Absolute path to the targeted application
      • args - The arguments to be passed to the targeted application. There are three currently supported placeholders: @object (replaced with the object name), @repository (replaced with the repository of the object), and @wkpath (replaced with the current workspace path). Please note that the replaced values might contain blank spaces, so they'll probably need to be surrounded with quotes.

    For example:

    changeset | Label changeset | "C:/Program Files/PlasticSCM5/client/cm.exe" | label create lb:MyLabel cs:@object

    This configuration will create a menu item called Label changeset under External Tools which applies the label MyLabel to the selected changeset.



By default, the first time you launch the Changesets view, you'll see all the changesets in the repository created by any team member, and these changesets are grouped by the Creation date. But the Changesets view also offers a lot of additional settings to customize the view, such as:

  • Display a standard list with no grouping
  • Group by any column in the list
  • Group by using several columns
  • Order columns in ascending or descending order
  • Hide/Show columns
  • Create a custom search
  • Create a custom filter

Any customization you create automatically saves for any workspace. So, the next time you open the Changesets view, you are presented with your last customized view.


Ungrouping the Changesets view

You can display the changesets as a standard list without using any "group by" column by dragging and dropping the Group by box into the columns header:

Changesets view - show list

After you perform this action, the result is a standard list:

Changesets view - show list - result

You can hide/show the Group by box by right-clicking the Group by section or the columns header. In the submenu, select the option Hide Group By Box or Show Group By Box:

Changesets view - hide/show groups


Grouping by columns

At any time, you can choose what field/column to use for grouping the changesets simply by right-clicking the column header you want to use and then selecting the option Group By This Column in the submenu:

Changesets view - group by column

You can also group the changesets by dragging and dropping the column into the Group by box:

Changesets view - group by column

After you perform this action, the results display the changesets grouped by the person who created them:

Changesets view - group by column - result

You can also add more columns by performing the previous action on any column you need. Adding columns in this way creates a nested "group by" option:

Changesets view - nested group

You can arrange the columns in ascending or descending order by clicking the specific triangle next to the column name in the columns header or the Group by box/es.


Show and hide columns

Another setting for customizing your Changeset view is choosing which columns to show or hide. If you want to remove (hide) a column, right-click the selected column header and select the Remove This Column option in the submenu:

Changesets view - hide column

After you perform this action, the results will be that the repository column is hidden from view:

Changesets view - hide column -result

To restore (show) any removed columns, right-click the columns header and select the Column Chooser option in the submenu:

Changesets view - column chooser

Performing this action will launch a new window with all the "removed" columns. Select the columns you want to restore by dragging and dropping them into the columns header:

Changesets view - column chooser - restore


Searching for changesets

If you want to retrieve changesets from the server based on specific search criteria, you need to click Advanced. This action opens a new search box to enter the search string criteria that will return the changesets from the server. By default, the advanced search retrieves the changesets created during the last 30 days. To perform the search, click Execute, and the changesets that meet your criteria are retrieved:

Changesets view - Advanced search

Going back to our example, Maria created a search string criterion to retrieve all the changesets created by John (the owner) where the creation date is greater than March 10th. When she clicked Execute, then she retrieved the following changesets:

Changesets view - Advanced search - result


Creating filters

Once you've retrieved the changesets you requested from the server using the Advanced search utility, you can use filters to hide or show changesets that match one or more filter types offered in the Changesets view. By entering your filter criteria (text) in the Filter box, you can hide any changesets from the list that do not match your criteria and only display changesets that match your filter criteria.

Going back to our example again, let's suppose that Maria retrieved from the server all the changesets created by anybody during the last 30 days:

Changesets view - Advanced search

If she only wants to see the changesets that have the add text in any of the changesets fields, then she needs to enter text in the Filter box to filter out the changesets that do not meet her criteria. The cool thing is that while Maria enters the text in the Filter box, the changeset list updates in real-time to show only the changesets that fit her filter:

Changesets view - Filter box

When she enters add, the result is the following:

Changesets view - Filter box

Another method of filtering is using column filters. By hovering over each column header, a "pin" icon displays. If you click it, then you'll be able to filter using one value in that column:

Changesets view - Filter by column

If you select the (Custom) option from the list, then you will see additional custom filtering options for that column:

Changesets view - Custom filter

The Changesets view lets you create even more complex filters by using the Filter editor option. You launch the editor by left-clicking any column and then selecting Filter Editor from the submenu:

Changesets view - Filter editor option

The filter editor enables you to create a complex filter using multiple filters:

Changesets view - Filter editor

...using multiple columns:

Changesets view - Filter editor

...using more than one operator:

Changesets view - Filter editor

...and entering the value you want to filter by:

Changesets view - Filter editor

Going back to our example, let's look at how filters are used.

Let's suppose that Maria wants to display a list of changesets created by John, or somebody whose name starts with ro and the comment contains the ad string. So, using the Filter editor, she builds the following complex filter:

Changesets view - Filter editor example

By clicking OK, Maria gets the following results:

Changesets view - Filter editor example

At the bottom of the window, the filter text that Maria entered displays. She can edit the filter criteria by clicking Edit Filter in the bottom right corner. Or, she can remove the filter by clicking X on the left side of the filter text box.


Searching files

Gluon contains a Search files utility in the Explore workspace view and the Configuration Mode view. This utility enables you to search files matching the filter you created in the search box by clicking Search files.

In the Configuration Mode view, the search helps you localize files in your workspace to the same level as the server repository (including the files that are not loaded into your workspace). In the image below, you can see that the files loaded into your workspace are marked with the checkin tip:

Search files - Configuration Mode

In the Explore workspace view, you can search the files in your workspace that match your filter. If you select the Include private option, then the search results will include your local items too.

It is possible to search files or folders by using patterns. Let's look at some examples:

  1. Search all the *.png files included in any \PNG folder:
    Search extension into directory
  2. Search all the files and folders that start with player:
    Search files and folders
  3. Search all the files and folders in the Power-ups directory that include the substring green:
    Search files and folders into directory

When you perform a search in the Explore workspace view, you can directly execute the following operations from the search results instead of going to the item in the workspace window. Just right-click any of the highlighted files (you can select more than one) and then select the required operation:

  • Checkin
  • Checkout
  • Lock and checkout
  • Undo checkout
  • Undo changes
  • Update
  • Open
  • Open with
  • Open in explorer

Search files - Operations


What happens if...

This guide shows you how to manage your repository and your workspaces in a "normal" environment using Gluon. But as you can imagine, you and your teammates may encounter some "strange" situations while using Gluon, so let's address some situations you may encounter.


...you try to add an item that already exists?

Going back to our example, John designed some texture images to be used in the story game. He saved those files in a new local Textures folder, and this is what his workspace looks like:

Private folder

He now decides to add those files to the repository because another teammate needs them to create a new game scenario. So, he performs an Add directory tree to source control action and performs a Checkin to save the new items in the repository:

Adding private items

But unfortunately, he receives the following message:

Checkin conflict

John got this message because several days ago, Maria created a folder called Textures so Gluon detects the conflict and alerts John that a Textures folder (Maria's) already exists on the server.

After clicking Close, John must complete these steps to solve this situation:

  1. First, John must undo the changes (by clicking Undo in the Checkin changes view), so the new items have the Private status again.
  2. Then, John opens the Configuration Mode view by clicking Configure, where he can now select/load the Textures folder. He can load the whole folder with all its files (Automatic mode) or only load the folder or the specific files in the folder by deselecting the files he does not need (Manual mode). After making his choice, John completes loading the folder by clicking Apply

    Configuration Mode view

  3. Gluon automatically solves the duplicated folder name issue (the local Textures folder and the server Textures folder just loaded), and this is what John's workspace looks like now:

    Folder loaded

  4. Now, John can add the new texture files to the server using the Checkin changes view:

    Checkin files

  5. After clicking Checkin, the new files are under source control in the repository:

    Added files

At this point, Maria could perform an Update to the Textures folder or an Update workspace to get John's textures files into her workspace.

But let's suppose that Maria doesn't perform any of those updates. Since the Textures folder in the repository was created by Maria, this means the folder is under the Automatic mode in her workspace. So, when she opens the Configuration Mode, the two new files that John created will automatically be marked as "to be loaded". If Maria applies the changes, those files load into her workspace:

Automatic mode


...somebody moved or renamed the directory you're working on?

Going back to our example, John has a new design requirement that must be applied to the text_wall_01.png file. As you've seen in this guide, John needs to perform a checkout to edit the file with his design tool:

Checkout file

John can perform the checkout operation from the command line:

cm partial co c:\Users\john\wks\battlegame\Textures\text_wall_01.png

While he's working on the file making the required changes, the story game team decides that the textures figures are too closely related to the enemy scenarios. So, the Project Manager asks Maria to move the Textures folder into the Enemies folder resulting in a new folder structure. As you can see in her workspace, the text_wall_01.png is locked by John, but Maria moves the Textures folder into the Enemies folder anyway:

Move folder

Run the following command to move the folder from the command line:

cm partial move c:\Users\maria\wks\battlegame\Textures c:\Users\maria\wks\battlegame\Enemies

After completing this move, Maria must perform a Checkin action to save this change to the server:

Moved folder - Checkin

And remember how to checkin the changes from the command line:

cm partial checkin -c="Move Textures folder" --applychanged

Now, Maria's workspace and the Configuration Mode view look like the picture below. The text_wall_01.png file is still locked by John:

Moved folder - After

John has now finished making his changes and is ready to checkin them into the repository to make them available to the team. A new changeset is created (by John), but he has not received any message or any error about the move of the Textures folder. This is because Gluon transparently performed all the actions to all users:

New changeset

At this point, if we compare John's current workspace structure to the repository workspace structure, you will see that they are inconsistent. John can continue working in his workspace as he usually would, but maybe, at any moment, he will load that change (the folder move that Maria performed). If he opens his Configuration Mode view, he will see a new folder structure. His current Textures folder is still loaded, but now he can see the Textures folder moved by Maria with his changes applied to the text_wall_01.png file:

New folder structure

To resolve this, John must update his workspace by clicking Update workspace in the Explore workspace view. After the update is finished, the workspace has the same structure as the repository in the server, which contains the moved folder:

Updated workspace

John can perform the update workspace operation from the command line:

cm partial update

If John now opens the Configuration Mode view, he will see that his "old" local Textures folder is not loaded and the moved Textures folder is loaded instead:

Updated configuration mode

John has successfully resolved the inconsistency between his workspace structure and the repository workspace structure.


Finding changes in your workspace

The Options dialog in the Checkin changes view lets you configure the following:

  • What to find—How to find changes in the workspace. You can finely tune how Plastic finds changes on disk and what to skip.
  • What to show—The types of changes to display. From auto-refresh to deciding if you want to see private files, ignored, and more.
  • Move detection—How Plastic finds moved files and directories in your workspace and can detect files and directories that you moved or renamed on a disk.

Click the Options button to configure the settings above:

Use the Previous (<) and Next (>) arrows to see the Options dialog in Windows, Linux, and macOS.

What to find

Show checkouts
Shows the files you explicitly checkedout in Plastic—the ones you moved by using the Plastic GUI or the command line, and the files involved in a merge process.
Find changed files in the workspace
Shows the files that were modified. Plastic detects changed files just by comparing timestamps. If the file timestamp is newer than the one it had when Plastic wrote it to disk, then it is modified. It is a super quick check that works most of the time.
Plastic can also check the file's content to see if it is changed, not only the timestamp. Some applications save files and change the timestamp even if the content doesn't change. This check calculates the new hash of the file contents to see if it was really changed.

What to show

Auto-refresh
If this option is marked, Plastic automatically refreshes the Pending changes when needed.
Show private files
Shows the files that are not under source control. For example, recently added files or even tool-generated files.
You can also enable always select private files, so they are always checked in the Checkin changes view. This is good to avoid forgetting to add new files. But you need to configure a good ignore.conf to avoid adding temporary files to version control.
Show ignored files
Shows the files that you previously ignored by adding them to the ignore.conf.
Show hidden files
Shows the files that you previously hid by adding them to the hidden_changes.conf.
Show deleted files and directories
Shows the files that you manually deleted in the workspace outside of Plastic control. (Not using the GUI or a command, but deleting them from disk.)

Move detection

These options let you tune move detection. This is one of the key features of Plastic. Plastic can easily detect when you moved a file, renamed a directory, etc. But at the end of the day, it uses a heuristic and it can make mistakes. While it achieves very good results by default, these settings let you customize the heuristic to your needs.
Find moved and renamed files and directories
Walks the workspace finding possible moves. If you rename foo.c to bar.c, Plastic will find bar.c as added, foo.c as deleted, and then try to match them. It can be slow if you have lots of private files because it will spend a long time matching deleted and added files to find moves. Normally, you'll have this setting enabled. But if you are sure that you don't have any moves and need to speed up your Checkin changes view, then it is a good reason to uncheck it.
You can also fine-tune how "find moves" works:
Match binary files only when they have the same extension
Doesn't try to match a .png with a .jpg, which makes much sense. The caveat is that it won't find a .doc to .docx rename. Binary file move detection is tricky because it is not based on how similar the file contents are, but on how similar the names and sizes are. Plastic doesn't calculate diffs on binaries because it could be super slow.
Match text files only when they have the same extension
Doesn't try to match a .cs with a .c. It can be useful in some circumstances. Plastic diffs the text files to figure out how similar they are. Plastic does it only for text files, not binaries. This setting helps you tune the algorithm, so that the matches are not tried between every possible pair of files but only those with the same extension. You'll only use this setting if the Checkin changes view is not showing what you expect.
Similarity percentage
Defines "how similar" two files need to be to detect them as moved or renamed. If you move foo.c to bar.c and modify it later, the percentage defines how similar the files need to be so that Plastic considers them the same file. If you changed a file a lot and you renamed it, and the file shows as added/deleted, chances are you need to tweak this setting so that Pending changes detect it as moved.
The similarity percentage applies to directories too. It defines how similar the directory structure needs to be—how many moved children relative to the total of directory entries.
Finally, it also applies to binaries. The percentage means the allowed difference in size.

Working with branches

The initial design of Gluon was "as an artist I don't want to see branches". But some of you needed to switch branches easily. Gluon lets you do just that!

Use the Previous (<) and Next (>) arrows to see the Switch branch feature in Windows, Linux, and macOS.
  1. Click the Switch branch button at the bottom panel:
  2. And choose the branch you want to switch to:

Gluon also has merge capabilities. So, when files conflict during checkin, Gluon launches the configured merge tool (same tool configured for regular Plastic) and helps you solve the conflicts.

Read more about the merge feature in Gluon .

Last updated

October 11, 2021
  • We added the recent Checkin comments button to the Checkin Changes view.
  • October 7, 2021
  • You can now configure custom actions that can be launched from the Changesets view context menu.
  • October 6, 2021
  • We have added a menu option to the Changesets view that allows you to switch the workspace to a specified changeset.
  • January 11, 2021
  • We added a note to let you know that Gluon won't remove the ignored/private items inside the folder you want to unload.
  • February 14, 2020
  • We updated the documentation and screenshots related to the Diff Window where you can explore the changeset contents.
  • February 14, 2020
  • Learn how to work with branches.
  • January 22, 2020
  • We documented how the Lock and checkout option works. We also updated a lot of screenshots to show this option.
  • January 21, 2020
  • Now, it's possible to update the whole current partial workspace without specifying any path.
  • November 13, 2019
  • We added the documentation about the Options that you can configure in the Checkin changes view.
  • November 8, 2018
  • Now, it is possible to load/unload files by using patterns (for example, *.jpg, *.png) in the search dialog.
  • November 7, 2017
  • We added the cm commands related to diff between selected revisions and revert to a specific revision.
  • September 19, 2017
  • We added the required cm partial commands to show you how to perform all the operations (configure workspace, add, checkin, checkout, and so on) from the command line.
  • July 10, 2017
  • Now, you can recover a deleted revision.
  • Learn when to use the Undo changes action.
  • There is a new context menu option to toggle the Workspace view mode: "View as a list" / "View as a tree".
  • The Diff option is now available in the context menu of the Explore workspace, Checkin changes and Changesets views.
  • Read how to perform a checkin from the Workspace view.
  • Some screenshots were updated to show you new actions in the contextual menus: undo changes, save a revision...
  • May 31, 2017
  • There is a new option that you can use to save a revision of a file to your computer.
  • May 12, 2017
  • Now, you can configure the maximum file size to generate the preview of a file.
  • April 17, 2017
  • We updated some screenshots to show you new features:
  • February 4, 2016
  • See some examples about how to search into directories using patterns.
  • March 24, 2015
  • This is the Manual and Automatic modes behaviour when updating
  • See how the Manual and Automatic modes work
  • Learn all about The Changesets view
  • We explain to you how to search files
  • In this new section we study what happens in some particular cases