BBIConfigFileFormat.txt #1

# 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/<DepotSpec>.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[|<StreamOptions>]

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/<StreamSpecFile>.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/<BranchSpecFile>.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/<BranchSpecFile>.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.<NAME>.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.