Vault Overview - SourceGear



Vault Overview

SourceGear Vault is a version control system built on SQL Server that provides both VSS style (Check Out, Edit, Check In) and CVS style (Edit, Merge, Commit) source control capabilities. Created by the makers of SourceOffSite, Vault is a compelling replacement for SourceSafe and other version control tools.

Advantages of Vault include:

Reliable

Vault's design places a strong emphasis on the integrity of the repository. The Vault repository is stored using Microsoft SQL Server 2000. Furthermore, Vault supports atomic check in transactions (change sets). When checking in a collection of files, the entire check in either succeeds or fails as an atomic unit.

Seamless transition from SourceSafe

A simple-to-use tool is provided to convert any SourceSafe database, including all history information, to Vault repositories.

Familiar features and interface

SourceSafe users will feel comfortable using Vault. The client user interface resembles that of SourceSafe and SourceOffSite – all major features of SourceSafe are present.

.NET Architecture

Vault is built entirely on Microsoft's .NET platform, including C#, ASP .NET and SQL Server 2000.

Open

The Vault server is built as a collection of .NET Web Services. The API provided by these services is fully available. Using the API documentation and commonly available tools, the Vault architecture allows clients to be created for any platform.

International

SourceSafe was created years before Unicode became the prevalent technology for I18N. Vault's design is thoroughly Unicode, largely because of its use of the .NET Framework. Vault is also localization-ready.

Concurrent Development

Vault's support for branching, automatic merging and multiple checkouts is superior to that of SourceSafe, even as the interface and paradigm are familiar to SourceSafe users.

History Explorer

The use of SQL Server as a repository storage allows Vault to easily provide more advanced ways of querying the history of a project.

Tips for SourceSafe Users

Vault has been designed to make a seamless transition from SourceSafe and, at the same time, add many improvements. This has resulted in the following differences.

History Explorer Window

The History dialog is replaced by a top-level, non-modal window that allows browsing the repository history through queries. It also does not include a destructive rollback function except in the Admin Tool, where it is called Obliterate.

Branch exists separately from Share.

In SourceSafe, Branch can only be performed after a Share operation, but Vault allows a Branch operation to happen by itself. The functionality is equivalent.

Atomic Check Ins and Check Outs

Add and Delete operations can be scheduled to happen as part of the next check in. Options exist that allow you to specify whether the operations happen immediately, or whether they are included with the next transaction.

SQL Server database

Vault’s repository is stored in SQL Server rather than a collection of files in an undocumented format.

Request Exclusive Lock

In lieu of Allow Multiple Checkouts, Vault has Request Exclusive Lock. The sense of the option is reversed and the default is to not request exclusive locks on files which are considered to be mergeable.

Terms

We have changed the following terms:

• In Vault, “Repository” (SourceSafe -- “Database”) refers to the place where source control files and history are stored.

• In Vault, “Folder” (SourceSafe -- “Project”) refers to folders in the repository.

Menu Items

The following menu items are no longer used:

• The File / Create Shortcut

• The Edit / Select

• The Web / Check Hyperlinks

• The Web / Create Sitemap.

• Reports (In SourceSafe, these features serve the same purpose as Print commands.)

Show Differences Feature

• Vault only supports the “visual” diff, not “SourceSafe”, not “UNIX”.

• Vault does not include the option to Ignore OS Differences because Vault’s diff code already ignores OS differences.

Miscellaneous Differences

• The Options dialog has no pane for Command Line Options.

• Check In and Check Out only function from and to the working folder.

• Vault does not always require files to be explicitly checked out before editing and checking in. Vault may be configured to create working copies without the read-only bit set.

• The Delete command does not include Destroy Permanently. This functionality is present in the Admin Tool where it is called Obliterate.

• Vault does not have a built-in text editor.

• There is no option to force MS-DOS compatible filenames.

• The Store Only Latest Version feature is not supported. In SourceSafe, it appeared in the File Properties dialog box.

• The Get Latest Version command is used to retrieve changes from the repository into the working copies, including any merge or conflict resolution. A file may not be checked in to the repository unless all changes from the server have been merged into the working copy using the Get Latest Version command.

• Vault makes use of a hidden state folder (named _sgvault) located in the local file system. These state folders keep track of the current version of files downloaded by the client and also store baseline versions of files for later merges. By default the state folders are kept in a user's application data folder, but a general option can be set to keep the state folders in the current working folders.

• All access to the Vault repository occurs through the Vault server. There is no “local-mode client” to manipulate the repository through the file system.

Documentation

The following list of documentation is available both in printable version and on-line. We have also provided help and tips within the application.

• User’s Guide

• Administrator Guide

• SourceSafe Import Tool Guide

• Command Line Client Help, available by typing “Vault.exe help” from a command line

Also available,

• FAQ support on our website

• Technical support via email (vault-support@)

We would like to make this the best source code control tool available. Your input is valuable to us. Please, do not hesitate to contact us with problems or suggestions.

Installation

Hardware Requirements

Both server and client require Windows 2000(SP3) and above for OS.

The .Net Framework is required. For information on the system requirements and installation, please refer to Microsoft.

Server Hardware Requirements

• Server class machine with 1GB RAM

• Disk space requirements dependent on size of source code tree

Client Hardware Requirements

• Client machine capable of running .Net apps

Software Requirements

Both server and client requires Windows 2000 (SP3) and above for OS.

The .Net Framework is required. For information on the system requirements and installation, please refer to Microsoft.

Server Software Requirements

• SQL Server 2000 and above; OR, MSDE 2000 and above

• IIS 5 or above with

• .Net Framework 1.1

Client Software Requirements

• .Net Framework 1.1

Client Installation

Installation of the Vault Client appears as a wizard. Clicking on Cancel at any time will give you the option to exit. Click Exit Setup to cancel and no files will be installed on your computer. Click Resume and the installation will continue.

Welcome to the Vault Client Installer

The installer will guide you through the steps required to install Vault Client on your computer.

Click Next to continue.

Software License Agreement

Please read the license agreement. Check I accept this agreement.

Click Next to continue.

Read Me

Please read the notes concerning the version of Vault being installed.

Click Next to continue.

User Information

Enter your name and company name. Select either Anyone so that Vault appears on the start menu no matter who logs on to the machine. Or, Only for Me so that Vault appears on the start menu only when you log in.

Destination Folder

The default installation location is C:\Program Files\SourceGear\Vault Client. To change this, type a new location in the box. Or, click Browse and locate a different location.

Start Installation

Check Source Code Control Provider if you want Vault to be your default source control provider in Visual Studio (or other compliant IDE). Checking this allows you to check in / check out files from within Visual Studio .NET, Visual Studio C++ 6.0 or Visual Basic 6.0 without using the Vault GUI client.

Click Next to continue.

Install

The program will copy the client files and install the Vault Client. When the copying is complete, click Next to continue.

Installation Complete

Click Finish to close the Vault Client Installation Wizard.

A SourceGear Vault folder will be created in the user’s Programs menu. The folder contains:

• a shortcut to the Vault Client

• Vault User Guide

A desktop icon will also be created.

Using Vault

Working in the Main Window

The Main Window of Vault is divided into three panes: the Folder Tree, the File List and a third pane with three tabs, Pending Change Sets, Messages and Search. The Window also has a Status Bar.

When Vault is opened, you must choose a Vault Server and then a repository within that server to connect to. The Repository Name and the Vault Server Name are then displayed in the title bar.

The main window has a menu bar with the following menus: File, Edit, View, Source, Tools and Help.

The Toolbar

The standard toolbar contains commands for all the basic tasks.

Create Folder

The Create Folder command allows you to create a new empty folder within the open repository.

Add Files

The Add Files command allows you to add new files or folders to the open repository by selecting files or folders accessible on the local machine.

Delete

The Delete command allows you to delete selected files or folders from the repository. If multiple files are selected, the Delete command will delete them all at the same time.

Please Note: The Delete command is non-destructive. The file or folder still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties.

Get Latest Version

The Get Latest Version command allows you to retrieve a copy of the file from the Vault server and place it in your working folder. If there is no current working folder, the Set Working Folder dialog will open first since a working folder must exist before files are retrieved.

Check Out

The Check Out command allows you to check out the latest version of a file or folder. You can then modify the file or folder.

Check In

The Check In/Commit command allows you to commit changes made to local files back into the repository. Files may or may not be checked out prior to checking in, depending on which options are set (See Check In Options.)

Undo Check Out

The Undo Check Out command allows you to undo the check out and not modify the contents of the file in the repository or change the version number.

Share

The Share command allows you to make files or folders appear in two distinct places in the repository.

Branch

The Branch command allows you to break a share (Share Branch) or to copy a file or folder to one or more locations allowing independent edits of the file following the branch (Copy Branch).

View

The View File command allows you to view the repository copy of a file without checking it out.

Edit

The Edit File command allows you to check out and edit a selected file in a single operation.

Diff

The Diff command allows you to compare working files and folders to the repository version or to the last version fetched from the server.

History

The History command allows you to open the History Explorer window to examine past versions to a file or folder.

Set Working Folder

The Set Working Folder command allows you to set a folder on the client machine to retrieve repository files.

Refresh

The Refresh command allows you to refresh the file list and folder tree by retrieving the latest information from the server. This command is merely used to update the display of status information – it does not modify the working folders in any way.

Abort

The Abort command allows you to cancel any current operation. After canceling the operation, the working directory and the repository will be in the same state they were before the initiating command was executed.

Help

The Help command allows you to view the Help files.

The Folder Tree

The Folder Tree is a listing of the folders in the repository. It reflects the status of folders as they exist on the server and does not reflect any pending changes. The Folder Tree is automatically refreshed periodically to retrieve any changes that may have been made on the server. This can be set in the General Options. The Refresh command (found on the Toolbar and View menu) manually refreshes both the File List and the Folder Tree.

Only one folder can be selected at a time. The files for the selected folder are displayed in the File List. Right-click on a folder to bring up the Folder Tree Context Menu for the selected folder.

The Folder Tree can by navigated by using the arrow keys. Up goes to the previous viewable folder and Down goes to the next one below. The right arrow expands the current node (if expandable) and the left arrow contracts the current folder, if contractible.

The Folder Tree displays the following kinds of folders.

• Regular Folders – shown as blue folders.

• Cloaked Folders – shown as gray folders. See Cloak Folders for more information.

• Shared Folders – shown as multiple folders behind one another. See Working with Shares and Branches for more information.

• Pinned Folders – shown as a folder with a pin icon over it. See Pin Folders for more information.

• Ghost Folders – shown as a light outline of a folder. See Ghost Folders and Files for more information.

The File List

The File List displays the files contained in the selected folder. It reflects the status of the files on the server and does not reflect any pending changes. Therefore, shares, pins, adds, deletes, branches, renames, moves, etc will not appear in the File List until they are committed to the server.

The File List must be refreshed periodically to retrieve any changes which may have been made on the server by other users. This can be set to automatically refresh in the General Options. The Refresh command (found on the Toolbar and View menu) refreshes both the File List and the Folder Tree.

One or multiple files can be selected. Right-click on a selected file to bring up the File List Context Menu for that file. Double click on the selected file to bring up View or Edit File dialog box. In the General Options, there is a setting to control whether a double-click’s default behavior will view or edit the file.

The File List can be sorted by clicking on the column headings. The sorted column is indicated by an arrow. An up arrow indicates the file list is sorted in ascending order. Conversely, a down arrow indicates the list is sorted in descending order. Click a different column to sort the list by that column. Clicking on the column which is already used for the sort will reverse the sort.

Following are the default columns for the File List. Other columns are available in the Options dialog, File List Columns pane.

File

The File column lists the names of the file in the selected folder. It also includes an icon for the file to indicate the state of the file. The appearance of the icon indicates the status of the file.

• When the file is not checked out and has not been pinned or shared, the icon is a single blue folder.

• When the file is checked out by a single user, regardless of who it is, the icon includes a red check mark.

• When the file is checked out by more than one user, the icon includes two red check marks.

• When the file is pinned, the icon includes a push pin.

• When the file is shared, the icon is a stack of multiple files.

• When the file is both shared and checked out, the icon is a stack of multiple files with one or two red check marks depending if it is checked out by one or multiple users.

• When a non-version-controlled file exists in your working folder, the icon is a dotted outline of a file (note this type of file will only show up if the “show non-version-controlled files ghosted in file list” option is turned on). See Ghost Folders and Files for more information.

Check Outs

The Check Outs column includes the name of any user(s) who has the file checked out. The term Exclusive appears next to the name if the file has an exclusive lock.

Local Version

The Local Version refers to the version number of the file in the working directory.

Remote Version

The Remote Version refers to the latest version number of the file in the repository.

Status

The Status is a one-word description of the state of the working copy of the file. Following is an explanation of the possible status of a file.

|Status |Explanation |

|(blank) |The working copy has not been edited. The working copy matches the version in the |

| |repository. |

|Edited |The working copy has been edited. The remote version has not changed. |

|Renegade |The working copy has been edited but is not currently checked out. This status only |

| |exists for mergeable files when you require a check out before a check in (see Check |

| |In Options). |

|Needs Merge |The working copy is checked out and edited. The remote version has also been edited. |

| |You must use the Show Merge command before this file can be checked in. |

|Merged |The working copy has been edited. The remote version has been edited and the file has|

| |been merged. You can use the Show Merge command to examine what was done or to revert|

| |back to Needs Merge status. |

|Old |The server copy of the file is newer than the working copy. The working copy has not |

| |been edited. |

|Missing |The working copy does not exist. |

|Unknown |The working copy exists but Vault cannot determine its status. |

|More Recent |The working copy has not been edited and is a version of the file which is more |

| |recent than the current version on the server. |

Ghost Folders and Files

Ghost Folders

If the Show non-version-controlled folders ghosted in folder tree is turned on in the General options, non-version-controlled folders that exist in your local file system along with all their contents* will show up ghosted in the folder tree. Ghost folders will only show up in the file tree if:

• The repository folder has a working folder defined.

• The non-version-controlled folder is not in the “folder exclusions” list defined in the Admin tool and is not a “special” vault folder (_sgvault, _sgbak)

• Ghost folders will not show up in a folder if that folder is cloaked

*If a Ghost folder has files, its files will show up ghosted in the file list if the Show files not in repository ghosted in file list option is turned on.

Ghost folders are updated in the folder tree when you log on, after a full refresh (f5) and after operations that change the folder tree (add folder, delete folder etc), and when the working folder is changed.

Context Menu

The Ghost folder context menu contains two menu items – Add this folder and Explore working folder.

 Add this folder - This command will add the selected ghost folder to the Vault at its current location in the folder tree. If you choose to add a ghost folder that’s parent is also a ghost, then the selected folder’s parent will be also be created in the tree and the ghost folder and all of its contents will be added.

 Explore working folder – This command opens a Windows Explorer window for the corresponding working folder.

Ghost Files

If the Show non-version-controlled files ghosted in file list option is turned on, non-version-controlled files that exist in your local working folder will show up as ghosted in the file list. Ghost files will only show up in the file list if:

• The file’s parent repository folder has a working folder

• The non-version-controlled file is not in excluded by the “file exclusions” list defined in the Admin tool

Ghost files are updated when you click on a folder and when you activate the client.

Context Menu

The Ghost File context menu contains one menu item – Add this file. If at least one ghost file is selected the ghost file context menu will be displayed.

Add this File – The add this file command will add the selected ghost file or files to Vault at the current location in the file list and folder tree. If the file or files selected for addition are in a Ghost Folder, the parent Ghost Folder(s) will also be created in the folder tree.

Pending Change Sets

The Pending Change Sets tab contains a list of all changes, anywhere in the working folders, which are waiting to be checked in to the repository. This provides a constant, visual reminder of items that need to be checked in.

Vault allows one direct change per item in a single transaction. In any given change set, an item will only be listed once. For example, you cannot both rename a file and move it in the same change set.

Multiple items can be selected and operations will apply to the items selected.

Comments can be created for the entire change set or for individual items within the change set. If an item does not have an individual comment associated with its action, the change set comment is automatically applied to it.

Right-click on a file or folder to bring up a Pending Change Set menu for the selected items.

Pending actions can be undone by selecting the action and hitting the delete key, using the Pending Change Set menu or the Pending Change Set toolbar.

The Pending Change Sets tab consists of a list and a toolbar.

List

The Pending Change Sets list contains the following information.

• Item – The full local path of the file or folder name on which the operation is taking place.

• Details – For file modifications, this is the size of the change (e.g., +9KB or -1KB). If the file has a state of Needs Merged, it is listed here instead of the Type column since the type is Modified. For folders, it is the size of all the files being added.

• Type – The type of change. This could be one of the following: Modified, Unmodified, Add, Delete, Branch, Label, Share, Move or Rename.

• Repository Path – The full path in the repository that corresponds to the item.

• Comment – The comment that will be applied to this particular item when it is committed / checked in. To change or enter the item comment, right-click on a selected item (or items) to bring up the Pending Change Set menu and click on Edit Item Comment.

Toolbar

The standard toolbar for Pending Change Sets contain the following commands.

• Commit – The Commit command allows you to Check In/Commit changes to the repository.

• Change Set Comment – You can add or edit the change set comment. Click OK to accept the comment or Cancel to revert to the comment that already exists.

• Undo – The Undo command will undo the selected operation. Modified files are reverted to their previous contents before they were edited, and if the file is checked out, it brings up the Undo Check Out dialog box on the selected item.

• Diff – The Diff command brings up the Diff dialog box for the selected file in the list.

• Show Merge – Brings up the merge window on the selected file. This is only available if the status of the file is Needs Merge or Merged.

• Rescan working folders – Searches all working folders on the local machine for files that have changed, and puts them in the pending change set if they were not already there. This is available only in CVS mode (when “Require Check Out before Check In” is off)

Messages

The Messages tab displays messages during operations to show status. It also displays error messages (displayed in red) that do not require user action. Typical examples of error messages would be permission problems, transactions that fail or not being able to write to files.

This pane supports select and copy operations. The Copy command is available through the right-click menu or Ctrl+C.

Search

The Search tab gives you the ability to search for files by status or filename in a selected folder.

Toolbar

The standard toolbar for Search contain the following commands:

• Search In – Select a folder in the Folder Tree to begin a search. The selected folder will appear in the Search box. Select a different folder and the contents of the Search In box will be updated as well as the new search results.

• Search By – Select the type of search –either a search by a specific status or a filename. When a new status is selected, a new search is automatically performed.

The default is Don’t Search and no searches will occur when this is selected.

• Username – A list of all Vault users for the current repository will appear when the Checked out by status has been selected. Select the user to search on.

• Recursive – When checked, the search from the selected folder will be recursive to include all subfolders.

The default is unchecked

• Lock onto this folder– This allows you to keep the search results on a locked folder as you select other folders in the tree. Normally, selecting other folders will update the search results automatically. If you want the search results for a folder to remain in the list regardless of which folder is currently selected, check this box.

The default is unchecked.

• Background updates – Check this to continue to update the search on the selected folder even as you use the Pending Change Set tab or the Messages tab. To notify you of a change, the Status Search on the tab will become bold.

Lock onto this folder must be checked in order to use this option. The default is unchecked.

• Filename – When a Filename search is selected, this input field becomes active. Enter the filename you wish to search on, and use ‘*’ for wildcards. Press Enter to start the search.

List

The Search list contains the following information. You can right click on an item to bring up the Status Search Context Menu. You can also double click an item to display it in the main file window.

• Item – The name of a file matching the search criteria.

• Repository Path – The full path in the repository that corresponds to the item.

• Status – The status of the file matching the criteria.

Email

The Email tab allows you to be notified by email if there are changes to the contents of the tree.

Toolbar

The standard toolbar for Email contain the following commands:

• Add – Add a folder in the to the list in the Email pane to be notified when anything under that folder is changed. The currently selected folder in the Folder Tree is the folder that will be added to the list.

• Delete – Remove item selected in the Email list. Once removed, you will no longer receive email notifications for that folder.

List

The Email List contains the list of all folders within the Vault tree that you will receive email for when the contents change.

You can double click an item to display it in the main file window.

Email List Control

Underneath the Email List a control shows the email address that will be used to notify you of changes. If you edit the email address, the “Change Address” button will become enabled. Pressing the Change Address button will cause Vault to send email to the new address.

Status Bar

The status bar displays the following information.

• Status Messages – Displays Ready when nothing is happening and Working, Uploading, Downloading, and Updating Local Files, etc when an operation is in progress.

• User – Lists the name of the user who is currently logged in.

• Secure Connection Status – Displays a padlock icon when the user is currently connected with SSL.

• Connection Status – Shows the connection state: Connected, Offline or Connecting.

• Progress Meter – Shows the progress of operations as they occur.

Working with Repositories

In Vault, a repository stores a logical grouping of files. You can have multiple repositories per server. It is recommended that you keep unrelated projects in separate repositories.

