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