The first part of configuration is deciding what to migrate. This is an important step because you not only need to consider what you want to migrate right now, but what features of Team Foundation Server you might want to use later and what you would need to migrate in order to use them.
For instance, if you want to migrate a single release branch, but know that sometime later you will want to use the built in branching/merging functionality of Team Foundation Server, you should plan to migrate the main development branch the release branch was branched off of.
If you have a source database that hosts multiple products, you should think about what Team Projects you want them to be migrated to and how you manage labels. Labels within TFS are global to a team project. If you have multiple products which each started off on a version 1.0 release and they have labels corresponding to build numbers that are unique to the product, but conflict across products, they will conflict in the Team Foundation Server "Find Label" UI and you’ll find your different products attributed to the same label.
To help prevent label conflicts there are two main options. The first is that you could move each product to a separate Team Project. Due to the performance considerations of having many Team Projects as well as user maintenance of each Team Project you may still want to locate the different products in the same Team Project. If that is the case you can migrate each product with a separate session and use the label prefixing functionality to add a prefix specific to the product.
Selecting what to migrate also includes what to ignore. Often times the source tree may be used to store large binary files that are loosely related to the product, but are not directly used in the official build process, such as SDK installs, sample databases or even documentation. Since these files will take up hard drive space on client machines and increase the overall time required to perform a get from TFS, it may be a good idea to prune them from the tree using cloaked folder mappings.
Once you have an idea of what you want to migrate it is time to use the MigrationConfig.exe application to create a new configuration file for a session with the settings you want. To start, launch MigrationConfig.exe and you should see the following form:
Select File->New to create a new configuration file. At this point you will be prompted to select some basic information for the session as shown in the following dialog:
Under "Adapter Type" select the Timely Migration adapter that corresponds to your original source control system. Note that because some of the APIs that vendors provide deprecate older releases there may be multiple entries for a given adapter type, each of which might have slightly different prerequisites. For instance, Microsoft stopped supporting TFS 2008 in their APIs that were bundled with Visual Studio 2013. So to migrate from TFS 2008 systems you would need to select the "TFS 2008 to TFS" adapter instead of "TFS to TFS" and you would need to have the Visual Studio 2012 TFS APIs installed on the system used for migration.
"Session Name" should be filled in with something that corresponds to what you want to migrate. If you are unsure of exactly what you want to migrate and think you may be performing multiple migrations, it is a good idea to add an identifier that indicates which iteration you are on.
Once these fields are filled out, select OK to start a new configuration file. At this point you should be brought back to the main form and new tabs should exist for the various types of information that you can configure for the selected Timely Migration adapter. Each of these tabs is described later in the Session Configuration section.
If the prerequisites for the adapter that are you are trying to configure are not installed on the system you will get an error message identifying the prerequisite that appears to be missing. You will still be able to configure a session without having the prerequisites installed on the system, but attempts to perform the migration will fail.
To save the configuration file, select either File->Save or File->Save As or press Ctrl-S.
Sample configurations are provided for each source control system under the Samples folder. To view them, launch MigrationConfig.exe, select File->Load to bring up an open file dialog and then select the configuration file you want to view.
During the migration process there may be configuration settings that you will want to adjust such as reorganizing where branches are migrated to or what content should be dropped out of the migration.
Note: When changing certain configuration settings such as folder mappings, errors can result if the same session is restarted and the paths after the restart no longer match the paths used before the restart. To prevent issues make sure to use a new session name.
To edit an existing configuration, launch MigrationConfig.exe, select File->Load to bring up an open file dialog and then select the configuration file you want to edit.
If the prerequisites for the adapter that are you are trying to edit are not installed on the system you will get an error message identifying the prerequisite that appears to be missing. You will still be able to edit a session without having the prerequisites installed on the system, but attempts to perform the migration will fail.
If you have already performed a migration, it should be noted that the staging database which stores session state will contain information about the current session. This session state is normally used to continue a migration where it was left off, but if you want to perform a new migration from the beginning, it will have the effect of preventing the migration.
In order to be able to run a new migration, you should either rename the session by pressing the "Rename" button next to the "Session" box or drop the staging database. Renaming the session used in conjunction with a setting to prefix labels with the session name has the benefit that the labels will not get overcrowded with files from multiple sessions. If the staging database is getting large and SQL Express is being used as the database engine, you may want to drop the staging database to prevent database size restrictions from being enforced.
Note: If you have performed a migration to a production server, the staging database will contain information that you may need if you ever want to continue a migration to pick up changes after an initial migration or if something in the initial migration needs to be repaired. To allow for these operations in the future the database should be backed up and archived before it is dropped.
In addition to state stored in the staging database, if the session had previously completed, TFS will contain files and labels that correspond to the current session. To prevent conflicts with files, you can either change the destination for files to as described in the Folder Mappings section so that they are different for the new migration or move/delete the folders within TFS.
Moving files within TFS over deleting files in TFS has the added benefit that you can more easily look at file history if you are trying to compare results from the different migration attempts.
To prevent conflicts with labels, labels can be automatically prefixed with either the session id or a specific prefix and is described more in the Settings section.
The "Source" tab contains information related to where the source that you want to migrate is located such as connection information for the source control database. As the connection information will be different across various source control systems, the contents of the "Source" tab will be tailored to each source control system.
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
CVSROOT | This setting stores the CVSROOT string that CVS and WinCVS use to locate the CVS database and help determine what type of authentication, user name, and password to use. |
Module | This setting stores the name of the CVS module that you want to migrate source from. |
Working Directory | This setting stores the name of a directory to be used with retrieving files from the origin source control system. The migration will overwrite all files in this directory so it should be a directory dedicated to the migration. |
Download Cache Directory | This setting stores the name of a directory to be used to cache individual files revisions. If repeated migrations are run, this setting can speed up the migration greatly if the database is a remote database. Additionally if there are problems with individual file revisions on the server, the file in the cache can be updated to hold a correct revision. |
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Connection String | This setting stores the connection string for the SQL server to connect to. |
Project | Name of the Project that should be used to connect to the SQL interface. |
Project Required | Specified whether Projects are required for the SQL interface. |
Working Directory | This setting stores the name of a directory to be used with retrieving files from the origin source control system. The migration will overwrite all files in this directory so it should be a directory dedicated to the migration. |
Download Cache Directory | This setting stores the name of a directory to be used to cache individual files revisions. If repeated migrations are run, this setting can speed up the migration greatly if the database is a remote database. Additionally if there are problems with individual file revisions on the server, the file in the cache can be updated to hold a correct revision. |
Stored Procedure - Projects | Name of the stored procedure to use when retrieving projects. This is only used by the configuration UI to browse projects if projects are supported. |
Stored Procedure - Branches | Name of the stored procedure to use when retrieving branches. |
Stored Procedure - Folders | Name of the stored procedure to use when retrieving folders. This is only used by the configuration UI to browse folders when creating folder mappings. |
Stored Procedure - Revisions | Name of the stored procedure to use when retrieving revision header information. |
Stored Procedure - Revision Items | Name of the stored procedure to use when retrieving the operations performed in each revision. |
Stored Procedure - Item Content | Name of the stored procedure to use when retrieving item contents. |
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Server | This setting stores the name of the StarTeam server to connect to. |
Port | This setting stores the port that the StarTeam server is listening on. |
Username | Name of the user that should be used to connect to the StarTeam server. |
Password | Password for the user that should be used to connect to the StarTeam server. |
Project | This setting stores the name of the StarTeam project that you want to migrate source from. |
Working Directory | This setting stores the name of a directory to be used with retrieving files from the origin source control system. The migration will overwrite all files in this directory so it should be a directory dedicated to the migration. |
Download Cache Directory | This setting stores the name of a directory to be used to cache individual files revisions. If repeated migrations are run, this setting can speed up the migration greatly if the database is a remote database. Additionally if there are problems with individual file revisions on the server, the file in the cache can be updated to hold a correct revision. |
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Repository | This setting stores the location of the Subversion repository to connect to. |
Username | Name of the user that should be used to connect to the Subversion server. |
Password | Password for the user that should be used to connect to the Subversion server. |
Working Directory | This setting stores the name of a directory to be used with retrieving files from the origin source control system. The migration will overwrite all files in this directory so it should be a directory dedicated to the migration. |
Download Cache Directory | This setting stores the name of a directory to be used to cache individual files revisions. If repeated migrations are run, this setting can speed up the migration greatly if the database is a remote database. Additionally if there are problems with individual file revisions on the server, the file in the cache can be updated to hold a correct revision. |
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Server | URL of the TFS server to migrate changes to. |
Working Directory | This setting stores the name of a directory to be used with retrieving files from the origin source control system. The migration will overwrite all files in this directory so it should be a directory dedicated to the migration. |
Download Cache Directory | This setting stores the name of a directory to be used to cache individual files revisions. If repeated migrations are run, this setting can speed up the migration greatly if the database is a remote database. Additionally if there are problems with individual file revisions on the server, the file in the cache can be updated to hold a correct revision. |
The "Destination" tab contains information about where the source should be migrated to. As the connection information will be different across various source control systems, the contents of the "Destination" tab will be tailored to each source control system.
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Repository | Path to the repository to migrate changes to. For initial migrations, it is recommended to use a local path to create a new repository and push the respository to the destination server once the session is complete as it will perform better. Afterwards incremental migration can use remote repository paths which will push each commit as it is made. |
Working Directory | Files in this folder will be repeatedly cleared out and updated. For local repositories it should be separate from the Repository path. For remote repositories it will be used to clone the remote repository. |
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Server | URL of the TFS server to migrate changes to. |
Workspace Name | This setting is used to identify the TFS workspace to be used with the migration. Files in this workspace will be repeatedly cleared out and updated so it is recommended that a dedicated workspace for the migration is used. |
Workspace Directory | This setting is used to identify the folder that the workspace will be mapped to on disk. Files in this folder will be repeatedly cleared out and updated so it is recommended that a dedicated folder for the migration is used. |
The "Staging Database" tab contains connection information for the SQL database used to store session state. As each Timely Migration adapter makes use of the staging database, the "Staging Database" tab will be the same across all Timely Migration adapters and will look like the following:
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Server Instance | The location of the server and SQL instance name to connect to. |
Database Name | This setting is used to identify the individual database to be used. |
Integrated/Windows Security | This setting is used to identify whether the Windows credentials of the logged in user will be used to connect to the database server. |
Username | This setting specifies the name of the user to connect to the database server if Windows credentials are not being used. |
Password | This setting specifies the password of the user to connect to the database server if Windows credentials are not being used. |
Connection Timeout | This setting is used to specify the connection timeout when attempting to connect to the database server during a migration. |
The "Settings" tab stores various options for how source control data should be migrated. As different source control systems have different characteristics, these options will change based on the source control system. The "Settings" tab will look like the following although not all adapters will show all fields:
The settings common between Timely Migration adapters are as follows:
Setting Name | Meaning |
SkipAnalysis | This setting can be used to disable analysis. Configure this setting to 'true' to skip the analysis phase. This setting can be used when troubleshooting issues in the migration phase to skip over the time it takes to perform an analysis. |
SkipMigration | This setting can be used to disable migration. Configure this setting to 'true' to skip the migration phase. This setting can be used when troubleshooting issues in the analysis phase to prevent any migration from occurring with analysis data that you want to examine. |
LoggingMode | This setting can be used to change the level of detail logging provides. 'Normal' - Regular log messages will be displayed. 'Verbose' - Detailed log information will be displayed. Note that setting logging to verbose may increase the size of the log file dramatically. |
ConfirmCheckins | This setting is used to have the session pause before checkins to allow pending changes to be reviewed before the checkin is committed. |
PrefixLabels (TFVC destinations only) |
This setting is used to add a prefix to any labels that are migrated. Configure this setting to the prefix that you wish to use. If multiple source projects have similar version schemes and are migrated to the same TFS project, this setting can be used to prevent label name conflicts. |
PrefixLabelsWithSessionId (TFVC destinations only) |
This setting is used to add a prefix to any labels that are migrated. Configure this setting to 'true' to automatically prefix labels. If multiple source projects have similar version schemes and are migrated to the same TFS project, this setting can be used to prevent label name conflicts. Additionally if you are performing multiple test migration attempts, this setting can be used to automatically change the label name based on the session id to prevent conflicts. |
IncludeLabels | This setting is used to filter labels that will be migrated. Only labels matching the label filter will be migrated. The format is a list of semi-colon delimited System.Text.RegularExpressions.Regex expression strings. Filtering for labels in either a 1.1 or 1.2 version would be represented by '1\.1;1\.2'. If you are have labels that are too long to fit in TFS, ^.{1,63}$ can be used to restrict labels to only those that will fit within TFS. |
ExcludeLabels | This setting is used to filter labels that will be migrated. Labels matching the label filter will not be migrated. The format is a list of semi-colon delimited System.Text.RegularExpressions.Regex expression strings. Filtering out labels in either a 1.1 or 1.2 version would be represented by '1\.1;1\.2'. |
RenameLabels | This setting is used to provide a way to perform basic renames on labels that are migrated. Sometimes label name conventions do not apply to TFS or can exceed the TFS limit of 64 characters so label names need to be changed to migrate them to TFS. The format is a list of semi-colon delimited pairs, where each pair has a format of <SourceText>:<ReplacementText>. Only basic string matching is performed. Regular expressions are not supported. An example to change labels to include periods which is something that CVS does not support would be "Build1_0_:Build_1.0.;Build1_1_:Build_1.1.". |
MigrationChangeCommentModifier | This setting is used to override the text that is appended to the end of each checkin comment to indicate that the change was made as part of an automated migration process. Keywords can be used to reformat the entire comment string. The currently supported keyword are: $(DateTime) - Original change timestamp $(Comment) - Original change comment $(Name) - The name used to track the change. This will translate to a source id if supported. $(WorkItemIds) - For adapters with TFS as the source, this will translate to a comma separated list of work item ids. Use the UseCommitMentionLinking setting to add the # prefix to link the work items for the final production migration in a same Azure DevOps collection migration. |
UserMappingFile | This setting can be used to set the name of the user mapping file to be used with the migration. If a file is not specified the user mapping file will default to "<SessionId>UserMappings.xml" |
DefaultUserEmailDomain (Git destinations only) |
This setting is used during the user mapping process to create default mappings for Active Directory accounts to email addresses for users that are no longer active. |
MigrationLogFile | This setting can be used to customize the name of the log file that the migration writes to. If a file is not specified the log file will default to MigrationConsole.log in the Timely Migration installation folder. |
MigrationStopChangeGroup | This setting can be used to stop the migration phase at a particular change group to assist in debugging or correcting issues with the session. |
ItemExistsHandler | This setting is used to determine what action to take if an Add operation is being attempted on an item that already exists. 'Fail' - This error will cause the migration to fail. This is the default option if a value is not specified. 'Ignore' - A warning message will be logged and the migration will continue. 'ChangeToEdit' - The operation will be changed to an Edit operation. |
SessionContinuationWarning | This setting is used to alert the user if they are continuing a session that was previously run. Configuration changes will not be reflected in previously analyzed or migrated data, so if a user is unaware that they are continuing a session the warning alerts the user that they may not see the changes they expect. |
DuplicateDestinationPathWarning | This setting is used to alert the user in the configuration tool if they have configured multiple folder mappings to have the same destination path so that they can validate whether this was intentional or if it was a typo. If the original source tree has been renamed a number of times multiple mappings may all point to the same destination structure to remove the rename from the migration. But if a folder mapping was copied and meant to be modified, having two separate folders with the same destination can cause conflicts with files from both folders migrating on top of each other. |
VerifyWorkspaceMappings (TFVC destinations only) |
This setting is used validate that each action to be migrated is under a valid folder mapping. If folder mappings have changed between restarts of a migration, it can result in files that are outside of the workspace that will not be migrated and result in errors. |
DropLongPaths | This setting can be used to drop out items that are causing errors by having a server path or a local path that exceeds the maximums defined by Windows. Typically local paths can be made shorter by changing the Workspace Directory used by TFS in the Destination tab. |
AggressiveWorkspaceMapping (TFVC destinations only) |
This setting can be used to try to work around errors caused by having a server path or a local path that exceeds the maximums defined by Windows. Enabling this setting will cause the TFS Workspace to get recreated with each checkin to try to shorten the path based on just the actions within the current changegroup. Note that the trade off is the additional time required to recreate the TFS Workspace with each checkin. |
BackDateTimestamps (TFVC destinations only) |
This setting can be used to attempt to reset checkin times in TFS to that of the original source checkins. Note that TFS currently restricts this functionality to prevent resetting checkin times before any other changes that are in the Team Project Collection. This will require a new Team Project Collection for each migration you want to reset checkin times for. Additionally this feature requires TFS 2010 SP1+ to be installed on both client and server machines in order for it to function. |
ChangeToAddOnBranchSourceNotFound (TFVC destinations only) |
This setting is used when examining history on items that have their branch or merge source as an item that is not mapped in the migration. If this value is set to true, then the migration will omit the relationship between the items. If this value is set to false, the migration will fail to allow folder mappings to be corrected. |
SkipFileDownloadFailures | This setting is used to have Timely Migration skip any download failures and commit 0 byte file place holders. Typically this is used to work around issues with the source repository not returning data for specific file revisions. |
SkipLabelFailures | This setting is used to have Timely Migration skip any label failures and drop out the files which could not be labeled. Typically this is used to work around issues where files may be missing do to conflicts with case sensitive file names. |
FileDownloadRetryCount | This setting is used to determine how many times Timely Migration will attempt to download a file before considering it a bad file in the repository and not a connectivity issue before moving on. |
DownloadCacheFileSizeLimit | This setting is used to individual file revisions over the specified size from being cached in the download directory. This can be used to control the size of the download cache by preventing large binary files from being persisted in the cache. Values can be formatted as: 65536 65536B 64KB 64MB 64GB |
GitIgnoreOverride (Git destinations only) |
This setting is used to provide filtering capability based on the .gitignore format. It can be used along with GitIgnoreMode to add to additional rules to customize what is left out of the migration or to replace the rules from the committed .gitignore file if historical .gitignore revisions cause items to drop out. A separate .gitignore file will still need to be added to the repository to handle day to day activities. |
GitIgnoreMode (Git destinations only) |
This setting is used to specify how .gitignore will be processed. 'None' - Ignored paths will not be checked at all. 'Override' - Only the file specified by GitIgnoreOverride will be used. This is useful when historical .gitignore revisions were committed and are causing items to drop out. 'Committed' - The committed version of the .gitignore version will be used when determining whether to add files. 'Both' - Both the override file and the committed version will be used when determining whether to add files. |
UseCommitMentionLinking (Git destinations only) |
This setting is used to prefix work item ids with # so that Azure DevOps commit mention linking associates the Git commit with the work item when pushed. Note: This should only be set to true for the final production migration for sessions where the source and destination are in the same Azure DevOps collection. It should not be used with test migrations and is not honored with a trial license to prevent linking the original tickets. Additionally Git LFS migration should be performed on the local repository before pushing it to Azure DevOps as Git LFS will rewrite history causing both pre and post LFS migration commits to be associated with the work item. |
The settings specific to CVS sources are as follows:
Setting Name | Meaning |
SaveParsedChangeLog | This setting is used to save out intermediate parsed forms of the migration data. Configure this setting to 'true' to save out the data to the CVS working directory. This setting can be used when troubleshooting issues in the analysis phase. |
SkipCVSInitialize | This setting is used to skip the initialization of the CVS working directory. Configure this setting to 'true' to skip initialization including a CVS checkout. This setting can be used save time when performing repeated migrations. |
CachedChangeLog | Set the value to the location of a CVS changelog that you want to use with the migration instead of querying a changelog from the server. This setting can be used when you want to customize what is migrated via the changelog. Note: If you use a cached changelog you will not get updates after the changelog was created. If you wish to use this setting it is a good idea to lock the CVS database so that no more changes can be made. |
SkipChangeLogErrors | This setting is used to skip over any errors that are returned from the CVS log command for individual files. Configure this setting to 'true' if there are problems with individual file entries being corrupted in the CVS repository but not enough corruption to require the use of the CachedChangeLog setting. |
RequestLog | This setting specifies the path to a log file that will be used to log all output from cvs.exe as it is received without any buffering. |
CaseDifferenceHandler | This setting is used to determine what action to take if there are files in the same directory where the file names differ only by case. 'Ignore' - A warning message will be logged and the migration will continue. Errors may occur during the migration phase if the actions between the different files conflict. 'DropDuplicateFiles' - Files with duplicate names except for case will be dropped from the migration. |
IgnoreDefaultVendorBranch | This setting is used to determine whether or not the default Vendor branch that is created when importing source into CVS is considered valid for operations like trying to determine which branch a tag should be applied to as the primary branch. |
LineEndingBinaryOverrides | This setting is used to have the tool retrieve files from CVS using the binary substitution mode for certain file extensions so that line ending conversion will not occur. This setting can be used if binary files were incorrectly added to CVS as text files and CVS.exe is converting some of their historical revisions. Specifying multiple file extensions would be configured like 'pdf;doc;xls;'. |
CVSLogEncoding | This specifies the text encoding format used when interpreting the CVS log file. Set to either UTF8, TFS16, ASCII or prefix a code page with CP as in CP437. |
CVSProcessEncoding | This specifies the text encoding format used when interpreting the output of CVS.exe. Set to either UTF8, TFS16, ASCII or prefix a code page with CP as in CP437. |
FileDownloadTimeout | This setting is used to specify the amount of time in seconds that the migration phase waits for files to be downloaded from the CVS server. This setting can be used to workaround issues in CVS databases that cause the CVS.exe client to hang when downloading files. |
LabelUserMapping | This setting is used to specify an account to attribute labels to when migrated to TFS. By default the identity of the user running the migration will be used. |
PruneEmptyDirectoriesAfterMigration | This setting is used to simulate the results of running cvs checkout with the -P option to prune empty directories. Pruning will be performed as a separate checkin after the migration phase completes successfully. |
The settings specific to SQL sources are as follows:
Setting Name | Meaning |
StartingRevision | This setting is used to indicate the ending revision that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
EndingRevision | This setting is used to indicate the starting revision that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
FileDownloadTimeout | This setting is used to specify the amount of time in seconds that the migration phase waits for files to be downloaded from the SQL server. |
SkipConsolidationWindow | This setting is used to delay looking at new history until sufficient time has passed so that new changes would not be consolidated differently between the current session run and future session runs. This is helpful when using the Windows Task Scheduler to schedule periodic runs as part of a mirroring job. |
The settings specific to StarTeam sources are as follows:
Setting Name | Meaning |
LabelDiscoveryMode | This setting is used to determine how StarTeamToTFS should look for labels. 'LabelViewBased' - Will use label based view configurations to examine the files in a label. 'FileBased' - Will scan for labels that are attached to an item as the item is processed. 'None' - Labels will not be processed. LabelViewBased is the most efficient option, but sometimes StarTeam will report labels on files that it will not map in a view. |
BlackListItems | This setting is used to indicate items that should not be processed at all. This can be used if the Borland StarTeam API repeatedly fails to access certain items to allow the problem items to be skipped and the rest of the migration to continue. The format of this setting is '<ItemId1>;<ItemId2>' where the item ids can be found in the log file directly after item names such as <Folder>\<Item>:<ItemId>. |
ScanAllViews | This setting is used to scan all views within the project when determining what to process. If this is set to false then only the views specified in folder mappings and the parent views will be examined. This must be set to true when wildcard branch mappings are used in order to find all the views to process. It is also used to output diagnostic information to the migration log file about view properties and the relationships between views to aid with troubleshooting issues. |
StarTeamSDKCommunicationLogFile | This setting is used to configure the StarTeam SDK to enable it's logging around commands that are being sent to the StarTeam Server. To turn on logging, configure this setting to name of the file that you want the StarTeam SDK to use. |
ForceItemRevisionDisabled | This setting is used to disable processing Item Revisions which store information such as if an item has been moved between folders. This setting can be used to fix files in place during a migration and prevent folder moves from being migrated. |
ForceItemRenameDisabled | This setting is used to disable processing item renames. This setting can be used together with ForceItemRenameDisabled to work around problematic StarTeam history that has duplicate items where each duplicate gets renamed to separate destinations. |
SearchOnlyMappedFolders | This setting is used to indicate that only the folders listed as non cloaked folder mappings should be searched for items to migrate. This will speed up the migration at the expense of losing history for items that were once in a mapped folder but were later moved out into an external folder that is not being mapped. |
StandaloneBranchMode | This setting is used to how branches will be migrated if they are not being migrated with their parent branch. 'AllRevisions' - Will attempt to migrate all revisions that are visible in the view. 'BranchedRevisionsOnly' - Will only attempt to migrate revisions that were either part of the initial branch point or were added afterwards. AllRevisions can be used when attempting to use a child view to selectively migrate folders in the root view. BranchedRevisionsOnly can be used to migrate a repository in stages by migrating child views as needed into TFS on top of branches created in TFS. |
DeletedItemDiscoveryMode | This setting is used to determine how StarTeamToTFS should look for deleted items if supported by StarTeam. Note only StarTeam releases 2006 and later support returning information about deleted items. 'RecycleBin' - Will use the StarTeam RecycleBin feature to ask the server for the deleted items. 'None' - Deleted items will not be migrated. This setting can be used if StarTeam has problems returning deleted item information. 'Scan' - Will scan for deleted items and will not use any cached information. 'PersistentScan' - Will scan for deleted items and will cache information about the files it has scanned between attempts. RecycleBin is the most efficient option. Scan is intended to be a troubleshooting option that scans through item ids to try to find deleted items. Because the operation is a scan it can be quite slow. PersistentScan behaves similar to Scan but will cache results between migration. If the same project is migrated twice, performance will be similar to that of RecycleBin. To improve initial performance, the DeletedItemExternalScanFile setting can be used to cache information manually extracted from the StarTeam database. |
DeletedItemExternalScanFile | This setting is used together with DeletedItemDiscoveryMode to cache deleted item information manually extracted from the StarTeam database. If DeletedItemDiscoveryMode is set to PersistentScan, the data in the file identified by DeletedItemExternalScanFile will be cached. This data should be in a comma separate file (.csv) with each line formatted like '<ViewID>, <ItemID>, <DeletedUserID>'. On newer versions of StarTeam this information can be extracted with SQL similar to the following: SELECT ViewID, ItemID, DeletedUserID FROM dw_File UNION SELECT ViewID, ItemID, DeletedUserID FROM dw_Folder ORDER BY ItemID |
AutomaticErrorPromptAction | This setting is used to automatically select an action when certain StarTeam server errors occur. |
LabelUserMapping | This setting is used to specify an account to attribute labels to when migrated to TFS. By default the identity of the user running the migration will be used. |
The settings specific to SVN sources are as follows:
Setting Name | Meaning |
StartingChangeset | This setting is used to indicate the starting Subversion revision that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
EndingChangeset | This setting is used to indicate the ending Subversion revision that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
OptimizeFolderScan | This setting is used to indicate whether or not to process all SVN revisions or to filter the revisions based on the history of the provided folder mappings. SVN stops returning history when a given instance of a folder path was created, so if a folder was deleted and recreated repeatedly, this may need to be set to false to include all instances of the folder. |
IgnoreKeywordSubstitution | This setting is used to indicate whether or not client side keyword substitutions should be maintained. If keyword substitutions are maintained, then keywords will be tracked and substituted across branching and renaming operations. When working with large remote repositories, querying for properties on a branch can be a time consuming operation taking 20 minutes or more to return. This setting can be used to disable keyword substitution to cut down on the amount of time needed to analyze a repository. |
ExternalsHandler (TFVC destinations only) |
This setting is used to determine what action to take when svn:externals properties are changed on a folder. 'Ignore' - Any svn:external changes that occur will be ignored. 'MapToFile' - Any svn:external changes will be mapped to a file named svnexternals.txt in the folder the properties are being applied to. 'MapToFileAndTranslateInfo' - Any svn:external changes will be mapped to a file named svnexternals.txt in the folder the properties are being applied to. Additionally any paths and revisions that appear to be part of the current session will have their SVN path and revision converted into TFS paths and revisions. |
FileDownloadTimeout | This setting is used to specify the amount of time in seconds that the migration phase waits for files to be downloaded from the SVN server. This setting can be used to workaround issues in SVN databases or remote repository connectivity that cause the SVN client to hang when downloading files. |
TagFolders | This setting is used to indicate which folders were used to tag releases or builds within Subversion and should be translated to labels within TFS. If multiple folders were used they should be separated with a ‘;’. Note that if the changes were checked in to these folders in SVN, TFS does not support checking changes in to labels and any changes checked in to SVN tags cannot be migrated. For cases where changes where checked in to SVN tags and you wish to keep them, create folder mappings for the tags to migrate them as branches. A typical repository layout with tags of "/tags/Build1" and “/tags/Build2" will have TagFolders set to "/tags" which will create TFS labels Build1, Build2. |
IncludeTagPathInLabelName | This setting is used to indicate whether the full path under a TagFolder should be used for the label name or just the first part of the path. For instance, if there are tag folders of /tags/DevBuild/1.0.1 and /tags/DevBuild /1.0.2, setting this value to true will change the label names to DevBuild_1.0.1 and DevBuild_1.0.2. If your build process tagged multiple folders individually with the same build label, such as /tags/1.0.1/Project1 and /tags/1.0.1/Project2, setting this value to false will cause both Project1 and Project2 to be labeled 1.0.1. |
PrefetchChangesetCacheSize | This setting is used to indicate how many revisions should be retreived at once when scanning the source repository. Large cache sizes can be used with remote servers to reduce the number of individual calls that are made. |
ConvertedChangesetCacheSize | This setting is used to indicate how many processed changesets will be stored in case a future changeset needs to reference it. Large cache sizes can be used to reduce the number of changesets that need to be reprocessed. |
The settings specific to TFS sources are as follows:
Setting Name | Meaning |
StartingChangeset | This setting is used to indicate the starting TFS changeset that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
EndingChangeset | This setting is used to indicate the ending TFS changeset that should be examined as part of the migration. This can be used with advanced migration to manually shape the content of what is migrated. |
ChangesetCacheSize | This setting is used to determine how many changesets which have been returned from the server should be cached to prevent further lookups from the server if the changeset is needed again. |
PageChangesetDetails | This setting is used to specify whether to retrieve all item level details when requesting a changeset or whether to page them. This can be enabled for changesets with hundreds of thousands of items to cut down on memory overhead. For most sessions leaving this disabled will improve performance by cutting down on server requests. |
ProcessLabelsOnFolderMappings | This setting is used to filter for labels on the folder mapping source folders to speed up analysis time. When used, labels that are only associated with sub items of the mapped folders and not the mapped folder will not be included. If a folder has been deleted and recreated, the labels on the previous instance of the folder may not be included. |
The "Folder Mappings" tab is used to customize what folders and branches will be part of the current session. Folder mappings can be similar across different source control systems, although differ based on whether the source control system has a special concept for a branch, or merges the concept of a branch into a folder path.
For systems that have a special concept for a branch, the "Folder Mappings" tab will look like the following:
For systems that do not have a special concept for a branch, the "Branch" column will be removed and the "Folder Mappings" tab will look like the following:
Both examples demonstrate how to migrate a trunk and its branches along with pruning a project named "DeadProject" and branch named "DeadBranch" out of the migration.
For source control systems that support a special concept of a branch, the branches that you want to be migrated can be specified by using a wildcard indicator, "*" or the individual branch name. When a branch is specified by a wildcard indicator, the "Destination" field is expanded and the "*" is replaced with the branch name. For source control systems that do not support a special concept of a branch, multiple branches can be specified at once if they are under the same folder, such as "/Branches" in the second example as well as individually by specifying the full path of the branch folder.
In order to omit a folder from migration, the "Cloaked" field should be set to true and the "Source" field should be set to the path you want to omit. If the branch concept is supported, a folder across all branches can be easily specified by using the wildcard indicator. If the branch concept is not supported, each branch that you want to remove the folder from needs to be specified individually. While no data will be migrated for a "Cloaked" folder, the "Destination" field should still be set to the location it would be moved to prevent internal TFS consistency constraints when setting up the migration TFS workspace.
Omitting a branch from migration is similar between both types of systems as the branch should be individually specified to be removed.
Descriptions for each of the fields are as follows:
Setting Name | Meaning |
Branch | Name of the branch that the entry corresponds to. "*" represents a wildcard indicator used to specify all branches. |
Source |
This setting is used to identify the folder in the origin source
control database that you want to migrate. This folder should be unique. Path
conventions in this setting should follow naming conventions for the origin
source control system.
|
Destination | This setting is used to identify the folder in TFS where you want the file in the src folder migrated to. This folder does not need to be unique if you want multiple folders to map to the same destination folder. Path conventions in this setting should follow TFS naming conventions. If a wildcard indicator is used as the Branch name, the Destination field should contain an "*" where the branch name should be included in the TFS path. |
Cloaked | This setting is used to indicate whether or not you want to migrate this folder or leave it out. This can be used to prune dead branches that you do not want migrated. It can also be used to ignore individual folders that may contain content that you no longer want in your source tree such as SDK installs, sample databases or documentation. |
To help map and prune branches with source control systems like SVN which do not have a good view of deleted items in the repository, a Scan Wizard is provided through the "Scan" button on the Folders Mapping tab which scans the source repository and creates individual folder mapping entries for each of the branches in the repository so that you can go back through and check which ones you want to cloak.
Note that the main purpose of the Scan Wizard is to manage branches and not for subfolders within branches. Trying to stitch together multiple subfolders with the Scan Wizard won't find the markers that the quick scan is looking for and won't set up proper mappings. If more detailed mappings are needed, the folder mappings should be added directly.
The SVN To TFS wizard is shown below:
For the SVN wizard, both the source and destination folders for the trunk and branches folder should be specified. For the StarTeam wizard, StarTeam has a built in concept of a branch, so only destination folders need to be specified.
Pressing "Scan" will access the source repository to determine what branches are available to be mapped. When the scan has completed, the "OK" button will become active. Pressing "OK" will then create the folder mappings from the information returned from the scan.