Perforce Public Knowledge Base - Sparse Branching
Reset Search



Sparse Branching

« Go Back



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.


In general, whenever you branch a project for new or private development, branch the complete project tree. 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 occurs 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.


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.

  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 do not need to create and sync an entire extra copy of the mainline files.

    For example, modify your client spec View field as follows:

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

    When using a client view as above and issuing a p4 sync command, the /private branch files 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 with an overlay mapping in effect, the edits 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 with an overlay mapping in effect), then you 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 branch spec for the purpose of integrating your changes back to the parent codeline. For example:

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

The branch spec 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.

Related Links
Overlay Mappings
Perforce User's Guide



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255