HomeGUI clientPrinter Friendly Version

GUI client

Questions specific to the Graphical User Interface Client

1. Getting Started with the PureCM GUI client

1.1. Getting Started with the PureCM GUI client

From PureCM 2009-1 onwards, the GUI has seen a redesign compared to previous releases. This page will explain first time users how to get started with PureCM.

How to populate your repository

  • Use our example database as a starting point and go on creating a workspace.
  • Create your own project. Then create the first version, which will lauch the file import wizard. 
  • To fully customise your import, use a manually created workspace. After creating your project and first version, do not use the import wizard. Instead, click on in the 'Workspaces' view to launch the workspace creation wizard. Indicate the local path to your files in the field “Workspace Path” and confirm. Then go to your newly created workspace and click on the “Check Consistency” icon to list the files. Specify the include/exclude filters and confirm your choice. Finally, click on “Submit” to send the files to the repository.
  • Import an existing repository from VSS, CVS or Perforce. Click here to learn more.

How to navigate the PureCM GUI

PureCM’s GUI views are repository centric, which means that you can efficiently navigate your repository depending on your role. Here is a quick description of each view:

This is where you are now. Once you have created your first workspace, the “Getting Started” screen will be replaced with a summary of your workspaces.
This is the view of your repository managed by the PureCM server. Create projects and browse their content, branch off new versions, define feature branches, take release snapshots and access a project's change history.
PureCM Professional only. Use this view to define “Merge Rules” to automate merging between branches of the same project. Note that PureCM automatically creates merge rules when working with 'Features' in PureCM Professional.
PureCM Professional only. Reports can be based both on changes made and based on tasks. Use them to automate your release note creation or to get insight into your project status. Only
Originally called “Explorer” in previous PureCM releases, this view gives you all: repository overview, permissions, user and user group administration, server administration and more. Only users with at least one administrative policy enabled will see this view.

2. Adding Files & Folders

2.1. How can I add files and folders recursively in the PureCM GUI?

In the GUI if you right-click a folder and select 'Add' this will launch a wizard allowing you to add all files.

An alternative method is to right-click the workspace and run 'All Tasks | Check Consistency...'. Within the wizard you must select that you want to check for new files.

3. Changeset Dialog

3.1. Why are unchanged files reverted when I launch the Changeset Dialog?

If you go to the 'Options | Submit' page you will see a checkbox 'Revert Unchanged Files before Submit'.

If this is checked then all unchanged files will be reverted when you launch the Changeset Dialog for submit. This can be useful because in some situations Visual Studio can check out lots of file which it doesn't change. Many users want these changes to be automatically reverted before submit. You can uncheck this option if you do not like this feature.

Note that if this option is unchecked you still cannot submit a file which has not been changed (unless it is part of a merge or has been renamed). The file will be ignored when you go to submit.

3.2. Shelving your changes within the Changeset Dialog

Shelving is the ability to save work-in-progress changes on the server and potentially transfer these changes to another user/machine if required.

As of the 2008/3 release you can shelve your changes within the Changeset Dialog. Open the Changeset Dialog with the 'Submit' or 'Properties' menus from a current changeset. Within the Toolbar you will see a new 'Shelve' button.

Pressing this button will shelve all changes belonging to this changeset (regardless of whether they are ticked). Please note that Shelving will perform a local checkin (not submit) for all files. So all 'checked-out' files will be 'checked-in'.

4. Resolve Tool

4.1. What is the 'Resolve Tool'?

The Resolve Tool allows you to merge multiple changes to the same file.

For example, suppose you are working on 'file1.txt'. Another user submit a change which also edits 'file1.txt'. When you 'Update to Latest' in the workspace the Resolve Tool will be launched allowing you to merge your file1.txt changes with the submitted changes. Note that this is necessary because your changes will be lost if the 'Update to Latest' simply copies the new version of file1.txt to your workspace.

The Resolve Tool shows the file you are trying to integrate in the top-left, the local file in the top-right and the new merged file at the bottom. When you press the 'Save' button the merged file at the bottom will overwrite your local file.

