November 1, 2007
Anatomy of a Share
Applies to Surround SCM 2008 and earlierImproper understanding of Surround SCM file sharing can lead to undesired situations. This article explains more of what actually occurs in the backend database. It should help you understand how Surround SCM shares files and its benefits. [toc] To learn more about how to share files, refer to the Surround SCM Sharing Strategywiki article. The main purpose of Surround SCM is to preserve file history, which is one reason why Surround SCM can be used in heavily regulated industries. This is also the main reason why there is no undo available in some situations or why a user can get into an irreversible situation. Surround SCM will not allow a user to perform any action that compromises the history of a file. Note: In Surround SCM 2009, data is stored in an RDBMS system. Some of the limitations mentioned in this article are not present in Surround SCM 2009.
The Example - How Sharing WorksA simple set up was created to test different scenarios and to display what occurs in these different scenarios. First, a mainline branch named 'Sharing Branch' is created, along with two child repositories, Repo A, and Repo B.
There is one archive directory assigned to every unique repository path ("Sharing Branch/Repo A", for example). Archive directories contain the repository database files that hold all the meta-data for files in the repository, and for all branches that the repository appears in. The actual file delta data and header data needed to reconstruct every revision of a file are stored in the aaaaaaaa/data sub-directory (referred to as the archive delta directory). The key here is that the archive delta files contain data that is referenced by the metadata for all branches of the mainline. This allows Surround SCM to be able to determine common ancestors across branches, even when files or repositories are renamed or removed or shared in one branch, but not another.After the repositories are set up, a new file is added to Repository A and immediately shared with Repository B:
It is important to note that the files in the database may not always have the same name as the file originally added. The name of the file might need some modifications to ensure that the name is portable to other file systems or if the name contains any unicode characters. Surround SCM will also choose a different name if the name would conflict with its naming convention (i.e., if a file named test.info is added).
Breaking SharesFirst, here is a high level definition of both types of break shares available in Surround SCM: Local Break Share A local break share refers to when “Break Share” is selected from the context menu of a file. A local break share is local to the branch that is being executed on. If the share exists on other branches, the share will be left intact in other branches. Internally, with a local break share, there is still a single archive object. Surround SCM creates different deltas for each change that occurs in each repository to keep the changes separate. In a local break share, Surround SCM breaks the share in the repository database for the branch in which the break was performed, but the file share and archive link remain in all other branches. The archive link remains because Surround SCM needs all the file delta information in the same place, so it can auto-merge any changes when promoting/rebasing between branches that still contain the unbroken share. Global Break Share A global break share refers to when "Break Share All Branches" is selected from the "Tools">"Administration" menu. A global break share is global because it applies to all branches. Internally, the archive object is copied to the folder for the other repository. The files are also truly separate copies in the database. The global break share breaks the internal archive link by copying the 'archive delta files' to both locations, so they each now have the complete history. Global break share also breaks the 'file share' in all branches. Restoring Shares It is important to understand the difference between the base of a share and the actual share.
- The base of a share is the file that is shared to another repository location.
- The share displays the history of its share base. All check ins to the share are really performed on the base. A share has no history of its own.
Single Branch ScenarioLocal Break Share In the single branch set up above, 'break share' is selected from the context menu.
- It removed all contents from the aaaaaaac/data/ folder (data folder for Repo B.
- It removed the file mytextfile.txt.link from the aaaaaaab/data/ folder.
This behavior is because we are in a single branch scenario. If the file existed in other branches, the files in the data folders would not be removed since they would be needed for those other branches. The file can now be shared again from Repo A to Repo B. Global Break Share Now we will see what happens when a global break share occurs. Select "Break Share All Branches" from the "Tools" > "Administration" menu. Figure 11 below illustrates the contents of both folders after the global break share action.
This behavior is because we are in a single branch scenario. If the file existed in other branches, the files in the data folder would not be removed since they would be needed for the other branches.The file can now be shared again from Repo A to Repo B.
Multiple Branch ScenarioTo illustrate how shares work in a multiple branch scenario, a baseline branch is created. The new branch is named "Sharing 1.x", and it contains both Repo A and Repo B. As illustrated by Figure 12 below, the files are also shared in the new branch.
- Share file from Repo A back to Repo B.
- Rebase from Mainline. This places the file on Repo B like a new file.
- Globally break share while selecting the file on Repo B in the baseline branch.
- Destroying the file from Repo B in the baseline branch.
- Destroying the files from Repo B in the mainline branch.
Directory contains a Surround SCM Mainline database.aaaaaaac/data/mytextfile.txt - was purged. You are now able to share the file. Losing the Share With branching, the only way to preserve the share in the new branch, is if the branch contains the base of the share. In the previous above, the share was preserved because Repo A was included in the new branch. Had it not been included, the file would have lost its share on the new branch. To better illustrate this, let's rewind back to our database before any branch we created. Suppose a child repository named "SubRepoB" is created under Repo B, and the file is shared from Repo B to SubRepo B. The result is illustrated in the following image: