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