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 in any way 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 that I will work on, makes changes to and easily 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 that nobody can work on them at the same time as me.
  • As a user, I don't want to be forced to download a file repository containing tons of huge files just so I can 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

Note: Before running Gluon, it's mandatory that you configure the locking system function. To do that, the server file, lock.conf must be correctly setup. The lock.conf file allows you to lock files upon checkout which prevents others from modifying those files while you are working on them. By controlling file access in this way, you avoid the need to merge 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 will need to create your first workspace by configuring the Plastic SCM server (IP address or Name). If you need help with this set-up, then 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, you will 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 not correct, then click Check and the server will allow you to choose your username from a list.
  2. Enter a repository name by typing in a name or using 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 by typing in a path name 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 then 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, then the Configuration Mode view window will open. You can view all the items stored in the repository stored on the server:

    Configuration mode view

    This is an extremely cool feature because the Configuration Mode view enables 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, simply check the boxes of those items and they will be loaded into your workspace:

    Configuration mode view - Load items

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

  4. Once those items are checked, we will click the Apply button to load these items into the workspace so that you can start working with them:

    Workspace - loaded items

If you prefer, you can use the command line to configure your workspace. For our example above, just 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 the Configure button 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 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.

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 then Gluon identifies the folder as Automatic Mode.

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


Unloading items

As you saw in our 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, then simply unload it from the workspace. This will reduce the number of files you must deal with in your workspace. The way that you would do this is to 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 need to follow two simple steps:

  1. Uncheck the Misc checkbox to remove the black square. The black square will be replaced by a red 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 be refresh and the Misc folder is 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

Workspace information

Options in the directory sizes

As you've seen in the previous screenshots, you're able to 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

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

To ensure that other user will not edit the same files as you, Gluon provides the Checkout feature. Just 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, you simply right-click any one of them and select the Checkout option from the submenu:

Checkout files

By selecting the Checkout option, the files you selected will lock and nobody will be able to 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 provides a visual indication to you and others 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 those files.


Checkout recursively

If you need to lock all of the files in a folder, then you simply 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

By performing this action on the folder, all the items in the folder are checked out (locked), so you don't have to select each individual 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 are done editing your files using the external tool, you will notice that, after refreshing the workspace view, 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), you simply 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, just enter 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), and 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 that there's 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 horizontally scroll through the History view to read the comment.


But are the files really locked?

Maria have made changes and checked them in, but then 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 team mate 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 is available for editing:

John workspace

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

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)

So, Gluon prevented 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 that she wants 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 a new changeset was created by Maria. 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 in 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, like John, can make their changes. But the file status was Out of date, so let's take a look at what that really means in the next section.


Working with the latest stuff

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

John has been waiting patiently to make his 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 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 outdatedd is because Maria made some changes to it. By the time John is able to 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 what John has to do is 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 really 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 is now able to 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 would have looked at the History view, she would have seen that there is 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 to always 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 made some changes to 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) so that he can check out 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 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 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 is because 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 is because 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 then saves the changes, he needs to click the Refresh button to see that the status is now 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 that 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 just 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 that she needs 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

For more information about the Side-by-side Diff Tool and binary files, click here. 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 here how it 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 must select 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.

By 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 (the "bolded" revision in the History view).
  2. The reverted item is locked (checked out).
  3. The reverted item has a new status, 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/Changed:

New status - Replaced/Changed


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. She selects the items to remove and right-clicks the Delete option:

Gluon - Delete items

A new message will show asking her to confirm the deletion. Maria has to select if she also wants to remove the items on disk or only delete them from the server. She wants to keep them on her 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 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 it 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 just right-clicks a revision and selects one of the following option:

  • 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 is going to 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" where deleted, so there is no revision linked to those files (no changes were done 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, which include adding new figures related to the background textures in the story game. 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. By right-clicking the parent folder, a submenu opens and Maria selects the New option which opens another submenu. From this, Maria selects the Directory option so that she can create a new directory:

New option

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

New directory

This action creates a new folder called Textures with a status of Private which means that it is in Maria's computer, but it's not under version control. Since it is not controlled by the repository on the server, 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 that there are 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 then 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 are 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 in order 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 to 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 how to add new items to the repository, let's look at how the Manual and Automatic modes work when someone else adds a new item to the repository.

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 that were done in every changeset by comparing one changeset 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 the files enemyGreen1.png and tank_blue_01_256.png where changed (C) on that changeset by Maria.

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:

  1. The top section shows information about the changeset such as: when it was created, the comment that included at checkin, a menu bar and all the items in the changeset 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.

Diff Window - changeset 3

If Analyze differences is clicked, then 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.

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

For more information about the Diff Window go here.


The Changesets view

At this point you should 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

As we've seen previously, by using the Diff changeset submenu in the History view, you can see the changes made in every changeset.

Gluon is also able to show you all the changesets that created in the repository you're working on. Just click the Changesets tab and you will see the Changesets view where you can launch the Diff changeset command too:

Changesets view

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 simply 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

It's possible to 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 in 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, simply 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, simply 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. Simply 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, then you need to click Advanced. This action opens a new search box where you can 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 by using the Advanced search utility, you can then 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 do 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 finishes entering the word add, the result is the following:

Changesets view - Filter box

Another method of filtering is to use 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 by 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 in 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 having to go 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
  • Undo checkout
  • Undo changes
  • Update
  • Open
  • Open with
  • Open in explorer

Search files - Operations


What happens if...

In this guide, we have shown you how to manage your repository and your workspaces in a "normal" environment using Gluon. But as you can imagine, you and your team mates may encounter some "strange" situations while using Gluon, so we would like to address some situations that 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 some other team mate 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

The reason John got this message is 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 follow 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, then this means that 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, then 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 which results 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 normally 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.


Last updated

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