Documentation

PVCS (and Serena ChangeMan) to TFS migration

Overview

This PVCS-2-TFS tool imports the PVCS archive as a flat file list with the complete history and all branched-versions and labels.

PVCS and TFS are two different systems. TFS is based on changesets and PVCS is based on labels and branches. But TFS also supports labels. This tool now imports PVCS databases into TFS and preserves the labels. It also imports all files (including all branched files) in a flat changeset hierarchy. And because these labels are imported you can access all files with the specified labels as in PVCS. Also you can additionally access all files by selecting a changest.

Support versions

  • PVCS Version Manager (PCLI)
  • Serena PVCS Version Manager (PCLI)
  • Serena ChangeMan Version Manager (PCLI)

Request a trial version

If you are interessted in this product, then please request a trial version.

Installation

You do not need to install anything (expect “PVCS version control” and “VS 2010/2012/2013/2015”). Just copy the “PVCS2TFS.EXE” into a separate directory, then you can directly start it.

VS2010 and newer TFS versions

If your PVCS version is too low, you need to use XP and therefor also VS2010 (because this is the last VS which is supported under XP). But you still can connect to a newer version of TFS.
On your XP client computer, you need VS2010 SP1 and the Compat GDR.
For more infos see: Compatibility between Team Foundation clients and Team Foundation Server.

Importing

User interface

The import tool has a simple user-interface:
Pvcs2Tfs_01

Prerequisties

  • You need to understand how PVCS works and how TFS works
  • You need to have a working PVCS environment on your local PC; you do not need to run this tool on a PVCS server, you just need the client PVCS version control installation on your computer.
  • Your PVCS projects must be in a consistent state and must not contain invalid characters like some characters between 0dec and 31dec
  • You need to have the right to read all metadata and all files in the PVCS project; normally you should be administrator in order to do the migration
  • Some older PVCS versions are only supported until XP, so you need to use a working XP installation of PVCS
    • Please be sure that your OS is supported by PVCS! PVCS 8.3.* is the first version which is supported under Windows 7! If you have a previsous version, you have to use Windows XP!
  • You need to have TFS-Explorer or VS 2010 (or 2012/2013) installed on your local PC; you do not need to run it on the TFS-server!
  • You need to be able to sucessfully log in into PVCS and TFS systems (if you use explicit login for PVCS then see below)
  • Before starting the import, you must ensure that you have no pending changes for this TFS server/workspace!
  • Before starting a import of a new PVCS archive you must ensure that the “Data” subdirectory for the Pvcs2Tfs tool is deleted or renamed (see below)!
  • Importing is only supported into an empty TFS folder.
  • It is recommended to you first do a test migration on a TFS test server (collection or special sub-directory) to ensure that the PVCS archive is valid. If the PVCS project contains invalid data, this might lead to an abort of the migration process.
  • It is recommended, that you give the importing user administration rights for the time of the import (some labeling operation might fail if not! You must have “LabelOther” permission, if some labels already exists!)

System requirements

  • Memory: 4 GB
  • Hard disk: 30 GB free space
  • PVCS version control
  • Visual Studio: VS2010 / VS2012 / VS2013
  • Team Foundation Server (TFS): All Version which are supported by your VS version

Settings files

You can save and load your settings. So there is no need to input the data several times.

Input fields

PVCS-settings: Tools

Here you need to specify the location of the PVCS tools direcory. You can use the drop-down list to select on of the following directories. if you start the tool, it will preselect either the version which was found, or the first entry.

  • For PVCS 7.5.x this is normally %ProgramFiles%\PVCS\vm\win32\bin
  • For PVCS 8.x this is normally %ProgramFiles%\Serena\vm\win32\bin

The path with “%ProgramFiles%” works for x86 and x64 systems…

PVCS-settings: Project

This is the path to your PVCS project. It must be the same as you would provide in the PVCS “Open database…” selection.
It might contain an UNC name or drive letter.
The project path can be found in the PVCS UI:
Pvcs2Tfs_ProjectDir

Examples

  • \\serenaSrv\db_test1
  • P:\pvcs\archive1

PVCS-settings: Root

If you have a large project (about > 50.000 files), it is always recommended to migrate the PVCS project in smaller parts. For this you use normally the “Select paths you want to import” (see below). This has the only disadvantage, that the list of all files must be fetched before the selection process can be shown. If your project is really large (about > 200.000 files) this first step can take several minutes or an hour.
In this situation, you can manually enter the PVCS directory your want to import. The directory must be in the form “/PVCS-Dir/PVCS-SubDir/(and so on)”. Then only this directory is fetched and imported.
For normal projects, you should leave this empty.

