br09.html

<html>
<head>
<title>The Branching Papers -- Perforce FAQs</title>
<head>
<body bgcolor=#ffffff>
<font size=-2><b><a href="branching.html#br09">[INDEX]</a></b></font>
<p>
<b>
We've got three related codelines we'd like to set up in Perforce,
but our current SCM system is so hopeless we don't have any branch
or integration history to convert. How can we make these three
separate directory trees into related Perforce branches?
Also, which Perforce commands would we use to exercise this
acceptance test ... <i>[gory details elided]</i>.
</b>
<blockquote>
<p>
First, my assumptions. You have:
<pre>
	M=/home/Master           # The last known good source
	V1=/home/v1root          # Variant 1 tree
	V2=/home/v2root          # Variant 2 tree
</pre>
I assume $V1 and $V2 both at one time looked like $M, but have each
evolved separately, right? 
<p>
And presumably, you have a snapshot of $M somewhere, right? As well
as current instantiations of $V1 and $V2? And all of these are on a
Unix filesytem somewhere, in the /home partition?
<p>
The natural way to handle this in Perforce is to create a depot that
contains all three variants. E.g., let's call them:
<pre>
        //depot/Master
        //depot/v1root
        //depot/v2root
</pre>
I will describe how you'd set these up and use them in Perforce, but
I'm not going to match your acceptance test blow-for-blow, because I
didn't completely understand what you were doing. If you'll take a 
look at what I describe first, I'll be happy to answer any questions
you have that will aid in setting up your acceptance test.
<p>
So first, here's how you load those codelines into Perforce. (I'll explain
using the command line interface, not the GUI, because it's easier to
demonstrate in email.)
<p>
First, set up a client view that "maps to the world". (I'm assuming you're
going to load your codeline variants from Unix):
<pre>
        cd /home
        setenv P4CLIENT world-unix
        p4 client
<p>
        | Client: world-unix
        | Root:   /home
        | View:
        |       //depot/... //world-unix/...
</pre>
Now, load the Master codeline:
<pre>
        cd /home/Master
        find . -type f -print | p4 -x - add
        p4 submit
</pre>
Branch the Master codeline into the v1root and v2root codelines:
<pre>
        p4 integ -v //depot/Master/... //depot/v1root/...
        p4 integ -v //depot/Master/... //depot/v2root/...
        p4 submit
</pre>
The 'integ -v' only operates on the depot -- it doesn't affect any local
files. 
<p>
Now, submit the actual v1root files as the first set of deltas applied
to the //depot/v1root codeline:
<pre>
        cd /home/v1root
        p4 flush ...     #like "sync", but doesn't alter workspace files
<p>
        find . -type f -print | p4 -x - add  #the result of this step is
                                             #that any files in /home/v1root
                                             #not already in //depot/v1root
                                             #will be opened for add.
<p>
        p4 diff -se | p4 -x - edit           #and this opens for edit any files
                                             #which exist but whose contents
                                             #have been changed
<p>
        p4 diff -sd | p4 -x - delete         #and this opens for delete any
                                             #files which are in //depot/v1root
                                             #but not in /home/v1root.
        p4 submit
</pre>
Now, do the above for v2root as well.
<p>
You now have 3 codelines in the depot related by integration. Any user
can map to one (or more) of the codelines and submit changes to that 
codeline. E.g., say I wanted to work on NT in //depot/v2root. I'd set up
my workspace thus:
<pre>
        p4 set P4CLIENT=laura-ws
        p4 client
<p>
        | Client: laura-ws
        | Root: C:\ws
        | View:
        |       //depot/v2root/... //laura-ws/v2root/...
</pre>
Now, I can sync my workspace and work on files in the c:\ws\v2root path.
I open files with <b>p4 edit</b> make changes to them, and put my changes into
the depot with <b>p4 submit</b>. (Or I could use the GUI, of course.)
Changes I submit will go in //depot/v2root.
<p>
You can propagate changes from //depot/v2root into //depot/Master, as
long as you are using a client view that is mapped to the //depot/Master
codeline. So, the "laura-ws" client wouldn't work, but the "world-unix"
one would. Or, you could set up a client just for working on 
//depot/Master files:
<pre>
        p4 set P4CLIENT=robert-master
        p4 client
<p>
        | Client: robert-master
        | Root: F:\ws
        | View:
        |       //depot/Master/... //robert-master/Master/...
</pre>
To propagate changes from v2root into Master:
<pre>
        p4 sync  #makes sure you have head revs of target files