You cannot share or branch files across repositories. So, files that need to be shared must exist in the same repository.

Connecting to the Server

Use the Connect to Server dialog box to connect to the Vault server. The dialog box will display when Vault is started unless you have previously chosen to automatically connect.

After the first connection to Vault, the server and username will automatically be filled in. If you previously used a profile to connect, the connection information will be automatically filled in and that profile will be selected by default in the Select Profile dropdown.

Once you are logged in and connected to a server, you can connect to a different server by invoking the Connect to Server command in the File menu.

If you click Cancel from the Connect to Server dialog box and are not currently logged in, the client remains in an unconnected state.

Profiles

Profiles are named sets of connection information. A profile stores connection information to different servers or different configurations of a server allowing you to use that profile to easily connect to a server.

For example, if you have 2 servers you normally connect to and each server has 2 repositories that you regularly use, you can define 4 profiles, one for each configuration, and to connect to each server/repository configuration using the profile, so you don’t have to remember the connection information.

To automatically connect to a server and then to a repository, you must use a profile.

Profiles are selected from the Connect to Server dialog, and are created and edited using the Edit Profiles dialog.

Choosing Repositories

The Choose Repository dialog box is displayed when you are connecting to the server (unless you are using a profile that automatically opens a repository).

To select another repository from the server you are already connected to, activate the dialog box by clicking Choose Repository from the File menu. You can also choose the Ctrl+P key.

When the Choose Repository dialog box is opened, the repositories you have access to in the currently connected Vault server are displayed. The repository’s version and number of files and folders will also be displayed. Access to a repository is set by the administrator in the Admin Tool.

If you Cancel the repository selection and a repository is open, the current repository remains open. If no repository is open and you click Cancel, you will remain connected but no repository will be open. To open a repository, select the File menu item and then select Choose Repository.

Disconnecting from Server

To disconnect from the current server go to the File menu and click Disconnect from Server.

Working with Folders

Create, Add and Delete Folders

Creating Folders

The Create Folder command is used to create a new empty folder within the open repository. If a repository has enabled security rights, the user must have permissions set by the administrator in the Admin Tool to create folders. The dialog box can be activated in several ways.

• Click Create Folder from the File menu.

• Select Create Folder on the Toolbar.

• Right-click on a folder to bring up the Folder Tree Context Menu, select Create Folder.

• Select the INSERT key.

If Auto-Commit has been selected (default), the folders will be created in the Vault repository immediately. If Auto-Commit has not been selected, the folders will be created in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Adding Folders

Adding folders uses the same process as adding files. See the Adding Files section for more information.

Deleting Folders

The Delete command deletes the selected folder and all of its contents, recursively, from the repository. If a repository has enabled security rights, the user must have permissions set by the administrator in the Admin Tool to delete folders. To activate the Delete dialog box, click Delete Folders from the File menu.

Please Note: The Delete command is non-destructive. The items still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties dialog box.

The Vault client does not allow operations which destroy history. To destroy history, use the Obliterate command available in the Vault Admin Tool.

Delete a Pinned Folder

A folder with a primary pin can be deleted.

A folder with a secondary pin cannot be deleted (except as part of a deletion on the pinned ancestor). For example, if $/foo/bar is pinned, then the delete operation will succeed at $/foo and $/foo/bar but will fail on any subfolder or file within $/foo/bar. An error message will be displayed if a delete on a secondary pin is attempted. Please see Pin Folders for more information.

Commit Delete

If Auto-Commit has been selected (default), the folders will be deleted in the Vault repository immediately. If Auto-Commit has not been selected, the folders will be deleted in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Check Out and Check In Folders

Checking Out Folders

The Check Out command allows you to retrieve the latest version of the folder and set the working copy to read-write. Select the item to be checked out and do one of the following:

• On the Source menu, click Check Out.

• Select Check Out on the Toolbar.

• Right-click on the selected folder to bring up the Folder Tree Context Menu, click Check Out.

• Ctrl+O.

If a working folder is not set for the item, the Set Working Folder dialog box will appear. After successfully setting the working folder, the check out procedure will continue.

The Check Out on a folder is a multiple (possibly recursive) file checkout. It does not lock the folder and still allows other users to add or delete files from the folder. Use of check out on a folder is discouraged since in most cases an entire directory of files need not be checked out together.

Checking In Folders

The Check In/Commit dialog box allows a user to check in all pending files. Select the item to be checked in and do one of the following:

• On the Source menu, click Check In.

• On the Toolbar, click Check In.

• Right-click on the selected folder to bring up the Folder Tree Context Menu, click Check in.

• Ctrl+I.

• On the Pending Change Set tab, click the Commit button or select an item and hit Ctrl+M.

Check In comments can be added in the Comment field of the Check In/Commit dialog box. Additional Check In options that can be selected on the dialog box include: Keep Checked Out and Remove Local Copy. See the Check In Options to set additional options.

When checking in a folder, only items within that folder that are also in the pending change set will be listed in the Check In dialog for inclusion for the transaction.

Rename and Move Folders

Renaming Folders

The Rename command allows the names of files and folders to be changed. To activate the dialog box:

• Click Rename from the File menu.

• Right-click on the selected item to bring up the Folder Tree Context Menu, click Rename.

• On the keyboard, use the F2 key.

Checked Out Folders

A folder can be renamed at any time except if it is pinned or if any files are checked out in that folder or subfolder.

Working Folders

If the working folder is inherited, the rename will alter the current working folder and the rename will act as if you changed the working folder. This means that all the files in the selected folder will have their status changed to Unknown or Missing. If you specify a working folder for the folder that is renamed, the working folder and the status of all the files in the folder will not change. See Rename and Working Folders for an example.

Commit Rename

If Auto-Commit has been selected (default), the files and folders will be renamed in the Vault repository immediately. If Auto-Commit has not been selected, the files and folders will be renamed in the repository as part of the next check in transaction.

Please see Auto-Commit more information.

Moving Folders

The Move command allows you to move folders from one folder to another. To activate the dialog box, click Move from the File menu.

Moving a folder will lose any associations with working folders that currently exist. If there are explicit rights assigned to the selected folder, they will move with the folder. However, inherited rights from parent folders will not.

Commit Move

If Auto-Commit has been selected (default), the files and folders will be moved in the Vault repository immediately. If Auto-Commit has not been selected, the files and folders will be moved in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Pin Folders

Folder pins allow you to pin an entire folder at the current version or an earlier version of the folder (primary pin), secondarily pinning all of its files and subfolders (secondary pin). This prevents you from adding, deleting or performing any operation on any file or folder within the pinned folder. To activate or deactivate, click on Pin/Unpin on the Action menu on the History Explorer menu.

The folder primary pin takes precedence over the subfolder or file primary pin. You cannot pin a file or folder that currently has a secondary pin on it, even if it also has a primary pin. Since pinning increments version numbers of folders, you can safely pin a folder that currently has a file or subfolder with a primary pin.

If a folder is pinned to a previous version, the folder will appear in your folder and file list exactly as it did in the previous version. Files that existed but have since been deleted will be displayed. Items that did not exist at that version are not displayed.

Status

If a folder is pinned at a previous version, the pin status of every file is reverted to its pin status at the version the folder was pinned. Unpinning the folder reverts back to the current pin status of the files. For example, if a file is pinned in folder version 8 but not in folder version 5, and the folder is pinned to version 5, the file appears unpinned in the newly pinned folder. Unpinning the folder will revert the file to pinned (its current state). Once the folder is pinned you cannot pin or unpin any files within the folder.

After a folder pin, the tree state gets refreshed, but no files themselves are retrieved, so the status of the files will be newer if you pin a folder to a previous version. Unpinning the folder will again refresh the tree state, but not re-get anything. If you pin a folder to a previous version, do a Get Latest, unpin it, then files that have changed since that version will have a status of Old after the unpin.

Shares

Pinning a folder at a previous version causes all shares within the folder to be temporarily broken until the folder is unpinned. This is true regardless of whether the file was shared in the current version or in the version being pinned.

Commit Pin

You can only Pin from the History Explorer. It is placed in its own change set (which is independent of any other pending changes), and always happens immediately, regardless of the Auto-Commit option.

Cloak Folders

The Cloak command allows you to specify that a folder should be ignored during other operations. Right-click the selected folder and click on Cloak/Uncloak.

Working with Files

Add, Detect New, View, Edit and Delete Files

Adding Files

The Add Files/Folders command allows you to add new files or folders to the open repository by selecting items accessible to the local machine. You can include or exclude any file or folder underneath the selected folder, and a default exclusion list automatically excludes files or folders containing defined string patterns.

To activate the dialog box, do one of the following:

• Select Add Folders/Files from the File menu.

• Select Add Folders/Files on the Toolbar.

• Select Add Folders/Files from the destination Folder’s context menu.

• Ctrl+N

In addition to invoking the Add Folder/Files command, you can also simply drag a file or a folder to the file list pane of the main window. This will automatically bring up the Add Folders/Files dialog with the contents of your selection from the Windows Explorer.

Commit Add Files

If Auto-Commit has been selected (default), the files and folders will be added to the Vault repository immediately. If Auto-Commit has not been selected, the files and folders will be added to the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Detecting New Files

The Detect New Files command allows you to see which files exist in your local working folder that do not exist in Vault, therefore allowing you to easily add newly created files to the repository.

To activate the dialog box, do one of the following:

• Select Detect New Files to Add from the File menu.

• Select Detect New Files to Add from the destination Folder’s context menu.

Viewing Files

The View File command allows a user to view the latest version of a file without checking it out or replacing the local copy of the file. To view the most recent version in the repository, select a file. Then do one of the following to bring up the View File dialog box.

• On the Edit menu, click View File.

• Click View on the Toolbar.

• Right-click the selected file to bring up the File List Context Menu, then click View.

• Double-click the selected file.

Editing Files

The Edit File command checks out a file and launches an external editor in a single operation. Select a file and do one of the following to launch the editor.

• On the Edit menu, click Edit File.

• Click Edit on the Toolbar.

• Right-click the selected file to bring up the File List Context Menu, then click Edit.

Working Folder

A working folder must be defined in order to edit a file. If the working folder is not defined, the Set Working Folder dialog box will be displayed first. Canceling the Set Working Folder will cancel the Edit command.

Check Out

After the working folder is set, the Check Out dialog box is displayed. If Check Out is cancelled or if the check out fails for any reason, the Edit operation is cancelled. If you successfully check the file out, the file will come up in the selected editor.

Editor

In Windows, Notepad is the default editor. To select a different editor as a default, please see External Programs Options.

Deleting Files

The Delete command allows you to delete files from the repository. If multiple files are selected, the Delete command will delete them all at the same time. A user must have permissions set by the administrator in the Admin Tool to delete files. To activate the dialog box, click Delete from the File menu or on the Toolbar.

Please Note: The Delete command is non-destructive. The file or folder still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties dialog box.

The Vault client does not allow operations which destroy history. The Obliterate command is available in the Vault Admin Tool.

Checked Out Files

You can delete a file that is currently checked out, even if it is exclusively checked out. A warning message is displayed before allowing this. If you attempt to check in a file that has been deleted, an error message will be displayed.

Pinned Files

A file with a primary pin on it can be deleted. A file with a secondary pin can be deleted only if the parent folder with the primary pin is also being deleted. For example, if $/foo/bar is pinned, then the delete operation will succeed at $/foo and $/foo/bar but will fail on any subfolder or file within $/foo/bar. Please see Pin Files for more information.

Commit Delete

If Auto-Commit has been selected (default), the files will be deleted in the Vault repository immediately. If Auto-Commit has not selected, the files will be deleted in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Check Out and Check In Files

Checking Out Files

The Check Out command allows you to notify others that you intend to make changes to a file and, in the case of exclusive locks, to prevent any other user from checking in a change while the file is locked. Select the item to be checked out and do one of the following:

• On the Source menu, click Check Out.

• On the Toolbar, click Check Out.

• Right-click on the selected item to bring up the File List Context Menu, click Check Out.

• Ctl+O

If a working folder is not set for the item, Set Working Folder will appear first. After successfully setting the working folder, the check out procedure will continue.

A mergeable file can be checked out by multiple people at the same time. A binary file or a file that is checked out exclusively may only be checked out by one person at a time.

Note that a file does not need to be checked out before being checked in if the Require Checkout before Check In option is off. This option can be set in the Check In Options.

If a shared file is checked out, it appears checked out from all links in the share. If it is checked out by multiple users, then all names are listed in all locations of the shared file, regardless of which link the file was checked out from. For more information, please see Check Out or Check In Shares.

Check Out File Multiple Times

The same user can check out a file multiple times, once per machine. When you check out a file multiple times, your name appears multiple times in the file list and the location is listed in the file properties as a separate checkout.

Checking in such a file is the same as checking in a file that is checked out by multiple people. The file will need merged if there are conflicts. Undoing the check out in one location does not affect the check out in other locations.

Checking In Files

The Check In/Commit dialog box allows a user to check in all pending changes to files or folders. Select the item or items to be checked in and do one of the following:

• On the Source menu, click Check In.

• On the Toolbar, click Check In.

• Right-click the selected item to bring up the File List Context Menu, click Check In.

• Ctrl+I.

• On the Pending Change Set tab, click the Commit All button or select an item, hit Ctrl+M.

Check In Comments can be added in the Comment field of the Check In dialog box. Additional Check In options that can be selected on the dialog box include Keep Checked Out and Remove Local Copy. See the Check In Options to set additional options.

If you have Bug Tracking Integration, you will be able to associate the file being checked in with a known bug at this time.

If a file is currently in a Needs Merge state (because it has been modified both locally and remotely since you retrieved it), it cannot be checked in until the merge has been resolved. Please see Merge for more information.

Rename and Move Files

Renaming Files

The Rename command allows the names of files and folders to be changed. To activate the dialog box, do one of the following:

• Click Rename from the File menu.

• Right-click on the selected file to bring up the File List Context Menu, select Rename.

• Select the F2 key.

A file cannot be renamed if it is currently checked out by anyone.

If a shared file is renamed, you cannot give it a name of any item (file or folder) that exists in any of the shared link’s parent folders. Changing only the case of the file name will work like any other file rename, including incrementing the version number.

If Auto-Commit has been selected (default), the files and folders will be renamed in the Vault repository immediately. If Auto-Commit has not selected, the files and folders will be renamed in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Moving Files

The Move command allows you to move files from one folder to another. To activate the dialog box, click Move from the File menu.

Moving a file will lose any associations with working folders that currently exist. Inherited rights from parent folders do not move with the file.

If Auto-Commit has been selected (default), the files and folders will be moved in the Vault repository immediately. If Auto-Commit has not selected, the files and folders will be moved in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Pin Files

Pinning a file prevents it from being modified. Essentially, it makes the pinned version the current version of the file and prevents any change to the file that would increase its version number. Doing a Get Latest will retrieve the pinned version of the file. To activate or deactivate, click on Pin/Unpin from the Source menu in the Main Window, or Pin/Unpin in the Action menu on the History Explorer.

Restrictions

• You cannot pin a file that is already pinned. You must unpin it before pinning it to a different version.

• You cannot pin a file that is currently checked out.

• You cannot pin a folder that has a file checked out anywhere below it.

Delete a Pinned File

You can delete a pinned file. If it is undeleted, it remains pinned at the same version number as when it was deleted.

Branch a Pinned File

Branching a pinned file will automatically unpin it at the new location. Branching a shared pinned file will unpin it at its current location since branching a shared file keeps the file in its current location.

Pin a Shared File

If a file has a primary share associated with it, the pin only applies to that link of the shared file. Other links can modify and retrieve the current version. When that shared link is unpinned, the most recent version is immediately available (e.g., the changes made to it via other shares is now available at that link).

If a file has a secondary share associated with it, the pin applies to all links of the secondary share.

Share a Pinned File

If a file is pinned and is then shared (either a primary or a secondary share), the newly shared file inherits the pin. Unpinning a file that is automatically pinned after a primary share unpins it only for that link. All other links are still pinned and must be unpinned individually (just as they were all shared individually).

Please see Share Items for more information.

Commit Pin

You can Pin the current version of a file or folder from the main window, or you can Pin a historical version from the History Explorer. Pin operations are placed in their own change set (which is independent of any other pending changes) and always happens immediately, regardless of the Auto-Commit option.

Working with Shares and Branches

Share Items

The Share command allows you to make files or folders appear in two distinct places in the repository. To activate the Share dialog box, do one of the following:

• Click Share from the Source menu.

• Click Share on the Toolbar.

• Right-click on the selected item to bring up the context menu, click Share.

Any change made to the file or folder in any of its shared locations will be reflected in all locations after the change is made. A file or folder can be shared in any number of other locations.

Shared files and folders are no longer shared when there is only one link remaining after a Branch or Delete command. Once all share links have been deleted or branched, the file is no longer shared. See Branch Items for more information.

Primary and Secondary

A Primary Share is a share on the file or folder itself and will appear as shared in the file list. A Secondary Share is inherited from a folder share and does not actually appear shared in the file list. See Primary and Secondary Shares for examples.

Shared Folders

A Folder Share keeps two or more folders completely in-sync with each other so that any change to the folder or its contents (adds, deletes, check ins, renames, etc.) is automatically updated in all folders that are part of the share. This has the effect of introducing a secondary share on all the files and subfolders within the shared folder to their counterparts in the other links of the shared folder. See Folder Shares for examples.

In a shared folder, individual files and subfolders within the folder are not displayed as shared in the file list unless they were shared prior to the folder share operation. This allows the individual files to be shared elsewhere and differentiates between existing file shares and folder shares. This also allows branching file shares without affecting the folder shares they are a part of. However, any sharing or branching of individual file shares within a folder share are reflected in all links of the folder share.

A folder cannot be shared into one of its descendent folders in order to avoid circular references.

Modified Shares

If you attempt to share a file and another user has modified the file before the share has been committed, the operation still succeeds and the latest version of the file is the one shared.

Likewise, if you share a folder, but files have been added or deleted since you last refreshed, the files that make up the latest version of the folder in the repository are shared.

Name, Rename, Move Shares

A file or folder cannot be shared into a folder with a file or folder of the same name.

A file or folder can be shared into a folder with a deleted item of the same name. See Delete for details.

A shared file or folder can be renamed or moved. All the links are updated to show the new name of the file or location of the new link. A shared file has only one name – renaming it in one location renames it in all locations.

Check Out or Check In Shares

When you check out a shared file, the checkout information is displayed in all links of the share. For example, if Joe checks out $/foo.txt and Mary checks out $/bar/foo.txt, and they are shared, then both Joe and Mary are displayed in both locations as users who have the file checked out.

You must Check In a shared file from the same location it was checked out. In the example above, Joe can check in $/foo.txt, but not $/bar/foo.txt.

Likewise, you must Undo Check Out a shared file from the same location it was checked out.

Delete Shares

Deleting a shared file keeps the share information with the deleted file so that if it becomes undeleted, it will automatically be shared as it was prior to the delete. Deleting a shared file with only one other link will cause the shared file that wasn’t deleted to appear unshared although both files will become shared again after an undelete. Undeleting a shared file when all other links in the share have since been deleted or obliterated will not cause the undeleted file to appear shared.

Obliterating a deleted share will break the link to the shared file. The contents are not really deleted since it came from a share, which is not itself obliterated. However, the shared file is of course no longer available from the location where it was obliterated.

Commit Share

If Auto-Commit has been selected (default), the files will be shared in the Vault repository immediately. If Auto-Commit has not selected, the files will be shared in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Branch Items

A Branch allows you to break a link for a shared file, creating a separate file at the location it was shared (Share Branch). It also allows you to branch any file or folder, whether it is shared or not (Copy Branch).

To activate the Branch dialog box, select a file or folder, then do one of the following:

• Click Branch in the Source menu .

• Click Branch on the Toolbar.

• Right-click on the selected item to bring up the context menu, click Branch.

You can select multiple files at the same time, but only one folder at a time to branch. When a new file or folder is created by the branch it is given a new version number. However, there is not a new version number at the folder or file that is being branched.

Branches on Folders

All branches on folders are implied recursive, just as all folder operations in the file explorer are implied recursive. You cannot branch on an item that is currently deleted.

Branching a folder maintains shares between files and subfolders that are self-contained within the branch, but breaks shares to any link outside the new branch. See Branching a Folder for examples.

Share Branches

For an item that is already shared, branch breaks the share link. The location of the newly branched file or folder does not change but underneath the file or folder contents are copied to that location.

If a folder branch is applied to a primary shared folder, it is a Share Branch and implied recursive. If a folder branch is applied to a Secondary Share on a folder, the operation is a Copy Branch rather than a Share Branch. You can only Share Branch from a Primary Share. See Share Branch for examples.

Copy Branches

For an item that is not already shared, this command requires you to specify the location and name of the new branch. If there are multiple files selected, only one location is prompted for and all files are placed in the location selected.

The results of a Copy Branch become a full-fledged member of the source tree. The newly branched tree items come pre-filled with a history of changes from their branched ancestor.

