# This file documents the format of a Baseline and Branch # Import (BBI) config file, as supported by bbi.sh. # # For documentation on the format supported by the older # p4bbi.py, see p4bbi.html. # BBI config files have a VERSION identifier and to data sections, # a Baseline Definition section and an Import Actions section. # Config and other supporting files exist in a BBI config # directory. By convention, $P4BBI_HOME/sample_cfg is used # for development, testing, and demonstrations, while # $P4BBI_HOME/cfg (typically /p4/p4bbi/cfg) is used to develop # real import files. That directory is refered to as 'CFG' # below. #------------------------------------------------------------------------------ # Header #------------------------------------------------------------------------------ # The Header section defines VERSION and NAME, which are required. # Sample settings are: VERSION=3.5.2 NAME=FGS # Except for the VERSION definition, all tags in this file use the # pipe character ('|') as a field delimeter. #------------------------------------------------------------------------------ # Baseline Definition #------------------------------------------------------------------------------ # This defines baselines to be imported, and indicates their current location # on the filesystem. These baselines must be extracted from the old version # control system, grabbing the appropriate versions of files to match the # baseline name. # # Each baseline is expected to contain essentially similar and fully # populated structures, all taken from the same relative root directory. # Collectively the baselines represent the evolution of a software product over # time, with each baseline being a snapshot in time. # # The tar files must be constructed with a relative path, typically from the # root of a build workspace. # The BASELINE_STOREAGE tag looks like this: BASELINE_STORAGE=/dir/where/baseline/tarfiles/are # Or it may reference a shell environment variable, which must be # defined, as in this example: BASELINE_STORAGE=$P4BBI_BASELINES # Subsequent BASELINE definitions have this value prepended to # their path unless they specify an absolute path (starting # with # a '/'). # # A BASELINE_STORAGE definition affects all subsequent BASELINE tags. # Multiple BASELINE_STORAGE definitions can defined, with each one # affecting subseuqent baselines until the next BASELINE_STORAGE # definition. # The BASELINE tag looks like this: BASELINE|BaselineName|BaselineSource[|RMTOP] # BaselineName - The name used to refer to this baseline in the Import Actions # section below. # BaselineSource - This defines where to find the source of the baseline. # This can be a path to a simple directory on the disk, a tar file (*.tar, # *.tar.gz, or *.tgz), or a *.zip file. # Alternately, you can specify a command line to populate files into a # staging directory. For this usage, prefix the BaselineSource field # with 'CMD:' followed by an executable command line that will acquire # a directory tree of files in the current directory to import. This # can pull files from your legacy system or any external system. # For example, BaselineSource might look like FGS1.0 FGS1.0.tar FGS1.0.tar.gz /p4import/baselines/FGS1.0.tgz FGS1.0.zip CMD:cvs checkout -r FGS1.0 CMD:CMD:git clone https://github.com/perl6/perl6-examples . # For the Git example, the directory argument '.' at the end tells git # to populate files in the current directory, rather than the default # behavior of using a subdirectory (which is usually no desired # for BBI usage). RMTOP - This optional field, appropriate only for *.(tar|tar.gz|tgz) files, indicates that the desired contents are one director level below the as-extracted root of the tar file. A tar file typically looks something like this when expanded: src/hello.txt src/goodbye.txt doc/hello.html bin/say_hello If your tar file is constructed with an extra level, RMTOP removes it after expanding. Use RMTOP if your as-extracted looks like this, but you don't want the 'fgs' folder in the relative root. fgs/src/hello.txt fgs/src/goodbye.txt fgs/doc/hello.html fgs/bin/say_hello Warning: Do not use RMTOP if you have more than one top-level folder. # The GLOBAL_UPDATE_OPTIONS tag defines Options to the UPDATE action # the apply to all UPDATE actions. It is equivalent to applying to # each GLOBAL_UPDATE_OPTIONS=Options #------------------------------------------------------------------------------ # Import Actions #------------------------------------------------------------------------------ # The following actions are supported: Action Description Legacy Synonyms ------------- ------------------------------------------------ --------------- DEPOT Creates a Perforce depot spec Form: DEPOT|Name|Type[|Desc] DEPOT_SPEC Form: DEPOT_SPEC|DepotSpec Creates a Perforce depot spec from a hand- crafted depot spec file stored in the 'specs' directory under the BBI config dir, named CFG/specs/.depot.p4s. MOVE Form: MOVE|Path1|Path2|Desc RENAME A MOVE (RENAME) action can be placed between two UPDATE actions to ensure files or folders that have been refactored are properly recorded as renames (with move/add and move/delete records). The Path1 and Path2 fields can be files or foler, the latter indicated with a trailing /... STREAM Creates a Perforce stream spec Form: STREAM|StreamPath|StreamType|StreamParent|StreamDesc[|] STREAM_SPEC Form: STREAM_SPEC|StreamsSpecFile Creates a Perforce stream spec from a hand- crafted stream spec stored in the 'specs' directory. Stream specs are stored in a directory structure derived from the stream name. The can be more than one directory level under the CFG directory if a depot with StreamDepth greater than the default is used. Stream spec files are named CFG/.stream.p4s. For example, the stream spec for //fgs/main would be specs CFG/specs/fgs/main.stream.p4s. The stream spec for //F1/Components/main is CFG/specs/F1/Components/main.stream.p4s. Stream specs can evolve over the course of history, e.g. to reflect stream reparenting of old release streams as as newer releases occur. This evolution can be simulated by specifying multipe STREAME_SPEC entries referencing different stream spec files that represent different versions of the same stream spec. For that usage, simply add a version identifier to the stream spec file. So, for //fgs/main, you might have: CFG/specs/fgs/main.V1.stream.p4s. CFG/specs/fgs/main.V2.stream.p4s. These would be loaded at the apprpriate point in the action sequence with: STREAM_SPEC|fgs/main.V1 and later in the file: STREAM_SPEC|fgs/main.V2 BRANCH_SPEC Form: BRANCH_SPEC|BranchSpecFile Creates a Perforce branch spec from a hand- crafted branch spec file stored in the 'specs' directory under the BBI config dir, named CFG/specs/.branch.p4s. As with stream specs, branch specs can also evovle over history, and that evolution can be simulated similarly, as described in the STREAM_SPEC section above. CLIENT_SPEC Form: CLIENT_SPEC|ClientSpecFile Creates a Perforce client spec (workspace) from a hand-crafted client spec file stored in the 'specs' directory under the BBI config dir, named CFG/specs/.client.p4s. Creating branch specs during the import process is useful for automated import verification and demonstration purposes. See also: VERIFY To create a stream workspace, the corresponding stream must be created first, e.g. using a STREAM_SPEC action. UPDATE Updates a path with a baseline. Form: UPDATE|Baseline|Path1|Desc[|ActionUpdateOptions] Applies a baseline to a target path. A 'p4 reconcile' determines the differences from any previous baselines added to the path. The first baseline applied to a path results in a bunch of files being added to Perforce. The ActionUpdateOptions field is optional. If the options field exist, it contains a space-delimited set of tokens that enable additional processing for the UPDATE action. The valid tokens are: ASTYLE DOS2UNIX LABEL:MyLabelName VERIFY If the ASTYLE token exists, it means to run the 'astyle' code cleanup utility after the baseline is positioned in the workspace, but before the reconcile to update Perforce is done. This can be done if the migration is deemed an opportunity to use the astyle utility to normalize C/C++ and Java code styles. The ASTYLE token requires that a file exists in the BBI configuration directory named astyle..dirs, where NAME defined above. The file contains a simple the list of directories relative to the root of the baseline in which to run the astyle utility. This option adds processing time. If the DOS2UNIX token exists, it means to run the dos2unix utility on every file with a base-type of text. This can be helpful when imports are run on Linux with files that may have Windows line endings. This option adds processing time. If the 'LABEL:' token exists, an automatic label is created with the 'Revision:' field set to the changelist generated by the update action. If the VERIFY token exists, a verification is performed comparing the contents of the staging area used to upload the baseline against those sync'd from a temporary workspace. The verification is done after the submit. A failure to verify cleanly results in failure of the UPDATE action during import. Actual verification is done with: diff -qr --no-dereference /staging/area /verification_workspace This detects any differences, including those where contents seem to match, but differ in types (e.g. a file vs. a symlink to a file). The VERIFY option significantly increases processing time for each verified baseline. The VERIFY option is ignored for baselines that have DOS2UNIX or ASTYLE defined, as these options are incompatible with VERIFY. POPULATE Populates a new/empty target path from a source BRANCH Form: POPULATE|Path1|Path2|Desc (p4 populate -f Path1 Path2) or Form: POPULATE|BRANCH_SPEC[-r]|BranchSpec|Desc This is used only to create new branches or streams. Perforce records the integration history relationship between the source and target paths. The first form specfies source and targets paths with literal values. The second form uses a branch spec by using a special Path1 value of BRANCH_SPEC or BRANCH_SPEC-r, which uses a branch spec in the typical left-right direction (with BRANCH_SPEC) or the reverse, right-left direction (with BRANCH_SPEC-r). COPY Does a "Copy Up" from one path to another. COPY_MERGE Form: COPY|Path1|Path2|Desc or Form: COPY|BRANCH_SPEC[-r]|BranchSpec|Desc Does a "Copy Up" from one path to another using the 'p4 copy' command. Perforce records integration history tracking of the copy. The target matches the source verbatim following a 'p4 copy'. The second form invovling BRANCH_SPEC works the same way as with the POPULATE action. RECORD_MERGE Records a merge. Form: RECORD_MERGE|Path1|Path2|Desc or Form: RECORD_MERGE|BRANCH_SPEC[-r]|BranchSpec|Desc Records that a merge from source to target was RECORD_AS_MERGED done in the legacy system, adjusting Perforce integration history appropriately. This should be preceeded by an UPDATE action that provides the content of files following the merge process in the legacy system. The RECORD_MERGE action updates integration history and will create new file revisions, but those revisions of files, but they will have the same content as earlier revisions. The second form invovling BRANCH_SPEC works the same way as with the POPULATE action. #------------------------------------------------------------------------------ # Import Action Fields #------------------------------------------------------------------------------ Each import action takes fields as arguments. See these sample BBI config files for illustrations of arguments: sample_cfg/FGS.Classic.bbi.cfg sample_cfg/FGS.Streams.bbi.cfg Description fields may use a '$N' that will be replaced with a newline when added to Perforce. [NOTE: While in the spec, this feaure is NOT presently implemented. This should be available in a future release.] The Description field for various actions does not support using certain characters such as '(' and ')'. These may be supported in the future, but presently are NOT supported.