Plastic SCM - Gluon guide

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.

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:

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.

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:
   

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

   

   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:
   

   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:
   

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

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.

<MaxPreviewFileSize>1048576</MaxPreviewFileSize>

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:

And you will see something like this:

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

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.

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:

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:
   
2. Execute the unload action by clicking Apply. Your workspace will refresh, and the Misc folder will be removed from the folder list:
   

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:

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:

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.

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:

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):

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

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

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:

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:

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):

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):

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:

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:

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:

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:

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 goes ahead and tries to initiate a checkout, but he gets an error message indicating that Maria has checked out the file:

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'.

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:

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:

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:

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.

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:

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:

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:

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

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:

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:

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:

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:

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):

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:

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

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.

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.

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

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):

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:

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:

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

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

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:
    

  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:

  
• 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:
  

  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:

  

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.

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

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. 

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:

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

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.

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:

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:

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:

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:

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

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:

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.

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:

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

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:

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:

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.

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:

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:

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:

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

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.

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:

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

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

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:

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:

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).

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:

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:

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

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

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:

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:

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.

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:

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

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:

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:

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

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

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:

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.

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:

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

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

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:

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:

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:

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:

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:

When she enters add, the result is the following:

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:

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

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:

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

...using multiple columns:

...using more than one operator:

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

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:

By clicking OK, Maria gets the following results:

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.

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:

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:
   
2. Search all the files and folders that start with player:
   
3. Search all the files and folders in the Power-ups directory that include the substring green:
   

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

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.

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:

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:

But unfortunately, he receives the following message:

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
   
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:
   
4. Now, John can add the new texture files to the server using the Checkin changes view:
   
5. After clicking Checkin, the new files are under source control in the repository:
   

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:

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:

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:

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

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:

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:

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:

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:

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:

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

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:

Gluon - Windows - Checkin changes options

Gluon - Linux - Checkin changes options

Gluon - macOS - Checkin changes options

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.

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!

1. Click the Switch branch button at the bottom panel:
   

   Gluon - Windows - Switch branch button

   

   Gluon - Linux - Switch branch button

   

   Gluon - macOS - Switch branch button

   
2. And choose the branch you want to switch to:
   

   Gluon - Windows - Switch branch dialog

   

   Gluon - Linux - Switch branch dialog

   

   Gluon - macOS - Switch branch dialog

   

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.

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:
  • Gluon now shows you the directory sizes in the Explorer workspace and Configuration views.
  • You can exclude or include the private items when calculating the directory sizes.
  • Learn how to show a list with all the updated items in your workspace.
  • You can easily read the comment for a selected revision in the History view.
  • New operations, as checkin, update, open..., are available from the Search results dialog in the Explore workspace view.
  • Read the reason why you'll see a warning message when you perform a checkin operation but no changeset is created.

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