Snapshots

A Snapshot is similar to a branch, except that it automatically pins the folder that gets created. Before version 2.0, snapshots were called labels. Version 2.0 of Vault implemented Labels as tags on a folder rather than separate entries in the tree. Snapshots are equivalent to Version 1.0 labels.

• Snapshots vary from branches in the following ways:

• Snapshots are only available on folders

• A snapshot folder is clear rather than blue.

• Snapshots are automatically pinned after they are created.

• You can hide snapshot folders from your tree unchecking the “Show snapshots in folder tree” option in Tools->Options.

• If you do a recursive Get Latest operation above a snapshot, it will not retrieve the snapshot. Snapshots are only retrieved if you do the Get on the snapshot itself.

• If a folder is shared, doing a snapshot on the shared folder will create a snapshot, not break the share. (If you were to branch a shared folder, it would break the share. This is not the case for a snapshot).

• You cannot cloak a snapshot folder, because they already act as a cloaked folder would.

It is recommended that you use branches or labels to mark a version of a tree. Snapshots are simply a historical oddity.

Working with Labels

A Label tags a version of a file or complete folder structure, allowing you to go back later and retrieve the file or folder based on the label name you gave it, rather than having to remember the version number. Vault’s Labels are similar Visual SourceSafe labels. Once applied, the label remains associated with the version of the file or folder structure it was labeled at, even as new modifications are made on the original objects.

To activate the Label dialog box, select a file or folder, and then do one of the following:

• Select a folder on the Main Window, and invoke the Label command.

• Select an individual file or group of files on the Main Window, and invoke the Label command. In the case of multiple selected files, the client will create individual file label requests to the server.

• Highlight a historical item from the History Explorer, and invoke the Label command.

You can label any version of a file or folder. In the case of a labeled folder, all sub-items of the folder will be stamped with an “inherited” label tag. Any file or folder can be labeled, including $/.

Labels do not increment the version numbers of the object after application. As such, they do not occur as part of a change set, and always are applied immediately.

The label’s text must be unique regardless of case. This also includes inherited labels. Although a Label’s text must be unique per object, there can be multiple labels associated with one specific version.

Deleted Items

When an item is deleted, the label remains, even though you can’t see the labels applied to an item while it is deleted. However, deleted items that had inherited labels applied to them will be retrieved during a Get Label operation on the ancestor, and will be displayed when viewing the label.

For example, if you label $/foo, then label $/foo/bar, and then delete $/foo/bar, you will not be able to retrieve the label on $/foo/bar (because it is currently deleted, and you can’t get any information on it other than it is deleted). However, getting the label on $/foo will retrieve $/foo/bar as it existed at the time of the label.

When an item is obliterated, any labels applied directly against that item will be removed from the database. Additionally, the obliterated item will be removed from any inherited labels. A Get on a label will not retrieve obliterated items.

Pinned Items

You can label a file that is currently pinned at a previous version and it will be applied to the pinned version, not the current version

Shared Items

You can label a shared file or folder. The label will create the label for the shared object and appear in the history of all shared links.

Because shared items will have labels applied from ancestors of any of its shared links, it is a requirement that label text be unique across all labels applied to any shared item.

Viewing Labels

Select Show Labels to view labels applied to the currently selected file or folder, including inherited labels that were applied above the file or folder.

From the same dialog you can also view labels that have been applied to items below the currently selected folder (e.g., recursively search the tree from this folder downward to find labels that have been applied to sub-files and sub-folders).

Label Promotion

Label Promotion is when you modify the contents of a label. Through Label Promotion, you can change the text of the label as well as the associations of file or folder versions of a specific label.

If the label has been applied to a folder, promotion will allow you to:

• Add files found in the current version of the source directory, which do not exist in the label’s folder.

• Change versions of current files found in the label’s folders to previous or later versions.

• Delete files and sub folders from the label.

Once a label has been promoted, it is no longer associated with a single version of the folder the label was applied to. As such, there are operations that can no longer be performed on the label. These include:

• Share

• Branch

• Pin

Label promotion is accomplished from within the Show Labels dialog.

History

As files and folders change over time, their history is stored in the Vault server, which is accessible to users via the History Explorer. You can also save pre-defined queries via History Favorites, which allow you to quickly query based on common history requests.

History Explorer

The History Explorer window is used to examine past versions to a tree or repository. The query features available in the History Explorer window offer a powerful way to see what has happened over the passage of time.

Click Show History on the Tools menu, History on the Toolbar or click Show History on the context menu. The History Query Filter command will come up to allow you to select a query. There are two main ways to query on folders:

• View by item – Select View by item to view the Version List. The Version List displays the Name of the file or folder, User, Date, Version Number, Action and any Comments

• View by version – Select View by version to view the Folder Versions screen. The Folder Versions shows all versions of the TOP folder in a list. Each version of a folder corresponds to a change set that changed some part of the folder or its descendants. This dialog box lists the versions and allows you view the change set that caused the folder to increment its version number.

In addition, you can save a pre-defined query via the History Favorites command.

History Favorites

History Favorites allow you to define history criteria so that common searches can be easily run without re-defining the query.

A History Favorite query can be run from the View->History Favorites->(favorite name) menu item from the main window menu, or from the History Favorites->(favorite name) menu item in the Vault Folder and File History context menus.  A History Favorite query can also be run from the Edit History Favorites dialog.

Merge

Merge allows you to handle you have modified a file locally on your client and someone else then checks in another version on the server underneath you. In this situation, the changes applied on the server must be merged into the local version before a checkin can take place, otherwise the server changes would be overwritten when you check in your file.

This command has two different, but similar, functions:

• Resolve conflicts between the two files

• Examine how Vault automatically resolves the conflicts.

The first case will arise when the you specify Merge Later on the Get Latest Version dialog box, or when an attempt at an automatic merge has failed. When either of these situations happens, select Show Merge to specify how the conflicts should be resolved.

The second will arise when you specify Attempt Automatic Merge on the Get Latest Version dialog box and the automatic merge succeeds. In this case, select Show Merge to examine precisely what was done by the automatic merge.

To activate the Merge window, select Show Merge in the Source menu or from the context menu.

Background

A merge involves four files:

• Baseline File – The original version of the file before edits.

• Local File – The local working copy.

• Repository File – The new version of the file in the repository made by a different user.

• Merged File – The file created by merging both the local and the new repository file together, to be checked back into the repository.

A successful merge will replace the local working copy with the merged file. This is true for automated merges that have produced no conflicts as well

If the repository (server) copy is revised again after a local merge has been completed, then the baseline file changes to the version of the file that was merged against locally. This essentially becomes a new merge at that point, and if an automatic merge reveals a conflict based on the new baseline, you must manually resolve them again. If there is no conflict, the results of the automated merge will replace the local working copy.

You have the ability to view a merge that has occurred on the current baseline only. If you do not like how the file was merged, click Undo on the Merge window to revert back to a local file’s pre-merge state.

Merge Window

Selecting Show Merge brings up the merge tool you have specified in the Options. By default, this is SourceGear’s DiffMerge. Documentation for SourceGear DiffMerge is available from within the tool itself. Documentation for others tools is available from the vendor who provides the tool.

Merge Branches

The Merge Branches command allows you to merge changes from any folder in Vault to any another folder within the same repository. Usually, these are folders that have been branched from each other and modifications have been continuing in one or both of them. At some point, you may want to resolve all differences between the branches, or move all the changes from one folder to another. Note that although the common case is to merge together branches that have a common ancestor, there is no requirement that they be related – any two folders can be merged.

The folder from which changes are to be migrated is called the origin folder, and the folder which changes are to be applied to is called the target folder.

To do this, go to the Tools menu and click Merge Branches. A wizard will come up to lead you through the steps.

The first page of the wizard will explain the steps in this operation. The merge has three phases:

• Moves ands Shares

• Renames

• Everything else

The Move and Rename operations are actually committed to the repository as the wizard progresses. The other changes are not committed but are put in the Pending Change Set for your review.

Merge supports the following operations:

• File modifications

• File and folder Renames, Moves, Adds and Deletions

• File and folder Shares. Shares created within the origin are created in the target folder, but are not shared between the origin and the target.

Shares going into or out of the origin are not shared in the target. Files and folders in the origin that are shared outside the origin will be ignored in the target, but a warning message will be put in the summary page indicating this. Files and folders shared into the origin will be treated as adds, with a warning message saying they are shares, and those items will be yellow in the list.

• File and folder Share Branch

• File and folder Copy Branch and Folder Snapshot. These are treated as adds in the target, and not as branches or Snapshots.

The following operations are completely ignored when merging a folder. The changes in the origin will not be applied in the target, and they will not show up in the wizard list:

• Cloak

• File Property Change

• Pin Status

• File and Folder Label

• Folder security changes

• File/folder undelete. Since branches don’t create deleted items in the branch, you can’t undelete a file or folder in the branch that existed in the trunk. You can delete and then undelete a file in the branch, but this won’t have any effect in the trunk unless the file was modified in some other way.

The screens in the Merge Branches are:

Welcome Screen

This screen describes the process the Merge Branches operation will have, and the items the user will need to specify to use the command.

Specify Origin Folder

This screen allows you to select the “origin” folder from which changes are to be migrated into a target folder

Specify Target Folder

This screen allows you to select the “target” folder, which will be modified to contain the changes that have been applied to the origin folder.

Select Changes To Be Merged

This screen allows you to select which changes in the origin folder to apply to the target folder. Select two versions of the folder, and differences between those versions in the origin folder will be applied to the target folder.

The earliest version you choose essentially becomes the baseline version between the origin and target folders. If the target file is different from the baseline version you’ve chosen, then a file merge takes place between the source and target files to resolve the differences, so that both sets of differences will be reflected in the merged target version.

Select the versions by using CTRL and the left mouse button to select exactly two versions.

Settings

This screen allows you to enter the following settings:

• Attempt Automatic Merge on Individual Files. If checked, Merge Branches will attempt to automatically resolve conflicts in files that have been changed in both the origin and the target folders. If unchecked, any file that needs merged will be added to the pending change set with “Needs Merge” status, and you will need to manually resolve each merge.

• Comment box (optional). Enter the comment that will be used by default as the change set comment for the changes that result from the Merge Branch operation.

Moves And Shares

The Move/Share page lists all the move and share operations to be performed as part of the merge.

• Items which cannot proceed are shown with a red background. For example, if a file was modified in the branch but has been deleted in the trunk.

• Items which appear to be harmless are shown with a white background and they are check by default. For example, renaming a file in the branch which has been unchanged in the trunk is an operation which will proceed by default.

• Items which can proceed but may be undesirable are shown with a yellow background. For example, if a file was renamed in the branch but has also been renamed in the trunk (to something else), then this operation will not be checked and will be shown in yellow.

• Items which do not need to proceed are shown in blue. These are cases where the trunk is in exactly the state it would be in if the merge were to occur anyway. For example, if a file has been renamed in the branch and has been renamed the same way in the trunk, then nothing needs to be done.

Choose the items that are to be included in the merge by selecting the checkbox next to each item. The move operations will be performed and committed to the repository as the wizard proceeds.

Renames

The Rename page lists all the rename operations in the same manner as the Move/Share list. Choose the items that are to be included in the merge by selecting the checkbox next to each item. The rename operations will be performed and committed to the repository as the wizard proceeds.

Retrieve Files from Server

In order to do the merge branch operation, files are retrieved from the server, so Vault can compute the differences between the version. The Retrieve Files from Server page shows you the status of the file downloads as they are being downloaded from the server.

Adds, Deletes, Edits

The Adds, Deletes, Edits page lists all adds, deletes and edits in the same manner as the Move list. Choose the items that are to be included in the merge by selecting the checkbox next to each item. These operations will be performed, but will not be immediately committed to the repository. Instead, they will be placed in the Pending Change Set for your review and can be committed once you’ve reviewed the changes. Any files in a Needs Merge status after the Merge Branches will need to have their conflicts resolved before the changes can be committed.

Modify Files

The Modify Files page simply shows you the progress of the merge and when it is completed.

Summary

The Summary page will show you all the operations that were performed and the ones which remain pending.

Binary Files

Merge operations cannot be done on binary files. However, a binary file can have a status of Needs Merged if it was modified locally and then checked out after another user checked in a change to the file. You can overwrite the version in the repository and change the status to Edited by selecting Merge. A warning dialog will appear.

Click Yes and the status of the file becomes Edited and the working file is not touched.

Click on No to cancel the operation. The file will retain the Needs Merged status.

Vault Options

General Options

Act on Folders Recursively

This option allows you to specify whether commands should operate recursively on folders instead of simply on the folder itself and the files directly within it. Several dialogs boxes contain a checkbox labeled Recursive. This global option establishes the default setting for all such checkboxes. If you change the recursive checkbox in one of the dialog boxes, it does not change the global option.

The default is Checked.

Always Request Exclusive Locks

This option allows you to establish a default for the Request Exclusive Lock checkbox in the Check Out dialog box. An exclusive lock on a file means that no one else can check the file in or out while the current user has it checked out.

The default is Checked.

Double Click on File

This option allows you to specify which operation to will be activated on a file that has been double-clicked. The possible values are:

• Edit

• View

The default is View.

Automatic Refresh

This option allows you to specify whether the Vault client should automatically perform the Refresh command and, if so, at what interval.

The default is Checked with the interval set at 10 minutes.

Show Snapshot in the folder tree

This option allows you to specify whether snapshots will appear in the tree control. This setting is for all snapshot folders – there is no option to display some but not others.

The default is Checked.

Show non-version-controlled files ghosted in file list

Check the Show non-version-controlled files ghosted in file list option if you want non-version-controlled files that exist in your local working folders to appear ghosted in the Vault file list.

Show non-version-controlled folders ghosted in folder list

Check the Show non-version-controlled folders ghosted in folder tree option if you want non-version-controlled folders that exist in your local working folders to appear ghosted in the Vault folder tree.

Enabling this option may slow down the load of the folder tree depending on the number of non-version controlled folders that exist in your working folders.

Make Vault your default SCC provider

Check Make Vault your default SCC provider if you want Vault to be your default source control provider in Visual Studio (or other compliant IDE). Checking this allows you to check in / check out files from within Visual Studio .NET, Visual Studio C++ 6.0 or Visual Basic 6.0 without using the Vault GUI client. Please see Visual Studio Integration for more information.

NOTE: The “Express” versions of Visual Studio do not support source control integration, and enabling this option does not override these limitations.

The default is set during installation of the Client.

Always display command dialog on Get Latest Version (available from IDE only)

In the IDE, the Get pre-command dialog does not come up by default, due to the way Visual Studio calls into Vault, which asks to display the dialog far more often than seems necessary. By default, Vault ignores these requests, so that the Get dialog does not get in the way of retrieving files. However, the Always display command dialog on Get Latest Version option, when checked, will dutifully display the dialog everytime Visual Studio asks Vault to. Sometimes this is valuable, for example, when you want to apply different Get options to different files as part of the Get.

Always disconnect from server on Add/Open To/From Source Control (available from IDE only)

In the IDE, you can switch projects while the IDE is still up. However, if you select or open a project that is stored on a different Vault server, the login dialog does not come up by default to allow you to choose a different server. Checking the Always disconnect from server on Add/Open To/From Source Control will bring up the dialog on operations where it is possible you might want to choose a different server.

Version Check

When the Vault GUI client is started, it does a few checks to verify the version numbers of the product you are running. One of these checks contacts the SourceGear website to see if you are running the most recent Vault release. No information from your computer or repository is transmitted to SourceGear. Nonetheless, if you prefer to disable this Version Check, you can do so by changing this setting.

Check In Options

Always Keep Files Checked Out

This option allows you to establish a default for the Keep Checked Out checkbox in the Check In/Commit dialog box.

The default is Unchecked.

Remove Local Copy after Check In

This option allows you to establish a default for the Remove Local Copy checkbox in the Check In/Commit dialog box.

The default is Unchecked.

Auto-Commit after each Operation

This option allows you to specify that all global operations except Check Out and Check In happen immediately. These include add, delete, label, pin, branch, move, rename, pin/unpin and property changes. With Auto-Commit off, these operations are put into change sets, and you must explicitly commit or check in the changes. See Pending Change Sets for more information.

The default is Checked.

Require Check out before Check in

This option allows you to specify that only files explicitly checked out can be checked in.

When this option is off, the file status of Renegade does not exist because it is assumed that any file that has been modified is going to eventually be checked in and is therefore not renegade. (See Status in the File List section for more information on Renegade files.)

In addition, when this option is off, all files that have been modified are included in the checkin dialog list of files to be checked in. When on, only files that are checked out appear in that list.

The default is Checked.

Check in Unchanged Files

This option allows you to establish the default for checking in files that have not changed. This option only applies to files that are explicitly checked out.

Select one of the following two options.

• Check In – Checks the file in normally which creates a new version. However, the diff will show no changes between versions.

• Undo Check Out – Uses the Undo Check Out command so the file’s version does not increment. This is the default.

The default is Undo Check Out.

Local Files Options

Modified Working Copy

This option allows you to establish a default for Modified Local File list in the Get Latest Version dialog box and the Check Out dialog box. This option applies only to files that have been modified locally in the working folder or have Unknown status and not to files that are known versions in the repository.

• Overwrite Working Copy – This overwrites the local file. If the file is not in your working directory (because you changed the To: field in this dialog), it will simply be overwritten. If the file is in your working folder and has a status of Unknown, it will be backed up in the _sgbak directory before being overwritten

• Do Not Overwrite/Merge Later – This will not overwrite an existing file if it has been changed locally. If the download is to the working folder, it will still download a new repository version into the hidden state folder, allowing you to manually merge the file later (in which case the file’s status becomes Needs Merge). If the download is not to the working folder, the file will simply not be retrieved.

• Attempt Automatic Merge – Vault will attempt to merge the changes from the server copy into the working copy. If it can do so without irresolvable conflicts, then it will do so. All three files will be archived so you can examine precisely what was done in the automatic merge step. However, if the file cannot be merged automatically, the behavior is identical to that of the Do Not Overwrite setting above: the working copy is untouched and you must resolve the conflict later before a check in is allowed. A message is written in red in the Messages pane for each file that could not be merged.

• If the file is being retrieved to a folder other than the working folder, this option is disabled altogether, since the working folder is required for merges. Overwrite becomes the default in this case.

The default is Attempt Automatic Merge.

Prompt before overwriting locally modified files

If checked, a dialog will be displayed before a locally modified file is overwritten by Vault, verifying the user’s choice for how to handle the file. This prompt will only be displayed for files that have been modified by the user. It does not apply to versions of files that can be re-created by the Vault server (e.g., files with an Old status).

Save files in backup folders before overwriting

If checked, any file that Vault cannot recreate will be backed up into a backup folder. See Cache/Backup Locations for the location of the actual backup folder.

The default is Checked.

Perform Repository Deletions Locally

This option allows you to establish a default for the Perform Repository Deletions Locally list in the Get Latest Version dialog box as well as the Check In/Commit dialog box.

Select one of the following options.

• Remove working copy

• Do not remove working copy

• Remove working copy only if unmodified

The default is Remove working copy only if unmodified.

This option also for renames and moves and is applied in the following manner.

• Do not remove working copy – the file will be copied and renamed or moved.

• Remove working copy – the file will be renamed or moved.

• Remove working copy only if unmodified – if the file has been edited, the file will be copied and renamed or moved.

The default is Remove working copy only if unmodified.

Make Writable

This option allows you to establish a default for the Make Writable list in the Get Latest Version dialog box.

Select one of the following options.

• Make binary files read-only

• Make all files read-only

• Make all files writable

The default is Make all files read-only.

Set File Time

This option allows you to establish a default for the Set File Time list in the Get Latest Version dialog box as well as the Check Out dialog box.

Select one of the following options.

• Current – the time the file was downloaded from the server.

• Modification – the time the client reports it last modified the file. This does account for time zones, but can not account for incorrect times set on a client machine.

• Check In – the server time at the time this version was checked in.

The default is Current.

On Undo Checkout

This option allows you to establish a default for the Local Copy option in the Undo Check Out dialog box. It determines what to do with the local version of a checked out file when that file’s checkout is undone.

Select one of the following options.

• Revert – Overwrite the local file with the baseline version (the version of the file that existed at the time of the check out).

• Leave – Do not modify the local file after undoing the check out.

• Delete – Remove the local file from the file system after undoing the check out.

The default is Leave.

Override Native EOL Type

This option allows you to override the current End of Line setting for files that are set to use “Native” EOL. The Native EOL is determined by the operating system the client is currently running on. For example, if this is a Windows client, the Native EOL for a file is CRLF, and text files retrieved from the database will use Windows EOL.

This option allows you to change the Native EOL type for this user to a value other than the current operating system. For example, if this is a Windows client, but retrieves files to a working folder that is actually a Unix disk, you can change this value to Unix when getting files to that folder so it will have the correct End of Line characters.

