Rules

The list of rules is evaluated top down; the first rule in the list that matches is used to generate the new name and branch_id. If no other rules match the implicit default rule is to copy files as is.

Patterns and Replacement Expressions

    name_expr<branch_id_expr>

The "<branch_id_expr>" (including angle brackets) is optional and may be forbidden by some sources or destinations that embed the concept of a branch in the name_expr. (See VCP::Dest::p4 for an example, though this may be changed in the future).

For now, the symbols "#" and "@" are reserved for future used in all expressions and must be escaped using "\", and various shell-like wildcards are implemented in pattern expressions.

Escaping

The characters "#", "@", "[", "]", "{", "}", ">", "<" and "$" must be escaped using a "\", as must any wildcard characters meant to be taken literally.

In result expressions, the wildcard characters "*", "?", the wildcard trigraph "..." and parentheses must each be escaped with single "\" as well.

No other characters are to be escaped.

Case sensitivity

Result Expressions

To explore result expressions, let's look at converting set of example files between cvs and p4 repositories. The difficulty here is that cvs and p4 have differing branching implementations.

Let's assume our CVS repository has a module named "flibble" with a file named "foo/bar" in it. Here is a branch diagram, with the main development trunk shown down the left (1.1 through 1.6, etc) and a single branch, tagged in CVS with a branch tag of "beta_1", is shown forking off version 1.5:

     flibble/foo/bar:

         1.1
          |
         ...
          |
         1.5
          | \
          |  \ beta_1
          |   \
         1.6   \
          |    1.5.2.1
         ...    |
                |
               1.5.2.2
                |
               ...

    NOTE 1: You can use C<vcp> to extract graphical branch diagrams by
    installing AT&T's GraphViz package and the Perl CPAN module
    GraphViz.pm.  Then you can use a command like:

        $ vcp cvs:/var/cvsroot:flibble/foo/bar \
            branch_diagram:foo_bar.png

    to generate a .png file showing something like the above diagram.

On the other hand, p4 users typically branch files using directory names. Here's file "foo/bar" again, with the main trunk held in the main depot's //depot/main directory, again with a branch after the 5th version of the file, but this time, the branch is represented by taking a copy

    //depot/main/foo/bar

         #1
          |
         ...
          |
         #5
          |\
          | \ //depot/beta_1/foo/bar
          |  \
         #6   \
          |   #1
         ...   |
               |
              #2
               |
              ...
          
    NOTE 2: the p4 command allows users to branch in very crafty and
    creative ways; it does not enforce the semantic of 1 branch per
    directory, and this gives p4 users a lot of power and flexibility.
    It also means that you might need some pretty crafty and creative
    branch maps when converting from p4 to other repositories.

    NOTE 3: that branch looks like a copy, but is actually just a
    metadata entry in the perforce repository, so it's very low
    overhead in terms of server effort and disk space, usually
    even more so than CVS branches.

    NOTE 4: Using GraphViz (as described in NOTE 1 above), you can
    build a diagram like this using vcp:

        $ vcp p4:perforce.our.com:1666://depot/flibble/foo/bar \
            branch_diagram:foo_bar.png

A user may or may not choose to label a branch in p4 with something called a "branch specification" (see "p4 help branch" for details). For this discussion, we'll assume they didn't.

First, let's look at cvs -> p4 conversion. To do this, we need to match the branch tags in the CVS repository and use them to map branched files in to a p4 subdirectory. Here's .vcp file for this:

   ## cvs2p4.vcp

   Source:
   # get all files in the flibble module from cvs
       cvs:/var/cvsroot:flibble/...

   Destination:
   # Put the files in the flibble directory in the main depot of p4
       p4:perforce.our.com:1666://depot/flibble/...

   Map:
   #   Pattern       Result
   #   ============  =======
       (...)<>       main/$1   # main trunk => //depot/flibble/main/...
       (...)<(...)>  $2/$1     # branches   => //depot/flibble/$branch/...

The "Source:" and "Destination:" fields are just pieces of a normal "vcp" command line moved in to "cvs2p4.vcp". The "Map:" field is a list of rules composed of pattern, result expression pairs.

In this example, all of the map expressions are relative paths. The patterns are relative to the "Source:" cvs repositories' ""flibble"" module. The results are relative to the "Destination:" p4 repositories' ""//depot/flibble/"" directory.

The first rule maps all files that have no branch tag in to the p4 directory "//depot/flibble/main/". The "(...)<>" pattern has two parts: a "name" part and a "branch_id" part. The "name" part, "(...)", matches all path names and copies them to the $1 variable. The "branch_id" part, " <" >, matches empty / missing "branch_id"s ("vcp"'s name for the CVS branch tag associated with a file on a branch). The " main/$1 " result retrieves the "name" part stored in $1 and prefixes it with ""main/"" to build the final "name" value.

The second rule maps all files on branches to an appropriately named subdirectory in the p4 destination. The pattern is a lot like the first rule's, but has a "branch_id" part that matches all "branch_id"s and copies them in to $2. The rule merely uses this "branch_id" from $2 instead of the hardcoded ""main/"" string to place the branches in appropriate subdirectories.

Here's how our flibble/foo/bar file version fare when passed through this mapping:

    CVS flibble/...              p4 //depot/flibble/...
    ========================     ======================

    foo/bar#1.1                  main/foo/bar#1
    foo/bar#1.2                  main/foo/bar#2
    ...                          ...
    foo/bar#1.5.2.1              beta_1/foo/bar#1
    foo/bar#1.5.2.2              beta_1/foo/bar#2
    ...                          ...

It's up to you to be sure there are no branches tagged ""main"" in the CVS repository. Also, no branch specification will be created in the target p4 repository (this is a limitation that should be fixed).

Result Actions: <<delete>> and <<keep>>

    Map:
    #   Pattern            Result
    #   =================  ==========
        old_stuff/...      <<delete>>  # Delete all files in /old
        old_stuff/.../*.c  <<keep>>    # except these

<<delete>> and <<keep>> may not appear in results; they are standalone tokens.

The default rule

    ...  <<keep>>  ## Default rule: passes everything through as-is

that is evaluated after all the other rules. Thus, if no other rule matches a revision, it is passed through unchanged.

Command Line Parsing

Because vcp command line parsing is performed incrementally and the next filter or destination specifications can look exactly like a pattern or result, the special token "--" is used to terminate the list of patterns provided on the command line. This may also be the last word in the "Map:" section of a .vcp file, but that is superfluous. It is an error to use "--" before the last word in a .vcp file.