A session consists of the configuration which defines what will be migrated as well as the state of what is targeted for migration. The configuration portion defines what code will be migrated and where in the target system it will be migrated to. A session also contains settings which define what labels/tags will be migrated.
Session state is stored in a SQL staging database and contains the list of items the configuration indicated should be migrated as well as whether or not those items have been migrated yet. This allows a migration to be interrupted and then pick up where it left off. This also allows a migration to be performed in phases and allow development to continue in the origin source database while the target source database becomes ready for production.
Mappings define the location of the code in the origin source database that you want to migrate and the destination where you want the code to be located in the target source database. For a simple migration, there may only be one mapping which defines the source and destination for a single branch, or the root of the origin source database if you want to migrate an entire database.
Mappings can also be made more complex if you want to use the migration process to help you reorganize the source tree. For example your source tree may have started out with release branches in the same location as the main development branch, and over time the source tree may have gotten cluttered with many release branches. You can use the migration effort as a chance to clean up the tree and use the mapping functionality to help you move where each individual branch get migrated to. Obsolete source can also be removed from a migration by creating a mapping that cloaks an individual folder.
Depending on the origin source control system used, reorganizing the source tree may be a necessity. TFVC has limitations on the number of characters allowed in a path, 248 characters for a directory and 260 characters for a file, so if the path depth from the origin system combined with where you want it to live in TFVC causes the limits to be exceeded, mappings can be used to rename or relocate folders to be able to meet those limits. More information on TFVC path limitations can be found on MSDN here.
Sometimes attempts to clean up the source tree in the origin source database by moving or renaming folders result in artifacts being left behind in the old directory names. Mappings can be used to help correct these issues by configuring all operations in the old directory to be migrated to the renamed directory.
Certain source control systems like CVS store items for different branches in the same location in the source tree, i.e. “/Foo/Bar/Baz.c”, and use another identifier such as a branch tag to help specify what branch the file is supposed to correspond to. For source control systems like CVS, the mappings will be used to help define what branches will be migrated and what their destination locations will be.
When converting from one source control system to another there are two phases to a session, analysis and migration. During the analysis phase the session configuration is applied to the origin source database and items to be migrated are identified and recorded in a SQL staging database along with their source and destination locations. After the analysis phase completes, the migration phase starts and reads the records in the SQL staging database to determine what it needs to move to the target source control system.
If a session is restarted, it starts by running the analysis phase to see if any new data has been added to the origin source control system and then proceeds to the migration phase once the analysis phase is over.