This value only overrides when the EOL type is Native for a given file. If the file’s EOL type is set to anything else, it will be used instead of this.

Select one of the following options.

• Do not override – Don’t override – continue to use the Native EOL type.

• Windows (CRLF) – Use CRLF when Native EOL is specified.

• Unix (LF) – Use LF when Native EOL is specified.

• Mac (CR) – Use CR when Native EOL is specified.

The default is Do not override.

Detect Modified Files Using CRCs Intead of Modification Times

This option allows you to determine whether files have been edited based on their contents instead of using the modification time of the file. A CRC is a computed number that is theoretically unique based on the contents of the file.

Using this option will cause Vault to be slower than using modification time when determining file status.

Only use CRC checks for files smaller than [size]

Since CRC checks are slower than modification time checks, this option allows you to compute the CRC only when a file is below a certain size, which allows CRC checks to be faster than they otherwise would be. However, any files above the size specified will still use modification time to determine file status.

Cache/Backup Locations

Store Client Cache Folder

The client cache is where Vault stores state information (such as working folder associations) and other data for faster retrieval (such as a copy of the repository structure).

By default, these cache files are located in the current user’s Local Settings folder (e.g., C:\Documents and Settings\user\Local Settings\Application Data\SourceGear). [Note, prior to Vault 3.1, these files were stored in the Application Data settings folder, such as C:\Documents and Settings\user\Application Data\SourceGear, so if your cache files are there, it is because that machine had a Vault version prior to 3.1 loaded].

You may change the location of these files to any disk location, but in doing so you will cause the client to lose all of its state information. For example, your working folder associations will be lost, and after being manually restored, the files in the working folders will have Unknown statuses (if your baseline files are stored here too – see next option below).

If you want to keep your client state, it is recommended that you move your state files into the new location prior to changing the location of the cache files (which you can do via the link provided in the options dialog).

NOTE: This change does not take effect until you restart the client. It is highly recommended that you restart the client immediately after changing this option.

Store Working Folder State/Baseline Files

A baseline file is the version of the file the user retrieved from the server prior to editing it. Baseline files provide Vault with working folder state information, enabling the client to know when a file has been edited, and is also used to compute a delta for the file that is sent to the server (so that less information needs to be sent and stored).

These baseline files can be stored in one of two places: Inside the client cache folder (whose location is determined in the option above), or within the working folder itself. Because these folders will grow quite large, you will want to make sure they are located in a place where there is plenty of disk space.

If you choose to store baseline files inside the working folder, an “_sgvault” folder will be created in each working folder.

As with changing the location of the client cache, if you change this option, working folder data and status will be lost (files will become of Unknown status).

The default is “In Client Cache Folder”.

Save files in backup folders before overwriting

If checked, any file that Vault cannot recreate will be backed up into the backup folder specified below.

The default is Checked.

Store Backup Files

This tells the Vault client where to store the backup files. Choosing “In Working Folders”, will place them in a folder named “_sgbak” within the working folder of the file being backed up.

Choosing a custom location will backup the files in the folder that you choose.

The default is “In Working Folders”.

Diff/Merge Options

Default item to diff against

This option allows you to specify the default option when doing a diff of a working file against other items.

Select one of the following options.

• Diff against last version retrieved from the repository. This is the baseline version, and will show you what changes you made to the file.

• Diff against current version in repository. This option will show you what changes you will introduce to the repository version if you check the file in. This is different from the baseline version if someone has checked in another version since you began editing.

The default is Diff against last version retrieved from the repository.

Diff Program

This option allows you to specify an external application to be launched by the Diff command.

Either type the full path to the External Diff program, or use the Browse button to find the diff tool, if necessary. The macro %VAULT_EXE_DIR% can be used to specify the location where the Vault client is currently running, and will expand to the actual folder of the executable folder.

The default entry for this field contains the default that is appropriate for SourceGear’s DiffMerge tool: %VAULT_EXE_DIR%/sgdm.exe

Diff Arguments

This option allows you to specify the arguments to supply to the diff tool when it is invoked, such as the files to use for the diff, and labels to use for them, if the diff tool accepts such arguments. The following macros are available:

• %LEFT_LABEL% - expands to be the label Vault will supply to the file being diffed on the left side of the diff output.

• %LEFT_PATH% - expands to the path of the file that Vault will supply for the left side of the diff output.

• %RIGHT_LABEL% - expands to be the label Vault will supply to the file being diffed on the right side of the diff output.

• %RIGHT_PATH% - expands to the path of the file that Vault will supply for the right side of the diff output.

The default entry for this field contains the default that is appropriate for SourceGear’s DiffMerge tool:

/ro1 /ro2 /title1:"%LEFT_LABEL%" /title2:"%RIGHT_LABEL%" "%LEFT_PATH%" "%RIGHT_PATH%"

Merge Program

This option allows you to specify an external application to be launched by the Merge command.

Either type the full path to the External Merge program, or use the Browse button to find the merge tool, if necessary. The macro %VAULT_EXE_DIR% can be used to specify the location where the Vault client is currently running, and will expand to the actual folder of the executable folder.

The default entry for this field contains the default that is appropriate for SourceGear’s DiffMerge tool: %VAULT_EXE_DIR%/sgdm.exe

Merge Arguments

This option allows you to specify the arguments to supply to the merge tool when it is invoked, such as the files to use for the merge, and labels to use for them, if the merge tool accepts such arguments. The following macros are available:

• %WORKING_PATH% – expands to the user’s working file that is being merged.

• %WORKING_LABEL% – expands to the label supplied by Vault to put on top of the working file.

• %DEST_PATH% – expands to the file that will be saved when the user merges the files together. In Vault, this is actually the same as the working file, but merge tools usually have a separate argument for this, so Vault will just supply the working file as this file.

• %DEST_LABEL% – expands to the label supplied by Vault to put on top of the merged file.

• %OTHER_PATH% – expands to the path of the “other” file being merged. For most cases, this is the current repository version that is being merged, but in the case of merge branches, it is the origin version of the file that needs merged with the target version.

• %OTHER_LABEL% – expands to the label supplied by Vault to put on top of the “other” file being merged.

• %BASELINE_PATH% – expands to the path of the file that is the common ancestor, or baseline between the 2 files being merged.

The default entry for this field contains the default that is appropriate for SourceGear’s DiffMerge tool:

/ro1 /ro3 /merge /title1:"%WORKING_LABEL%" /title2:"%DEST_LABEL%" /title3:"%OTHER_LABEL%" /result:"%DEST_PATH%" "%WORKING_PATH%" "%BASELINE_PATH%" "%OTHER_PATH%"

History/Labels Options

History Diff when single version selected

This option allows you to specify the version the history diff will diff against when only one file is selected in the version list.

Select one of the following options.

• Diff against previous version in repository

• Diff against current version in the repository

• Diff against working folder copy

The default is Diff against previous version in repository.

Label Diff when single version selected

This option allows you to specify the version the diff from the Show Labels dialog will diff against when only one label is selected in the label list.

Select one of the following options.

• Diff against current version in the repository

• Diff against working folder copy

The default is Diff against current version in repository.

Limit Queries to

This option allows you to limit the number of rows returned for a single history or label query. The number must be greater than 0.

This limit exists because the user interface will reach a limit to how many rows of text it can display at one time. This option will ensure that the user interface will always be able to handle the query sent by the server, even if the user accidentally created a query that was not intended and retrieved far more rows than the interface can handle.

The default is 1000 and there is an upper limit of 10,000.

Fetch rows in chunks of

History and label entries are fetched in chunks so you need not wait for all the data to be transferred before viewing the results. As you scroll to areas where data has not been fetched, the history explorer and the labels dialog will automatically fetch the rows needed.

This option allows you to configure how many rows to fetch at a time.

The default is 200 rows.

Act on queries recursively

This option sets the default for whether a history or a label query will be recursive or not.

The default is Checked.

External Programs Options

Editor

This option allows you to specify a default for the external application to be launched by the Edit File commands.

Select either Use system default for this file type or type the full path to the editor. Use the Browse button to find the editor, if necessary.

The default is the system default for the file type.

Viewer

This option allows you to specify a default for the external application to be launched by the View File commands.

Select either Use system default for this file type or type the full path to the viewer. Use the Browse button to find the viewer, if necessary.

The default is the system default for the file type.

Command Dialogs Options

Several commands bring up a dialog box which has a checkbox that says “Only show this dialog when the shift key is down”. If that checkbox is selected, the dialog box will be disabled and will not appear when the commands are opened unless the shift-key is held down.

This option can also be set in the Command Dialogs options.

When the following operations are checked, the dialog boxes will be displayed when the commands are opened. When unchecked, the dialog boxes are not displayed unless the Shift-Key is pressed along with the command. If the dialog box is not displayed, the default selections are used.

The commands used on files that can be disabled:

• Get Latest Version

• Check Out

• Undo Check Out

• Diff

• History Filter

• History Diff

• Label Diff

• Edit

• View

The commands used on folders that can be disabled:

• Get Latest Version

• Check Out

• Undo Check Out

• Diff

• History Filter

• History Diff

• Label Diff

File List Columns

This pane allows you to select which columns you want displayed in the file list of the repository explorer. Checking a column will cause the column to be displayed, and unchecking a column will cause it to not be displayed.

The available columns are:

• Checkouts (the list of users who currently have the file checked out)

• Status (The state of the file, such as Old, Edited, Needs Merge, etc)

• Local Version (the version number of the file on the local machine)

• Remote Version (the current version number of the file in the repository)

• Local Date (the datetime of the file on the local machine)

• Remote Date (the datetime of the checkin of the latest version in the repository)

• Modified Date (the datetime of the last time the file was edited on a client’s machine before it was checked in, and therefore dependent on client machine clock accuracy)

• File Type (as determined by the file suffix)

• Local Size (the size of the file on the local machine)

• Remote Size (the size of the latest version of the file in the repository)

• Checkout Location (the folder on the client machine where the file is checked out)

The default set of columns to display is: Checkouts, Status, Local Version, Remote Version.

Warnings Options

The various warning dialog boxes that appear throughout Vault are listed on this pane. Select the warnings that you do not want to be displayed.

The default for all the warnings is ON.

Concurrent Development Style

This option pane allows you to choose SourceSafe style, CVS style or customize the style for concurrent development. All of the settings exist elsewhere in the options and changing the options here will update the other controls to reflect the new values.

SourceSafe Style Checkout/Edit/Checkin

When clicked, sets options as follows:

• Auto-Commit is on

• Require Check Outs is on

• Make all files read-only is selected

• Always Request Exclusive Locks is on.

CVS Style Edit/Merge/Commit

When clicked, sets options as follows:

• Auto-Commit is off

• Require Check Outs is off

• Make all files writable is selected

• Always Request Exclusive Locks is off

Network Settings

Use chunked encoding

This option allows you to reduce the memory consumption of the Vault Client during file uploads. Without chunked encoding, the entire file must be read into memory before it can be uploaded. This means the amount of memory available on the computer must be greater than the size of the file being uploaded. This setting is not compatible with some proxy servers, routers or firewalls.

The default is unchecked

Proxy

Please note that changes to your proxy settings will not take effect until the next time that you connect to a Vault Server.

Use system default proxy

This setting causes Vault to use the system default proxy which is specified in Control Panel -> Internet Options -> Connections -> LAN Settings. Note that due to a limitation in the .NET Framework, automatic configuration is not supported. If your LAN uses automatic configuration to set the proxy server, you must manually configure that proxy server in Vault.

This is the default setting for Proxy.

Use a manually configured proxy

This option allows you to specify the address and port of the proxy that should be used. Type the proxy server name in the Address text box and the port number in the Port text box.

Do not use a proxy

This option allows you to connect directly to the Vault Server overriding any system default proxy.

Reset proxy user

Click this button to clear any saved authentication information used while connecting to an authenticated proxy

Visual Studio Integration

The Vault source control can be used within one of the supported Integrated Development Environments (IDE). The supported IDEs are:

• Microsoft Developer Studio 6.0 (C++)

• Microsoft Visual Basic 6.0

• Microsoft Visual Studio .NET 2003

Please Note: The “Express” versions of Visual Studio do not support source control integration and enabling this option does not override these limitations.

Enable / Disable Integration

To enable IDE Integration:

• Go to Tools on the Vault client menu bar. Select Options.

• Under General Options, check the “Make Vault your default SCC provider”.

To disable IDE Integration, uncheck the box.

The default setting is unchecked.

Vault Global Options

Vault gives you the ability to work in either VSS mode, CVS mode or a combination of both.

However, when using IDE integration, the IDE that you choose will always work as if in VSS mode. The global Vault options that contradict working in VSS mode are disabled from within the IDE.

Accessing Vault Command Options

When performing basic source code control operations from within the IDE, an Advanced button appears on each of the applicable dialogs. Click Advanced to set Vault’s command options for that particular command.

For example, click Advanced in Visual Studio .NET Check Out dialog to bring up the Vault Check Out dialog. This allows you to set the available Vault options relevant to the check out operation.

Bug Tracking Integration

Vault currently supports integration with two bug tracking systems: SourceGear Dragnet and FogCreek’s FogBUGZ. Bug tracking integration refers to the ability to update bug tracking items from within a Vault client, and for the bug tracking system to see changes in source control that resulted from changing the status of a bug.

Dragnet

Dragnet is Vault’s bug tracking solution and is fully integrated with the Vault client.

Both Dragnet and Vault need to be configured to allow communication with one another. See the Vault Admin Tool for documentation on how to configure the Vault server to communicate with Dragnet, and Dragnet documentation for how to configure it to communicate with Vault.

Updating an Item from Vault

Updating a Dragnet item from within Vaults is accomplished from within the Vault Check In/Commit dialog. From that dialog, you can select or enter a Dragnet item number, mark the item completed, and choose whether to add the Vault checkin comment as a Dragnet comment for the chosen tems.

Viewing an Item in Dragnet

In Dragnet, go to the detail page of a item that was changed from Vault. In the comments section, information about the checkin will be displayed, including a list of files that were included as part of the checkin.

From the comment, you can select the file link of any of the changed files. This will bring up a history of the file’s changes in Vault.

If you select the version number, it will bring up a page that shows the differences between the checked in version and the previous version in the repository (showing how the file changed for this checkin).

FogBUGZ

Vault supports integration with FogBUGZ, a web-based, bug-tracking product developed by Fog Creek Software. ( )

FogBUGZ must first be configured to communicate with Vault. To do this, you must have admin rights for both Vault and FogBUGZ. For more information, see the Vault Admin Tool documentation.

Once FogBUGZ and Vault have been configured, you can associate a file in Vault with a case in FogBUGZ.

Please Note: In FogBUGZ, a bug is referred to as a case.

Updating a Case

The Vault Check In/Commit dialog allows you to associate a Vault file with a FogBUGZ case during the check in process. Type the case number in the Update Bugs box. When the commit has been completed, the Vault file name and path will appear in the FogBUGZ case detail page.

Viewing a Case

In FogBUGZ, go to the detail page of a selected case.

A list of all the files that have been associated to the case through Vault’s check in process will appear next to the CheckIn label. This list includes:

• The Vault Repository ID

• The path to the associated file

• The version of the file.

Click on the file to view the Vault History page.

Vault History

The Vault History page gives you a detail history of the selected file on the case detail page. The page shows the following information for each check in operation completed:

• The user who committed the change

• The version of the file created

• The action that was performed

• Any comment the user may have entered as part of the commit

On the first attempt to see the history page during a FogBUGZ session, you will be asked for a username and password. Upon success of the login, you will be presented with the Vault History page.

Vault Diff

The Vault Diff page shows you the diff between the selected file and the previous version.

Please Note: Diff must first be configured on the FogBUGZ Site Configuration screen. To do this, you must have admin rights for both Vault and FogBUGZ. For more information, see the Vault Admin Tool documentation.

Click the link showing the version number of the file. The diff window will appear and display a side by side comparison of the two versions of the file, in a manner similar to the current diff application in Vault. Line numbers are displayed for each line of the file, modified lines are colored red, added lines green, and deleted lines blue.

Reference Guide

Menus

Main Window

The following menus and menu items appear in Vault’s Main Window.

File

Connect to Server

The Connect to Server command allows you to connect to the Vault server. This command is also available on the Toolbar and will display when Vault is started. You can choose to automatically connect on startup with a profile.

Disconnect from Server

The Disconnect from Server command allows you to disconnect from the current server.

Choose Repository

The Choose Repository command allows you to select the repository from the connected server. You can choose to automatically open a repository when connecting to Vault by using a profile.

Add Files/Folders

The Add Files/Folders command allows you to add new files or folders to the open repository by selecting files or folders accessible on the local machine. The Add Files command can also be found on the Toolbar.

Detect New Files to Add

The Detect New Files command allows you to see which files exist in your local working folder that do not exist in Vault, therefore allowing you to easily add newly created files to the repository.

Create Folder

The Create Folder command allows you to create a new empty folder within the open repository. The Create Folder command can also be found on the Toolbar.

Delete

The Delete command allows you to delete files or folders from the repository. The Delete command can also be found on the Toolbar.

Please Note: The Delete command is non-destructive. The items still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties.

Rename

The Rename command allows the names of the selected files or folders to be changed.

Move

The Move command allows you to move the selected files or folders from one folder to another.

Properties

The Properties command allows you to view and modify the properties of the selected file (File Properties) or folder (Folder Properties).

Set Working Folder

The Set Working Folder command allows you to set a directory on the client machine to store files retrieved from the server. The Set Working Folder command can also be found on the Toolbar.

A working folder must be set in order to Get Latest, Check Out or Edit.

Explore Working Folder

The Explore Working Folder command allows you to open a Windows Explorer window on the corresponding working folder. If there is no working folder set or the working folder does not exist, the command will not be available.

Exit

The Exit command allows you to close the Vault client application.

Edit

View File

The View File command allows you to view the repository’s latest version of a selected file without checking out or replacing the local copy of the file. The View File command can also be found on the Toolbar.

Edit File

The Edit File command allows you to check out and edit a selected file in a single operation. The Edit File command can also be found on the Toolbar.

Select All

The Select All command allows you to select all of the files in the file list.

Invert Selection

The Invert Selection command allows you to invert the already selected files. For each file in the file list, if it is selected, it will be unselected and, if it is unselected, it will be selected.

View

Refresh

The Refresh command refreshes the file list and folder tree by retrieving the latest information from the server. This command is merely used to update the display of status information, it does not modify the working folders in any way.

See Automatic Refresh in General Options to set the refresh option.

Show Differences

The Show Differences command opens the Diff dialog box to examine the differences between versions of a file. The Diff command can also be found on the Toolbar.

Show History

The Show History command opens the History Explorer to examine past versions to a tree or repository. The History command can also be found on the Toolbar.

History Favorites->Edit Favorites

The History Favorites->Edit Favorites command opens the Edit History Favorites dialog that allows you to manage saved queries.

History Favorites->(Saved Query)

The History Favorites->(Saved Query) command invokes a specific named query and displays it in the History Explorer dialog..

Show Blame

The Show Blame command opens the Blame window, which shows which user modified which lines in the file.

Show Labels

The Show Labels command opens the Show Labels dialog to examine labels that have been applied to the currently selected file or folder, or labels that have been created recursively below that file or folder.

Source

Get Latest Version

The Get Latest Version command retrieves a copy of the file from the Vault server and places it in your working folder. If there is no current working directory, the Set Working Folder dialog box is displayed first since a working directory must exist before files are retrieved. The Get Latest Version command can also be found on the Toolbar.

Check Out

The Check Out command allows you to check out the latest version of a file or folder to modify the item. The Check Out command can also be found on the Toolbar.

Check In/Commit

The Check In/Commit command allows you to commit changes made to local files back into the repository. The Check In command can also be found on the Toolbar.

Undo Check Out

The Undo Check Out command allows you to undo a checkout and not modify contents of the file in the repository or change the version number. The Undo Check Out command can also be found on the Toolbar.

Show Merge

The Show Merge command allows you to resolve merges for files of status Needs Merge and also to examine how Vault automatically resolved the conflicts between two files.

Resolve Merge Status

The Resolve Merge Status command resets the status of a file from Needs Merge to Edited, which allows you to check in the file.

Label

The Label command allows you to tag a version of a file or folder with a text string. The Label command can also be found on the Toolbar.

Share

The Share command allows you to make files or folders appear in two distinct places in the repository. The Share command can also be found on the Toolbar.

Branch

The Branch command allows you to either Share Branch or Copy Branch. A Share Branch allows you to break a link for a shared file; creating a separate file at the location it was shared. A Copy Branch allows you to branch any file or folder, whether it is shared or not. The Branch command can also be found on the Toolbar.

Snapshot

The Snapshot command allows you apply snapshots to a folder.

Pin/Unpin

The Pin command allows you to pin a file or pin a folder to its current version, disallowing any changes to the file or folder until it is unpinned.

