HomeDeveloper WorkspacePrinter Friendly Version

Developer Workspace

General questions about working in a workspace

1. General

1.1. Is it possible to move a workspace to a different folder?

In the 2009/2 release you can open the GUI. Select the workspace in the Workspace View and select 'All Tasks | Move Workspace'. You will then be asked to enter the folder where you want the workspace files to be moved into.

If you are using a previous version of PureCM then you will need to... 

If the workspace was created with the 'store database in home directory' check disabled then you can move the workspace by:

    Copy your old workspace folder to the new location (including the _purecm folder which contains the workspace database).
    Open the GUI.
    Delete the old workspace.
    Create a new workspace to the new location.
    You should get a warning that it is a multi-user workspace.
    Everything should now work as usual.

If the workspace was created with the 'store database in home directory' check enabled then you can move the workspace by:

    In the home directory (you can see this in the Options | General page) you should see the workspace database files named after the location of the workspace. Take a copy of these files. Open the GUI.
    Delete the old workspace.
    Create a new workspace to the new location (note that you can cancel
the update).
    In the home directory delete the new workspace database files (named
after the workspace path)
    In the home directory rename the old workspace database files to
reflect the new path
    Everything should now work as usual.

1.2. What does Check Consistency do?

Check consistency is a way to make sure that PureCM has detected all of the changes you have made in your workspace. Check consistency is available from all PureCM clients (GUI, Visual Studio, command line & explorer etc) and is launched from different places but always gives the same options.

New Files

If new files is checked PureCM will look for files inside your workspace that it does not yet control. This can be useful when you have created a new file but have not added it to PureCM. As you often can have many files in a workspace which you do not which to control (such as debug object files etc) you are given the option to provide different filters.

Include Filters - This allows you limit which types of files are found by the consistency check. If you know you only modify *.cpp and *.xml then it can help to limit the number of files found to the ones you are interested in.

Exclude Filters - The exclude filters allow you to exclude specific file types or directories. It can often be useful to exclude debug directories as this will speed up the running time of the consistency check.

Edited Files

If edited files is checked PureCM will look for controlled files which have changed from the server version but have not been checked out. This can be useful when you work in a writable workspace or in an enviroment that does not have a PureCM plugin.

Missing Files

If missing files is checked PureCM will look for files which have been deleted on disk but have not been deleted from PureCM. If any of these files are found you will be given the option to either recreate these files from the server or to delete them from PureCM.

Unchanged Files

If unchanged files is checked PureCM will look for checked out files which have not been modified. This is useful for when you check out a file but then undo the change or if you check out a folder of files and don't change all of them.

Readonly Files

If readonly files is checked PureCM will look for checked out files that are read only. This will make sure that the files are set back to writable.

Writable Files

If writable files is checked PureCM will look for files which are writable but have not been modified or checked out. This will change them back to read only. note this will not be available from writable workspaces.

Quick Check

If quick check is selected PureCM will use a files modification time to determine if a file has been modified. This will significantly speed up the running time of the consistency check but may miss some changes. If this is not selected then each file will be compared against the server version.

2. Creating a Workspace

2.1. Can I create a workspace to only include some stream folders?


If you select a stream folder and select 'Create Workspace' then a workspace will be created for this individual folder only.

Alternatively, when creating a workspace in the GUI expand the 'Advanced' + box and notice the 'Multi-Path...' button.


Select this button to launch the 'Workspace Folder Mappings' dialog. You will only be able to edit this if the 'Store workspace database within home directory' is checked. You cannot create a multi-path workspace if the workspace database is not stored in the home directory because the workspace will not have a root.



Within this dialog you can create folder mappings. The 'Stream Path' is the folder in the stream. The 'Local Path' is the local folder on your machine. Press the 'Add' button to add a new mapping.


Note that PureCM will process these mappings from the most specific stream folder upwards. So you can specify the mappings:

    '/folder1/folder2' -> C:\Folder2

    '/folder1' -> C:\Folder1

    '/' -> C:\Root

PureCM will put '/folder1/folder2' in 'C:\Folder2'. The rest of '/folder1' will be put into 'C:\Folder1'. Finally everything else will be put in 'C:\Root'.

After confirming the 'Workspace Folder Mappings' dialog and the 'Workspace Creation' dialog the workspace will be created with the specified mappings.

2.2. Why are all my files checked out when creating a workspace?

Typically you will create a workspace in a new location. In this case PureCM will download all the workspace files and there will be no files checked out.

If you create a workspace in a directory where the files already exist then PureCM will automatically checkout the files which exist. Note that PureCM does not overwrite your local files. It checks them out to show that they have been changed. You can then revert these edits if the changes are not relevant (e.g. creating a workspace over an old workspace where the files were not deleted).

Note that if you do not revert these changes, it is very dangerous to submit the edits. If you make some changes without a workspace and then create a workspace using these files - any changes submitted between you getting the initial files and creating the workspace will be lost.

We therefore strongly recommens that you always create a workspace in a new location.

3. Updating to Latest

3.1. What Are 'Pending Changesets'?

Updating a workspace with PureCM is a 2 stage process.

    1) PureCM downloads the new changes and file data from the server. This operation creates a 'pending changeset' for each newly submitted changeset.

    2) PureCM integrates each 'pending changeset' into your workspace.

By default the 'Options | Integration | Automatically Integrate Pending Changsets' flas is set. In this case after doing the download (1) PureCM will attempt to integrate each pending changeset automatically (2). If the integration is successful then you will never see the 'pending changesets'.

