= Bazaar-Perforce User Guide = Author: Matt McClure 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 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\master * 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 \ | python C:\bzr\stable\bzr fast-import - Create a work branch. 1. > python C:\bzr\stable\bzr branch repo1\master 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. Create a patch from your work branch. 1. > python C:\bzr\stable\bzr --no-aliases diff -r \ ancestor:../../repo1/master > ..\a_patch.patch Apply a patch to your Perforce client workspace and submit. 1. > cd C:\p4\bzrp4 2. > patch -p0 < a_patch.patch 3. > 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 \ | python C:\bzr\stable\bzr fast-import - Rebase changes in a working Bazaar branch that was branched from a branch that mirrors a Perforce depot directory. 1. > cd repo2\work 2. > python C:\bzr\stable\bzr rebase ..\..\repo1\master == 7. Other Documents == See also: NEWS, release notes TODO, planned future work == 8. Credits == Bazaar-Perforce is based on: git-p4 by Simon Hausmann bzr2p4 by Robey Pointer