The Resolve Tool will automatically merge changes on separate lines. So if you have changed line1 and you are integrating a change to line10 then the Resolve Tool will automatically apply your change to line1 and the new change to line10. So the merged file at the bottom will contain both edits by default. If you want to override this behaviour then you can double-click the change you want to be included in the merged file. So for example if you did not want the line10 changes to be included you would double-click line10 in your local file (i.e. the top-right window with the original line10). The merged file will then be updated to not include the changes for line10.

The lines in the merged window are coloured according to where the line has been merged from. If the line is purple then it is a local change (top-right window). If the line is yellow then it is a server change (top-left window). If the line is grey then it has been changed both locally and on the server, but it is the same change.

If the same line has been changed locally and on the server then this will cause a conflict. A conflict will appear as empty red lines in the merged window. The resolve tool will not allow you to save your changes until all conflicts have been resolved. You can resolve the conflict by double-clicking on the line you want to use (top-left window for server changes or top-right for local changes). The merged window will then contain this line and the conflict will be resolved.

Note that you can always left-click into the merged window and edit the file directly. Edited lines are indicated by a small yellow arrow in the edited line margin.

4.2. When will the Resolve Tool appear?

The Resolve Tool can appear when you are:

  • 'Updating to Latest' within a workspace
  • Unshelving a shelveset into a workspace
  • Merging a changeset into a workspace
  • 'Quick Merging' a changeset where the bases do not match (2009/1 Release)

You can determine when the Resolve Tool will appear with the 'Options | Integration' flags.

If the 'Automatically Integrate Pending Changesets' option is not checked then the Resolve Tool will always appear in the above situations.

If the 'Automatically Merge Non-Conflicting Edits' option is not checked then the Resolve Tool will always appear in the above situations if you are editing a file in the workspace which is being changed within the changeset/shelveset you are integrating.

If both these options are checked then the Resolve Tool will only appear if you have changed the same line within a file which has also been changed within the changeset/shelveset you are integrating.

4.3. What does the 'View Original Change' button do?

When resolving conflicts during a merge or integrate, it is sometimes necessary to see what the original submitted change was to a file. This can help you decide how to proceed with the resolve process..

Resolve tool

By clicking the 'View Original Change' button, a diff window is launched showing the changes that were made to the file ..

5. Check Consistency Wizard

5.1. Loading/Saving Include/Exclude Filters

Often the files you want to include/exclude for adding is different depending on the workspace you are working on. For example, when working on a C++ project you might only want to include *.cpp and *.h files. But when you do some work on your website you might want to include all *.html, *.xml, etc. files. Having to redo these filters can be a time consuming task when the filters are complex, and as such many users stopped using the 'Check Consistency Wizard' for added files (or would only run it when they knew they had added some files).

In such situations it is common for Developer1 to forget he added file1.txt on Friday when he submits the work on Monday. Developer2 then gets frustrated when the build fails and Developer1 has to submit a new changeset 'Add missing files'. This also complicated the merge because the merger must remember to merge the 2 changesets together. The situation is even worst for web developers where a missing file might go unnoticed for weeks - until a customer spots it in the website. By this time the file might have been deleted!

The 2008/3 PureCM Release addresses this problem by allowing users to save and load file filters.

When the 'New Files' checkbox is checked on the Check Consistency Wizard, the 'Include/Exclude' filters button will appear.

Pressing this button will launch a Property Sheet allowing you to Add, Update and Delete filters for Include or Exclude. When you are happy with your filters you can save them by pressing the 'Save Filters' button.

6. File History Dialog

6.1. How do I show the Changeset for a file revision?

If I open the File History Dialog for a file can I see the changeset for a revision?

------------------------------------------

Yes. Right-click the revision and select 'Show Changeset'. This will launch the Changeset Dialog.

 

In server history the 'Show Changeset' option should be available if only one revision is selected. In worksapce history it should be available if one revision is selected and the revision is not a local revision.

7. Show Differences Tool

7.1. Why does the Differences Tool not show spaces?


