//open/dev/..., which we'll use in the examples below.
Next, you need to decide where your branched files will live in the
Perforce depot. Standard policy is to create your branch under
//open/users/.... Never create your branch under a
shared tree, otherwise everyone who maps that shared tree will
accidentally map your private branch as well. So, if your Perforce
user name is pmarlowe, you might use
//open/users/pmarlowe/dev/... to branch from
Your new branch also needs a name. A good name in this case would be
dev_to_pmarlowe, which specifies the branch origin
dev), branched location (
branching direction (later on it will become apparent why this naming
convention is important).
To actually create the branch, issue a command like:
p4 branch dev_to_pmarlowe
Descriptionfield to give more details on the purpose of your branch, and define the branch view mapping:
Defining the branch view is pretty much like defining a client view, except that the right hand side references the depot rather than the client. It's a good idea to include everything you think you're going to need, because changing the branch definition later can lead to trouble. For example, don't try to economize on disk space by leaving out thirdparty and trying to share the local copy from another branch; getting this right and keeping it working as things change is more trouble than it's worth.
View: //open/dev/thirdparty/... //open/users/pmarlowe/dev/thirdparty/... //open/dev/saffron/... //open/users/pmarlowe/dev/saffron/... //open/dev/fennel/... //open/users/pmarlowe/dev/fennel/... //open/dev/farrago/... //open/users/pmarlowe/dev/farrago/...
This would place your local
View: //open/dev/thirdparty/... //pmarlowe.pi/dev/thirdparty/... //open/dev/saffron/... //pmarlowe.pi/dev/saffron/... //open/dev/fennel/... //pmarlowe.pi/dev/fennel/... //open/dev/farrago/... //pmarlowe.pi/dev/farrago/... //open/users/pmarlowe/dev/thirdparty/... //pmarlowe.pi/pmarlowe/thirdparty //open/users/pmarlowe/dev/saffron/... //pmarlowe.pi/pmarlowe/saffron //open/users/pmarlowe/dev/fennel/... //pmarlowe.pi/pmarlowe/fennel //open/users/pmarlowe/dev/farrago/... //pmarlowe.pi/pmarlowe/farrago
pmarlowedirectory as a sibling to your local
devdirectory. This structure is up to you to decide; something deeper becomes necessary when you have multiple private branches corresponding to multiple shared trees.
Now, before performing the initial integration (populating the private branch in the depot), sync all files which are to be branched so that you are branching from the latest version. In this example:
will do the trick. Also, make sure you have no files open before starting the integration. This is very important, and is true for the other integrations described later on. Run
p4 sync //open/dev/...
p4 openedand make sure that the response is "File(s) not opened on this client." Mixing real changes with integrations will lead to much gnashing of teeth and tearing of hair.
Now, tell Perforce to do the integration:
p4 integrate -t -b dev_to_pmarlowe
-tis redundant here but becomes important later, so get in the habit of including it whenever you invoke
p4 integrate; otherwise you'll have nasty problems when file types change.
p4 integrate command doesn't really do all of the
work; it just tells Perforce what you're planning to do. To complete
the branching in your client workspace:
At this point, you should be able to build, run, and test under the local
p4 resolve -am
pmarlowedirectory just created by
p4 resolve. Once that looks good, check in (this won't affect anyone else):
The checkin comment should indicate
p4 syncto start from the latest code. With a private branch in place, there are a few extra steps:
p4 syncas usual. Make sure you sync both the shared tree and your private branch location, otherwise you'll experience unpleasant anomalies later. And make sure you have no files open.
p4 integrate -t -b dev_to_pmarlowe
p4 help resolveto try to figure out what you need to do.
p4 resolve -am. If you have made changes in your private branch, they may conflict with changes coming in from the shared tree. In that case, use the normal conflict resolution process.
p4 revertto undo the integration. If you trust the shared tree, you can skip this step.
p4 submitto update your private branch with the integration before starting on your own changes or integrating subsequent changes from the shared tree (it's not a good idea to mix). This submit does not affect anyone else, so you should always do it sooner rather than later. A good convention for the checkin comment is
XXXis the change number you synced and integrated from.
p4 sync. And make sure you have no files open.
p4 integrate -t -r -b dev_to_pmarlowe. The
-rtells Perforce to go in the reverse direction. Since the branch name was chosen to describe the forward direction, reverse integration will be from
dev, which is what we want.
p4 resolve -amand resolve any conflicts. If you followed the advice above about doing another forward integration, there shouldn't be any unless some other doofus just checked in during this window.
p4 revertto back out of the integration before fixing the problem (in your private branch).
p4 submit; this is the only real checkin from the perspective of other developers, so your checkin comment should probably summarize all of the changes made in your private branch (and maybe list the relevant change numbers).
p4 submit. So if you want to back out and restart the whole procedure, just use
p4 revertand then
p4 openedto make sure that all files have been successfully reverted.