The motivation for the Hackystat Workspace construct is to provide a way for the system to recognize that two or more absolute file paths actually refer to the same file, even when the individual file paths originate from different operating systems and/or local copies of the source code under configuration management control.

As a concrete example, consider two developers, Sharon and Sam, who are working on a system called Saturn. The source files for Saturn are all located in a directory tree whose root is a directory called Saturn. One day, Sam decides to work on Saturn's config.xml file, located in Saturn/lib/config.xml. Sam uses a Windows machine and maintains a local copy of CVS modules in the directory c:\cvs. He uses his CVS client application to check out the latest version of Saturn into the directory c:\cvs\Saturn. As he works on config.xml, his Hackystat editor sensor will thus record Active Time associated with the file c:\cvs\Saturn\lib\config.xml. When he's done, he commits his changes back to CVS.

After the daily build fails the next day, Sharon decides to fix Sam's changes to config.xml. Sharon uses a Unix machine, and she keeps her local copies of CVS modules in /usr/stone/work. She users her CVS client application to check out the latest version of Saturn to /usr/stone/work/Saturn, and then begins work on config.xml. Her editor will thus record Active Time associated with the file /usr/stone/work/Saturn/lib/config.xml.

Although Sam and Sharon are working on the same file, the absolute paths recorded by the two tools for this file are quite different: c:\cvs\Saturn\lib\config.xml and /usr/stone/work/Saturn/lib/config.xml. In order to support even the most simple analysis, such as the total time spent editing the config.xml file, Hackystat must somehow see beyond the superficial differences between these two absolute file paths and recognize that the underlying file is the same in both cases.

The Hackystat Workspace and WorkspaceFile abstractions solve this problem. Workspaces map two directory paths that look different but should be viewed as the same to the same Workspace. WorkspaceFiles are built off of Workspaces, and map two absolute file paths to the same WorkspaceFile if and only if the underlying file should be viewed as the same file for the purpose of analyses.

There are two steps to generating a Workspace from a raw file path. First, Hackystat automatically transforms the raw file path to a canonical, OS-independent representation. This involves changing forward slashes to backward slashes. Table 3.1, “Raw File Path to Canonical File Path” illustrates the canonical form of the two example file paths given above after applying this first step.

The two automatically generated canonical paths are a bit more similar than their raw file path counterparts, but for the system to actually recognize that config.xml in both cases refers to the same file, some explicit help from the user is required. The second step in creating the Workspace represention requires the user to specify "Workspace Roots", which are the "root" directories containing the project directories. In our example, Sam stores his copy of the Saturn source code in the directory c:\cvs\, while Sharon stores her copy in /usr/local/stone/work. Thus, Sam must define c:\cvs\ as a Workspace Root, while Sharon must define /usr/local/stone/work as a Workspace Root.

Table 3.2, “Canonical File Path To Workspace” illustrates how the canonical file path combines with Workspace Root information to create Workspaces and WorkspaceFiles.

As the table illustrates, given a canonical file path and a Workspace Root, Hackystat generates a Workspace by stripping off the Workspace Root and the actual file name. If Sharon and Sam specify their Workspace Roots correctly, then their raw data for the config.xml file will generate the same Workspace (Saturn\lib), and the same WorkspaceFile (Saturn\lib\config.xml). This enables Hackystat analyses to compute the total Active Time associated with this config.xml file across a set of developers who may be working on different platforms and who locate their project files in different places. Of course, many developers work on multiple platforms, or have multiple local configuration management repositories. Hackystat allows you to define as many Workspace Roots as you need to handle these situations.