Cloak/Uncloak

The Cloak command allows you to specify that a folder should be ignored during other operations. For example, Get Latest Version operation will not get files from a cloaked folder unless the cloaked folder is specifically selected.

Tools

Merge Branches

The Merge Branches command allows you to merge changes from any folder to any other folder.

Options

The Options command allows you to set global options by opening the Options dialog box.

Change Password

The Change Password option allows you to change passwords.

Abort Current Operation

The Abort command cancels any current server operation. It is only available during attempts to contact the Vault server. The Abort command can also be found on the Toolbar.

Help

Contents

The Contents command will bring up the Help files. The Contents command can also be found on the Toolbar.

Search

The Search command will bring up the Search page for the Help files.

Technical Support

The Technical Support command will provide you support contact information and links to the FAQ lists. It will also list your system and version information that will be relevant for tech support issues.

About Vault

The About SourceGear Vault will show you the version number and the current locale.

Folder Tree Context Menu

Create Folder

The Create Folder command is used to create a new empty folder within the open repository. The Create Folder command can also be found on the Toolbar..

Add Files/Folders

The Add Files/Folders command allows you to add new files or folders to the open repository by selecting files or folders accessible on the local machine. The Add Files command can also be found on the Toolbar.

Detect New Files to Add

The Detect New Files command allows you to see which files exist in your local working folder that do not exist in Vault, therefore allowing you to easily add newly created files to the repository.

Set Working Folder

The Set Working Folder command allows you to set a folder on the client machine in which to retrieve repository files. The Set Working Folder command can also be found on the Toolbar.

A working folder must be set in order to Get Latest, Check Out or Edit.

Explore Working Folder

The Explore Working Folder command allows you to open a Windows Explorer window on the corresponding working folder. If there is no working folder set or the working folder does not exist, the command will not be available.

Get Latest Version

The Get Latest Version command allows you to retrieve all the latest files within the folder from the Vault server and place them in the working folder. If there is no current working folder, the Set Working Folder dialog box is displayed first since a working directory must exist before files are retrieved. The Get Latest Version command can also be found on the Toolbar.

Check Out

The Check Out command allows you to check out the latest version of a files in the selected folder. You can then modify the files. The Check Out command can also be found on the Toolbar.

Check In/Commit

The Check In/Commit command allows you commit changes made to local files found in the selected folder or one of its sub-folders back into the repository. The Check In command can also be found on the Toolbar.

Undo Check Out

The Undo Check Out command allows you to undo the check out and not modify the contents of the file found in the selected folder or its subfolders in the repository or change the version number. The Undo Check Out command can also be found on the Toolbar.

Show Differences

The Show Differences command opens the Diff dialog box to examine the differences between versions of a folder. The Show Differences command can also be found on the Toolbar.

Show History

The Show History command opens the History Explorer to examine past versions to a tree or repository. The Show History command can also be found on the Toolbar.

History Favorites->Edit Favorites

The History Favorites->Edit Favorites command opens the Edit History Favorites dialog that allows you to manage saved queries.

History Favorites->(Saved Query)

The History Favorites->(Saved Query) command invokes a specific named query and displays it in the History Explorer dialog..

Show Labels

The Show Labels command opens the Show Labels dialog to examine labels that have been applied to the currently selected folder, or labels that have been created recursively below that folder.

Share

The Share command allows you to make the selected folder appear in two distinct places in the repository. The Share command can also be found on the Toolbar.

Branch

The Branch command allows you to either Share Branch or Copy Branch. A Share Branch allows you to break a link for a shared item; creating a separate item at the location it was shared. A Copy Branch allows you to branch any item, whether it is shared or not. The Branch command can also be found on the Toolbar.

Label

The Label command allows you to tag a version of a file or folder with a text string. The Label command can also be found on the Toolbar.

Pin/Unpin

The Pin command allows you pin a folder to its current version, disallowing any changes to the folder until it is unpinned.

Cloak/Uncloak

The Cloak command allows you to specify that a folder should be ignored during other operations. For example, Get Latest Version operation will not get files from a cloaked folder unless the cloaked folder is specifically selected.

Delete

The Delete command allows you to delete the selected folder from the repository. The Delete command can also be found on the Toolbar.

Please Note: The Delete command is non-destructive. The items still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties.

Rename

The Rename command allows the names of the selected folder to be changed. The item will be immediately renamed unless Auto-Commit has been turned off in the Check In Options.

Properties

The Properties command allows you to view and modify the properties of the selected folder (Folder Properties).

File List Context Menu

View File

The View File command allows you to view the latest version of a selected file without checking out or replacing the local copy of the file. The View File command can also be found on the Toolbar.

Edit File

The Edit File command allows you to check out and edit a selected file in a single operation. The Edit File command can also be found on the Toolbar.

Get Latest Version

The Get Latest Version command allows you to retrieve a copy of the file from the Vault server and place it in your working folder. If there is no current working folder, the Set Working Folder dialog box is displayed first since a working directory must exist before files are retrieved. The Get Latest Version command can also be found on the Toolbar.

Check Out

The Check Out command allows you to check out the latest version of the selected file. You can then modify the file or folder. The Check Out command can also be found on the Toolbar.

Check In/Commit

The Check In/Commit command allows you to commit changes made to local files back into the repository. The Check In/Commit command can also be found on the Toolbar.

Undo Check Out

The Undo Check Out command allows you to check in a file and not modify the contents of the file in the repository or change the version number. The Undo Check Out command can also be found on the Toolbar.

Show Differences

The Show Differences command opens the Diff dialog box to examine the differences between versions of a file. The Show Differences command can also be found on the Toolbar.

Show History

The Show History command opens the History Explorer to examine past versions to a tree or repository. The Show History command can also be found on the Toolbar.

History Favorites->Edit Favorites

The History Favorites->Edit Favorites command opens the Edit History Favorites dialog that allows you to manage saved queries.

History Favorites->(Saved Query)

The History Favorites->(Saved Query) command invokes a specific named query and displays it in the History Explorer dialog..

Show Labels

The Show Labels command opens the Show Labels dialog to examine labels that have been applied to the currently selected file.

Show Merge

The Show Merge command allows you to examine how Vault automatically resolved the conflicts between two files, and to manually merge a file if it still needs merged.

Resolve Merge Status

The Resolve Merge Status command resets the status of a file from Needs Merge to Edited, which allows you to check in the file.

Share

The Share command allows you to make files appear in two distinct places in the repository. The Share command can also be found on the Toolbar.

Branch

The Branch command allows you to either Share Branch or Copy Branch. A Share Branch allows you to break a link for a shared file; creating a separate file at the location it was shared. A Copy Branch allows you to branch any file, whether it is shared or not. The Branch command can also be found on the Toolbar.

Label

The Label command allows you to tag a version of a file with a text string. The Label command can also be found on the Toolbar.

Pin/Unpin

The Pin command allows you pin a file to its current version, disallowing any changes to the file until it is unpinned.

Delete

The Delete command allows you to delete the selected files from the repository. If multiple files are selected, they will all be deleted at the same time. The Delete command can also be found on the Toolbar.

Please Note: The Delete command is non-destructive. The file or folder still exists in the history of the repository and can be recovered by clicking the Undelete command found in the Folder Properties.

Rename

The Rename command allows the names of the selected files to be changed.

Properties

The Properties command allows you to view and modify the properties of the selected file (File Properties).

Pending Change Set

Select All

Allows you to select all the entries in the pending change set.

Copy

Copies all the currently selected entries in the pending change set to the clipboard in a text format.

Edit Item Comment

The Edit Item Comment allows you to add or edit the comment associated with this item (not the overall change set comment).

Commit

The Check In/Commit command allows you to bring up the Check In/Commit dialog box containing the selected items in the pending list and then commit them to the repository.

Undo

The Undo command allows you to check in a file and not modify the contents of the file in the repository or change the version number. The Undo command can also be found on the Toolbar.

Show Differences

The Show Differences command opens the Diff dialog box to examine the differences between versions of a file. The Show Differences command can also be found on the Toolbar.

Show Merge

The Show Merge command allows you to examine how Vault automatically resolved the conflicts between two files.

Resolve Merge Status

The Resolve Merge Status command resets the status of a file from Needs Merge to Edited, which allows you to check in the file.

Status Search Context Menu

The Status Search context menu is available on an item by right clicking the mouse over an item. Not all search result items have a context menu and the set of commands in each menu is not the same for each search type. The following tables list each status search type and its context menu commands, if any.

|Status |Menu |

|Old |Get Latest Version, Show Differences, Check Out, Delete |

|Missing |Get Latest Version, Check Out, Delete |

|Checked out by |Get Latest Version, Check In, Undo Check Out, Show Differences, Delete |

|Merged |Get Latest Version, Check In, Undo Check Out, Show Differences, Show Merge, Delete |

|Edited |Get Latest Version, Check In, Undo Check Out, Show Differences, Delete |

|Renegade |Get Latest Version, Check Out, Show Differences, Delete |

|Unknown |Get Latest Version, Check Out, Show Differences, Delete |

|Needs Merged |Get Latest Version, Check Out, Show Differences, Show Merge, Delete |

|More Recent |Get Latest Version, Check Out, Show Differences, Delete |

Show Label Menus

The following menus and menu items appear in the Show Labels dialog.

Label

Delete

The Delete command allows you to delete a selected label. You will be prompted to confirm the label deletion. Once confirmed, the label is removed from the repository.

This command is only available on labels that were created at the same file or folder the Show Labels command was invoked on.

Rename

The Rename command allows you to rename a label. The “rename” must maintain label “uniqueness” for all items in the label

This command is only available on labels that were created at the same file or folder the Show Labels command was invoked on.

Promotion

The command brings up the Label Promotion dialog, which allows you to add or delete files to or from the label, and also allows you to change the version numbers of files associated with the label.

This command is only available on labels that were created at the same file or folder the Show Labels command was invoked on.

Close

View

Refresh

The Refresh command allows you to re-query the label to get updated results.

Action

Diff

Invokes the diff command on the item listed in the menu item that is associated with the selected label.

View

Views the item listed in the menu item that is associated with the selected label. For a folder, this invokes a window that allows you to see the tree structure of the folder at the time it was labeled.

Get

Gets the item listed in the menu item that is associated with the selected label.

A working folder is required to Get a label to the local disk. The Get dialog is displayed when getting the item, and you can choose to get the item to a different folder from that dialog.

If the folder the label is retrieved to is a working folder, it will update the state files to reflect the versions of the label, and will honor the Get options that apply to history Gets, for issues like overwriting existing files, timestamps, etc.

Share

Shares the item listed in the menu item that is associated with the selected label at the version associated with label. This works same way as if it were shared from history, in that it shares the item, then pins it to the version it was shared from.

You can only share an item that is part of a label that has not been promoted.

Branch

Branches the item listed in the menu item that is associated with the selected label. This works same way as if it were branched from history at the version associated with the label.

You can only branch an item that is part of a label that has not been promoted.

Pin/Unpin

Pinning / Unpinning an item associated with the selected label will operate as if the main object is pinned or unpinned using the label’s version.

You can only pin or unpin an item that is part of a label that has not been promoted

Edit Comment

Invokes a dialog that allows you to change the text of the comment is associated with the selected label.

Label Promotion Menus

The following menus and menu items appear in the Label Promotion dialog.

File

Delete

The Delete command marks the currently selected file or folder to be deleted from the label. Once deleted, the file or folder is not retrieved as part of the label. The deletion actually happens when the Save command is invoked.

This command is not available on the label root.

Add

The Add command allows you to add files or folders to the label. Only files or folders that currently exist at the selected folder in the repository can be added to the label. You can select any folder in the label to add files or folders to. If there are no new files or folders to be added, a dialog will be displayed telling you so.

The add of the files or folder actually happens when the Save command is invoked.

This command is not available when a file is the current selection.

Change Version

The Change Version command allows you to change the version of a file associated with the label. When invoked, a dialog is displayed showing all the versions of the selected file, and you can choose which new version you want to associate with the label.

The version number change actually happens when the Save command is invoked

This command is not available when a file is the current selection.

Save

The Save command saves the label’s edited contents. The changes to be saved are listed in the bottom pane of the window

Close

The Close command will close the Label Promotion window, offering to save any unsaved changes first.

View

Refresh

The Refresh command gets the latest version of the label from the server, and updates the tree view and file list.

History Menus

The following menus and menu items appear in the History Explorer dialog.

Query

Top

The Top command allows you to specify which portion of the repository is to be included in the query by opening the Show History For dialog box. If the Top of the query is specified to be a file, then that file is the only object of interest. More commonly, the Top of the query is specified to be a folder, in which case the query includes all changes to that folder and all of its contents, recursively.

Filter/Sort

The Filter/Sort command allows you to specify criteria which define a subset of changes which are of interest for the query and to sort those results by opening the History Query Filter dialog box.

Save All Results As

The Save All Results As command allows you to export the results of the query for other uses by opening the Save History Results dialog box. This command will retrieve and export all of the results, not just the ones currently being viewed by the paging code.

Close

The History Close command closes the History Explorer window.

View

Refresh

The Refresh command allows you to re-query the server with the same filter/sort criteria, showing you changes in history made since the history window was first invoked.

Act Recursively

The Act Recursively command is a toggle that shows whether the current query is a recursive query, and allows you to change the value, and re-query with the value toggled from how it is currently set.

Action

Diff

The History Diff command allows you to compare a version with a previous version or the working folder. If two versions have been selected, the command retrieves both versions and compares them against each other using the default Diff Program. If only one version is selected, the History Diff dialog will be displayed to allow you to choose which version you want to diff against.

View

If a file is selected, the History View command allows you to retrieve the selected version and display its contents by launching the appropriate editor.

View is not supported for an entire folder.

Get

The History Get command gets the version that corresponds to the current selection. For example, if the current selection is a file check in, it retrieves the version associated with that check in. If the current selection is a folder, it retrieves the files (and their versions) that existed at the time of that folder version. Files are retrieved to their working folders by default.

Details

The Details command allows you to see the details for the entire check in, including the other files included in that file version’s check in, of the selected file by displaying the Version Details dialog box.

Pin

The Pin command allows you to pin the selected item.

Unpin

The Unpin command allows you to unpin the selected item.

Share

History Share works similarly to the regular Share command except that it works on a historical version of a file or folder instead of sharing the most recent version.

In the case of a file, it will share the file to a new location, and then pin it to the version you have selected in the list. For folders, it will share the folder to a new location and pin the folder to the version that was selected.

A History Share will always pin the file or folder being shared even if it is the most recent version. If the file or folder being shared is already shared, it will merely add the new file or folder as another link in the shared file.

Branch

The Branch command allows you to branch on the selected file or folder at the version that is selected. You cannot branch a deleted file or folder.

Please Note: A branch on a previous version of an item is always a Copy Branch. A branch on the current version follows the normal rules of branch. See Branch Items for more information.

Label

The Label command allows you to label the selected file or folder at the version that is selected. You cannot label a deleted file or folder.

Rollback

The History Rollback command is a non-destructive way to make a previous version the current version. It checks out the file at the version selected and checks in that file as the latest version. A rollback does not break a share.

Rollback is not available when the file is pinned.

Check Out

The History Check Out command is used to check out a file while simultaneously retrieving the selected version. This only allows a single checkout at a time.

Help

Contents

The Contents command will bring up the Help files opened to the History Explorer.

About Vault

The About SourceGear Vault will show you the version number and the current locale.

Dialog Boxes

Add Files/Folders

The Add Files/Folders dialog box allows you to add new files or folders to the repository by selecting files that are accessible to the local machine.

The Add Files/Folders dialog box can be opened:

• From the File menu, select Add Files/Folders

• Right-click on selected folder to bring up the Folder Tree Context Menu, select Add Files/Folders

• Select Add Files/Folders on the Toolbar

• Ctrl+N

Tree View of Local File System

The top pane contains a tree control and a file list of the local file system. If a working folder exists at the node this command was invoked on, the tree control will have that working folder selected. Selecting a node in the tree will fill the file list with the files in that local folder.

Checking a folder will automatically check all the folders and files under that folder that meet the exclusion rules, and add that folder to the File/Folder to be Added list. If not all files/folders underneath a folder are checked, the folder’s checkbox will be partially checked.

Checking a partially checked folder will fully check all files and folders under that folder. Checking a fully checked folder will uncheck all files and folders, and remove the entry from the Files/Folder to be Added list.

Files/Folders to be Added

The Files/Folders to be Added is the list of pending folders or files that are to be added from the local directory. Following are the columns in this list.

• Items – The local path of the file or folder to be added.

• Properties – For files, the size of the file being added. For folders, the total size, and the number of folders and files included in the folder being added.

• Repository Path – The path in the repository the items will be added.

Exclude

Click Exclude to display a dialog that allows you to view/edit the list of files and folders to exclude when checking a folder. This list is defined in the Admin Tool and making changes to it here does not update the default list.

Changing this list does not go back and re-apply the exclusion rules to already checked folders, since it is possible you could have already made changes to the file list that cause it to not follow the exclusion rules. If you want to re-apply the exclusion rules, you need to uncheck the folder, then check it again.

Browse

Click Browse to add additional drives or shared network folders to the Local File System tree view. This allows you to add files from any drive that can be accessed from the local machine. New drives are rooted at the top of the tree view.

Remove

Click Remove to remove the selected files or folders from the pending list. This will update the state of the tree and file list to reflect that the items are not to be added.

Comment

Type a comment in the Comment dialog box. The comment applies to all files being added. If the Auto-Commit is on, they become the change set comment.

OK

Click OK to add the files and folder to the Pending Change Set window.

If Auto-Commit has not been selected, the files and folders will be added to the repository as part of the next check in transaction. The comment is applied individually to each file.

If Auto-Commit has been selected (default), the files and folders will be added to the Vault repository immediately. The comment will become the change set comment.

Please see Auto-Commit for more information.

Cancel

Click Cancel to exit the Add Files dialog box without making any changes.

Blame

The Blame window shows the last user to modify any given line in a file. This is useful for determining why a build broke or to just generally assign credit or blame to content changes in a file.

The blame window has the following columns:

• Line – The line number of the given line.

• User – The user who made the last change. If the same user made changes for a block of lines, only the first line will display the user’s name and all the remaining lines in that block will be in the same shading to indicate it is the same user (without repeating the user’s name).

• Version – The version number of the file that the line last changed on. Each version number is linked to a footnote table at the bottom of the page that shows which versions have changed content, which user checked that version in, and what the comment was for that check in.

• File Contents – The actual line in the file.

Browse Bug Tracking

The Browse Bug Tracking allows you to view your open items in Dragnet. It is only available when Dragnet is configured as your Bug Tracking Application in the Vault Admin tool.

The Browse Bug Tracking can be accessed from the View->Show My Open Bugs menu item or from the checking dialog.

By default the Browse Bug Tracking dialog only displays open items assigned to the logged in user grouped by project then milestone.

Check the “Show All Open” checkbox to view the open items assigned to all users.

To view the Dragnet item in more detail, select the item from the Items list box and click the Details button.

Change Password

The Change Password dialog box allows a user to change his password.

The Change Password dialog box can be opened:

• From the Tools menu, select Change Password

Old Password

Type your current password in the Old Password box.

New Password

Type a new password in the New Password box.

Verify

Type the new password again in the Verify box.

OK

Click OK to save the changes and close the Change Password dialog box.

Cancel

Click Cancel to close the Change Password dialog box without changing the password.

Check In/Commit

The Check In/Commit dialog box allows a user to check in all pending changes to files and folders. For more information, please see the section for checking in Files or Folders.

The Check In/Commit dialog box can be opened:

• From the Source menu, select Check In/Commit

• Right-click on selected file to bring up the File List Context Menu, select Check In/Commit

• Right-click on selected folder in bring up the Folder Tree Context Menu, select Check In/Commit

• Select Check In or Commit All on the appropriate Toolbar

• Ctrl+I

• In the Pending Change Set, click the Commit button or use Ctrl + M

Changes

The Changes box contains a list of all files (added, deleted or modified) that are included in this check in. The following are the columns of the list.

• Item

• Type

• Details

Please Note: If a file’s status is Needs Merge, it must be merged prior to being committed to the repository, which can be accomplished by invoking the Show Merge command. If the file is already merged, invoke the Resolve Merge Status command to reset the file’s status to Merged.

Check All

Click Check All to select all the items in the list.

Uncheck All

Click Uncheck All to clear all the checkboxes in the list

Keep Checked Out

Check the Keep Checked Out checkbox to perform a check out operation on each file after the check in has completed.

Remove Local Copy

Check the Remove Local Copy checkbox to remove the checked in files from the working folder.

Update Bugs

If a SourceGear Dragnet or FogCreek FogBUGZ server is enabled, Update Bugs allows you notify the bug tracking system that files relating to item numbers were checked in.

For Dragnet, you can either type in the item ID in the text box or click the Browse button to see a list of bugs that are currently assigned to you, and select one or more from that list.

