README #13

= Bazaar-Perforce User Guide =

    Author: Matt McClure <mlm@aya.yale.edu>
    Date: 2009/01/01

== 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 C/C++ API
        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, using a DOS shell:
    
        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

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

    To perform a one-time migration from Perforce to Bazaar, use the
    p4-fast-export and bzr fast-import tools.
    
    The following example assumes you have:
    
        * a Perforce server listening on perforce:1666
        
        * a Perforce user name: "mlm"

        * a Perforce depot directory to migrate in //depot/bzrp4

        * an empty directory C:\bzrp4\p4 to store a Bazaar shared repository
          that will contain the destination Bazaar branch C:\bzrp4\p4\trunk.remote

        * bzrp4 installed at C:\bzrp4\plugin\bzrp4
        
        * Bazaar installed at C:\bzr\stable\bzr
        
        * the fast-import plugin installed at
          C:\bzr\stable\bzrlib\plugins\fastimport
        
    Example, using a DOS shell:
    
        1. > set P4PORT=perforce:1666
        
        2. > set P4USER=mlm
        
        3. > set P4CLIENT=mlm
        
        4. > p4 login
        
        5. > set BZR_PLUGIN_PATH=C:\bzrp4\plugin
        
        6. > python C:\bzr\stable\bzr init-repo C:\bzrp4\p4
        
        7. > python C:\bzrp4\plugin\bzrp4\p4-fast-export.py //depot/bzrp4@all \
           | python C:\bzr\stable\bzr fast-import - 

=== 6.3. Cycle: Perforce, Bazaar, Patch, Submit, ...  ===

    Mirror the Perforce depot directory, using a one-time migration.  See
    "One-time migration from Perforce to Bazaar" above, for instructions to
    set up your environment.
    
        1. > python C:\bzrp4\plugin\bzrp4\p4-fast-export.py //depot/bzrp4@all \
           | bzr fast-import -
           
    Create a work branch.
    
        1. > python bzr branch C:\repo1\trunk.remote C:\repo2\work
        
        Note: As of 2008/12/27, bzr fast-import does not handle updating a
        branch in a shared repository that also contains native Bazaar
        commits.  Keep your working branch in a separate repository to work
        around this limitation.

    Commit new revisions to your work branch.
    
    Push your work branch to your Perforce client workspace.

        1. > bzr push C:\p4\bzrp4

    Check consistency in your Perforce client workspace to open files for
    add/edit/remove.

    Submit the change to the Perforce depot.

        1. > p4 submit

    Update an existing Bazaar branch that mirrors a Perforce depot
    directory.

        1. > python C:\bzrp4\plugin\bzrp4\p4-fast-export.py //depot/bzrp4@all \
           | bzr fast-import -

    Rebase the Bazaar branch in your Perforce client workspace.

        1. > cd C:\p4\bzrp4

        2. > bzr rebase C:\repo1\trunk.remote

    Rebase changes in a working Bazaar branch that was branched from a
    branch that mirrors a Perforce depot directory.

        1. > cd C:\repo2\work

        2. > bzr rebase C:\repo1\trunk.remote


== 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>