PVCS-settings: Only first 50 files

If you just want to test the migration without importing all files, you can check this checkbox.
Also the demo version limits the number of files to about 50.

PVCS-settings: Select paths you want to import

If you want to select specific folders of the PVCS porject and do not want to import the whole project,
you can check this box and after you have started the import and the PVCS files are retrived,
you can select which top-level folders you want to import.

PVCS-settings: Common changset detection tolerance in seconds

See Generation of changsets

PVCS-settings: Ignore empty revisions

Some PVCS archives have files which have no revisions. These files cannot be imported into the TFS, because there is no data available for import. Normally this is a error in the PVCS project and we report an error. If you want to ignore files with empty revisions, you can check this checkbox and then we will just report a warning for each file.

PVCS-settings: Ignore missing archives

Some PVCS files have no archives. In this case, the import would stop, because the file could not be retrived. If you check this option, these files get ignored and it will just display a warning, but the import will continue. A missing archive will be detected by the following error messages from PVCS:

  • The archive … could not be found at the specified location
  • could not read the information stored in the archive

PVCS-settings: Create top changeset for “latest revision”

Normally this should be activated. It ensures that the last PVCS revision is also inside the latest TFS changeset. So if you do a “get latest” you will automatically get the latest revision from all of your PVCS files.
If this is checked, then the label “__PvcsImportLatest__” (see below) will not generated, because the last changeset is exactly the latest PVCS revision.

PVCS-settings: Revisions Filter

If you want to import all revisions, you must not check any of these filter options!

Only include all labeld revisions

If you check this option, then at least all labeld revisions will be included in the import.

Min. Revision Date

If this option is check, then only the revisions with the minimum date will be included. But at least the latest revision will be included.

Max. Revision count

If this option is check, then only the maximum number of revisions will be included. But at least the latest revision will be included.

TFS: TFS-Server

This is the URL name of the TFS server. Normally this looks like:

  • http://TFSSERVER.net:8080/tfs/DefaultCollection
  • http://TFS2010Srv:8080/tfs/SomeName

TFS: Project

This is only the project name of the TFS project on which you want to import the PVCS database.
Normally it looks like:

  • Project1
  • Test

TFS: Workspace

This is the mapped location of a TFS directoy in which you want to import the PVCS project.
Normally it looks like:

  • C:\TFSServer\Project1\PvcsImport
  • D:\MyServer\Test\SomePath\Pvcs\Import

TFS: Label scope

Normally you should leave this empty. If you want to import several separate PVCS porjects which contains the same labels, then you need to use this field. For more infos see below.

TFS: 8.3 DOS file names

Short 8.3 filenames (like DOCUME~1.TXT) cannot be imported by default into TFS. Here you can select what should happen with 8.3 file names:

  • Ignore: File will not be imported
  • Allow: File will be imported. Please be aware that you first have to enable 8.3 file names in your TFS server!
  • Rename: 8.3 file names will be renamed. The “~” will be renamed to “_tilde_0” (or a bigger number if there is a file name collision).

If you want to allow 8.3 files, then please be sure you have configured your TFS server correctly!.

For more info see:

TFS: Filename starting with ‘$’

File names starting with a dollar sign ($) are not supported by TFS server.
Here you can select what should happen with 8.3 file names:

    • Ignore: File will not be imported

  • Rename: file names starting with a dollar ($) will be renamed. The “$” will be renamed to “_dollar_0” (or a bigger number if there is a file name collision).

For more info see:

Result of the import

The PVCS Comment, Username and CheckIn-DataTime will be shown in the comment of the changeset.

Pvcs2Tfs_02

Of course, the “(PVCSUserName)” and “(PVCSCheckInData: yyy-MM-dd HH:mm:ss)” will be replaced in the none-demo version with the correct fields from PVCS.

Resuming of the import

If for whatever reason there is a problem with the TFS server and an exception occurs,
you can resume the import by just doing the import again. It will look in the “Data” subsdirectory if the import has already started and continues on the next changeset.

Because of this resuming feature, you need to delete the Data subdirectory in order to import a different project!
In this Data directory all the information of a previous started import is saved. If you changes the PVCS project, you need to manually delete the directory!

Working with the imported files

To get the latest version of the files (PVCS: 1.*), you need to get the special auto.generated label “__PvcsImportLatest__”.
This is because the lasted changeset needs not to be a change in the main-branch, but this can also be a change in one of the PVCS branches. So therefor the label “__PvcsImportLatest__” is generated for all real latest files.