For FogBUGZ, type the case number in the Update Bugs box.

Please Note: The update bugs section of the checkin dialog is only enabled if files in the checkin transaction have a status of added or modified.

When the file is commited, the files that were checked in will be associated with the items in the bug tracking system.

Multiple ID or case numbers may be entered, separated by a comma or semicolon.

For more information, please see Dragnet or FogBUGZ in the Bug Tracking Integration section.

Diff

The Diff button is available when a selected file has been modified. Click on the button to bring up the Diff window to see your changes.

Comment

Type a comment in the Comment box. This will apply to all files checked in with the change set. This is optional.

OK

Click OK to commit the selected items to the Vault repository and close the Check In/Commit dialog box.

Cancel

Click Cancel to close the Check In/Commit dialog box. No items will be checked in.

Check Out

The Check Out dialog box allows you to check out a file from the Vault repository. Checking out a file marks your intention to edit it and ensures it has write permission locally. Proceeding with a Check Out retrieves the latest version of the file. For more information, please see the section for checking out Files or Folders.

The Check Out dialog box can be opened:

• From the Source menu, select Check Out

• Right-click on selected folder to bring up the Folder Tree Context Menu, select Check Out

• Right-click on file to bring up the File List Context Menu, select Check Out

• Select Check Out on the Toolbar

• Ctrl+O

You must have a working folder defined to check out a file. If a working folder is not set for the selected file or folder, the Set Working Folder dialog box will appear first. Select a working folder and continue with the Check Out command. Click Cancel on the Set Working Folder dialog box to abort the operation.

File Options

Set File Time

The Set file time list allows you to select the timestamp to give the local file after it is retrieved from the repository. Select one of the following options.

• Current – the current client time the file is download from the server.

• Modification – the time the file was last modified on the client before it was checked in. This time depends on the clock of the client machine where it was checked in.

• Check In – the server time the file was checked in on the server.

Modified Local Copy

This option tells Vault how to handle files that have been modified locally since they were retrieved or exist but have a status of Unknown. This option doesn’t apply to local files that are known versions in the repository. Select one of the following options:

• Overwrite Working Copy – This overwrites the local file. If the file has a status of Unknown, it will be backed up in the _sgbak directory before being overwritten

• Do Not Overwrite/Merge Later – This will not overwrite an existing file if it has been changed locally. Vault will still download a new repository version into the hidden state folder if one exists, allowing you to manually merge the file later (in which case the file’s status becomes Needs Merge).

• Attempt Automatic Merge – Vault will attempt to merge the changes from the server copy into the working copy. If it can do so without irresolvable conflicts, then it will do so. All three files will be archived so you can examine precisely what was done in the automatic merge step. However, if the file cannot be merged automatically, the behavior is identical to that of the Do Not Overwrite setting above. The working copy is untouched, and you must resolve the conflict later before Check In is allowed. A message is written in red in the Messages pane for each file that could not be merged.

The default for this option is Attempt Automatic Merge.

Request Exclusive Lock

The Request Exclusive Lock checkbox is checked or unchecked as per your setting in the General Options dialog.

An exclusive lock on a file means that no one else can check the file in or out while the current user has it checked out.

This option is disabled and checked for non-mergeable files which must be checked out exclusively since they cannot be merged.

Recursive

Check the Recursive checkbox to check out all files and subfolders of the selected folder.

Only Show this Dialog When the Shift Key is Down

If you select this option, the dialog box will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item checked out. See Command Dialogs Options to change the default selections.

Comment

Enter a comment in the Comment box. This comment will be the default check in comment for the file that was checked out (or all files if this was a recursive operation). This is optional.

OK

Click OK to check out the selected items and close the Check Out dialog box.

Cancel

Click Cancel to close the Check Out dialog box. Nothing will be checked out.

Choose Repository

The Choose Repository dialog box allows you to choose a repository from the connected server. For more information, please see Working with Repositories.

The Choose Repository dialog box can be opened:

• From the File menu, select Choose Repository

• When connecting to a server, the Choose Repository dialog box will automatically appear

• Ctrl+P

Available Repositories

The Available Repositories box lists the repositories you have access to in the currently connected Vault server. The repository’s version and number of files and folders are also listed. Access is set by the administrator in the Admin Tool.

OK

Click OK to choose the selected Vault repository and close the Choose Repository dialog box.

Cancel

Click Cancel to close the Choose Repository dialog box. If a repository is already opened, the current repository remains open. If no repository is open because you have just logged into a new server, the client is still logged into the server and you can still choose to open a different repository. Go to the File menu and select Choose Repository.

Connect to Server

The Connect to Server dialog box connects you to the Vault server. For more information, please see Working with Repositories.

The Connect to Server dialog box can be opened:

• From the File menu, select Connect to Server

• Upon starting Vault

You can only be connected to one server at a time. Therefore, if connect to a different server during a session, you will be disconnected from the current server.

Username

Type your User name. You must be an active Vault user as defined in the Vault Admin tool.

Password

Type your Password.

Vault Server

Type the name of the Vault server. This is the host name of the server and not a URL.

Use SSL

Check the Use SSL checkbox if you are using Secure Sockets Layer (SSL) for security.

Select Profile

Allows you to select an existing profile. If you select a profile, the information from that profile will be automatically placed in the login fields.

Edit Profiles

Click to bring up the Edit Profiles dialog, which allows you to enter and edit profiles for use in automatically logging in.

Automatically Connect using this profile

Check the Automatically Connect using this profile checkbox to automatically connect to the server specified by the current profile the next time Vault is started. This option is available only if you are currently using a profile, and if that profile is configured to remember the user’s password (since the password must be supplied to automatically login).

OK

Click OK to attempt a login to the specified server. The Connect to Server dialog box will close and the Choose Repository dialog box will open unless you are using a profile that automatically connects to a repository, in which case that profile will be automatically chosen.

Cancel

Click Cancel to close the Connect to Server dialog box. If you are not currently logged in, the client remains in an unconnected state.

Copy Branch

A Copy Branch allows you to branch any file or folder, whether it is shared or not. For more information, please see Branch Items.

To open the Branch dialog box select a file or folder then either:

• From the Source menu, select Branch

• Select Branch on the Toolbar

Specify a folder/file name

Select a folder in the tree to place the branched version, and if desired, provide a new name for the copy of the file.

Comment

Type a comment for the branch operation in the Comment box. This is optional.

OK

Click OK to branch the select file or folder and return to the main window.

Cancel

Click Cancel to exit the Branch dialog box without making any changes.

Create Folder

The Create Folder dialog box allows you to create a new empty folder within the repository. For more information, please see Create, Add and Delete Folders.

The Create Folder dialog box can be opened:

• From the File menu, select Create Folder

• Right-click on folder to bring up the Folder Tree Context Menu, select Create Folder

• Select Create Folder on the Toolbar

• Press the INSERT key

New Folder Name

Type a new folder name in the New Folder Name box.

OK

Click OK to create the folder and close the Create Folder dialog box.

If Auto-Commit has been selected (default), the folder will be created in the Vault repository immediately. If Auto-Commit has not been selected, the folder will be created in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Cancel

Click Cancel to close the Create Folder dialog box. A new folder will not be made.

Detect New Files

The Detect New Files to Add from Working Folder dialog box allows you to see which files exist in your local working folder that do not exist in Vault, therefore allowing you to easily add newly created local files to the repository.

The Detect New Files dialog box can be opened:

• From the File menu, select Detect New Files to Add

• Right-click on selected folder to bring up the Folder Tree Context Menu, select Detect New Files to Add

• Ctrl+T

Tree View of Local File System

The top pane contains a tree control and a file list of the local file system, rooted at the working folder where the command was invoked. The tree is actually the repository tree, and if a node is selected, the working folder at that node is used to display the list of files that exist in the working folder, but not in the repository at that level.

Checking a folder will automatically check all the folders and files under that folder that meet the exclusion rules. All files that meet the exclusion rules are added as individual entries in the Files to be Added list, and they are added at the level in the repository that corresponds to the working folder the files belongs too.

If not all files/folders underneath a folder are checked, the folder’s checkbox will be partially checked. Checking a partially checked folder will fully check all files and folders under that folder. Checking a fully checked folder will uncheck all files and folders, and remove the entry from the Files to be Added list.

Files to be Added

The Files to be Added is the list of pending files that are to be added from the local directory. Following are the columns in this list.

• Items – The local path of the file or folder to be added.

• Properties – For files, the size of the file being added. For folders, the total size, and the number of folders and files included in the folder being added.

• Repository Path – The path in the repository the items will be added.

Exclude

Click Exclude to display a dialog that allows you to view/edit the list of files and folders to exclude when checking a folder. This list is defined in the Admin Tool and making changes to it here does not update the default list.

Changing this list does not go back and re-apply the exclusion rules to already checked folders, since it is possible you could have already made changes to the file list that cause it to not follow the exclusion rules. If you want to re-apply the exclusion rules, you need to uncheck the folder, then check it again.

Remove

Click Remove to remove the selected files or folders from the pending list. This will update the state of the tree and file list to reflect that the items are not to be added.

Comment

Type a comment in the Comment dialog box. The comment applies to all files being added. If the Auto-Commit is on, they become the change set comment.

OK

Click OK to add the files and folder to the Pending Change Set window.

If Auto-Commit has not been selected, the files and folders will be added to the repository as part of the next check in transaction. The comment is applied individually to each file.

If Auto-Commit has been selected (default), the files and folders will be added to the Vault repository immediately. The comment will become the change set comment.

Please see Auto-Commit for more information.

Cancel

Click Cancel to exit the Add Files dialog box without making any changes.

Diff

The Diff command allows you to compare working files and folders to previous versions of themselves.

The Diff dialog box can be opened:

• From the Tools menu, select Show Differences

• Select Diff on the Toolbar

• Right-click on folder to bring up the Folder Tree Context Menu, select Show Differences

• Right-click on file to bring up the File List Context Menu, select Show Differences

Compare to the working folder/file to:

• The last version retrieved from the repository – This compares the working file or folder to the version that you started editing from which is the version that was retrieved from the repository.

• The current version in the repository now – This compares the working file or folder to the current version in the repository that may have changed since you started editing.

• A label applied to this folder/file – This compares the working file or folder to a version of the same file or folder that is part of a label that was previously applied. The Browse button will display the list of available labels that can be compared to the working file or folder.

• Any local folder/file – This compares the working file or folder to a file or folder on the local disk. The browse button will display a local file/folder chooser that allows you to choose which file or folder to compare against the working file or folder.

• Any repository folder/file – This compares the working file or folder to the current version of any file or folder in the repository. The Browse button will display the current repository tree and allow you to select a repository file or folder to compare against the working file or folder.

Recursive

When a folder has been selected, the Recursive checkbox will be available. Check Recursive to view the difference in the selected folder and all the subfolders. Uncheck Recursive to view the differences just in the selected folder.

The default is Checked.

Only show this dialog when the shift key is down

If you select this option, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See History/Labels Options to change the default selections.

OK

Click OK to bring up the default Diff Program.

Cancel

Click Cancel to close the Diff dialog box.

Delete

The Delete dialog box allows you to delete files or folders from the repository. The Delete command is non-destructive and the items still exists in the history of the repository. The items can be recovered by clicking the Undelete command found in the Folder Properties dialog box.

The Vault client does not allow operations that destroy history. The Obliterate command is available in the Vault Admin Tool, which actually destroys the deleted file.

The Delete dialog box can be opened:

• From the File menu, select Delete

• Right-click on selected folder to bring up the Folder Tree Context Menu, select Delete

• Right-click on selected file to bring up the File List Context Menu, select Delete

• Select Delete on the Toolbar

Are you sure you want to delete the following files?

A list of the selected files or the folder will appear in the box. If a folder is selected, the folder and all of its contents, recursively, will be deleted.

OK

Click OK to delete the items and close the Delete dialog box.

If Auto-Commit has been selected (default), the files will be deleted in the Vault repository immediately. If Auto-Commit has not selected, the files will be deleted in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Cancel

Click Cancel to close the Delete dialog box. The item will not be deleted.

Edit File

The Edit File command edits a file by launching an external editor and allows you to check the file out if it is not already checked out. For more information, please see Editing Files.

The Edit File dialog box can be opened:

• From the Edit menu, select Edit File

• Select Edit on the Toolbar

• Right-click the selected file to bring up the File List Context Menu, then select Edit

Use the system default

Select Use system default for this file type to use the default editor.

Use

Select Use and type the full path to the editor to use a different editor application. Use the Browse button to find the editor if necessary. Once a different application is selected, it will become the default.

The default editor for Windows is Notepad. To change the default application, see External Programs Options.

Check out file before editing

Select Check out file before editing to check out the file from the Vault server. This option is disabled if the file is already checked out.

If you have the Requires Check Out before Check In option enabled in the Check In Options, the default will be checked.

Only show this dialog when the shift key is down

If you select this option, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See External Programs Options to change the default selections.

OK

Click OK to launch the external application and edit the selected file.

Cancel

Click Cancel to abort the operation.

Edit History Favorites

The Edit History Favorites dialog allows you to change and create history favorites.  It lists all of your defined history favorites in alphabetical order.  Clicking on a history favorite in the list will display a brief description of the query for the selected favorite beneath the favorites list. 

Adding a History Favorite

 To add a new History Favorite, click the New button.  This will display the History Query Filter dialog.  Choose the history filter options you want for your history favorite then click the Save button.  Provide a name for your favorite then click OK. 

 Renaming a History Favorite

 Click the Rename button and enter a new name in the dialog.

 Editing a History Favorite Query

Select a history favorite from the list and choose Edit to edit the query associated with the favorite.  This will display the History Query Filter dialog with the currently filtered items selected.  Make your changes to the filter options and then click the Save button.

Deleting a History Favorite

To delete a History Favorite, select one or more items from the History Favorites list then click the delete button.

 Run Query

To see the query results for a History Favorite, select an item from the History Favorite menu then click the Run Query button.  The query results will be displayed in a new History Explorer window.

Edit Profiles

The Edit Profiles command allows you to create and edit profiles for use in connecting to a Vault server and repository. For more information, please see Profiles.

The Edit Profiles dialog box can be opened from the Edit Profiles button on the Connect To Server dialog.

Profile List

The Profile List contains the list of profiles that have already been defined. Selecting a profile in the list will populate the Login Information and Repository Information boxes with the data specified for that profile.

New

Click New to create a new, empty profile. You will be prompted to enter the profile name.

Delete

Click Delete to delete the selected profile.

Username

Contains the Username associated with the selected profile.

Password

Contains the Password associated with the selected profile. This is only enabled if the Remember Password checkbox is enabled. If this field has a value and the Remember Password checkbox is unchecked, the password will be removed on Save and the profile will no longer contain a password.

Vault Server

Contains the Vault Server associated with the selected profile, as it would be entered in the Connect To Server dialog.

Use SSL

If checked, this will connect to the server using SSL for the selected profile.

Remember Password

If checked, the password specified in the Password field will be saved and remembered, allowing the user to automatically connect to the server using this profile. If unchecked, the user will need to enter the password for each connection using this profile.

Default Repository

Contains the name of the repository to select by default after a connection is made to the server for this profile.

Automatically Choose This Repository

If checked, the Default Repository will be automatically chosen after connecting to the server for this profile. The Choose Repository dialog will not be displayed at all when this profile is used. This is only enabled if there is a value in the Default Repository List

Get Repository List

Brings up a dialog containing a list of repositories in the Vault server associated with this profile. Note that this uses values specified in the Username, Password, and Vault Server fields to login to that server in order to retrieve the repository list, so if they do not contain valid values, the repository list cannot be retrieved.

Save

Click Save to save any changes you have made to the profiles while in the dialog and then exit.

Cancel

Click Cancel to abort the operation.

File Properties

The File Properties dialog box allows you to view and modify the properties of a file. The dialog box has three tabs: General, Check Outs and Links.

General

Name

The name is the full repository path of the selected file.

Type

The type of the selected file is displayed. This can be changed by selecting one of the following.

• Binary – Marks the file as not able to be merged. The file will require exclusive check outs and no attempt will be made to merge different versions together.

• Mergeable – Marks the file as able to be merged and not needing to be locked exclusively.

• Use default for this file type – File extensions are used to determine default types for mergeable files. This options uses the system default the file.

You must click Apply in order for this change to take effect.

EOL Conversion

The EOL (End of Line) of the selected file is displayed. The can be changed by selecting either:

• None

• Native – Native chooses the format of OS the client is currently running on

• Windows (CLRF)

• Unix (LF)

• Mac (CR)

You must click Apply in order for this change to take effect.

Local Copy Information

The Local Copy Information box contains the following information.

• Version – the version number of the file when it was checked out

• Modified Date – the last modified date time of the file in the working directory

• Size – the size in bytes of the file in the working directory

• Status –the status of the file as shown in the file list

If there is no local copy, this will be blank.

Latest in Repository Information

The Latest in Repository Information box contains the following information.

• Version – the most recent repository version number of the file

• Modified Date – the last modified date time of the file in the repository

• Check in Date – the check in date time of the file in the repository

• Size – the size in bytes of the file in the repository

• Status – this displays only if the file is pinned and will display which version the file is pinned at

Comment

The Comment box contains the comment the user entered when the file was first added, if any. The value cannot be changed.

Apply

Click Apply to apply any changes made to any of the properties. The property changes increment the version number of the file.

Please Note: If the file is currently pinned, the edit is not allowed.

Close

Click Close to exit the Properties dialog box. If you have edited a property but not applied it, you will get a warning asking you whether you want to apply the change.

Check outs

The Check outs tab displays checkout information about the selected file. No items on this tab can be edited.

User

The User box lists all users who currently have the selected file checked out and includes the machine they have it checked out to.

The properties reflect the values for each user as they are selected.

Version

The Version is the repository version at the time the selected user checked out the file.

Date

The Date is the repository server’s date time when the selected user checked out the file.

Folder

The Folder is the folder and file name of the file that was checked out by the selected user.

Comment

The Comment is the check out comment the selected user entered.

Share Links

The Share Links tab contains all links of the shared file in a list that you have access to. No items on this tab can be edited.

Folder Properties

The Folder Properties dialog box allows you to view and modify the properties of a folder. The dialog box has three tabs: General, Deleted Items and Links

General

Name

The Name displays the name of the selected folder.

This project is cloaked for me

Check This project is cloaked for me checkbox to cloak the folder. This will update the state of the folder immediately.

Contains

The Contains box shows:

• the number of files and the number of files deleted

• the number of subprojects and the number of sub-folders deleted

• the Tree Size which is the total size of all files recursively in the folder

• the Disk Space Needed which is the amount of disk space required to do a Get to a working folder, which is double the tree size, since the state folder keeps a baseline copy of each file on the local disk.

Latest in Repository

The Latest in Repository box shows the version number and date of the selected folder.

Comment

The Comment box contains the comment that was entered when the user created the folder.

Close

Click Close to close the Folder Properties dialog box.

Deleted Items

The Deleted Items tab contains a list of all items that have been deleted at this folder level.

Date Time

Since a deleted item may have the same name as another deleted item, there is a column with the date and time that each item was deleted.

Undelete

Click Undelete to remove a selected item from this list.

Close

Click Close to close the Folder Properties dialog box.

Share Links

The Share Links tab contains all links of the shared folders in a list that you have access to. No items on this tab can be edited.

Folder Versions

The Folder Versions dialog box shows all versions of the TOP folder in a list. Each version of a folder corresponds to a change set that changed some part of the folder or its descendants. This dialog box lists the versions and allows you to view the change set that caused the folder to increment its version number. For more information, please see History Explorer.

To open the dialog box, select a file or folder, then:

• From the Query menu in the History Explorer, select View Folder Tree by version.

Folder Tree Versions for:

The name of the selected file or folder is displayed at top. The list shows all the versions for the selected item. The columns include:

• Version

• Date

• User

• Comment

Select a version to make the controls on the dialog box available. You can also double-click an item in the list to get the details for that transaction.

Close

Click Close to close the Tree Version dialog box.

Details

Click Details to view the Version Details.

Diff

Click Diff to bring up the default Diff Program on two selected versions or to show the diff between that version and its previous version if only one version is selected.

Share

Click Share to bring up the Share dialog box for the selected version of the tree. This will share the folder, then pin the new share link it to the version selected.

Branch

Click Branch to open the Copy Branch dialog box and branch the selected version.

Label

Click Label to open the Label dialog box and label the selected version.

Pin/Unpin

Click Pin to pin the selected version. If the selected version is already pinned, the button will say Unpin. Click Unpin to unpin the selected version.

View Tree

Click View Tree to view the tree at the time of the selected version. This brings up a window with a tree view and file list containing the entire folder tree for that selected version. This allows you to get selected files or folders from within that tree.

Get Tree

Click Get Tree to open the Get Latest Version dialog box. Click OK to download the entire tree associated with the version.

