Moving Files

From Seapine Labs

Contents 1 Introduction 2 The Current Structure 2.1 Repository Structure 2.2 Branch Model 3 The Need to Reorganize 3.1 Moving the Files 3.2 Step by Step Process 4 Issues, Caveats and Pitfalls 4.1 Can Not Promote or Rebase Any More 4.2 Pre-Existing Shares Are Gone 5 Conclusion

[edit] Introduction

One common question that is asked by users of Surround SCM is how to move files without losing history. This usually comes out of a need to restructure the repositories.

Because all the branches in a mainline point to the same archive object, there is really no easy and clean way to move files. If a drastic change is needed, I suggest to pick a 'cut off' time and start a brand new mainline branch.

Maybe the end of a major development cycle, the end of the business year, you pick a time that any new feature development will start on the new mainline brach. You will keep the existing mainline branch and child branches for maintenance releases and reference.

There are no limits to how many mainline branches you can have. You can keep the old one until enough time passes away where it is rarely referenced and the old releases no longer mantained. When the time arrives, you can remove the mainline branch and archive it. You can always add it back with a couple of mouse clicks ("Tools">"Administration">"Add Existing Mainline Branch") if it is needed again.

Keep in mind that each mainline will be kept in separate databases and that they are completely separate.

In this article I will illustrate a reorganization of repositories in Surround SCM. I will show how to move files without losing their history, but at the same time will also show the caveats and pitfalls that you will run into.

Please make sure you read the entire article before doing any action mentioned in this article. The article purposefully shows possible incorrect/undesired actions to show possible pitfalls

[edit] The Current Structure

First, let's look at the current repository and branch model that is in Surround SCM. For this article, I am using the same database that is used for training and for the weekly public Surround SCM demo. We will be using the ficticious company WysiCorp, Inc.

[edit] Repository Structure

WysiCorp, Inc. has several products on the market. Some are native OS applications and some are web applications. Under the original repository model, a mainline branch was created using the company name, and then a repository for each product was created under the main repository.

Figure 1 below illustrates this structure.

[edit] Branch Model

WysiCorp, Inc. decided that the best way to approch their development cycle is through the Branch By Purpose branch model. In a nutshell, this model dictates that all new feature development is performed on the mainline branch. For each version or release of each specific product, a product repository is branched off, meaning that the new branch starts at the product repository, not the main repository. Snapshot branches are then created off this branch whenever certain milestones are reached or relases are made.

Figure 2 below illustrates the branch model currently in place for WysiCorp, Inc.

Figure 3 below illustrates how a maintenance branch is branched off a product repository. Notice that the top level repository is not "WysiCorp, Inc.", like on the mainlie branch (figure 1 above).

[edit] The Need to Reorganize

WyisCorp, Inc. decided that the current repository structure is a little too cluttered. They would like to now divide their OS native applications and their web applications into separate repositories.

The end result will be two subrepositories under the top repository in the mainline branch, one for the OS native applications and one for the web applications.

[edit] Moving the Files

There is no 'move' file functionality in Surround SCM. The only way to move a file is to first share it to the destination, break the share, and then destroy the original file. This is the only way to preserve the history.

Doing this file by file in this situation would take a long time. Luckily you are able to select a repository and share its entire contents at once. You can also break shares at the repository level.

[edit] Step by Step Process

The first step in the reorganization process is to create the two new repositories under the main repositories. We rigth click on the main repository on the mainline branch and select "Create Repository". Two new repositories are created under the main repository. Figure 4 below shows the two newly created repositories.

Next, we start the process of sharing each project repository to its new corresponding parent repository. For example, WysiCM is a native OS application. To share it, we select the repository and drag it to its corresponding new parent repository. The share files dialog appears. We make sure the check the 'recursive' check box. This ensures that all of the files under child repositories are also shared.

The main advnatage of sharing a group of files at the repository level is that Surround SCM will create the repositories for you. This makes this very easy. Figure 5 below illustrates the share file dialog window.

This process is repeated for every single product repository. Figure 6 below shows the end product.

Now that all the product repositories have been moved, the next step is to break the shares and then destroy the original product repositories.

To break the shares, we right click on a product repository and select "Break Shares...". This opens the Beak Shares dialog window. Notice that if the repository has child repositories, you have a "recursive" check box available. This it to break the share of files in the child repositories.

The process is repeated on each original product repository.

Once the shares are all broken, we can proceed with destroying the original product repositories. To destroy a repository, we right click on the desired repository and click on "Remove Repository". The Remove Repository dialos window appears. To destroy the repository, we check the "Force recursive remove" and "permanently destroy repositories and contents" checkboxes. The process is repeated for each original product repository.

Figure 7 below shows the repository structure once all of the original product repositories have been destroyed.

[edit] Issues, Caveats and Pitfalls

At first glance, once could say that this process is pretty straight forward and simple, what is the big deal?

While at first that may appear to be the case, once users start to continue work, some issues (some major) may start to become apparent.

[edit] Can Not Promote or Rebase Any More

The main issue that WysiCorp, Inc. will run into is that they will not be able to promote or rebase files from the pre-existing child branches. This is because in these branches, for each file, the archive object that they point to in the database is no longer referenced in the Mainline branch.

For example, in the WysiCM repository, there is a file called AssemblyInfo.cs. This file resides a couple of repositories under the main WysiCM repository. The file in Surround SCM is not known simply as "AssemblyInfo.cs", rather it is known by an entire path, "WysiCorp, Inc./WysiCM/WysiCM/Properties/AssemblyInfo.cs". This object is no longer referenced on the mainline branch. This file on the mainline branch is now "WysiCorp, Inc./Native OS applications/WysiCM/WysiCM/Properties/AssemblyInfo.cs".

When they try to promote this file to the mainline branch, they get an error message that the record is not found, may not exist.

How to overcome?

WysiCorp, Inc. could overcome this problem two ways:

- Not breaking the share and not destroying the original parent repository on the mainline branch. The promote would then update the original file on the mainline branch, and since the share would still exists, the merged changes would be visible on the new repository as well. Drawback: This would make the repositories under the mainline branch even more cluttered than when they started out.

- Recreate All the Branches. Surround SCM gives you the option to create a branch based on timestamp. Looking at the existing child branches' history, this feature could be used to create new child branches using the timestamp of when the original child branch was created. The new branches would point to new files and promotes and rebases could then continue. Drawback: This would create the branches with the same content as when they were originally created. Any changes on the original branches would have to be merged. The easiest way to do this would be to recursively get the latest version from the orignal child branch into the working directory of the new child branch and then check the files into the new branch.

[edit] Pre-Existing Shares Are Gone

In the process of moving the files, it is recommended that the shares are broken before the original files are destroyed. If these files were already shared somewhere else, then that share may also be destroyed.

This situation may be avoided if the "break share" action is performed on the new repository instead of the old one.

[edit] Conclusion

Moving files in Surround SCM is possible, but one must understand the scope of the operation before one undertakes such action. After reading this article you should be able to make a good decision between starting with a new mainline branch or doing the above.