Understanding the Vault Client

A collection of information about Vault, including solutions to common problems.

Moderator: SourceGear

Post Reply
Posts: 3647
Joined: Tue Dec 16, 2003 1:17 pm
Location: SourceGear

Understanding the Vault Client

Post by jclausius » Fri Mar 19, 2004 10:05 am

Lately, I've answered user questions regarding problems encountered by first-time users of Vault. Additionally, I've noticed some bloggers expressing their experiences with Vault. If you would like to gain a better understanding of Vault Client basics, please read on.

1) Understanding the Vault Tree / Working Folder data
One of the features of the Vault Client is the use of a distributed cache for each repository source tree. Because the client has up-to-date information about the repository source tree, it is less dependent on the server for retrieving repository changes.

Another design feature of the Vault Client works by only using "file deltas". With this design, the client stores a pristine copy of the latest version for a file in which you executed a "get". This is known as a file's baseline version. So, when you modify and commit a file change, a delta is computed against this baseline file. The transmission of this smaller based "delta" is what gives Vault its performance edge when transmitting information over networked connections.

By default, this information along with other client settings, such as working folder settings, is stored in %APPDATA%\SourceGear\Vault_1\<AppType>\<Unique Repository ID>\<user>\_sgvault. In this directory you will see other folders named after a hash of the local disk path where the Vault Client executed a "get" command (i.e. c:\dev\work\project). In these sub-directories, you will find the baseline files from the repository.

It is possible to store the _sgvault folders "inline" with your working directories. ( See the option to "Store working folder data inside working folders" ). When this option is enabled, a "get" will create the _sgvault directories directly in the same destination folder of the "get".

Please note, due to the possible performance hit involved , the Vault Client will not move _sgvault folders when the option is changed. If a change to "Store working folder data inside working folders" is made, please execute a FULL GET, so the working folder state information is updated.

Here is another article related to this subject http://support.sourcegear.com/viewtopic.php?t=6

2) Vault over-wrote and lost my changes
The default setting in Vault is to save any information that could be lost during a "get" operation. In this case, your changes are not really lost, just re-located. You can find these backed up files in the _sgbak directory - located in the destination folder of the "get" operation. In the event there was a mishap, simply rename and move these files to their original location.

Please note, there is a setting in Vault to "Save files in backup before overwriting. When this option is disabled, Vault will not move any file into the _sgbak directory that was overwritten during a "get" operation.
  • UPDATE: In later versions of Vault, files copied to the _sgbak folder can be restored using the Vault GUI client. Right-click the parent folder of the item you want to restore changes to and select Properties. Click the Backup Files tab. Add the file or files you want to restore, then click Restore All.
3) A Vault "get" operation does not change my files on disk
When the Vault Client issues a get command, it will store the files in the directory that has been designated through the "Set Working Folder" command. If you think the Vault Client is getting the latest version of files, but your local file has not changed, please try the following steps:
  1. Open the Vault GUI client.
  2. Find the repository's path (ex: $/foo/bar/file.txt) in your source tree.
  3. From the File Menu (or context menu) on the owner FOLDER of the file, invoke "Explore Working Folder".
The files during any get will be retrieved to this location. Verify this folder is the same destination folder where you think the files should be located.

Note, when using the IDE client, you should triple check your working folder settings. The specification for Integrated Source Code Control leaves it up to the IDE (Visual Studio, Visual Basic, etc) to determine the local paths where files will be stored. It is quite common, for these IDEs to change the working folder setting without notifying you of the change.

4) Moving Projects or Renaming Paths to Projects on your local disk
As mentioned above, the default is to store working folder state information in your %APPDATA% directory. However, this can cause problems when a project is moved from location to location or the path to that project is changed on your local disk (the hash of the path is different and cannot be located in %APPDATA%). After moving a folder or renaming a path, you will notice the Vault Client reports the files as Missing†. To correct this problem, you will need to reset the working folder. Once you have set the correct working folders, you will notice the file status is now Unknown†. To remove the Unknown status, a FULL GET will update your state folder information.

Please note, as mentioned above, any overwritten files will be placed in the _sgbak folder.

If you're like me, you eventually find it tiresome to invoke "get" commands and replace files from _sgbak after moving a project around on disk. In this case, I would strongly recommend looking at the option to store working folder state information in the actual working folder. With the _sgvault folders stored within the working directories, moving a project is a snap. Just move the project, point the working folder from within Vault to the new location, and voila', you're ready to go.

One final note. If you are using the Integrated Development Environment (IDE) Client and you move a project, you will need to use either the Windows or Command line Vault Client to resolve these issues I described above.

In conclusion, we're glad you decided to use Vault, and hope you found this information useful.

† - file status definitions http://support.sourcegear.com/viewtopic.php?t=131
Jeff Clausius

Post Reply