Get Latest Version

The Get Latest Version dialog box allows you to get the latest version of files and folders from the Vault repository.

The Get Latest Version dialog box can be opened:

• From the Source menu, select Get Latest Version

• Right-click on folder to bring up the Folder Tree Context Menu, select Get Latest Version

• Right-click on file to bring up the File List Context Menu, select Get Latest Version

• Select Get Latest Version on the Toolbar

• Ctrl+G

A working folder must be set to get the latest version of a file or folder. If a working folder is not set for the selected file or folder, the Set Working Folder dialog box will appear. Select the working folder and click OK to continue with the Get Latest Version command.

To

The To box defaults to the working folder but can be changed by typing a new folder in the box or using the Browse button to locate a new folder.

Please Note: Changing the To: folder does not reset the working folder – it just overrides where files go for a particular Get Latest Version.

File Options

Modified Local File

The Modified Local File option tells Vault how to handle files that have been modified locally since they were retrieved or exist but have a status of Unknown. This option doesn’t apply to local files that are known versions in the repository. Select one of the following options.

• Overwrite Working Copy – This overwrites the local file. If the file is not in your working directory (because you changed the To: field in this dialog), it will simply be overwritten. If the file is in your working folder and has a status of Unknown, it will be backed up in the _sgbak directory before being overwritten

• Do Not Overwrite/Merge Later – This will not overwrite an existing file if it has been changed locally. If the download is to the working folder, it will still download a new repository version into the hidden state folder allowing you to manually merge the file later (in which case the file’s status becomes Needs Merge). If the download is not to the working folder, the file will simply not be retrieved.

• Attempt Automatic Merge – Vault will attempt to merge the changes from the server copy into the working copy. If it can do so without irresolvable conflicts, then it will do so. All files will be archived so you can examine precisely what was done in the automatic merge step. However, if the file cannot be merged automatically, the behavior is identical to that of the Do Not Overwrite setting above: the working copy is untouched, and you must resolve the conflict later before check in is allowed. A message is written in red in the Messages pane for each file that could not be merged.

• If the file is being retrieved to a folder other than the working folder, this option is disabled altogether since the working folder is required for merges. Overwrite becomes the default in this case.

The default is Attempt Automatic Merge.

Prompt for modified files

The Prompt for modified files option tells Vault whether to prompt you before overwriting a file that has been modified locally, or has an Unknown status.

If checked, any file that you have modified locally (has an Edited, Needs Merge, or Merged status), or any file that Vault can’t reproduce (Unknown status) will not be overwritten unless you explicitly tell Vault to do so with a prompt dialog that is displayed during the Get.

If not checked, no dialog will be displayed, and the value of the Modified Local File option will be used to determine whether to overwrite the file, leave the file, or attempt to automatically merge it (if it is currently Edited).

Set file time

The Set file time list allows you to select the time to be associated with the selected file or folder. Select one of the following options.

• Current – The current client time the file is download from the server.

• Modification – The time the file was last modified on the client before it was checked in. This time depends on the clock of the client machine where it was checked in.

• Check In – The server time the file was checked in on the server.

Repository deletions

Select Repository Deletions options to determine when to delete files locally that were deleted in the repositories. This option will apply to folders recursively. This is enabled only when the Get Latest Version is on a folder.

Select one of the following options.

• Remove working copy – The local file will be removed if it was deleted in the repository, regardless of the state of the file.

• Do not remove working copy – The local file is left untouched.

• Remove working copy only if unmodified – The local file is removed only if it is not a known version in the repository.

This option also applies to renames and moves.

• Do not remove working copy – the file will be copied and renamed or moved.

• Remove working copy – file will be renamed or moved.

• Remove working copy only if unmodified – if the file has been edited, the file will be copied and renamed or moved.

Make Writable

Select one of the following options.

• Make binary files read-only

• Make all files read-only

• Make all files writable

Recursive

Check the Recursive checkbox to get the entire content, files and subfolders, of a folder. This is enabled only when the Get Latest Version is on a folder.

Only show this dialog when the shift key is down

If you select this option, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See Local Files Options to change the default selections.

OK

Click OK to retrieve the items.

Cancel

Click Cancel to close the Get Latest Version dialog box and no action will be taken.

History Diff

The History Diff dialog box allows you to compare a file or folder with a previous version or the working folder version. This dialog is only displayed when a single file or folder is selected in the History Explorer.

The History Diff dialog box can be opened:

• In the History Explorer window, select Action menu, then Diff

• Right-click on a file in the History Explorer window and select Diff

Select one of the following options. The default is Diff against working folder version. See History/Labels Options to change the default.

Diff against previous version in repository

Check the Diff against previous version checkbox to diff against the compare version previous to the one selected. This allows you to see the changes that were introduced in this version of the file

Diff against current version in repository now

Check the Diff against current version in repository now checkbox to compare the version of the file or folder selected against the most recent version checked into the repository.

Diff against working folder version

Check the Diff against working folder checkbox to compare the version of the file or folder selected against the file in the working folder.

If a working folder is not set for the selected file or folder, the Set Working Folder dialog box will open first. Select the working folder and click OK to continue with the Diff command.

A Label applied to this folder/file

Check the label applied to this folder/file to compare the version of the file or folder selected to a version of the same file or folder that is part of a label that was previously applied. The Browse button will display the list of available labels that can be compared to the selected file or folder version.

Any local folder/file

Check the any local folder/file to compare the version of the file or folder selected to a file or folder on the local disk. The browse button will display a local file/folder chooser that allows you to choose which file or folder to compare against the selected file or folder version.

Any repository folder/file

Check the any repository folder/file to compare the file or folder selected to the current version of any file or folder in the repository. The Browse button will display the current repository tree and allow you to select a repository file or folder to compare against the selected file or folder version.

Only show this dialog when the shift key is down

If you select this option, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See History/Labels Options to change the default selections.

OK

Click OK to bring up the default Diff Program.

Cancel

Click Cancel to close the History Diff dialog box.

History Get

When the History Get command is clicked, the Get Latest Version dialog box will open on the selected version of a file or folder. For example, if the current selection is a file checkin, it gets the version associated with that check in. If the current selection is a folder, it will retrieve the files (and their versions) that existed at the time of the selected folder version.

If you choose to get previous versions into the current working folder, it will overwrite what is there. If a file to be overwritten has been modified by you since the last time it was retrieved from the repository, it will be backed up in the _sgbak folder within the working folder.

For more information, please see History Explorer.

History Query Filter

The History Query Filter dialog box allows you to define the criteria for the query and sort the results. For more information, please see History Explorer.

The History Query Filter dialog box can be opened:

• From the Tools menu, select Show History

• Right-click on folder to bring up the Folder Tree Context Menu, select Show History

• Right-click on file to bring up the File List Context Menu, select Show History

• Select History on the Toolbar

• Ctrl+H

• In the History Explorer window, from the Query menu select Filter/Sort

If this dialog box is brought up while an existing query is displayed in the History Explorer, the controls are set to match that query allowing you to tweak an existing query. If you want a fresh query, a new History Explorer window must be opened.

The following criteria are available on separate tabs

General

Show History for

The Show History for box shows the current History Top. This can be changed by clicking the Change Top Object to bring up the Show History for dialog box.

Search Type

This determines the type of items displayed for folder history searches. This is disabled on files. Select one of the following options.

• View folder history by item – Shows individual item history in the History Explorer window. This shows the history of each item within a folder as a separate entry.

• View folder history by version – Shows change sets that resulted in a version change to the folder. This will list each transaction and the resulting version number of the folder in the Folder Versions window. When this type is chosen, the Dates & Labels, Users, and Sort tabs are the only criteria available to query by. All other criteria are disabled.

The default is View folder history by item.

Recursive Search

Check the Recursive checkbox to search on all of a folder’s descendents in the same query. If this is not checked, the search will be on the Top folder and any files that are direct children of that folder.

The default is Checked.

Only show this dialog when the shift key is down.

When Only show this dialog when the shift key is down is checked, the History Query Filter dialog box will not display when the History Explorer has been selected. The History command will automatically do a recursive search on the History Top for the selected item.

Dates & Labels

The Dates & Labels tab allows you to limit the query by dates or by the dates the labels were applied to file or folder. It includes the following selections. Check the appropriate filter for the search. Note that you can only choose dates or labels, not both.

• Do not filter by date

• On or after – Include changes which occur after a given date – Type a date or select one from the calendar.

• On or before – Include changes which occur before a given date – Type a date or select one from the calendar.

• Include range (of dates) – Include changes which occur between a range of dates – The dates are inclusive. Type the dates or select them from the calendar.

• Include days – Include changes which occur a number of days prior to the current date – Type the number of days or select by clicking the up or down arrow.

• Do not filter by label.

• On or after label. Include changes which occur after the label was applied. Either type a label, or select one using the Browse button.

• On or before label. Include changes which occur before the label was applied. Either type a label, or select one using the Browse button.

• Include range (of labels). Include changes that occur between the From and To label. Type the labels or select them from the Browse buttons.

The default is Do not filter by date or label.

Users

The Users tab includes the following selections. Check the appropriate filter for the search.

• Do not filter by user

• Include only selected users – When this box has been checked, the query includes only those changes made by specific users. Select a user from the list of all available users. Multiple users can be selected by holding the CTRL or SHIFT key down as you select.

The default is Do not filter by user.

Filenames

The Filenames tab includes the following selections. Check the appropriate filter for the search. Valid wild card characters are * and ? . To search for any string of zero or more characters use *. To search for any single character use ?.

• Do not filter by filename

• Include by file extension – Include only files with the specified file extension. File types can be separated by spaces, commas or semicolons. If a period is not entered before the string, it will be added. You can use the wildcard character ‘*’, but it only applies to the file extension, and not to any other part of the file (so, for example, *.txt will not retrieve any .txt files, but both .t*t and t*t will).

• Include by name substring – Include only files whose names match the input substring. The ‘*’ wildcard character can be used in the substring You cannot enter multiple substrings to query against.

The default is Do not filter by filename.

Actions

The Actions tab allows you to include only specific actions in the query. Check the appropriate filter for the search from the following list. Multiple actions can be chosen.

• Check in

• Add

• Delete

• Undelete

• Obliterate

• Pin/Unpin

• Label

• Rollback

• Rename

• Move

• Share

• Branch

• Property Change

The default has all of the actions Checked.

Comments

The Comments tab includes the following selections. Check the appropriate filter for the search.

• Do not filter by comments

• Include any comments – This includes only entries that have check in comments. Entries with no comments are not retrieved.

• Include by search string – This includes only entries that match the substring entered. You cannot enter multiple substrings to query against.

The default is Do not filter by comments.

Sort

The Sort tab allows you to specify the order in which the results of the query will be sorted. The sort columns are Name, User, Date, Version, Action and Comment. Select the appropriate columns and ascending or descending sort.

The default selection is Date with a descending sort.

OK

Click OK to filter the items and close the History Query Filter dialog box. The History Explorer will come up with results of the selected query.

Cancel

Click Cancel to close the History Query Filter dialog box. The filter criteria will not change.

Favorites Menu

Save Menu Item - Allows you to save the currently selected criteria in this dialog as a new History Favorite. Selecting Save will ask you to name the query, and it will be stored with the other History Favorites.

View – Brings up the Edit History Favorites dialog, which allows you to manage history favorites.

Item Details

The Item Details displays the Dragnet item in full detail. To view the comments associated with the item click View Comments.

The Dragnet item can be edited from Item Details.

To Edit the Dragnet item, make your changes to the item then click Update.

Label Diff

The Label Diff dialog box allows you to compare a file or folder with a version of a file or folder associated with a label. This dialog is only displayed when a single file or folder is selected in the Show Labels dialog.

Select one of the following options. The default is Diff against current version in the repository now. See History/Labels Options to change the default.

Diff against current version in repository now

Check the Diff against current version in repository now checkbox to compare the labeled file or folder selected against the most recent version checked into the repository.

Diff against working folder version

Check the Diff against working folder checkbox to compare the labeled file or folder selected against the file in the working folder.

If a working folder is not set for the selected file or folder, the Set Working Folder dialog box will open first. Select the working folder and click OK to continue with the Diff command.

Any local folder/file

Check the any local folder/file to compare labeled file or folder selected to a file or folder on the local disk. The browse button will display a local file/folder chooser that allows you to choose which file or folder to compare against the selected file or folder version.

Any repository folder/file

Check the any repository folder/file to compare the file or folder selected to the current version of any file or folder in the repository. The Browse button will display the current repository tree and allow you to select a repository file or folder to compare against the selected file or folder version.

Only show this dialog when the shift key is down

If you select this option, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See History/Labels Options to change the default selections.

OK

Click OK to bring up the default Diff Program.

Cancel

Click Cancel to close the Label Diff dialog box.

Label File or Folder

A Label allows you to create a textual tag associated with a version of a file or complete folder structure. For more information, please see Working with Labels.

To open the Label dialog box select a folder or file then do one of the following:

• Select a folder or file on the Main Window, and invoke the Label command from either the main menu or the context menu.

• Select an individual file or group of files on the Main Window, and invoke the Label command. In the case of multiple selected files, the client will create individual file label requests to the server.

• Highlight an object’s historical line item from the History Explorer, and invoke the Label command.

Item

Contains the item being labeled, and the version number that will be associated with the label.

Label

The Label field allows you to enter the label, or textual tag, that you want associated with the version of the file or folder selected.

A label name must be unique for any item being labeled. For folder labels, this includes all subfolders and files. For example, if a sub-file already has a label “Foo”, the folder cannot have the label “Foo” applied to it, because it would cause a name conflict for the sub-file.

Comment

The Comment field allows you to associate a comment with the label, which will be displayed in the Show Labels dialog and the Show History dialog for the label item.

OK

Click OK and close the Label dialog box. The label will be applied immediately.

Cancel

Click Cancel to close the Label dialog box. The label will not be made.

Label Promotion

The Label Promotion dialog allows you to make changes to a folder label by adding files or folder, deleting files or folders, or changing the version number of individual files associated with the label.

Please Note: Once you promote a label, you can no longer apply commands to that label that require a unique version number, such as Share, Branch, or Pin.

See the menu items section for information on the menu items available from this dialog.

The Label Promotion dialog can be opened from the Show Labels dialog.

Folder

Displays the name of the folder this label was applied to.

Label Name

Displays the name of the label. You can modify the label name from this textbox, and doing so will list the change in the Changes pane at the bottom. You can undo this change this by pressing the Revert button.

Folder Tree

The folder tree contains the folder structure at the time the label was applied (or the current label structure if the label has since been promoted). It is rooted at the folder for which the label was applied.

A context menu exists for folder entries that allow you to add or delete folders to the label.

File List

The file list contains the files and their versions numbers for the currently selected folder that are associated with the label.

A context menu exists for folder entries that allow you to delete files from the label or change the version number associated with the label.

Changes Pane

The Changes pane lists all unsaved changes you have made to the label. These changes get applied to the label only after you save them.

A context menu exists for the Changes pane that allows you to undo any changes before saving them.

Move

The Move dialog box allows you to move files or folders from one folder to another. For more information, please see either Moving Files or Moving Folders.

The Move dialog box can be opened by first selecting a file or folder to be moved, then:

• From the File menu, select Move

Select a folder into which file should be moved

Select a folder from the tree.

OK

Click OK to move the items and close the Move dialog box.

If Auto-Commit has been selected (default), the folder will be moved in the Vault repository immediately. If Auto-Commit has not been selected, the folder will be moved in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Cancel

Click Cancel to close the Move dialog box. The items will not be moved.

Rename

The Rename dialog box allows you to rename a file or folder. For more information, please see either Renaming Files or Renaming Folders.

The Rename dialog box can be opened:

• From the File menu, select Rename

• Right-click on folder to bring up the Folder Tree Context Menu, select Rename

• Right-click on file to bring up the File List Context Menu, select Rename

• Select Rename on the Toolbar

• Press F2

Old Name

The Old Name is the current name of the file or folder.

New Name

Type a new name into the New Name box.

OK

Click OK to rename the item and close the Rename dialog box.

If Auto-Commit has been selected (default), the folder will be renamed in the Vault repository immediately. If Auto-Commit has not been selected, the folder will be renamed in the repository as part of the next check in transaction.

Please see Auto-Commit for more information.

Cancel

Click Cancel to close the Rename dialog box. The items will not be renamed.

Save History Results

The Save History Results command opens the customary Save As window to allow you to export the results of the query for other uses. This command will retrieve and export all of the results, not just the ones currently being viewed. Choose either HTML; tab delimited text or comma separated.

For more information, please see History Explorer.

Set Working Folder

The Set Working Folder dialog box allows you to select a local folder in which to edit files from a corresponding repository folder. Working folders are automatically inherited in subfolders if no explicit working folder association exists for the subfolder.

To open the Set Working Folder dialog box, select a file or folder, then do one of the following:

• Select Set Working Folder on the Toolbar

• From the File menu, select Set Working Folder

• Right-click the selected file to bring up the File List Context Menu, then select Set Working Folder

• Right-click the selected folder to bring up the Folder Tree Context Menu, then select Set Working Folder

Select a working folder for the repository folder

Select a folder accessible to the local machine to place the checked out files.

Add new folder

Click Add new folder to create a new local folder to use as the working folder.

Ok

Click OK to set the working folder and close the dialog box.

Cancel

Click Cancel to close the dialog box without setting a working folder.

Unset Working Folder

To Unset a working folder, select the folder and click on Set Working Folder. In the Add new folder box, delete the folder name. Click OK to unset the working folder.

Share

The Share command allows you to make files or folders appear in two or more distinct places in the repository. For more information, please see Share Items.

To open the Share dialog box, select a file or folder, then do one of the following:

• Select Share on the Toolbar

• From the File menu, select Share

• Right-click the selected file to bring up the File List Context Menu, then select Share

• Right-click the selected folder to bring up the Folder Tree Context Menu, then select Share

Please specify a folder

Select a folder from the connected repository tree to place the shared file.

Comment

Type a share comment in the Comment box. This is optional.

Ok

Click OK to share the file or folder and close the dialog box

Cancel

Click Cancel to close the dialog box without sharing a file or folder.

Share Branch

A Share Branch allows you to break a link for a shared file creating a separate file at the location it was shared. For more information, please see Share Items.

To open the Share Branch dialog box select a file or folder then either:

• From the Source menu, select Branch

• Select Branch on the toolbar

Items

Lists all the files or the folder that will be branched from the share.

Comment

Type a comment for the branch operation in the Comment box. This is optional.

OK

Click OK to branch the select file or folder and return to the main window.

Cancel

Click Cancel to exit the Share Branch dialog box without making any changes.

Show History For

The Show History For dialog box allows you to specify which portion of the repository is to be included in the query. For more information, please see History Explorer.

To open the Show History For dialog box, do one of the following:

• Click on Change Top Object on the History Query Filter dialog box

• On the History Explorer window, from the Query menu, select Top

Select a file or folder

Select a file or folder from the tree.

If a file is selected for the Top of the query, then that file is the only object of interest. If a folder is selected for the Top of the query, then the query includes all changes to that folder and all of its contents, recursively.

OK

Click OK to set the Top and close the History Top dialog box and return to the History Explorer. The new selection will appear.

Cancel

Click Cancel to close the History Top dialog box. The History Top of the query will not change.

Show Labels

The Show Labels dialog displays labels in two ways:

• View labels that have been applied to a selected file or folder. This includes labels that the selected file or folder inherited from labels applied to folders above it.

• View labels that have been directly applied to folder or its descendants. This is for searching recursively below the selected folder for labels that have been applied to other files or folders below it.

To open the Show Labels dialog box, invoke the Show Labels command from the Main Window menu, or the main window folder or file context menus.

See the menu items section for information on the menu items available from this dialog.

Labels List

The List View box contains a list of all the labels in the current pane (see below for the panes or views available). It has the following columns.

• Label –The label text for the labels.

• Created At – The file or folder the label was created at, with the name and location at the time of the label.

• Version – The version of the file or folder when the label was applied. Note that if the label has been promoted, this version number will not correspond to the actual contents of the label.

• User – The user who applied the label.

• Date – The date on which the label was applied.

• Changes – The number of times the label has been promoted (changed).

• Comment – The label comment applied with the label.

• Item – The current location in the tree of the item that was labeled (which could be different from Created At if it has been renamed or moved). Note column only exists in the Recursive Labels pane.

Labels Pane

The Labels Pane displays the labels that have been applied to the selected file or folder. It contains a labels list and the following fields:

Show Inherited Labels

When checked, Show Inherited Labels will display labels that were applied to this item from folders above the currently selected file or folder in the tree. If unchecked, it shows only labels that were directly applied to the selected file or folder.

Recursive Labels Pane

The Recursive Labels Pane displays the labels that have been directly applied to the selected folder or its descendants. It contains the following fields:

Act Recursively

