» Support » Knowledge Base »  User Tasks » Codelines and Branching » Sparse Branching

SUMMARY

Branching a subset of project files, rather than branching an entire project tree, is often referred to as "sparse branching". A sparse branch might also be referred to in some contexts as a "private" or "task" branch. This article explains when sparse branches are appropriate and offers guidance for their use.

DETAILS

In general, it is recommended that whenever a project is branched for new or private development, that the complete project tree is branched. By branching the entire project, all of the components necessary to build the project are collected in one location. Having all needed files under one project tree eliminates dependencies on source files residing in a different depot context that could change independently and adversely affect your private development work.

There are some cases, however, where branching an entire project tree is either impractical, undesirable, or both. For example, if your project tree has 100,000 files and you only need to modify a small, well-defined subset, it might make sense to only branch those files you are likely to modify. This situation commonly obtains when there is a large base of common or shared code and small platform-specific variants.

Among the benefits of sparse branching are the reduction of the number of files that need to be manipulated in the depot and reduction of server processing overhead. Using sparse branches can also result in smaller, more manageble, and more comprehensible changelists.

The downside of sparse branching is that the complexity of client mappings increases and the standard one-to-one mapping between client and server files is modified, potentially confusing users.

Implementation

The sparse branching methodology typically uses "overlay mappings" in Perforce client specs. Use of overlay mappings allows the "sparsely branched" files to be combined with common files from a "base codeline". With overlay mappings, two (or more) different depot paths map to the same client workspace path.

For example, if you only need to work on a single component of Project X, you might branch only those component files into a private development area -- and then use an overlay mapping to retrieve those "sparsely" branched private files into your workspace in place of their main Project X variants.

Example

1. Branch your subset of files into a "private" or shared development branch. This "sparse" branch of the main codeline uses just the component files of interest. For example:

p4 integ //depot/main/ProjectX/widget/... //depot/private/ProjectX/widget/...
p4 submit

2. In your workspace, overlay map the /private development branch files over their /main codeline variants; by doing so, you don't need to create and sync an entire extra copy of the mainline files.

For example, modify your client spec View as follows:

View:
    //depot/main/ProjectX/... //myclient/main/ProjectX/...
    +//depot/private/ProjectX/... //myclient/main/ProjectX/...

When using a View as above and issuing a p4 sync command, the /private branch files will overwrite any /main codeline files in the client workspace. This behavior allows you to test your private branch modifications using the latest code in the mainline. See p4 help views for more details on using client Views and overlay mappings.

When you p4 edit a file where an overlay mapping applies, the edits will apply to the overlay branch (in this case /private), not the /main branch.

NOTE: If you want to edit files on the /main branch (or any branch where an overlay mapping applies), then you will either have to temporarily use a different workspace, or modify your client workspace mappings temporarily to remove the overlay mapping.

When you are satisfied with your /private changes, you can re-integrate them into the mainline and then delete your private branch. Alternatively, you can re-use this sparse branch for the next development task.

If you intend to re-use your private or task branch, then it often makes sense to create a branchspec for the purpose of integrating your changes back to the parent codeline. For example:

Branch: Main2Task
View:
    //depot/main/ProjectX/widget/... //depot/private/ProjectX/widget/...

The branchspec is primarily a convenience to avoid re-typing the source and target path names as well as a means to document the relationship between the source and target codelines.