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 Professional 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 implicitly 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.

  • Snapshots vary from branches in the following ways:

  • Snapshots are only available on folders

  • A snapshot folder is clear rather than buff.

  • 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.