1 Introduction
Plastic SCM provides a tool to import repositories from other version control systems. Plastic will attempt to import as much information as possible; however each version control system has its own features and limitations, therefore the final result is not an exact copy of the original repository due to adjustments made to the original repository in order to import into Plastic SCM.
For further information about Plastic SCM properties and representation, please take a look at the user’s manual.
1.1 General description
The Plastic SCM importer reads data from the source repository by executing commands of the original version control system, and writes that data in the Plastic destination repository, accomplishing the necessary data adjustments, taking into account Plastic SCM features.
The Plastic SCM importer has two interfaces:
· Graphical User Interface importer tool.
· Command-line Interface importer tool.
1.2 Document contents
This document contains all the information necessary to understand how the Plastic SCM importer works and how to use it.
We will begin explaining the requirements that are necessary to successfully achieve a complete import.
We will go on to explain in detail the specific features, requirements and known issues for every supported version control system, including how to proceed in the graphical user interface.
Finally, we will study carefully how the command-line importer works. This interface offers additional options for advanced users and can be used to automate the process using scripts. The command-line importer could be used on operating systems that do not support graphical interfaces.
1.3 General requirements for the importer
Before starting to import any data it is mandatory that the Plastic SCM client is correctly configured to use the appropriate Plastic SCM server that will be used during the importation and it is mandatory that the Plastic SCM server is running during data importing operation.
These key points can be verified before the import process starts by using the configureserver (which will launch the server configuration wizard) and plastic --configure (which will launch the client configuration wizard) commands. Check that the server, port and authentication modes are correct. View the server log (loader.log.txt in the Plastic SCM server location) to verify that the server has been able to connect to the database. See the administrator’s manual to get further information on database connections.
It is necessary that a destination repository has been created before importing can begin. Creating a new repository can be accomplished with the Plastic SCM graphical client or the command line using cm mkrep command.
An important thing to keep in mind is that each version control system (VCS) has its own requirements; some may require having installed the client of that VCS system on the machine that will be used to perform the import. Specifics will be detailed in the following sections.
2 The graphical importer
The graphical user interface importer consists of a wizard that will ask the user several questions required to run the importation process. This wizard can be executed by typing guimporter in a shell or command prompt. To execute the graphical importer in Windows click on Start > All programs > Codice Software Plastic SCM professional > Client components > Plastic SCM Import tool.
Figure 1: Welcome screen of the Plastic SCM importer wizard.
In the following sections we will explain in detail all the information that is necessary to introduce for each supported VCS, which are:
- Microsoft Visual SourceSafe.
- CVS.
- SVN.
- Perforce.
The wizard will vary depending on the version control system to import from but for all version control systems it is necessary to specify a workspace path to use which is used to store all the data to the destination repository, the name of that workspace and the Plastic SCM repository in which the data will be stored.
Notes: To load every Plastic SCM repository in the wizard it is necessary that the Plastic SCM server is running correctly. If there is no Plastic SCM repository listed in the wizard verify the configuration details as noted in Section 1.3 General requirements for the importer.
Figure 2: There are no repositories listed because the Plastic SCM server is not running or not properly configured. See section 1.3 for details on server setup and verification.
In the following sections the import process will be described in detail for each supported VCS, including: requirements to successfully complete the import process from the specific VCS, the wizard depicted in detail and some known issues related with that VCS and how to cope with them.
Notes: It is important to remark that the Plastic SCM client must be correctly configured in order to use the appropriate Plastic SCM server. Also, it is essential that the Plastic SCM server is running during the importation process. To get further information, see the administrator’s manual.
2.1 Microsoft Visual SourceSafe
2.1.1 Requirements
Before starting to import a project from Visual SourceSafe, the following must be true:
- The SourceSafe client must be on the execution path.
- The Plastic SCM workspace used for the import must be empty.
- Every object controlled by Visual SourceSafe must be pinned; otherwise they will not be imported.
· Verify that every shared file belongs to the same version.
· If the SRCSAFE.INI file is located in a shared folder, it is important to make sure that Windows has created a network connection pointing to that resource.
2.1.2 The importer wizard
After guimporter.exe has been launched, click on ‘Next’ and select the option ‘Visual SourceSafe’.
Figure 3: Visual SourceSafe import configuration.
The name of the Project can be typed, or the option ‘Import entire database’ can be checked. Click on ‘Next’ to continue:
Figure 4: Configuration parameters: srcsafe.ini location, user and password.
It is necessary to input the srcsafe.ini location in the Database Path field and supply an active Visual SourceSafe login. After that information has been entered we can test the connection to Visual SourceSafe by clicking on ‘Test connection’. If the connection is successful Click on ‘Next’ if the connection fails verify that the information supplied is correct and that the requirements from Section 2.1.1 are properly met.
Now the wizard will ask for the destination of the import; it is necessary to input the name and path used by the workspace and the repository to store the data.
Figure 5: Configuration parameters regarding the destination of the import.
Click on ‘Next’ to start the import process.
2.1.3 Known issues
Before starting an import process from Visual SourceSafe, it is recommended to take into account the following:
· The SourceSafe concept of share/branch does not directly correlate to Plastic SCM, so if there is an item that is shared this way then every revision will be imported.
· Every revision will be imported from Visual SourceSafe including information about its owner, date and associated comments. All the labels as well as revisions labeled will be imported.
· The importer is not able to import items that have been deleted. This might leave old labels incomplete since deleted items which are part of those labels are not imported.
2.2 CVS
2.2.1 Requirements
Before starting to import a project from CVS, the following must be true:
· CVS client must exist in the execution path.
· The workspace that will be used during the import process must be empty.
2.2.2 The importer wizard
After guimporter.exe has been launched, click on ‘Next’ and select the option ‘CVS’.
Figure 6: CVS import configuration.
Input the name of the Project and click ‘Next’:
Figure 7: Configuration parameters of CVS: connection string to connect to the CVS server.
Input the CVS connection string used to connect to the CVS server. Use ‘Test connection’ to verify that the connection string and the project name are both correct. Click ‘Next’, otherwise review the requirements in Section 2.2.1
Now the wizard will ask for the destination of the import; it will be necessary to input the name and path used by the workspace and the repository to store the data.
Figure 8: Configuration parameters regarding the destination of the import.
Click ‘Next’ to start the import process.
2.2.3 Known issues
Before starting an import process from CVS, it is recommended to take into account the following:
· CVS allows revisions that do not belong to a branch which is not possible in Plastic SCM. To keep these revisions the importer stores them in an assisting branch named LOST+FOUND, and introduces a comment regarding the CVS revision it corresponds to.
· As CVS doesn’t support directory versioning, it is necessary to supply a directory versioning mechanism when migrating to Plastic SCM. To emulate this functionality, Plastic SCM adds all the directory entries that the directory would load on every configuration at the beginning of the import process, and delegates on each Plastic SCM configuration the loading of an item if applicable.
Remember that an item will be loaded on a given configuration if that item has a revision on the branch or their parent branch(es) have a revision of that item, and if that item has a directory entry on its parent directory.
This behavior is error prone when trying to add an item which is not loaded on a
branch, but its parent directory contains the item entry. In this case, Plastic
SCM will return an ‘Item <itempath> already exists’ error message.
2.3 Subversion
2.3.1 Requirements
Before starting to import a project from Subversion, the following must be true:
· Subversion client must exist in the execution path.
· The workspace that will be used during the import process must be empty.
2.3.2 The importer wizard
After guimporter.exe has been launched, click on ‘Next’ and select the option ‘Subversion’.
Figure 9: Configuration parameters for Subversion import.
Click ‘Next’:
Figure 10: Configuration parameters of SVN import: URL, trunk location, branches and tags.
Input the base URL of the SVN server. Leaving branches or Labels fields empty will result in those items not being imported. Also, we can test the connection with the SVN server by clicking on ‘Test Connection’ and test if the specified location of ‘trunk’, ‘branches’ and ‘tags’ is correct by clicking on ‘Test Configuration’. It is possible to import SVN tags as branches by clicking on ‘Import labels as branches’. See the following section to understand why this option would be used. Click ‘Next’ once connection and configuration tests are successful; otherwise review the requirements in Section 2.3.1 Requirements.
The wizard will ask for the destination of the import; it is necessary to input the workspace name and path to specify the repository to import into.
Figure 11: Configuration parameters regarding the destination of the import.
Click ‘Next’ and the import process will start.
2.3.3 Known issues
Before starting an import process from Subversion, it is recommended to take into account the following:
· Given Subversion architecture and taking into account that it does not make a distinction between the main branch and the rest of the branches or labels the Subversion repository must be properly structured for a successful import
A properly structured SVN repository must have a directory containing the main branch (usually called “trunk”), another one for the rest of branches (usually called “branches”) and another for labels (called “tags”); so these directories must not have been renamed, no work must be done outside these directories and no copies within the same branch must have been performed.
If the standard directory structure has not been used, then the import process will try to retrieve as many revisions as possible, but depending on the structure used some revisions could be lost or an item could have its history divided into different items.
·
A SVN changeset could contain the creation
of a new directory coming from another path of SVN repository. Let’s suppose
that this newly created directory is placed inside the “tags” folder specified
in the Plastic SCM importer as a “Tags” placeholder, and the SVN changeset
tells that the directory revision comes from a changeset different than their
children items, and the revision of the directory from the changeset that it
comes is older than the changeset which contains the children items. Also, the
directory revision of the source changeset did not contain some of their
children items yet.
In this case, Plastic SCM will label the directory revision loaded from its
coming changeset, and the imported label will not load those children items that
the labeled directory revision did not contain in its coming changeset.
This is an example:
------------------------------------------------------------------------
r670 | (no author) | 200X-04-2Y 10:54:11 +0200 (……..) |
1 line
Changed paths:
A /tags/Release2_20/project/doc (from /trunk/project/doc:458)
A /tags/Release2_20/project/doc/help.html (from
/branches/br04/doc/help.html:516)
Tag 'Release2_20'
------------------------------------------------------------------------
…
------------------------------------------------------------------------
r498 | (no author) | 200X-08-1Y
15:21:43 +0200 (……..) | 1 line
Changed paths:
A /tags/Release2_20/project/doc/help.html
Added help
------------------------------------------------------------------------
Specified Tags folder = /tags
Plastic SCM will label as ‘Release2_20’ the ‘/tags/Release2_20/project/doc’
directory loaded in SVN changeset # 458, but that revision does not contain the
item /tags/Release2_20/project/doc/help.html, which was added on a newer changeset
(#498).
Plastic SCM will also label as ‘Release2_20’ the
‘/tags/Release2_20/project/doc/help.html’ file loaded in SVN changeset #516,
but it will not be loaded in Plastic SCM label ‘Release2_20’.
·
Plastic SCM will mark as labels those
directories that are placed on specified “Tags” directory path of SVN
repository. Those directories are typically created by a copy operation from
another path of SVN repository. The labelled revisions by Plastic SCM importer
are the revisions loaded in the specified source of the copy operation to the
“Tags” directory.
So, further modifications after copying a directory to the “Tags” directory in
SVN will be discarded by the Plastic SCM importer.
In order to minimize this kind of problems related with importing tags, Plastic allows importing tags as branches.
· If a copy of ‘trunk’ (itself and its contents) to a label is done, Plastic will label the contents of ‘trunk’, but not ‘trunk’ itself.
· It is highly recommended to use the svn://, http:// or file:// protocols to specify the base URL of SVN. Using the https:// protocol may cause that the import process slows down considerably.
· Importing from a GNU/Linux system it is necessary to install the appropriate subversion-devel package.
· If the SVN repository is big enough, it is recommended to increase the ‘TransactionTimeout’ parameter in the server.conf file and the ‘CommandTimeout’ parameter in the db.conf file in case of using SQLServer as Plastic SCM backend.
· Due to the limitations discussed before, related to tags and elements that are labelled more than once, Plastic SCM provides the ability to import the tags as branches; this option may solve many of the problems associated with labels.
2.4 Perforce
2.4.1 Requirements
Before starting to import a project from Perforce, the following conditions must be observed:
- The Perforce client must be on the execution path.
- The Plastic SCM workspace to use must be empty.
2.4.2 The importer wizard
After guimporter.exe has been launched, click on ‘Next’ and select the option ‘Perforce’.
Figure 12: Perforce import configuration.
Click on ‘Next’:
Figure 13: Configuration parameters: depot, client, user and Perforce server.
It is necessary to complete the whole information asked: depot path, a Perforce client, a Perforce user and the Perforce server.
The depot path will be managed as root item, so that Plastic will import that root item and all its contents in the main branch.
After that information has been indicated, we can test the connection to Perforce by clicking on ‘Test connection’. Click on ‘Next’.
Now the wizard will ask for the destination of the import; it is necessary to type the workspace to use and the repository to store the data.
Figure 14: Configuration parameters regarding the destination of the import.
Click on ‘Next’ and the import process will start.
2.4.3 Known issues
Before starting an import process from Perforce, it is recommended to take into account the following:
· The importer will handle the specified depot path as the Plastic SCM main branch. The specified depot path will be managed as the root item on Plastic SCM main branch, and those Perforce contents whose depot path are outside from the specified depot path will be discarded.
·
If there is a changelist in Perforce which
states that there is an item that is branched/integrated under the specified
depot path to import, Plastic SCM will create a new item, and, in consequence,
the history of the new item will be independent from the source item.
Example:
p4 integrate //depot/fileA.txt //depot/fileB.txt
p4 submit
In the above example, Plastic SCM will create a new
item for "fileB.txt", breaking the history from the source revision
("fileA.txt").
· Plastic SCM won't delete the empty directories coming from a Perforce import process.
3 The command line importer
In addition to the graphical user interface, the Plastic SCM importer provides a command line application that can be very useful in those environments in which there is no graphical environment. Also, it can be very useful to automate the import process with a script.
This application is placed in the execution path after the installation of Plastic SCM, and can be invoked by the command climporter.exe (climporter in GNU/Linux and Mac environments).
3.1 climporter.exe options in detail
The climporter program needs several options in order to run correctly; you can obtain that list of options typing the following in a shell or command prompt:
climporter --help
In order to execute the command-line importer, type the following:
climporter <scm> <project> --cla <options>
Where <scm> is the VCS used to import from (vss, cvs, svn). The name of the project is only necessary when importing from Visual SourceSafe and CVS.
The different options of the climporter, introduced always by –cla, are explained below:
Visual SourceSafe
--usr= Visual SourceSafe user to connect to that system.
-- pss= password.
--database= Visual SourceSafe database path.
CVS
--connstr= CVS connection string.
SVN
--url = base URL of the SVN repository.
--tags = relative path from the base URL, used as SVN tags location.
--branches = relative path from the base URL, used as SVN branches location.
--trunk = relative path from the base URL, used as SVN trunk location.
--startcs = initial changeset from which the importation will start. By default, 1.
--endcs = final changeset to import. By default, HEAD.
Using these parameters, --startcs and --endcs, it is possible to perform incremental imports or specify a range to import.
--cachedirectory = to specify a directory to store the temporary information obtained from the SVN repository for the import process. By default, this information is stored in the user's local directory.
--test = lastcheck|fullcheck, this parameter is used to verify the integrity of the repository recently imported once the import process has finished. lastcheck is used to verify every possible workspace configuration (branches and labels), while fullcheck is used to verify every changeset imported. The fullcheck argument is remarkably slower, but it performs a more complete verification. When the value is fullcheck, this option allows --startcs and --endcs in order to verify the integrity of a specific range of changesets.
Perforce
--p4client = Perforce client to use in the import process.
--p4user = Perforce user to use in the importation.
--p4port = Perforce server specification, in the format: machine_name:port
--depot = depot path that will be used as root item. Plastic SCM will import that root item and all its content in its main branch. Example: //depot
--startcs = initial changeset from which the importation will start. By default, 1.
--endcs = final changeset to import. By default, HEAD.
Using these parameters, --startcs and --endcs, it is possible to perform incremental imports or specify a range to import.
--cachedirectory = to specify a directory to store the temporary information obtained from the Perforce repository for the import process. By default, this information is stored in the user's local directory.
--test = lastcheck|fullcheck, to verify the integrity of the repository recently imported once the import process has finished. lastcheck is used to verify every possible workspace configuration (branches and labels), while fullcheck is used to verify every changeset imported. The fullcheck argument is remarkably slower, but it performs a more complete verification. Also, when the value is fullcheck, this option allows --startcs and --endcs in order to verify the integrity of a specific range of changesets.
Common Parameters
--wkspath = the entire path to the workspace used for the import.
--wksname = the name of the workspace that will be used.
--repository = Plastic SCM repository that will store the imported data.
3.2 Example
The following example shows how to import a SVN repository located on svn://myserver:9017 as base URL, '/trunk' as trunk path, '/myproject/branches' as branches path and '/myproject/tags' as tags path. The destination of the import will be myPlasticRepository accessed from the workspace mywk, located on C:\myPlasticWk. When the import process is finished, an integrity verification will be performed for every possible configuration of workspace (branches and labels):
climporter.exe
svn --cla --url=’svn://myserver:9017’--trunk=’/trunk’
--branches=’/myproject/branches’ --tags=’/myproject/tags’
--wkspath=’C:\myPlasticWk’ --wksname=’mywk’
--repository=’myPlasticRepository’ --test=’lastcheck’