May 11, 2009

Search File Contents Utility

Surround SCM
A common request is to add a feature to Surround SCM that allows the user to search file contents. I have created a utility that you can use to achieve this. It is a .NET application created with Visual Studio 2008 and is written in C#. The application uses the Surround SCM Command Line Interface (CLI) to retrieve information from Surround SCM. It's worth noting that this is the first version of this utility. As time allows, I plan on improving this to add better search options and maybe also query the database directly for certain operations. The entire Visual Studio 2008 is provided, so feel free to download it and make changes that better fit your needs. If you think other users may find those improvements helpful, you can upload the file and make it available as well. [toc]

How the utility works

The utility uses the CLI for most of the work. It retrieves the list of mainline branches and then retrieves the list of branches based on the selected mainline. It then does a recursive get (latest) to a temporary directory where the utility performs the search. The results are displayed in sscm:// format, which allows you to double-click the file and have the Surround SCM client select the file. You can then view the file history, check it out, view it, etc.

Why this approach?

Instead of using the CLI, the other approach could have been to query the database directly. After careful consideration, it was determined that the CLI was the best approach. These are some of the factors considered:
  • Access to the Database System: The utility would need enough access to query the database. A DBA might not feel comfortable providing this access to users, especially in highly regulated industries.
  • Rebuilding the Files: Surround SCM only stores change information in the database. Also, the file contents are stored in binary format. The utility would first have to convert the binary data and then rebuild the file. I would not have been able to provide source code for this application because it would contain proprietary information.
  • Database System: Surround SCM supports both PostgreSQL and MS SQL (2005 & 2008). The first version would have probably only supported one of these.
The CLI requires the same access that any user has that uses the client. Also, the process of rebuilding a file is already done by a get operation.

Using the utility

The application stores its settings in a configuration file, named SCMConfig.xml, which is stored in the same location as the executable. When the application is started, it first looks for this file. If the file is not found (when the application is run for the first time), the Settings tab opens automatically.


The Settings tab includes the following fields:
  • Temporary Folder Location: Enter the location where the utility will create a temporary directory, named SCMTemp, to get the files to. The utility will delete the directory and recreate it each time a search request is initiated. The working directory is not used because it may contain modified files. Note: In order for the utility to delete the folder, it needs it to be writable. Same thing for its contents. The get command that the utility calls is set to make the files writable.
  • Surround SCM Server Address: The address of the Surround SCM Server. Ideally this should be in the same format that the GUI client uses.
  • Surround SCM Server Port: The port the Surround SCM Server is running on.
  • User Name: The user name to use when passing CLI commands. This user must have permission to log in via the CLI.
  • Password: Password for the user. Only field that is not required.
Following is a screenshot of the Settings tab:

Figure 1 - Settings tab

Saving the settings

Click the Save button to save the settings to the configuration file. Once the configuration file is saved the utility calls the CLI to get a list of mainline branches.

Finding files

Figure 2 - Find Files tab

The Find Files tab includes the following fields:
  • Mainline: Select a mainline branch to get a list of branches to search.
  • Branches: The list of branches is populated after a mainline is selected. Select the branch to search for files.

Figure 3 - Branch selection

  • Text to search: Enter text to search for. At this time, it is considered a case-sensitive, exact phrase search.
  • Find Files: Click the Find! button to perform the search. Files that include the specified text will be displayed in the sscm:// link format.

Figure 4 -Search Results

  • Go to File: Select any of the found files and double-click it (or click Go to File) to select the file in the Surround SCM client. If the Surround SCM client is not open, the utility starts it. Hint: Set your Surround SCM client to Always login with this username and password. Surround SCM will try to authenticate you each time you click on a link. If this option is not selected, a separate instance of the client will be opened each time a selection is made. Also, if the Surround SCM Server address is different in the settings than what it is in the connection settings for your Surround SCM client, it may cause a separate instance of the client to open.

Figure 5 - Result in Surround SCM client


The entire Visual Studio 2008 is provided here. You can find the compiled binary under the SCMFileContentSearchSCMFileContentSearchbinDebug directory.