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 and 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 game teams only.

Here are a few scenarios that may 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. I don't ever want to deal with merging or branching files either. Those functions should happen in the background automatically.
  • As a user I want to lock files so that nobody can work with them at the same time.
  • 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 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 the Connect button. 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. Enter the working directory (workspace) location typing in a path name or using the Choose button to select one from a list.
  4. Once all information is entered click the Apply button.

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... To start configuring your Workspace, click the Open button in the Workspace Switcher view:

Workspace Switcher view

You will then 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. To do that, click the Configure button:

Explore workspace

After you click the Configure button, then the Configuration Mode view window will open and, at that point, you can view all of the items stored in the repository that is 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. 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. 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

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 the preview of a file when that file is not loaded in the workspace (Configuration mode). To do so, add the following key to your client.conf file:

<MaxPreviewFileSize>1048576</MaxPreviewFileSize>

The default value is 1 MiB (1048576 bytes). It 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.)



Manual and Automatic modes

Gluon has two modes depending on whether you specific 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 have seen in our example, Gluon lets you configure your workspace at anytime 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 which will reduce the number of files you have to 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 you want to remove from your workspace:

Configuration Mode - Unload items

As you can see in the above window, the Misc folder is loaded (indicated 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.

The first step is to uncheck the Misc checkbox to remove the black square. The black square will then 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

The second step is to execute the unload action by clicking the Apply button. Your workspace will be refreshed and the Misc folder will be removed from the folder list:

Workspace - unloaded folder


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 / 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 is how this report looks like:

Explore workspace - Update report

The 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 so it's time to start modifying them.

In order to ensure that another user will edit the same files as you, Gluon provides the Checkout feature. By checking out the file it is essentially 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 be locked and others will not be able to edit them until you check them back in. Once you have checked out the files, those files will be 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 are now ready to edit the files by dragging and dropping them into an external editing tool. The files are locked so you never have to worry that nobody else will edit those files too.


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

By performing this action on the folder, all of the files in the folder will be checked out (locked) so you don't have to select each individual file. The result is the same as we have seen before, every file will have a new icon, the Last edited field for every file in the folder will change from root to your user name (in this case Maria) and the status of every file in the folder will change to Checked-out (unchanged):

Checked-out recursively


Saving your changes in the server

When you are done editing your files using the external tool, you will notice that after you refresh 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 have been edited and those changes have been 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 will be 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 was updated to Controlled indicating that the files were checked in successfully. Also the history view displays the new changeset:

Checkin changes successfully

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

If you've noticed, 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 horizontal scroll the History view to read the comment.


But are the files really locked?

So you have made changes and checked them in but then you realize that you forgot to add one change to the tank_blue_01_256.png file so you check it out again but at the same time your team mate John wants to check it out as well.

You get there first and your workspace looks like this:

Maria's workspace - Checkout file

In 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 it was modified several hours ago 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 to his surprise he gets an error message indicating that the file has been checked out by Maria:

Error - file is locked

So Gluon has prevented John from editing the file while Maria has it locked. 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.

So not only is John prevented from editing the file, Maria has decided that she wants to keep the file locked for the rest of the day because she has some additional changes that she wants to make. She can save the changes to the server and keep the file locked by simply selecting the Keep items locked option.

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

Keep items locked

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

Keep items locked - New changeset

So now poor John, after doing a Refresh in his workspace, will continue seeing 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

So after a couple of days work Maria is finally ready to check-in the file and unlock it (by unselecting the Keep items locked option ) so that others (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 be sure that 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 has not yet been updated in John's workspace.

Here is how 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 out of date 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 get the latest version of this file into his workspace by selecting the Update option from the submenu:

John's workspace - Update out of date

By performing the update John has loaded the latest revisions of the file into his workspace which he can see in 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 because if he tries to do that the Gluon will display an error message indicating that the file is not up to date in his workspace.

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

John's workspace - Loaded file

John is now able to check out the file and make his modification which is to add a grey center point. After completing this update he then checks in the file which results in the creation of a new changeset (changeset 6) that was created by John as can be seen 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 check out and 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

If Maria had 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 and 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 colors of 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 has been 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 is updated but the tank_blue_01_256.png file is still out of date. As you can see the Gluon has 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 will deliver the same result as selecting Update from the submenu but instead of updating a specific file the complete workspace (all files) will be updated so none will be out-of-date.


Manual and Automatic modes - Update

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

The mode assigned to each folder will determine whether new files added to the folder will be downloaded 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 be automatically downloaded 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 be automatically downloaded 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):

John's checkout

If he opens the file using his favorite editor, modifies it then saves the changes he will need to click the Refresh button to see that the status has now updated to Checked-out (changed):

John's file 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. Fortunately Gluon makes this very easy.

All that John has to 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 will display 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 be restored as if nothing was ever done to it:

John's workspace - Undoing checkout

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

John's workspace - Undoing checkout


Find the image differences

Let's say that the team Project Manager sent Maria the new design requirements that she will need to implement in the soldier_blue_04_256.png file. After loading the file in her workspace she can move forward with making 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 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 wanted to see the differences between the last two changes she would need to right click last change and select the option Diff with previous revision from the submenu:

Diff with previous revision

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 is the last revision and on the left side is the previous revision. The changeset version will be displayed 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

Maria is now ready to show her colleagues how the first revision compares to the latest revision so she selects both revisions from the history view, right clicks either file and selects the Diff selected revisions from the submenu:

Diff selected revisions

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

Get here further information about the Side-by-side Diff Tool and binary files.

As you can imagine the Side-by-side Diff Tool will be launched 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 what every user did in every moment.


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 has 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 try to 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 locate the revision that she wants to go back to and right click it which will open a submenu where she can select the Revert to this revision option:

Revert to this revision

By selecting the Revert to this revision, a box will open asking Maria to confirm revert and she will obviously select Yes:

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 was loaded into Maria's workspace (marked in bold)
  2. The folder containing the revision will be locked (checked out) so Maria is able to edit it right now (add some contrast) or run a checkin action to keep this reverted revision (recovering the original blue color)

Reverted revision - Message

Once Maria added the contrast and saved the change then she has to 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


Uploading new items into the repository

Maria's Project manager has given her new requirements which include adding new figures related to the background textures in the story game. Maria will need to create a new folder called Textures. She can do this from the browser interface 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 will open and Maria will select the New option which will open another submenu. At this point Maria would select the Directory option so that she can create a new directory:

New option

Maria would then enter the name of the new directory and click the OK button:

New directory

This action will create 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 in the server, no one can access it:

Private directory

Maria has used her design tool to create a new a new figure called text_wall_01.png which she saved to the new Textures folder. If she now does a refresh on the Explore Workspace view, she will see this:

Private file

As you have seen 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 has created the file she will need to save it to the server repository. Gluon provides two methods for accomplishing this so let's take a look.

Note: If you compare the Workspace explore view method with the Checkin changes view method you will see that there are some difference in the status and icons associated with the selected items. Either method 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 will mark the new folder and all of its associated files to be added to the repository. Each of the files to be added have been 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

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

Checkin added items


From the Checkin changes view

By clicking the Checkin changes tab Maria will see 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 into the repository (or select the checkbox near the Added and private category to select all of them)
  2. Enter a comment
  3. Click the Checkin button

Manual and Automatic modes in action

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

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

In order 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 has completed 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 how her workspace looks 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 but 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 was updated (it was out of date)
  2. The enemyYellow.png file was 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 have changed.

The Checkin changes view shows a warning message when no changeset has been 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 so let's take a look at how this works.

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

Diff changeset

This will open a Diff Window that will display 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 was 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 the Analyze differences button is clicked then two new columns (Status and SLOC) will appear in the top section and will 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 will display the items that were 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 that are 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 what changes have been made in every changeset.

Gluon is also able to show you all the changesets that were created in the repository you're working on by simply clicking the Changesets tab which will open the Changesets view:

Changesets view

By default, the first time you launch the Changesets view you'll see all the changesets in the repository that were created by any team member, and these changesets will be 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 will be automatically saved for any workspace so the next time you open the Changesets view, you will be presented with your last customized view.


Ungrouping the Changesets view

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

Changesets view - show list

After you perform this action the result will be 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 by simply 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 result will 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 will create 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 result will be that the repository column will be hidden from view:

Changesets view - hide column -result

To restore (show) any removed column, 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 will need to click the Advanced button. This action will open 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 will retrieve the changesets that were created during the last 30 days. To perform the search, click the Execute button and the changesets that meet your criteria will be retrieved:

Changesets view - Advanced search

Going back to our example, Maria has created a search string criteria to retrieve all of the changesets created by John (the owner) where the creation date is greater than March 10th. When she clicked the Execute button, 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 filters, that can be selected from several 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 has retrieved from the server all of the changesets created by anybody during the last 30 days:

Changesets view - Advanced search

If she really only wants to see the changesets that have the add text in any of the changesets fields then she will need 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 is entering the text in the Filter box, the changeset list is being updated in real time to show only the changesets that fit her filter:

Changesets view - Filter box

When she is finished entering the word add the result will be the following:

Changesets view - Filter box

Another method of filtering is to use column filters. By hovering over each column header, a "pin" icon will be displayed. 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 be presented with 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 which you can launch by simply 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 take a look at how filters can be used.

Let's suppose that Maria wants to display a list of changesets that were 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 the OK button, Maria will get the following results:

Changesets view - Filter editor example

At the bottom of the window the filter text that Maria entered will be displayed. She can edit the filter criteria by clicking the Edit Filter button in the bottom right corner. Or she can remove the filter by clicking the X button 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 simply clicking the Search files button.

In the Configuration Mode view, the search will help you to 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 see 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 has designed some texture images that will be used in the story game. He saved those files in a new local Textures folder and this is how his workspace looks:

Private folder

He now decides to add those files to the repository because some other team mate will need 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 the Close button John must follow these steps to solve this situation. It's an easy way.

First of all John has to undo the changes (by clicking the Undo button in the Checkin changes view), so the new items will have the Private status again.

Then John opens the Configuration Mode view by clicking the Configure button 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 the Apply button:

Configuration Mode view

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

Folder loaded

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

Checkin files

After clicking the Checkin button 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 will be loaded 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 will need to perform a checkout in order to edit the file with his design tool:

Checkout file

While he's working on the file to make the required changes, the story game team decides that the textures figures are closely related to the enemy scenarios so the Project Manager asks Maria to move the Textures folder into the Enemies folder which will result 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

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

Moved folder - Checkin

Now the Maria's workspace and 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 check them in into the repository to make them available to the team. In doing so 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 performed all the actions transparently 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 to work 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 that was moved by Maria with his changes applied to the text_wall_01.png file:

New folder structure

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

Updated workspace

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

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