In the Show Differences options could you check whether the 'Ignore Whitespace Differences' option is checked. If this is cheked then all spaces, tabs and newlines which are added/deleted will not be dispayed as a difference.


8. Stream/Folder Comparer

8.1. How do I compare a file revision against the same file in a different stream?

The easiest way to do this is to select the folder the file belongs to in the stream (not the workspace) and select 'Compare With'. This will launch the Stream Comparer with the contents of the selected folder on the left. Select the stream you want to compare against by clicking the '...' button on the right.

This will launch the Stream Selector allowing you to select the destination stream. After selecting the stream and confirming with 'OK' all different file will be colored green. You can now double-click the file you want to compare which will launch the Diff Window to show the differences.

If you want to compare a particular file revision with another stream (rather than the head revision) you can open the Stream Comparer by clicking the '...' button for the left hand side. You will notice at the bottom there is a radio button 'Use Changeset'. Select this radio button and press the '...' button to select a changeset.

You can therefore select the changeset for the revision you want to compare. When you confirm this with the 'OK' button, the files on the left will be the files as they were when this changeset was submitted.

8.2. How do I see what files in my workspace are out of date (Update Preview)?

If you right-click the workspace and select 'View Outstanding Changes' this will show you which files have been changed on the server since you last did an 'Update to Latest'.

9. Options

9.1. 'Check Consistency' before Submit

If this option is set then PureCM will run the 'Check Consistency Wizard' before a current changeset is launched for submit. This is especially useful if you are using a writable workspace and always want PureCM to check which files have been edited before submitting.

Note that as of the PureCM 2008/3 release the Check Consistency Wizard will no longer ask for any parameters in this mode. It will use the same setting as when 'Check Consistency' was last run manually (i.e. by clicking 'Check Consistency' on a workspace). So if you want to change the settings you should run it manually first.

9.2. 'Revert Unchanged Files' before Submit

If this option is checked then all unchanged files belonging to a current changeset will be reverted when launching the Changeset Dialog for submit. So when a user goes to submit a changeset, PureCM will loop through each change item and check if the file has changed. If the file hasn't changed it will be reverted.

This is especially useful if using the Visual Studio plugin which creates lots of blank edits under certain circumstances. For example, it will checkout files when they are added to a project.

10. File Type Options

10.1. Diffing and Merging Word Files

From 2008/2 PureCM will support diffing and merging word files 'out of the box' as long as Word is installed on the client machine. If you add a word file to PureCM it should automatically use the file type 'application/msword'. If you open the file it will open the file with Word. If you make a change and select 'Show Differences' it will launch Word to display the differences. If you are interested in how this is setup, so you can customize it further then read on...

If you go to the 'Options | File | Preferences' page you will see an entry for 'application/msword'. Any *.doc or *.docx will automatically use this file type (unless the file type has been manually overridden).

If you open the 'application/msword' options and go to the 'Diff | Apps' page you will see that 'MS Word' has been added as an entry. Because this is the top entry this is the default application which will be used when diffing 2 word files. So this will be launched when calling 'Show Differences' rather than having to use 'Show Differences Using...'.

If you open the properties of the 'MS Word' Options you will see that it calls 'wscript' on the script file "C:\Program Files\PureCM\Client\Scripts\msword-diff.js". This is a simple javascript which is installed when you install the client. The javascript file simply opens Word passing in the relevant files to diff.

10.2. Can I open files using my own editor from PureCM?

If you open the GUI 'Options | File | Preferences' you will see options for various file types.

For each file type you can specify what editor to use, what diff tool to use, etc. For this example lets suppose we want to open all image files in Paint. You first need to add options for the file type 'image/*' so click on the 'New...' button.

Add 'image' as the type and '*' as the Subtype (so this will be used for all image files). Next click on the 'Editors' page to select which editor to use.

In this example we have specified 3 possible editors. Because 'PureCM Editor' is at the top this will be the default editor, so this will be used if you double-click a file or select 'Open'. Alternatively if you right-click a file and select 'Open Using' then a dialog will launch listing all 3 possible editors. So you could specify Paint as the default editor but Paint.Net as a secondary editor which we may want to use from time to time.

