Practical Perforce by Laura Wingerd
Subscribe to RSS
To create a new codeline referred to as branching or propagate a bug fix or new feature from one codeline to another, you integrate the required files to the target codeline. To integrate files, you open them for integration, specifying source and target, then submit the changelist containing the open files. For more information, see Creating Branches. Merging, which propagates change from one existing codeline to another and prompts you to resolve any conflicts between the codelines. Copying, which is reserved for propagating a straightforward duplicate of the files in one codeline to another. If you are merging changes into an existing codeline, you are required to resolve the files to ensure that you do not overwrite other users' changes and to preserve the file's revision history. Typical steps for propagating changes from one codeline to another are as follows:. Resolve the files, deciding how changed files are to be submitted. When you open files for merge, you can specify the mapping of source to target using either a file specification or a branch mapping. File specification : you specify the source and target files when you open files for merging. Branch mapping : you select a branch mapping when you open files for merging. Branch mappings enable you to predefine source and target codelines. For details about branch mappings, see the P4 User's Guide. The workflow for propagating change between streams "merge up, copy down" is simple and specific. In the Perforce Command-line Client, the term integrate is used not only to encompass all three integration types branch, merge, copybut is also used synonymously with the P4V term, merge. Within P4V, merge can refer both to merging files from one codeline to another and to merging conflicts between files the function performed by P4Merge. For Merge method, choose Specify source and target files. To specify additional merge options, click the Options disclosure triangle. Resolve and Submit Options : These options enable you to specify whether files are submitted manually or automatically, and to configure how conflicts are resolved. Filter Options : Filtering enables you to choose a subset of the revisions that are queued for merging. For more information, see Searching and Filtering. Advanced Options : These options enable you to refine the results of the merge as follows:. Do not copy newly branched target files to workspace -v : Create a branch in the depot without retrieving the corresponding files from the depot to your workspace. Enable baseless merges -i : Perform the integration even if source and target share no common ancestor, using the most-recently-added revision of the source file as the base. Try to integrate changes when source deleted and re-added -Di : If the target file has been deleted and the source file changed, this option re-branches the source file on top of the target file. If the source file has been deleted and the target file has changed, this option deletes the target file. By default, outstanding edits cannot be integrated with a deleted file. Force integration on all revisions, disregarding integration history -f : Integrate all revisions of source and target files, including revisions that have already been integrated. Typically used with a specified revision range. Do not get latest revision of selected files -h : Use the workspace revision of the target file. By default, the head revision of the target file is automatically retrieved into the workspace before integrating. Disregard indirect integration history -1 : Restrict selection of the base file revision to direct parent-to-child or child-to-parent integration history. Propagate source filetypes to target files -t : Assign the target file the same file type as the source file when integrating to existing target files. Schedule 'branch resolves' -Rb : Schedules a branch resolve, instead of branching new target files automatically.
In the course of software development, we branch files to do concurrent, parallel work on them, and we integrate files to combine the results of such work. In this book we use the term branch to mean a set of files that is a variant of another, each set evolving independently. Codeline and stream are other words for this set. In Perforce, we say we integrate changes from one branch into another. This is not a capricious choice of words. Why was this change never merged? Is it not applicable? Or did someone simply forget to merge it? The business of accounting for every change is what Perforce calls integrating. A change can be integrated from branch to branch by merging, when appropriate, or by simply deciding that it should be ignored. Of all the uses for branchingthe one best understood is that of branching recently developed software for a product release. Our plan is to release Ace Version 1. Meanwhile, those of us testing and stabilizing the 1. The two file trees are shown in Figure Over time, content diverges between the two trees as new development proceeds. This notion of cloning a tree of files from another is the essence of branching in Perforce. We clone a tree of files so that we can make changes to either tree—or branch—without affecting the other. The two file trees are peers in the depot hierarchy. Moreover, every file is a full-fledged file in its own right. Files in either branch can be edited, added, deleted, renamed, or moved. And changes made in one branch can be merged or otherwise integrated to the other. Behind the scenes, Perforce keeps track of branching. Although every branched file is a file in its own right, its lineage is stored in the Perforce database. Even more important is that Perforce can tell us the integration history of a branch. Given a pair of branches, Perforce can tell us which changes have already been integrated from one into the other, and which have yet to be integrated. The goal of this chapter is to front-load you with knowledge to keep you from making the common mistakes the first time out. However, the classic case is certainly not the only use to which Perforce branching can be applied. As with all operations that affect depot files, creating a branch is a two-step process in Perforce.
The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page. For a list of other such plugins, see the Pipeline Steps Reference page. The character set used by Jenkins when syncing files from the Perforce server. This should be set to 'none' unless connected to a Unicode enabled Perforce server. Specify the name of the Perforce workspace to be used as the Jenkins build workspace. If the workspace does not yet exist, the configuration will be saved in Jenkins; the workspace is created only when it is to be used. If the workspace exists and you are connected to a Perforce server the auto-text fill should list suitable workspaces; updates are only applied when the workspace is used. Maps files in the depot to files in your client workspace. Defines the files that you want in your client workspace and specifies where you want them to reside. The default view maps all depot files onto the client. See 'p4 help views' for view syntax. A new view takes effect on the next 'p4 sync'. By default all clients are 'writeable', certain clients are short lived and perform long sync and build cycles. Over time these build clients can fragment the 'db. Setting a type of 'readonly' gives the client its own personal 'db. A 'readonly' client cannot 'edit' or 'submit' files, however for build automation this is not usually a requirement and the performance tradeoff is worth considering if your build automation is causing issues with the 'db. This option requires that an administrator has first configured the 'client. If it is necessary to submit changes as part of your build, you may specify a 'partitioned' client: like a 'reaonly' client, this type also has a separate 'db. If not specified backup of a writable client defaults to enabled. Specify the name of an existing workspace in Perforce to be used as the Jenkins build workspace. If connected to a Perforce server the auto-text fill should list suitable workspaces.
What is Branching? Branching is a means of keeping two or more sets of similar but not identical files synchronized. Most software configuration management systems have some form of branching; Perforce's mechanism is particularly efficient because it mimics the style in which users create their own file copies when no branching mechanism is available. Suppose for a moment that you're writing a program and are not using an SCM system. You're ready to release your program: what would you do with your code? Chances are that you'd copy all your files to a new location. One of your file sets would become your release codeline, and bug fixes to the release would be made to that file set; your other files would be your development file set, and new functionality to the code would be added to these files. What would you do when you find a bug that's shared by both file sets? You'd fix it in one file set, and then copy the edits that you made into the other file set. The only difference between this homegrown method of branching and Perforce's branching methodology is that Perforce manages the file copying and edit propagation for you. In Perforce's terminology, copying the files is called making a branch. Each file set is known as a codelineand copying an edit from one file set to the other is called integration. The entire process is called branching. When to Create a Branch Create a branch when two sets of code files have different rules governing when code can be submitted, or whenever a set of code files needs to evolve along different paths. For example: The members of the development group want to submit code to the depot whenever their code changes, whether or not it compiles, but the release engineers don't want code to be submitted until it's been debugged, verified, and signed off on. At the time of release, branch a release codeline from the development codeline. When the development codeline is ready, it is integrated into the release codeline. Afterwards, patches and bug fixes are made in the release code, and at some point in the future, integrated back into the development code. A company is writing a driver for a new multi-platform printer. The developers create a branch from the existing UNIX code, and now have two copies of the same code. These two codelines can then evolve separately. If bugs are found in either codeline, bug fixes can be propagated from one codeline to the other with the p4 integrate command. Perforce's Branching Mechanisms: Introduction Perforce provides two mechanisms for branching. One method requires no special setup, but requires the user to manually track the mappings between the two sets of files. The second method remembers the mappings between the two file sets, but requires some additional work to set up. In the first method, the user specifies both the files that changes are being copied from and the files that the changes are being copied into. The command looks like this: p4 integrate fromfiles tofiles In the second method, Perforce stores a mapping that describes which set of files get branched to other files, and this mapping, or branch specification, is given a name. The command the user runs to copy changes from one set of files to the other looks like this: p4 integrate -b branchname [ tofiles ] These methods are described in the following two sections. Branching and Merging, Method 1: Branching with File Specifications Use p4 integrate fromfiles tofiles to propagate changes from one set of files the source files to another set of files the target files. The target files need to be contained within the current client workspace view. The source files do not need to be, so long as the source files are specified in depot syntax. If the target files do not yet exist, the entire contents of the source files are copied to the target files. If the target files have already been created, changes can be propagated from one set of files to the other with p4 resolve. In both cases, p4 submit must be used to store the new file changes in the depot. Examples and further details are provided below.