When checked, the Act Recursively will display label recursively, which is the default. When unchecked, it will only show labels that were directly applied to the selected file or folder.

Filter Items

Filter Items allows you to filter labels in the list to view only file label, only folder labels, or both.

Snapshot Folder

A Snapshot is similar to a Branch, but with a few differences. See Snapshots for more information.

To open the Snapshot dialog box select a folder then from the Source menu, select Snapshot

Specify a folder name

Select a folder in the tree to place the snapshot, and if desired, provide a new name for the copy of the folder.

Comment

Type a comment for the snapshot operation in the Comment box. This is optional.

OK

Click OK to create a snapshot of the folder and return to the main window.

Cancel

Click Cancel to exit the Snapshot dialog box without making any changes.

Undo Check Out

The Undo Check Out dialog box unlocks a selected file or folder that is currently checked out. It does not modify the contents of the file or folder in the repository.

The Undo Check Out dialog box can be opened:

• From the Source menu, select Undo Check Out

• Right-click on selected folder to bring up the Folder Tree Context Menu, select Undo Check Out

• Right-click on the selected file to bring up the File List Context Menu, select Undo Check Out

• Select Undo Check Out on the Toolbar.

• Press F2

If a folder is selected and there are files checked out in that folder (recursively), the undo command will be available undo the checkouts in that folder.

Local copy

Select what to do with the file in the working folder from one of the three choices.

• Revert – Replace the file in the working folder with the latest version in the repository

• Leave – Do not change the contents of the file in the working folder

• Delete – Delete the file from the working folder

OK

Click OK to undo the check out of the selected item and close the Undo Check Out dialog box.

Cancel

Click Cancel to close the Undo Check Out dialog box.

Version Details

The Version Details dialog allows you to view the history details of a selected item’s change set transaction. It shows all the items that were included in the same change set as the selected item. For more information, please see History Explorer.

This dialog box can be opened from either the History Explorer or the Folder Versions screen by double clicking an item or invoking the Details command.

The details that can be viewed, but not edited, are:

• File/folder

• User

• Version

• Date

• Files Modified as part of the version

In addition, the Change Set Comment is displayed, and can be edited if the user who made the change is the one viewing the details (or the user is the Admin user).

Version List

The Version List displays all changes to the database that match the current query. It displays changes to the repository at the location they happened – it does not list folder versions that cascade up as a result of a change.

Only one entry exists per change, except for shared items. For example, adding a file to the repository lists the file as the change item and does not list all the incremented folder versions up to the root node that happens as a result of the change. If a query includes multiple links in a shared file or folder, all links in the share will report the same action separately.

Recursive operations list history for every item affected. For example, recursively adding an entire folder of files as part of one check in will display every file that was added as a separate entry in this list (unless filtered out by one of the filter criteria).

Double-clicking an item in the list brings up the details of the change.

See the menu items section for information on the menu items available from this dialog.

This list contains the following columns:

• Name – The item the operation occurs on.

• User – The user who made the change.

• Date – The date and time the change was added to the repository.

• Version – The version number of the file or folder that resulted from the change, if applicable.

• Action – The action used that created the change to the repository.

• Comment – The user comment.

The following table lists how actions affect what is displayed in the list.

|Action |Parent Folder Action |Item History Action |

|Add Folder |Added [item name] |Created |

|Add File | | |

|Create Folder | | |

|File Check In |(no entry) |Checked In |

|Delete File |Deleted [item name] |(no entry) |

|Delete Folder | | |

|Undelete File |Undeleted [item name] |(no entry) |

|Undelete Folder | | |

|Obliterate File |“Obliterated [item name]” |(no entry) |

|Obliterate Folder | | |

|Pin File |Pinned [item name] at version [number] |(no entry) |

|Pin Folder | | |

|Move |(To Parent Folder): “Moved [item] from [from |(no entry) |

| |folder]” | |

| |(From Parent Folder): “Moved [item] to [to | |

| |folder]”. | |

|Renamed File |Renamed [old item name] to [new item name |Renamed from [old item name] to [new item |

|Renamed Folder | |name] |

|Share File |(Destination folder only): | New item lists all history from other share |

|Share Folder |Shared [repos path of shared item] as [new link|links. |

| |item] | |

|Share Branch File |Branched [item name] from share |Branched from share |

|Share Branch Folder | | |

|Copy Branch File |Branched [item name] from [trunk item path] |Branched from [trunk item path] |

|Copy Branch Folder | | |

|Property Change |(no entry) |[Property name] changed to [new property |

| | |value] |

|File Label |(no entry) |(no entry) |

|Folder Label |(Destination Parent)) Labeled [from item path] |(Destination Folder) Labeled from [from item |

| |as [to item name) |path] |

| |(Source Parent): (no entry) |(Source Folder) (no entry) |

| | |(Every new file/folder created within the |

| | |destination folder) Labeled from [item path] |

For more information, please see History Explorer.

View File

The View File dialog box allows you to view the repository copy of a file without checking it out. For more information, please see Viewing Files.

The View File dialog box can be opened:

• From the Edit menu, select View File

• Right-click on selected file to bring up the File List Context Menu, select View

• Select View on the Toolbar.

Select External Viewer application

The default choice for viewer is determined in the External Programs Options

Use system default for this file type

Check the Use system default for this file type if you would like to use the system default program for files of the same type as the selected file.

Use

Check Use if you would like to use a specific viewer to view the file. Type the viewer name in the box or click Browse to select an available viewer. Once a different application is selected, it will become the default. The default is Notepad.

Only show this dialog when the Shift key is down.

If you select Only show this dialog when the Shift key is down, the dialog will be disabled and will not appear unless the shift-key is being held down. The default selections will apply to any item selected. See Local Files Options to change the default selections.

OK

Click OK to view the selected file and close the View dialog box.

Cancel

Click Cancel to close the View dialog box.

Keyword Expansion

Keywords allow you to specify strings in your source control files that get expanded to contain dynamic content in the file when retrieved to a client.

Keywords must be enabled in the Admin Tool before they will work on files. Also, they only work on file types that are specified in the Admin Tool.

Following is a list of supported keywords. This list is identical to the list in Visual Source Safe with the addition of UTCDate and UTCModtime.

|Type this keyword |To add the following |

|$Archive: $ |Vault archive file location |

|$Author: $ |User who last changed the file |

|$Date: $ |Date and time of last check in |

|$Header: $ |Logfile, Revision, Date, Author |

|$History: $ |File history |

|$JustDate: $ |Date, without the time addendum. |

|$Log: $ |File history, RCS format |

|$Logfile: $ |Same as Archive |

|$Modtime: $ |Date and time of last modification |

|$Revision: $ |Vault version number |

|$UTCDate: $ |Same as Date, but time is given in UTC |

|$UTCModtime: $ |Same as Modtime, but time is given in UTC |

|$Workfile: $ |File name |

|$NoKeywords: $ |No keyword expansion for all keywords that follow |

Keywords are case-sensitive and must not include any blank space between the first dollar sign and the colon. Blank space and/or arbitrary text can be included between the colon and the trailing dollar sign.

• History Keywords - The History and Log keywords expand to the file’s current repository path. They result in additional lines being inserted in the file on the line following the keyword. These inserted lines are subsequently treated as text, so no further expansion or changes will occur in them (unless they, in turn, contain keywords).

You can specify optional start and end strings to be placed before and after the inserted lines. For example, “.c” files could be configured to place /* and */ around inserted lines to make them comments.

• HTML Keywords - Two dollar signs can be placed in front of a keyword to specify that it should be formatted as HTML. For example:

$$Author: $

will expand to

$$Author: -->FredFred

Note that this does not apply to history lines inserted into a file.

• Expanding Keywords - When a keyword is expanded, the new information is placed between the colon and the trailing dollar sign. Any existing text is replaced. For example:

$Author: this is some text $

will expand to (assuming Fred was the last person to change the file)

$Author: Fred $

• Preserving Spacing - Blank space can be preserved inside a keyword by using two colons. For example:

$Author:: $

will expand to

$Author:: Fred $

Note that this does not apply to history lines inserted into a file.

• Time Formats - Dates and times are presented in ISO 8601 format. Time zones are always included, but can be displayed as a number offset ("-06:00" for CST) or "Z" (for UTC time). All times are in 24-hour format, so the AM/PM designator is no longer present.

An example in non-UTC format:

2003-06-30 13:25:57-06:00

An example in UTC format:

2003-06-30 19:25:57Z

Keyboard Shortcuts

|Command |Shortcut |

|Add Files |Ctrl + N |

|Check In/Commit |Ctrl + I |

|Check In entire Change set |Ctrl + M |

|Check Out |Ctrl + O |

|Choose Repository |Ctrl + P |

|Create Folder |Insert |

|Delete |Delete |

|Exit |Alt + X or alt + F4 |

|Get Latest Version |Ctrl + G |

|Refresh |F5 |

|Rename |F2 |

|Select All |Ctrl + A |

|Set Working Folder |Ctrl + D |

|Show Differences |Ctrl + F |

|Show History |Ctrl + H |

Client Logging

Vault clients can be configured to log certain operations to a file for support and debugging purposes. Vault clients that can be logged include the Vault GUI client, the IDE client, the command line client, and the Shadow Folder plugin (since it is actually a client of the Vault server, too).

Note that the IDE client also has an additional log file (see below) that can be turned on that just logs the calls from Visual Studio, which can often be helpful in tracking down IDE issues.

Enabling Logging – Finding the Configuration File

Except for the Shadow Folder plugin, the log is disabled by defult (the Shadow Folder plugin only logs errors by default; you’ll need to edit the file to see more verbose messages). You can enable the log file by editing the application’s .config file for the executing assembly. The locations of the .config files for the various clients are found below.

• Vault GUI Client – VaultGUIClient.exe.config

This file can be found in the folder where the Vault client executables are installed, usually C:\Program Files\SourceGear\Vault Client

• Shadow Folder – Web.config

This file can be found in the folder where the Shadow Folder plugin is installed, usually C:\Inetpub\wwwroot\VaultService\VaultShadowFolder

• Visual Studio .Net 2003 – devenv.exe.config

This file can be found in the folder where the Vault client executables are installed, usually C:\Program Files\SourceGear\Vault Client.

• Visual C++ 6 – msdev.exe.config

This file is not installed with the Vault clients. Copy VaultGUIClient.exe.config to create msdev.exe.config in the folder where theVault client executables are installed, usually C:\Program Files\SourceGear\Vault Client.

• Visual Basic 6 – vb6.exe.config

This file is not installed with the Vault clients. Copy VaultGUIClient.exe.config to create msdev.exe.config in the folder where theVault client executables are installed, usually C:\Program Files\SourceGear\Vault Client.

Enabling Logging – Editing the Configuration File

Open this file in Notepad or some other text editor. The logging sections can be found near the end of the file. The relevant settings look like:

| |

| |

| |

| |

| |

| |

| |

| |

| |

| |

Set the enableLogging setting’s value to true to enable logging. However, this alone won’t be very useful, because you also need to enable specific classes for logging.

What Should I Log?

If you simply enabled logging but didn’t set any classesToLog, you’ll see very few messages in the log file. You’ll want to change the classesToLog setting’s value to something other than the default to start seeing helpful information. Here are some of the available logging classes, which you can combine in a comma separated list as per the comment’s example. Not all of them apply to all Vault clients; for example, shadowfolder only applies to the Shadow Folder service. Remember than you’ll need to restart your client for these changes to take effect.

• All – Enable all messages to be logged. This include very low-level (and numerous) events such as the mutex take/release, working folder creation/deletion, etc. The class string will appear in the log file with each message, so they can be grepped.

• Mutex – Mutex creation, take, release, and disposal

• Wf – Working folder creation, lock, unlock, disposal

• Refresh – The work the client does to request, retrieve, apply a tree structure delta from the server, and save the results to disk.

• Get – the work the client does to request files from the server, download them, and send them to the update thread..

• Checkoutlist – Writes our the partial check out lists as they are received from the server, and the full in-memory list after they have been merged.

• Mergebranches – Logs information about the merge branches process

• Shadowfolder – Logs information about Shadow Folder operations.

You can always specify all if you are not sure where the problem is, but your log file may be huge.

Where is the Log File?

You can find the log file in the %TEMP% directory of the user running the Vault client. If you’re running the standalone GUI client or the IDE client, simply open a Windows Explorer window and type %TEMP% into the location bar at the top and press Enter to find this folder. The file will be named something like “VaultGUIClient.txt”.

If you want to find the Shadow Folder’s log file, look in the temporary directory of the user the web service runs as. Usually, this is the ASPNET user, whose temp folder is something like C:\Documents and Settings\\ASPNET\Local Settings\Temp. If you have configured the Shadow Folder service to run under an impersonated account, check that users’s Local Settings\Temp folder.

Special IDE Log File

In addition to the log file above, the IDE has an additional log file that just outputs calls from Visual Studio. This is often helpful in determing issues related to Visual Studio (instead of issues within the Vault operations libraries).

To activate this log, create a registry entry named SCCLogFileName in HKEY_LOCAL_MACHINE\SOFTWARE\SourceGear\Vault Client. The value of SCCLogFileName is the path to the log file that you want to create. Once this registry entry exists, the IDE will log entries to it, after the next restart of the IDE.

Examples

Branching a Folder

Branching a folder maintains shares between files and subfolders that are self-contained within the branch, but breaks shares to any link outside the new branch.

For example: If $/foo/a.txt, $/foo/bar/a.txt and $/xyz/a.txt are all shared, and $/foo is branched to $/fooBranch, then $/fooBranch/a.txt and $/fooBranch/bar/a.txt are shared in the new branch. They are not shared with the three original links for a.txt. If in the example the $/foo/a.txt was not part of the share in the trunk, then the file would not be shared at all in the branch because there would be no other links within the branch to share with. This works the same way for folder shares that would be self-contained within the new branch. Deleted links should be counted as actual links when determining whether an item should be shared in the branch.

Folder Shares

A Folder Share keeps two or more folders completely in-sync with each other so that any change to the folder or its contents (adds, deletes, check ins, renames, etc) is automatically updated in all folders that are part of the share. This has the effect of introducing a secondary share on all the files and subfolders within the shared folder to their counterparts in the other links of the shared folder.

For example, if $/foo/bar is shared with $/xyx/bar, you can share $/foo/bar/a.txt to $/a.txt, and $/a.txt automatically becomes shared with $/xyz/bar/a.txt too. A file share icon now appears on all three links. Breaking the share at either $/foo/bar/a.txt or $/xyz/bar/a.txt will break it from both places (due to the folder share), and $/a.txt will become unshared (although if a fourth link had been created, $/a.txt and the fourth link would remain shared with each other).

Primary and Secondary Shares

The example below should help understand the difference between primary and secondary shares:

Assume we start out with the following, one shared file (a.txt) with three links.

$/bar/foo/

$/bar/foo/a.txt (Shared)

$/bar/foo/b.txt

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz

Now, we apply a folder share at $/bar/foo with $/xyz:

$/bar/foo/ (Shared)

$/bar/foo/a.txt (Shared)

$/bar/foo/b.txt

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz/foo/ (Shared)

$/xyz/foo/a.txt (Shared)

$/xyz/foo/b.txt

Now $/bar/foo is shared with $/xyz/foo, so all files within it a secondarily shared. In addition, since a.txt already had a primary share, it inherits the primary share and has a primary share the other a.txt files as well.

Now if we add c.txt and delete b.txt from $/bar/foo, $/xyz/foo gets updated with those changes as well:

$/bar/foo/ (Shared)

$/bar/foo/a.txt (Shared)

$/bar/foo/b.txt (deleted)

$/bar/foo/c.txt

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz/foo/ (Shared)

$/xyz/foo/a.txt (Shared)

$/xyz/foo/b.txt (deleted)

$/xyz/foo/c.txt

Next, if we pin a.txt, and c.txt in $/bar/foo, then a.txt and c.txt both get pinned in $/xyz/foo as well at the same version. Note that $/a.txt and $/proj/a.txt do not get pinned too, because a pin operation only applies to a single primary link. However, they apply to all links in a secondary share.

$/bar/foo/ (Shared)

$/bar/foo/a.txt (Shared and pinned)

$/bar/foo/b.txt (deleted)

$/bar/foo/c.txt (pinned)

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz/foo/ (Shared)

$/xyz/foo/a.txt (Shared and pinned)

$/xyz/foo/b.txt (deleted)

$/xyz/foo/c.txt (pinned)

Likewise, if we unpin and branch a.txt in one of the shared folders, both of them get branched from the other a.txt links.

$/bar/foo/ (Shared)

$/bar/foo/a.txt

$/bar/foo/b.txt (deleted)

$/bar/foo/c.txt (pinned)

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz/foo/ (Shared)

$/xyz/foo/a.txt

$/xyz/foo/b.txt (deleted)

$/xyz/foo/c.txt (pinned)

Note that even though $/bar/foo/a.txt and $/xyz/foo/a.txt have their primary shares broken, they are still have secondary shares, so any change made to one is made to the other. They are just not shared with the other a.txt files any longer.

Finally, suppose we re-share $/bar/foo/a.txt with $/a.txt and then branch $/bar/foo from $/xyz/foo. This results in:

$/bar/foo/

$/bar/foo/a.txt (Shared)

$/bar/foo/b.txt (deleted)

$/bar/foo/c.txt (pinned)

$/a.txt (Shared)

$/proj/a.txt (Shared)

$/xyz/foo/

$/xyz/foo/a.txt (Shared)

$/xyz/foo/b.txt (deleted)

$/xyz/foo/c.txt (pinned)

$/bar/foo and $/xyz/foo are no longer shared and changes made to one do not get reflected in the other. However, the a.txt files in each are still shared with each other, because they had a primary share prior to the folder branch.

Query Description

The Query Description is displayed beneath the menu bar. The basic format of the description is:

[RECURSIVE] changes [ACTIONLIST] to [TOP], made by [WHO], [WHEN], including [WHICHFILES], with [COMMENTCRIT], sorted by [SORT].

• [RECURSIVE] – Recursive or Non-recursive depending on selection in query.

• [ACTIONLIST] – If the current query is filtering by actions, the actions are collected into a list and displayed.

• [TOP] – The complete repository path and name of the file or folder which defines the top of the query.

• [WHO] – If the current query is filtering by user, the list of the filtered users is displayed.

• [WHEN] – If the current query is filtering by date, the filtered date is displayed.

• [WHICHFILES] – If the current query is filtering by filename, the filter is displayed. For example: only files/folders with names containing ‘gr’

• [COMMENTCRIT] – If the current query is filtering by comment, the filtered comment is displayed.

• [SORT] – The name of the column on which this query is sorted, followed by the word ‘ascending’ or ‘descending’.

Rename and Working Folders

If the working folder is inherited, the rename will alter the current working folder and the rename will act as if you changed the working folder. This means that all the files in the selected folder will have their status changed to Unknown or Missing. If you specifies a working folder for the folder that is renamed, the working folder and the status of all the files in the folder will not change.

For example, if $/foo has a working folder specified as c:\foo, then $/foo/bar inherits c:\foo\bar as its working folder. If $/foo/bar is renamed to $/foo/barnone, its new working folder is c:\foo\barnone, and no files in $/foo/barnone exist, so their status is all Missing. However, if $/foo/bar already had a working folder of c:\someotherfolder, then renaming $/foo/bar has no effect on its working folder – it is still c:\someotherfolder and the files all retain their current status. Note this logic applies recursively to all folders below a rename, since they all could have different working folders after a rename

Share Branch

If the Share Branch is on a shared folder, it is implied recursive. If a folder branch is applied to a Secondary Share on a folder, the operation is a Copy Branch rather than a Share Branch, meaning you can only Share Branch from a Primary Share.

For example: If a share was done on $/foo and a branch is applied to $/foo/subfolder, then the Copy Branch command is invoked on $/foo/subfolder, and you would choose another location to copy the folder to. $/foo/subfolder would remain shared after such a branch. Breaking the share must be done at $/foo. This applies to any files as well. For example, $/foo/abc.txt would invoke a Copy Branch on abc.txt, not a Share Branch.

Naming Syntax, Conventions and Limitations

User names

Length of user login = 64

User names can consist of any alphanumeric characters, plus dashes and underscores.

A user name cannot consist entirely of periods or spaces.

User passwords

Length of password = 128 chars

Can be empty.

Repositories

Length of repository name = 256 chars

Label Names

Length of label names = 256 chars

File Names

Length of a single file or folder name= 256 chars

Filenames are case-insensitive, so for example, files called File.txt and FILE.txt cannot exist in the same folder.

Filenames can consist of any characters except: / \ : * ? “ < > |

A file or folder name cannot consist entirely of periods or spaces, nor can it end in a period.

Paths

Length of an entire path in tree = 1024 chars

Groups

Length of a group name = 32

Length of group description = 256

Size of File Stored in Database

Limited to SQL or MSDE limits for binary large objects (image column type).

Number of Versions of a Given File

2^63-1

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download