'Default Application' refers to the application associated with this file in Windows. If you want to use the default Windows application simply move this to the top of the list by selecting 'Default Application' and pressing the 'Up' arrow.

This may be what you want. If so press 'OK' in this dialog and the Options dialog and try double-clicking on a file associated with the filetype 'image/generic'. It should now launch whatever application you have associated with this file in Windows. Alternatively, try right-clicking on the file and selecting 'Open With'. This will launch a dialog allowing you select the editor from this list.

Try selecting the 'PureCM Editor'. This will launch the PureCM Editor in Hexidecimal mode.

You may notice that 'Notepad' is appearing as an editor, Where it is not valid for image files. Go back to the options for 'image/*' select the 'Notepad' entry and press the delete button to remove it from the list. Note that you can never delete the 'PureCM Editor' entry.

Lets add Paint as an option. Click the 'New...' button and specify the name as 'Paint' and the path as the location of the Paint executable (%SystemRoot%\system32\mspaint.exe). The Params field can be left as %1, this will be filled in as the file name when Paint is called. Tick the 'Default' to make this the defaul editor within PureCM (this will put it to the top of the list).

Click 'OK' and notice that 'Paint' has been added to the list and is at the top.

Now click 'OK' for both the Options dialogs and double-click an 'image/generic' file. The file should now be launched using Paint.

10.3. How do I integrate a 3rd party diff and merge tool (e.g. Guiffy) with the PureCM GUI?

To use another diff or merge tool with PureCM you need to add it to the file types you wish to use it with on each client.

You do this by going to the main options 'Tools > Options' and selecting 'File > Preferences'. This will list a number of file types which have preferences selected on that client.

 

If the file type you wish to use is there you can click the properties button, else you will need to add a new type. This will open up another property window. In this you can view both 'Diff Apps' and 'Merge Apps'.



If Guiffy is set as the default diff or merge tool for that file type on that computer, it should automatically be listed here. If not you will need to add it manually.

For the diff app my machine is using "%1 %2" as the parameters. "%1" is used for the base file path and "%2" is used for the new file path.

For the merge app my machine is using "-s -h1%5 -h2%6 -hm%7 %2 %3 %1 %4" as the parameters. "%1" is used for the base file path, "%2" for the path of a local copy of the server file, "%3" for the local file path, "%4" for the saved merge file path, "%5" for the server title, "%6" for the local title and "%7" for the merge file title.

If you wish PureCM to default to use another diff app you need to move this application to the top of the list. Otherwise you can select "Open with..." from right clicking on various things such as two revisions in the history dialog and this will give you the choice of all the application in the list for that file type.

To resolve a conflict using a different merge tool you need to right click on the file in the conflict window and select "All tasks > Resolve Using...". This will list all available merge tools. Or if Guiffy was at the top of the list you can right click and select “Resolve > Resolve Interactively...”. When you have finished merging in the selected tool you need to save the file. PureCM will ask if you wish to save the merged file, which you do. And this will resolve the conflict inside PureCM.

11. Filter Toolbar

11.1. What is the Filterbar?

 Filterbar

 

The Filterbar allows you to filter many of the lists inside PureCM to make it easier for you to find items or view data.  By default the filterbar will filter all columns in the list by the text that you enter into the control.  If you want to filter by a specific column you need to select it from the drop down menu.

 

Filterbar Menu

 

However some lists have more advanced filters to help you find what you are looking for. You can also select these filters from the drop down menu on the filterbar.

My Issues and Issue Views

Issue views have an extra filter called 'All Fields'. This filter does not search the list but will search the issues themselves. It will compare the text entered into the filterbar against every field your issues. This filter can be slow as it has to filter a lot of information but can be very helpful for finding specific issues.

 

Changeset Lists

All changeset lists (including Integrated Changes, Shelvesets, Submitted Changes etc) give an extra filter called 'Full Description'. This filter does not search any of the list columns but filters on the description of the changeset. This is different that the 'Description' field as this only shows a short description.