Background informations

Process

Here is a very short description on how the tools does the import:

The import is done in 4 steps:

  1. All PVCS meta-data will be retrived. This data is stored in the “Data” subdirectory of the current directory. You can also take a look at these files to see what is used as base-data for generating the changesets.
    If the data was already exported (the file ‘PvcsData.xml’ is already existing), then this step is jumped over.
  2. The changesets are generated via the metadata infos
  3. The changesets gets imported; one-by-one
  4. The labels will be set

For all of these 4 parts the progressbar will begin at 0 😉

Generation of the changesets

In PVCS there is no information like a “changeset”. In TFS you can checkin several files within a changeset. In order to mimic the TFS way, the changesets are generated by using “similar PVCS checkins”. Similar means, that the username and the comment must be the same. Also the checkin date must almost be the same (by default about +/- 6 seconds; this can be modified in the setting “Common changset detection tolerance in seconds”). If this condition fits for several files, then these files will be checked in using the same TFS changeset.

Known limitations

  • The PVCS history is imported in a flat, chronical ordered list for each file. All branches are also imported into this flat list. This means that the order of the generated changeset contain main-revisions and branches in the same level. If you do a “compare with previous” version it might happen, that it will compare a main-revision with a revisoon from a branch, because the previous version was a branched version!
  • The directory structure of the PVCS project is imported as displayed in the PVCS explorer. No folder or file-mapping is used.
  • TFS: TFS does not support 8.3 filenames. For more info see above.
  • TFS: TFS filenames must not contain a semicolon. This is allowed in PVCS. During the import a semicolon will be replaced with an underscore (_). This might lead to duplicate files if another file uses already the underscore. For more info see Adding Files into Version Control.
  • TFS: The label names of TFS labels are very restricted. Therefor all invalid characters (“/:<>\|*?@) are replaced with an underscore (_). Also the length of a label name is limited to 64 characters. This limitations might lead to duplicate label names. For more info see Label names.
  • TFS: In PVCS is was possible to check-in files, which were not changed. TFS will not generate a changeset for files, which was not changed! So there might be a different in the changeset between PVCS and TFS if you made check-ins und did not really changed the file!

PVCS login/authentication

If you have enabled security and you need to log in with a different user/password, then you need to provide this information in the environment variable “PCLI_ID”. You can either set this variable for the user (Control Panel|System|Environment) or open a command prompt, set the variable (SET PCLI_ID=”UserId:UserPassword”) and the start the Pvcs2Tfs program from this command prompt. For more informations about the “PCLI_ID” environment variable please see the “plci.pdf” documentation of your PVCS installation. On some PVCS installation you also need to enable the PCLI_ID environment variable by changing the file “Install_Dir\vm\common\pvcsprop\pvcs\vm\security.properties” and setting “vm.allowEventPassword=enabled”.

Special features

Importing of different PVCS archives with the same labels

Label scope in TFS

If you also have several PVCS databases with same labels you can do it as follows. Each database must be imported on its own. But in TFS you later want to access the labels the imported projects. Because of this, you need to specify a label scope. By default, if you create a label in TFS it has only the scope of the directory (and below) where you assign the label. So for example you can have a dir “Path1” and “Path2” in a parent directory called “root”. You can assign the label “L1” to “Path1” and “L1” to “Path2”. But if you want to get the label “L1” from the parent directory “root”, it will be not found! That is because there are two label scopes. And the root directory does not have the same label scope. Therefor if you want to use a label across several imported PVCS databases, you need to specify the label-scope on a (parent) directory on which all projects have access to.
During the import the label “L1” will then be created on the first PVCS database-import; and on the second PVCS-import the label “L1” will be merged together with the existing “L1” label.
Therefor you can now access all imported files across the proejcts by accessing the label “L1” in the parent folder.

For more info see:

Username mapping

Currently there is no username-mapping implemented. The current TFS user will be used for all check-ins.

Command line interface

The Pvcs2tfs tool has the following command line options:

/file=<string>             Settings file which contains all settings for starting the import.
                           This will be ignored if the import has already been started!
/autoStart[+|-]            If this is specified, the import will automatically start.
/undoPendingChanges[+|-]   If this is specified, then all pending changes will be undone before the import starts.
/autoTerminate[+|-]        If this is specified, the application will terminate after the import is finished or has stopped.

Support

