Re: [PATCH v3 0/4] git-p4: Improve branch support

vitor.hda@gmail.com wrote on Fri, 19 Aug 2011 15:30 +0100:

On Fri, Aug 19, 2011 at 12:53 PM, Pete Wyckoff [off-list ref] wrote:

quoted

Patches 1 and 2 are great.  We should have gotten those in way
back when you first submitted them.  I happily ack those.

I'm still a bit hung up on #3, mainly because I don't get branch
support.  Let me play around with your test.  Having this
playbook of how it is supposed to work will help to educate me.

(I am probably going in too much detail here. Please skip any
redundant information.)

In general, you can see branches in P4 as you do in SVN. They are
simple copies from one directory to another. For example:

    p4 integrate //depot/big/directory/path/myproj/version_A \
                 //depot/big/directory/path/myproj/version_B

Now the history of "version_B" is tied to "version_A". If you want to
integrate (merge, in this case) new updates from one of the
directories to the other you can just rerun the above command
(version_A and version_B order may change depending on the direction
of the merge).

P4 also allows you to define "branch specs" that you can use as a
short hand instead of having to type in the full directory paths. So,
assuming that you have a branch named "myproj_B" with the following
view defined:

    //depot/big/directory/path/myproj/version_A \
        //depot/big/directory/path/myproj/version_B

When you want to integrate it again you can simply type:

    p4 integrate -b myproj_B

or, if you want to integrate from version_B into version_A instead:

    p4 integrate -b myproj_B -r

git-p4 is using these branch specs to identify branches. Without this
extra information it is nearly impossible for it to identify branches
because an integrate can be done of a single file.

But since P4 does not strictly require branch specs and because most
of the time integrations are done through P4V, then most of the time
no branch specs are created. Now, if this happens git-p4 will not be
able to detect branches! And creating branches in P4 just for git-p4
does not make much sense, right? This is the main reason behind the
third patch... :)

Thank you for these useful comments.  I have taken a first stab
at documenting the bevy of confusing branch flags and settings
in git-p4.  Please correct my errors and add other information
that is missing.

In particular, a clear case of how to set up the branches for
the branchList example would be good.  My minimal test did not
exactly work.


		-- Pete

--------------8<----------------------

From 36608a6e195041e8738bab24b84fadd0bf386865 Mon Sep 17 00:00:00 2001
From: Pete Wyckoff <redacted>
Date: Sat, 20 Aug 2011 15:04:09 -0400
Subject: [PATCH 4/4] git-p4: branch detection documentation start

Initial stab at documentation for --detect-branches and the
new branchList config setting.

Signed-off-by: Pete Wyckoff <redacted>
---
 contrib/fast-import/git-p4.txt |   48 +++++++++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 1 deletions(-)

diff --git a/contrib/fast-import/git-p4.txt b/contrib/fast-import/git-p4.txt
index 52003ae..6d21557 100644
--- a/contrib/fast-import/git-p4.txt
+++ b/contrib/fast-import/git-p4.txt

@@ -265,11 +265,57 @@ Only use branch specifications defined by the selected username.
 
 git-p4.branchList
 
-List of branches to be imported when branch detection is enabled.
+List of branches to be imported when branch detection is enabled.  This
+example shows that branchA and branchB are both created off branch main.
 
   git config [--global] git-p4.branchList main:branchA
   git config [--global] --add git-p4.branchList main:branchB
 
+Branch Detection
+================
+
+There are a few options that try to automatically create branches in git
+corresponding to branches in p4.
+
+Unfortunately, the concept of branch in p4 is quite different:  a p4
+branch is a mapping from one area of the repository to another.  It is
+used as input to "p4 integrate" to specify the source and destination of
+an integration.
+
+If you have a repository where all the branches are below a single
+directory, you can use "--detect-branches" when cloning or syncing to
+have git-p4 automatically look up the p4 branches and use these to
+generate branches in git.  Example:
+
+    P4 repository structure:
+
+	//depot/main/...
+	//depot/branch1/...
+    
+    View section from "p4 branch -o branch1"
+
+	//depot/main/... //depot/branch1/...
+    
+    Git clone command:
+
+	git-p4 clone --detect-branches //depot@all
+
+    Produces a separate branch in remotes/p4 for
+    //depot/main (called "master"), and one for //depot/branch1
+    (called "depot/branch1").
+
+However, it is not necessary to create branches in p4 to be able to
+use them like branches.  It is quite difficult to detect this
+automatically, but a git configuration setting "git-p4.branchList" can be
+used to explicitly identify branch relationships.  It is a list of
+"source":"destination" pairs, like a simple p4 branch specification,
+where the "source" and "destination" are the path elements in the
+p4 repository.  The example above relied on the presence of the p4
+branch.  Without that, you can get the same results by setting:
+
+  git config git-p4.branchList main:branch1
+
+
 Implementation Details...
 =========================
 

-- 
1.7.5.4