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 Standard 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 Standard, 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.

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.

Note

The Vault Standard Client does not support mulitple users working from the same working folder.

The Vault Standard Client was designed to provide accurate file status information to users, and expects a one-to-one relationship between user, repository folder and working folder. Both the Vault Standard client and Vault Standard integration with Visual Studio use baselines to determine the status of files in the working directory.

Working folder file status values my be erratic if multiple users have configured the Client to use the same working folder, or if the same directory is a working folder for more than one Vault repository.

When a user does a Get Latest from the repository, the Vault Standard Client creates a copy of the file in the _sgvault (baselines) folder. The Vault Standard client gets a new baseline every time the user performs a Get Latest, and when the user checks in a modified file. By default the baselines are in the user's local settings folder.

The client compares the file in the working directory with the baseline to determine if the file has changed. If the file in the working directory has changed, or has a different timestamp than the baseline, Vault considers the file to be Edited, Renegade, More Recent, Needs Merge, etc.

When more than one user works in the same working folder, the Vault Standard Client will display incorrect working folder status because the Vault is comparing working folder files against files not updated by the user's specific Vault Standard client. Also, users may have inadvertently removed the read-only file status or modified the file's timestamp which may cause the Vault Standard client to overwrite files modified by other users.

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 Web Client to delete files. To activate the dialog box, click Delete from the File menu or on the Toolbar.

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 Standard client does not allow operations which destroy history. The Obliterate command is available in the Vault StandardAdmin Web Client.

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 Standard repository immediately. If Auto-Commit has not selected, the files will not appear in the file list, but will actually 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:

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 Standard repository immediately. If Auto-Commit has not been selected, the files and folders will appear to be renamed in the client, but will not be renamed in the repository until the the rename transaction is committed.

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 Standard repository immediately. If Auto-Commit has not selected, the files and folders will appear to be moved in the Vault Client, but will not be moved in the repository until the transaction is committed. 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 to another user.

  • You cannot pin a folder that has a file checked out by another user 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's context menu, or you can Pin a historical version from the History Explorer. Pin and Unpin operations from the History Explorer are placed in their own changeset (which is independent of any other pending changes) and always happen immediately, regardless of the Auto-Commit option. Pin operations from the main window will obey the Auto-Commit option.