My preferred structure is for each project to have a root in the depot, then each branch to have a root within the project. So as the codebase matures you end up with:

\\depot
    \ProjectX
       \MAIN
          \source
       \R1
          \source
        \R2
          \source
    \ProjectY
       \MAIN
          \source
etc.

Nothing revolutionary there, but it gives some context for the examples.

Branching the Codeline

There are  four steps to creating and populating a branch from the main codeline:

1. Create a branch view
2. Create a master workspace (client view) for the branch
3. Flag files to be branched (integrated in Perforce terminology)
4. Submit the change list from 3) to the depot

(there are other approaches but this is straightforward and recommended. See Practical Perforce - Google Book Search
 and Perforce Branching for more details).

Walkthrough

I'll follow this through with the example that ProjectX has just been released to version 3.0. The build applied a label of 3.0.4.86 to the code which has gone into release, and work has been checked into the main branch since, so we want to create a new R3 branch and populate it from the MAIN branch at label 3.0.4.86.

The example will use the command line tool p4.exe, so when we look at automating this in a script the commands will be familiar. Note that in Perforce most command lines take a small number of arguments, then launch a text editor with a pre-populated specification form. After editing and saving the form, the command will complete.

1. Create the branch view
   
We start by creating a branch with a view that links it back to the main codeline. Following best practice guidelines, the branch name reflects the project and the views it links: ProjectX_MAIN-R3. Creating it is as simple as issuing:

    p4 branch ProjectX_MAIN-R3

- and setting the view in the specification form to map the existing MAIN branch to the new R3 branch:

//depot/ProjectX/MAIN/... //depot/ProjectX/R3/...

This creates the branch view which you will see listed in the Branches tab of P4V, but the new branch is not yet in the depot.

2. Create the master workspace

We'll create a workspace for the branch which will be the master - by integrating the R3 master workspace with the main branch, we'll populate the depot with the desired source. Using the p4 client command, we'll create the workspace ProjectX_R3-MASTER:

    p4 client ProjectX_R3-MASTER

- and in the specifcation form, set the view to map the R3 master to the R3 branch:

//depot/ProjectX/R3/... //ProjectX_R3-MASTER/...

You should now see the new master in the P4V Workspaces view, but the depot won't have an R3 branch populated yet.

3. Flag files to be branched

Using p4 integrate, we create a changelist which will populate the R3 master from MAIN, via the R3 branch:

p4 -cProjectX_R3-MASTER integrate -b ProjectX_MAIN-R3 @3.0.4.86

There is no specification form for this command. Note that we tell P4 to use the R3 master workspace with the -c global option before issuing integrate. This will flag all the files from the R3 branch with the 3.0.4.86 label in the R3 master's default changelist as new additions. To populate the branch in the depot we just need to submit the changelist.

4. Submit the change list

p4 -cProjectX_R3-MASTER submit

The specification form here shows you all the files that will be added and requires you to give the changelist a description - you must change it from the default <enter description here>.

Assuming there were no errors, we'll now have the populated R3 branch under ProjectX, without the changes made in MAIN after the 3.0.4.86 build. You may well have errors as the views you enter in the spec forms are not validated against what's in the depot. This is a brittle operation which is likely to be needed repeatedly, so in the next post we look at scripting the whole branch creation.

Developing Against Branches

You can create your dev workspaces with a view over the whole project (e.g. \\depot\\ProjectX\... \\a.developer\ProjectX\...), so when the new branch is added it will be automatically brought into the developers' workspaces when they Get Latest.

I'd prefer to set workspaces up to a specific branch (\\depot\\ProjectX\MAIN\... \\a.developer\ProjectX\MAIN\...). This means you only have people working in the branch they need. When a new branch is made the people who need to work on it can edit their workspace to add the new view (\\depot\\ProjectX\R3\... \\a.developer\ProjectX\R3\...). The main dev team continue as they are and don't end up having to synchronize to branches they never use.

Alternatively, you can set up a workspace for each branch you work on, so developers would have a main workspace and a Release 1 workspace. The new dev workspace can be created using the branch master as a template. I'm disinclined to use this as there's a greater admin/maintenance/licensing overheead, with no benefits above the single-workspace-multiple-views approach.

Posted on Friday, April 4, 2008 9:27 AM Perforce | Back to top