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

[Pete Wyckoff <pw@padd.com>]

vitor.hda@gmail.com wrote on Fri, 19 Aug 2011 15:30 +0100:
> On Fri, Aug 19, 2011 at 12:53 PM, Pete Wyckoff <pw@padd.com> wrote:
> > 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 <pw@padd.com>
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 <pw@padd.com>
---
 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