If you have any problems, please sent us the logfile “PvcsImportLog.txt” which is located in the directory of the application to “support add pvcs2tfs dot com”. We then get in contact with you within the next couple of days.

History

  • 2012-10-10, v1.18: Added more logging for labeling
  • …several improvements on customer feedback…
  • 2013-02-25; v1.26: Display error information if PCLI could not be found and if there are pending changes while starting the import
  • 2013-02-27, v1.27: Bugfix for different major versions
  • 2013-03-15, v1.35: Fixed escaping of PVCS paths
  • 2013-03-20, v1.36: Added command line interface
  • 2013-03-25, v1.37: Replacing invalid TFS filename-characters (;) with “_”
  • 2013-04-11, v1.38: New demo version
  • 2013-05-24, v1.38: Documentation updated
  • …several improvements on customer feedback…
  • 2013-07-26, v1.44: Bugfix for $ character at top-level path / Added “Select paths you want to import” option
  • 2013-10-09, v1.48: Bugfix 8.3 file names / more logging / memory footprint improvements
  • 2013-12-10, v1.50: Demo version release
  • 2013-12-13, v1.51: VS2012 Release
  • 2013-12-13, v1.52: Added setting for “Common changeset tolerance in seconds”
  • 2014-01-09, v1.54: Demo version release / V2012 release
  • 2014-08-26, v1.60: VS2013 release
  • 2014-09-27, v1.64: Better logging during labeling (errors)
  • 2014-10-01, v1.66: New PVCS-setting: “Ignore empty revisions”
  • 2014-10-14, v1.67: 8.3 file names can now be renamed automatically
  • 2014-10-15, v1.68: Dropdown for PVCS tools directories
  • 2014-11-25, v1.71: Logging of environment variables for better support
  • 2014-12-30, v1.73: More logging for TFS collection and VCS information / Enumeration of workspaces on workspace errors
  • 2015-01-07, v1.74: Automatic retry now working for missing files / Switched some error messages or warnings into “Progress” Infos, so it will be displayed in the UI-ListBox
  • 2015-02-05, v1.75: Better logging in workspace error situations
  • 2015-04-10, v1.77: Explicit set WorkingDirectory when starting pcli (problem with ‘servers.ini’ on x64 systems with PVCS ChangeMan plci v8.1.4.1)
  • 2015-06-16, v1.80: Platform set to “Any CPU”
  • 2015-07-24, v1.82: Added filtering / VS2015 support
  • 2015-08-12, v1.83: Labeling imporvement (replace ‘;’ and TAB as invalid charachters in labels)
  • 2015-08-28, v1.84: If PVCS-Filelist was filtered, then also merge the labels, if the import is done in several steps / Output the filtered files in the logfile
  • 2015-09-08, v1.85: If the archive is not readable, this can now also be ignored with the “Ignore missing archives” option / better detection of “End of Revision” and “End of comment” / Ignoring “Unknown os = Windows NT (unknown)” in PVCS file list
  • 2015-10-25, v1.86: Smaller improvements
  • 2016-01-08, v1.87: Labeling improvements (replace all chars < 32dec with ‘_’)
  • 2016-01-20, v1.88: Labeling improvements (ignore empty labels)
  • 2016-02-07, v1.89: Special handling of files starting with Dollar sign ($); this is not supported by TFS; Option to ignore or rename it
  • 2016-02-09, v1.90: Invalid character-bug in deserializing data solved / new demo Version
  • 2016-03-21, v1.92: Invalid date/time in “Last modified” will now be ignored; “Last Checkin” will be used instead / Optional (default=true) create a changset with the latest Revision; so no need to use “__PvcsImportLatest__” anymore
  • 2016-04-24, v1.93: Small bugfix regarding VS2015
  • 2016-04-28, v1.94: Added some more logging for TFS connection problems
  • 2016-05-12, v1.95: Logging Problem for TFS properties solved
  • 2016-06-09, v1.98: Support for manual PVCS root directory for very large projects
  • 2016-06-10, v1.99: Bugfix for PVCS root path
  • 2016-07-08, v1.100: New demo version
  • 2016-09-03: v1.101: Prevent crash when logging TFS properties
  • 2016-11-07: v1.102: New demo version
  • 2017-04-30, v1.104: Try to detect the correct workspace / VS2015 version package update
  • 2018-03-01, v1.116: Additional arguments for VLOG command are now possible
  • 2018-03-05, v1.117: UI adjustments regarding args
  • 2020-12-06, v1.120: fixed workspace detection
  • 2020-12-29, v1.121: fixed comment bug in demo version