If this option is disabled or if the automatic integration failed then you will need to manually integrate the pending changesets. Right-click the first pending changeset and select 'Resolve' to launch the PureCM Resolve Tool. See the User Guide 'File Conflicts | PureCM Resolve Tool' for details on how to manually integrate a changeset. Note that you can only integrate the first pending changeset. It would not make sense to integrate the changesets in a different order from which they were submitted.

Alternatively you can right-click the 'Pending Changesets' tree item and select 'Integrate'. This will try and automatically integrate each pending changeset and will launch the Resolve Tool if an integration fails.

The automatic integration will fail if the pending changeset has changed a file which is being changed in the workspace. If the 'Options | Integration | Automatically Merge Non-Conflicting Edits' flag is set then PureCM will automatically merge the edits if they are on different lines. If the same line on a file has been changed in the worksace and also in a pending changeset then the Resolve Tool will always be launched to resolve the conflict.

4. Showing File Differences

4.1. I do I see what files have been changed on the server (Update Preview)?

If you right-click on a workspace and select 'All Tasks | View Outstanding Changes' this will launch the Folder Compare Tool showing which files have been changed on the server. This shows the differences between the last updated changeset in your workspace and the latest changes on the server. This will not show any workspace changes you have made.



If you double-click a file it will launch the PureCM Differences Tool showing the file differences.


If the workspace is out-of-date it will have the 'clock' icon.



Out of date files will be illustrated by the 'clock' icon and a blue backgroud.



If a file is out of date and is checked out this will have a red background to indicate a potential conflict which should be resolved as soon as possible. You can resolve the conflict by running 'Update to Latest' which will launch the PureCM Resolve Tool.



The workspace gets the status of server files every 30 seconds for each workspace (so if you have 10 workspaces, each workspace will be updated every 300 seconds). You can force the workspace to get the latest file status by right-clicking the workspace and selecting 'All Tasks | Refresh Status'.

4.2. How do I compare my file with the server version?

When I 'Show Differences' on a file it show the changes I have made to the file. In the general case this is exactly what I want. However, there is also the situation where another user has submitted some changed to the file and I want to see what the changes are before 'Updating to Latest'. Is this possible with PureCM?


If you right-click on a file nd select 'All Tasks | Differences | Server Version' it will compare the local version of the file with the latest server version. If you want to see all the changes which have been submitted since your last update you can right-click the workspace and select 'All Tasks | View Outstanding Changes'. This will launch the Folder Comparison window shwoing which files have changesd.



Double-clicking on a file will launch the PureCM Differences Tool.

5. Synchronising the Workspace

5.1. What does 'Synchronise a Workspace' mean?

By synchronising a workspace you put all files back to a previous changeset.

A typical situation where this might be useful is if you find a bug and want to know when it was introduced. You might then synchronise back 10 changes and see if the bug still exists. By doing this multiple times you can isolate the exact change which introduced the bug.

5.2. How do I synchronise back to when a child stream was created (label)?

Right-click the workspace and select 'All Tasks | Synchronise'. This will launch the 'Synchronise Details' dialog. Select the ' To the revision current when a Changeset was submitted' option.

If you select the '...' button this will launch a dialog allowing you to select a changeset. Notice that this dialog includes all child streams. So you just need to select the changeset before when the stream was created.

In the picture above this will synchronise the workspace back to when the '1.8.2' release was created.

5.3. How do I get a deleted file back?

I have a file which was not checked out but has been deleted. How do I get the latest version again using PureCM? I tried doing an 'Update to Latest' and a 'Revert' but it is still missing.


If you right-click the file and select 'All Tasks | Synchronise' this will launch the 'Synchronise Details' dialog. Check the 'Force the latest revision to be written to disk' checkbox and press 'OK'. This should create the latest version of the file.

Alternatively you can run 'Check Consistency'. Click on a Workspace or Workspace Foler and run 'Check Consistency', or use 'pcm consistency --missing'.

6. Local Changesets

6.1. How do I move a file from one local changeset to another?

If I accidentally add a source program to the wrong changeset, how do I remover it from one changeset and add it to another one that I am working on? (Neither Changeset had been submitted yet).

You can right-click a current changeset and select 'Add Change Items'. This will bring up a dialog allowing you select which files you want to add to the selected changeset. By default, all files in the 'My Changes' will be selected but all files in local changesets will not.

Alteratively you can launch the same dialog by launching the changeset dialog for the current changeset (select 'Properties) and pressing the 'Add Items' button.

7. Writable Workspaces

7.1. What are writable workspaces

By default, when creating a workspace all files are made read-only. This is generally good because you have to check the file out to start working on it - which will make it writable. Checking a file out is recommended because this allows you to keep track of which files you are working on.

The problem comes when you are working on a lot of files and your IDE does not intergrate with PureCM. It can be a real pain to have to manually check out each file before you start working on it.

In such situations it is recommended to create a writable workspace. When creating the workspace, uncheck the 'Checked-in files are read-only' checkbox under the 'Advanced options'.

Now all the files are writable - so you do not need to check them out before working on them. All you need to do is run 'Check Consistency' before you submit to identify which files have been edited/added/deleted.

It is recommended that you enable the 'Check Consistency before Submit' option in the GUI 'Options | Submit' page.

This will mean you do not need to take the extra step of running Check Consistency before you submit. Simply select 'Submit' from the Local Changesets item in the GUI tree. This will run the Check Consistency Wizard with the same settings as the last time you ran it. The necessary files will be checked-out/added/deleted and the Changeset Dialog will be lauched ready to submit.

7.2. How do I see which files have been changed

In a writable workspace you work on files which are not checked out. When you want to see which files you have changed/added/deleted you should run the Check Consistency Wizard.

Another feature of the writable workspace is that all workspace files which have been changed without being checked out are highlighted with a red background.