p4bbi.py - Import Baselines into a Perforce branching structure.
To make sure BBI is installed correctly, do like so:
Make sure 'p4' and 'p4d' executables are installed and in your PATH.
Create a /p4import directory writable by your user.
Extract p4bbi.tar.gz:
cd /p4import gunzip p4bbi.tar.gz tar -xvpf p4bbi.tar
Prepare a Perforce server and baselines for import.
cd /p4import ln -s p4bbi/test/baselines cd p4bbi/sample_cfg ./start_p4d.sh reset
This creates a Perforce server on port 8674.
Run an import.
cd /p4import/p4bbi ./p4bbi.py sample_cfg/p4config.test sample_cfg/FGS.bbi.cfg
Review output. Run 'p4 changes -p 8674' and 'p4 describe 12', and the output should look something like this:
$ p4 -p 8674 changes
Change 12 on 2012/07/27 by p4import@p4import_ws 'Captured current state of devel'
Change 11 on 2012/07/27 by p4import@p4import_ws 'Created FGS-2.0 development bra'
Change 10 on 2012/07/27 by p4import@p4import_ws 'Rename makefile'
Change 9 on 2012/07/27 by p4import@p4import_ws 'Imported baseline FGS-1.1.p3.'
Change 8 on 2012/07/27 by p4import@p4import_ws 'Merged FGS-1.1.p2 back to MAIN.'
Change 7 on 2012/07/27 by p4import@p4import_ws 'Result of merging FGS-1.1.p2 ba'
Change 6 on 2012/07/27 by p4import@p4import_ws 'Imported baseline FGS-1.1.p2.'
Change 5 on 2012/07/27 by p4import@p4import_ws 'Imported baseline FGS-1.1.p1.'
Change 4 on 2012/07/27 by p4import@p4import_ws 'Created branch FGS-1.1.x-R.'
Change 3 on 2012/07/27 by p4import@p4import_ws 'Import Baseline FGS-1.1.'
Change 2 on 2012/07/27 by p4import@p4import_ws 'Created branch FGS-1.0.x-R.'
Change 1 on 2012/07/27 by p4import@p4import_ws 'Import Baseline FGS-1.0.'
$ p4 -p 8674 describe 12
Change 12 by p4import@p4import_ws on 2012/07/27 13:35:50
Captured current state of development files on FGS-2.0 branch.
Affected files ...
... //ImportTest/Dev/FGS-2.0/fgs/src/CVS/cvs_file.txt#1 add
... //ImportTest/Dev/FGS-2.0/fgs/src/hello.c#2 edit
... //ImportTest/Dev/FGS-2.0/fgs/src/makefile_renamed#2 edit
==== //ImportTest/Dev/FGS-2.0/fgs/src/hello.c#2 (text) ====
6c6
< printf ("\nHello, New World!\n");
---
> printf ("\nHello, Brave New World!\n");
==== //ImportTest/Dev/FGS-2.0/fgs/src/makefile_renamed#2 (text) ====
10a11
> echo "Built $>"
p4bbi.py [options] p4_config_file bbi_config_file
OR
p4bbi.py {-h|--help}
This script creates a branching structure in Perforce, given a set of baselines and a defined branching structure.
This script must be run from a valid Perforce workspace on an existing server with the user and depot already configured.
Once the baselines are identified, the actual files from the baseline must be extracted from whatever version control system they are coming from, and put somewhere on a local disk. All baselines must be readily accessible by this script, so all operations necessary to extract baselines and get them to the locations defined in the config file must be done before this script is executed.
This config file has one section, a Header section.
This contains name=value pairs, one entry per line. Values for P4PORT, P4CLIENT, and P4USER are required.
Be sure to set P4PASSWD=password in the environement, or run 'p4 login' for the given P4PORT/P4USER prior to running this script.
The following values are set in the Header section:
Specify the P4PORT for the server where the branching structure is to be imported.
Specify the P4CLIENT value to use. Be sure the client spec has all directories in the intended target directory structure mapped. Also, be sure to set the line ending to share for the import.
Specify the P4USER. All checkins of baselines and branching operations will appear to be done by this user. Make sure this user has sufficient access (i.e. write access) to create the structure.
The config file has two sections, a Baseline Definition section, and a Branching Information section.
This section defines all baselines that are available for import, those baselines having been extracted from (or available from) other version control systems. This section contains baseline definition entries of the form:
BASELINE|BaselineName|Directory
or
BASELINE|BaselineName|TarFile
or
BASELINE|BaselineName|GzippedTarFile
or
BASELINE|BaselineName|ZipFile
or
BASELINE|BaselineName|CMD:Command
where:
is the name of the baseline, which typically matches a release label. This might be something like R4.0 or MyApp6.0.1.
is the path where files for the named baseline exist. This area is typically populated by extracting files from some other version control system. An example might be C:\P4Import\BaselineName on Windows or /home/p4adm/p4import/BaselineName on Unix.
Alternately, this can be a path to a *.tar file or zipped tar file (*.tar.gz), or a zip file (*.zip) conforming to the PKZip file format.
If the directory starts with CMD:, the rest of the string is assumed to be a command that, when executed, will put the desired files into the current directory. Make sure that the command will reliably generate the same set of files each time it is executed.
There are six types of entries in the Branching Info section, update, branch, copy_merge, record_as_merged, and rename.
The Branch Update entry is of the form:
UPDATE|BaselineName|P4Dir|Description|Options
where:
is the name of the baseline to be used for the given update, and
is the directory to be updated, in Perforce depot syntax, and
is the Perforce changelist description to be associated with the update. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
is an optional comma-delimited list of options for the operation. Valid options include:
Causes empty directories to be populated with placeholder text files and imported.
Causes symlinks to be preserved on import. Not applicable on Windows platforms.
Missing files in an updated baseline will not be deleted from the server.
Files with wildcards in their names will be imported.
Top level directory of baseline will be removed. Especially useful for tar files and zip files.
The Update entry will result in a Perforce changelist being created that will apply files from a given baseline to a specified directory in Perforce.
For example, say you have two baselines named REL1.0 and REL1.1, and you want them checked into //import/MAIN. You might have:
UPDATE|REL1.0|//import/MAIN|Added REL1.0 to MAIN.
UPDATE|REL1.1|//import/MAIN|Updated MAIN with REL1.1.$NContains only deltas.
The first update would create a changelist consisting of adds of all files in REL1.0 to //import/MAIN. The second update would contain only the deltas between REL1.0 and REL1.1.
The Branch SafeUpdate entry is of the form:
SAFEUPDATE|BaselineName|P4Dir|Description|Options
where:
is the name of the baseline to be used for the given update, and
is the directory to be updated, in Perforce depot syntax, and
is the Perforce changelist description to be associated with the update. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
is an optional comma-delimited list of options for the operation. Valid options include:
Causes empty directories to be populated with placeholder text files and imported.
Causes symlinks to be preserved on import. Not applicable on Windows platforms.
Missing files in an updated baseline will not be deleted from the server.
Files with wildcards in their names will be imported.
Top level directory of baseline will be removed. Especially useful for tar files and zip files.
The SafeUpdate entry will result in a Perforce changelist being created that will apply files from a given baseline to a specified directory in Perforce.
For example, say you have two baselines named REL1.0 and REL1.1, and you want them checked into //import/MAIN. You might have:
SAFEUPDATE|REL1.0|//import/MAIN|Added REL1.0 to MAIN.
SAFEUPDATE|REL1.1|//import/MAIN|Updated MAIN with REL1.1.$NContains only deltas.
The first update would create a changelist consisting of adds of all files in REL1.0 to //import/MAIN. The second update would contain only the deltas between REL1.0 and REL1.1.
It is important to note that the SAFEUPDATE command is parallel to but differs from the UPDATE in the treatment of files which have been deleted in the target location. The before a file is added it is checked against the identically named file in the depot and if the head revision is deleted the file is not included in the changelist and not added. SAFEUPDATE handles situations such as when code branched and developed is returned (copied back) to an ancestor branch where one or more of the files may have been deleted. By avoiding doing a blind copy of a deleted file and reporting the difference, a case-by-case review of files that are skipped can be done.
The Branch entry is of the form:
BRANCH|SourcePath|TargetPath|Description|Options
where:
is the source directory for the given branch, in Perforce depot syntax.
is the target directory for the given branch, in Perforce depot syntax.
is the Perforce changelist description to be associated with the update. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
is an optional comma-delimited list of options for the operation. Valid options include:
A branch spec with the name branchname will be created for use in future integrations. The view will be set to map SourcePath to TargetPath.
The Copy Merge entry is of the form:
COPY_MERGE|SourcePath|TargetPath|Description|Options
where:
is the source directory for the given branch, in Perforce depot syntax.
is the target directory for the given branch, in Perforce depot syntax.
is the Perforce changelist description to be associated with the update. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
is an optional comma-delimited list of options for the operation. Valid options include:
Normally, this operation just uses a resolve -at integration. In cases where the source and target codelines may diverge, the FULLCOPY option follows up with a diff-driven merge, which forces the codelines to converge.
The Record As Merged entry is of the form:
RECORD_AS_MERGED|SourcePath|TargetPath|Description
where:
is the source directory for the given branch, in Perforce depot syntax.
is the target directory for the given branch, in Perforce depot syntax.
is the Perforce changelist description to be associated with the update. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
Bear in mind that this operation runs a normal integration followed by a resolve with the accept yours option. It does not guarantee that the source and target paths will be identical afterwards, merely that the source path will have complete integration credit for merging to the target path. You may wish to follow this operation with an UPDATE to the target codeline with the actual state of the codeline after the merge was done.
The Rename entry is of the form:
RENAME|SourcePath|TargetPath|Description
where:
is the source file or directory to be renamed, in Perforce depot syntax.
is the new name for the file or directory, in Perforce depot syntax.
is the Perforce changelist description to be associated with the rename. Any occurences of "$N" in the description are replaced with a newline/tab, so multi-line descriptions are possible. You should only have about 65-70 chars before a $N.
Specify the verbosity level, from 1-3. 1 is quiet mode; only error output is displayed. 2 is normal verbosity; 3 is debug. The default for this program is 3.
Specify No Op mode, indicating that the script should display what it would do with given arguments and config file, but take no action that affects data.
Removes CVS/SVN/Mercurial/Git directories from the server after the import.
At level 1, detects and reports potential case sensitivity problems in imported data. At level 2, fails if these problems are detected. Files that have the same full path, ignoring case, are detected. This option is best effort; on case-insensitive platforms, some case sensitivity problems may already be obscured during baseline extraction.
Display the help.
Specify the absolute or relative path to the perforce connection config file.
The P4 configuration file is the settings file for connection to the Perforce server that is being updated with the BBI import. It contains name-value pairs (e.g. P4PORT=perforce:1666) to define the connection, workspace, and related details. In most cases, this file can be edited once and re-used.
Specify the absolute or relative path to the branching information config file.
The BBI configuration file contains the list of definitions and commands to perform to do the BBI import. Baselines define define the information sources (inputs) for the import and the other command types are the operations to be performed to apply the files to the target defined to complete importing of files. The commands are processed in the order they are read from the which does affect how content should be defined. Each command (line in the BBI configuration file) is a single change; lines are not combined into a compound update.
The target Perforce server must be available and, the server must have the import Depot and workspace with a mapping to that depot created. The workspace line ending should be set to share. The workspace name should be the same as the one specified in the P4CONFIG file. If the server requires the user to login, that should be done before running the script.
The p4 and p4d binaries should be available in the path.
The validation script is p4bbi_validate.py. This tool will attempt to verify the BBI's actions. It will report any suspected discrepancies between the imported data and the baselines.
Run this script with the same inputs as the regular BBI, except for the -m | --mode flag. This option now specifies the level of checking the validator will perform. Current options are:
1 - Verify file metadata
2 - Verify file checksums. Note that this may return bad results if the +k file type modifier is in use, as the file checksum will change due to RCS keyword expansion.
Note that the validator looks for changelist description in order to determine the revisions to verify. Changelist descriptions in the configuration file should be unique. (If there are no changes to submit for a command, the description is stored in a counter for later use.)
Setup steps:
Zero = success, non-zero = failure.
Perforce Baseline and Branch Import Tool
Copyright (c) 2012 Perforce Software, Inc.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THIS SOFTWARE IS NOT OFFICIALLY SUPPORTED.
Please send any feedback to consulting@perforce.com.