<p>
        p4 integ //depot/v2root/... //depot/Master/...
        p4 resolve
        p4 submit
</pre>
You can do the same thing to propagate from v1root into Master, also
using the 'robert-master' client workspace.  (You need simply to
be using a client mapped to the <i>target</i> files in an integration):
<pre>
        p4 sync
        p4 integ //depot/v1root/... //depot/Master/...
        p4 resolve
        p4 submit
</pre>
(The <b>p4 resolve</b> step is where you get to handle conflicts between
v1root changes and v2root changes.)
<p>
Later on down the line, you could branch your patch line. We'll
say it's going to be called //depot/patch1. 
<p>
You could use that 'world-unix' client again, because when you're mapped
to the world you're mapped to //depot/patch1.  Or maybe you'd want to
modify your 'robert-master' client spec so you could do the integrations
on NT. So you add a mapping for //depot/patch1 to your client view:
<pre>
        p4 client
<p>
        | Client: robert-master
        | Root: F:\ws
        | View:
        |       //depot/Master/... //robert-master/Master/...
        |       //depot/patch1/... //robert-master/patch1/...
<p>
</pre>
To create the //depot/patch1 codeline:
<pre>
        p4 integ //depot/Master/... //depot/patch1/...
        p4 submit
</pre>
You can pull changes from Master into patch1 as needed:
<pre>
        p4 sync //depot/patch1/...
        p4 integ //depot/Master/... //depot/patch1/...
        p4 resolve
        p4 submit
</pre>
Perforce keeps track of what's been integrated.  If you try to do the
above <b>p4 integ</b> a second time, Perforce will tell you all revisions
have already been integrated (unless someone has submitted something
into //depot/Master in the interim!).
<p>
If you look in the manual you'll see that there are all kinds of refinements
to how you specify which changes are being integrated. For example, to
propagate changes up to and including changelist 341 from Master into patch1:
<pre>
        p4 integ //depot/Master/...@341 //depot/patch1/...
        p4 resolve
        p4 submit
</pre>
Or to propagate changelist 435, and only changelist 435, from patch1 
back into Master:
<pre>
        p4 integ //depot/patch1/...@435,@435 //depot/Master/...
        p4 resolve
        p4 submit
</pre>
You can also use the codelines paths (also called "filepatterns" or
"filespecs" in our documentation) in reporting commands.
<p>
E.g., to list the files in the patch1 codeline:
<pre>
        p4 files //depot/patch1/... 
</pre>
To show which changelists were submitted directly into the v2root
codeline:
<pre>
        p4 changse //depot/v2root/... 
</pre>
To show changelists which were either submitted directly or
integrated into the v2root codeline:
<pre>
        p4 changes -i //depot/v2root/...
</pre>
To show who has files opened in the Master codeline:
<pre>
        p4 opened -a //depot/Master/...
</pre>
<p>
Note that your branching structure is:
<pre>
                        Master
                       /  |  \
                      /   |   \
                     /    |    \
                v1root  v2root  patch1
</pre>
I.e., v1root, v2root, and patch1 are all "children" of Master.  That
means it is a piece of cake to propagate changes between v1root and
Master, but you can't propagate a change directly between v1root and
patch1, say, without affecting Master.  (Actually, you can, but you'd
have to do an integration to reset the base, which effectively rearranges
the branching structure.)
<p>
So when you set up your depot codelines, keep in mind that Perforce
makes it easy to propagate changes between parent-child codeline pairs,
but propagating changes between further removed codelines pairs is more
complicated.
<p>
Also FYI: If you are doing your <b>p4 resolve</b> commands on Sun, you can
set P4MERGE to 'filemerge' and use Sun's nifty graphical merge tool 
instead of editing Perforce's merge file. And I'm sure there are some
equivalent NT tools. 
<p>
Hope this helps. I hope I haven't made too many typos -- I don't always
proofread as well as I type....
<p>
</blockquote>
<p>
<p>
<i>(August 1998)</i>
</p>
<font size=-2><b><a href="branching.html#br09">[INDEX]</a></b></font>
<p>
<hr>
<h6>This is file $Id: //guest/laura_wingerd/perforce/faq/br09.html#1 $ in the 
<a href="http://public.perforce.com/public/index.html">Perforce Public Depot</a></h6>
</body>
</html>
#	Change	User	Description	Committed
#1	83	Laura Wingerd	The Branching Papers.	26 years ago