= Bazaar-Perforce User Guide =

    Author: Matt McClure <mlm@aya.yale.edu>
    Date: 2008/11/14

== Contents ==

    1. Introduction
    2. Status
    3. Installation
    4. p4-fast-export
    5. bzr2p4
    6. Workflow
    7. Other Documents
    8. Credits

== 1. Introduction ==

    Bazaar-Perforce facilitates source control workflows that use both
    Perforce and Bazaar.

== 2. Status ==

    The first release of Bazaar-Perforce will perform one-way migrations
    from Perforce depots to Bazaar branches.

    As of 2008/11/14, Bazaar-Perforce is pre-release software.  In the
    spirit of releasing early and often to inspire feedback, I invite you
    to try it.  Beware that Bazaar-Perforce may force you to become a
    tester and a developer before it will let you be a user.  Please let me
    know how spectacularly it fails, so that future users may have more
    success in their attempts.

    The p4-fast-export tool is ready for you to be a tester.

    The bzr2p4 tool is ready for you to be a developer.

    The command-line interfaces and APIs are subject to change.

== 3. Installation ==

=== 3.1. Prerequisites ==

    To use Bazaar-Perforce, you will need:

        Bazaar
        Perforce command-line client (p4)
        Perforce Python library (P4Python)

    To run the self-test, you will additionally need:

        Git
        Perforce server (p4d)

=== 3.2. Setup ===

    Copy the bzrp4 directory to your Bazaar plugins directory.

    Set the BZR_PLUGIN_PATH environment variable to the location of your
    Bazaar plugins.

    Set the P4PORT environment variable to the host and port of your
    Perforce server.

=== 3.3. Self-test ===

    Synopsis

        bzr selftest bzrp4

    Description

        The self-test runs Bazaar-Perforce's unit tests and functional
        tests.

    Prerequisites

        setup_env.bat (Windows)
        . setup_env.sh (Cygwin)

=== 3.4. Complementary Tools ===

    The bzr-fastimport Bazaar plugin can consume the output of
    p4-fast-export to produce a Bazaar branch.

== 4. p4-fast-export ==

    Synopsis

        p4-fast-export.py perforce_depot_path

    Description

        The p4-fast-export tool produces a fast-export representation of a
        Perforce depot.

        The perforce_depot_path can be:

            //an/example/path

                Exports the current head.

            //an/example/path@all

                Exports all changelists.

            //an/example/path@6,9

                Exports changelists 6-9.

        P4-fast-export is based on git-p4.  It may support additional
        undocumented behavior.

== 5. bzr2p4 ==

    Synopsis

        bzr2p4.py [options] bzr_branch_path p4_client_workspace_path

    Description

        The bzr2p4 tool submits Bazaar revisions to a Perforce depot.

        Bzr2p4 may support additional undocumented behavior.

    Options
        
        -q Display no information as bzr2p4 works.

        -v Display verbose information as bzr2p4 works.

== 6. Workflow ==

== 6.1. One-time migration from Bazaar to Perforce ==

    To perform a one-time migration from Bazaar to Perforce, use the bzr2p4
    tool.
    
    The following example assumes you have:
    
        * a Bazaar branch to migrate in C:\bzrp4\bzrp4.dev
        
        * a Perforce client workspace named "mlm" in C:\p4
        
        * an empty directory within the Perforce client workspace at
          C:\p4\bzrp4
        
        * a Perforce server listening on perforce:1666
        
        * a Perforce user name: "mlm"
        
        * the bzr2p4.py tool installed at C:\bzrp4\stable\bzr2p4.py
        
    Example:
    
        1. > set P4PORT=perforce:1666

        2. > set P4USER=mlm

        3. > set P4CLIENT=mlm
        
        4. > p4 login
        
        5. > python C:\bzrp4\stable\bzr2p4.py C:\bzrp4\bzrp4.dev C:\p4\bzrp4

== 7. Other Documents ==

    See also:

        NEWS, release notes
        TODO, planned future work

== 8. Credits ==

    Bazaar-Perforce is based on:

        git-p4 by Simon Hausmann <simon@lst.de>

        bzr2p4 by Robey Pointer <robey@lag.net>