Practical Perforce

Practical Perforce

by Laura Wingerd
Released November 2005
Publisher(s): O'Reilly Media, Inc.
ISBN: 9780596518073

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

When developers build software, they're able to keep track of all the different versions and all the components they use with software configuration management (SCM) systems. One of the more popular SCM products is Perforce.

Authored by Perforce's own VP of product technology, Practical Perforce is the ideal complement to the existing product manual, focusing less on the 'how" and more on the "why" and "when." The book is not only a helpful introduction to Perforce,it's an enlightening resource for those already familiar with this versatile SCM product. Whether you're a programmer, product manager, or build engineer, you stand to benefit from the many insider tips and ideas presented in this convenient guide.

Practical Perforce is divided into two main parts. Part I offers a whirlwind technical tour, complete with careful descriptions of basic and advanced Perforce commands designed to give you a baseline knowledge. Part II describes the big picture-using Perforce in a collaborative software development. It outlines recommended best practices and quickly shows how to implement them with the Perforce operations introduced in Part I. Throughout the book, you'll learn how to maximize Perforce so it completes tasks like these in the most efficient manner possible:

  • Keep track of changes as you conduct concurrent parallel work on files
  • Log activity
  • Generate reports on who did what when
  • Compare, merge and branch files
  • Store files and file configurations
  • Restore lost bug fixes

Recognizing the pitfalls and practices of an SCM system like Perforce is absolutely essential to producing good software. Now, with Practical Perforce, you have the edge you need to ensure success.

Table of contents

  1. Preface
    1. What Is Perforce?
    2. The Perforce System in a Nutshell
    3. Why Perforce?
    4. About This Book
    5. What’s Not In This Book
    6. Additional Reading
    7. Conventions Used in This Book
    8. Using Code Examples
    9. Safari® Enabled
    10. How to Contact Us
    11. Acknowledgements
  2. 1. Files in the Depot
    1. 1.1. The Perforce Filespec Syntax
      1. 1.1.1. The depot hierarchy
      2. 1.1.2. Wildcards and file collections
      3. 1.1.3. Views and mappings
      4. 1.1.4. File and directory revisions
      5. 1.1.5. Changes and changelists
    2. 1.2. Browsing Depot Files
      1. 1.2.1. Navigating the file tree
      2. 1.2.2. Listing directories
      3. 1.2.3. Listing directory history
      4. 1.2.4. What’s in a changelist?
      5. 1.2.5. Listing files and file information
      6. 1.2.6. Finding files
      7. 1.2.7. Perusing file history and file origins
      8. 1.2.8. Perusing file content
      9. 1.2.9. Saving informal copies of files
      10. 1.2.10. Comparing depot files
      11. 1.2.11. Comparing depot directories
    3. 1.3. File Types at a Glance
      1. 1.3.1. Type modifiers
      2. 1.3.2. What kind of file is this?
  3. 2. Working with Files
    1. 2.1. An Overview
    2. 2.2. Creating A Workspace
      1. 2.2.1. Specs and spec forms
      2. 2.2.2. Editing a client spec
      3. 2.2.3. Customizing a Workspace View
      4. 2.2.4. Identifying the current workspace
      5. 2.2.5. Listing Workspaces
      6. 2.2.6. Setting the current workspace
      7. 2.2.7. Switching between workspaces
    3. 2.3. Synchronizing a Workspace
      1. 2.3.1. Listing unsynchronized files
      2. 2.3.2. Synchronizing the entire workspace
      3. 2.3.3. Synchronizing in bits and pieces
      4. 2.3.4. When did I last synchronize?
      5. 2.3.5. What’s new in the depot?
      6. 2.3.6. Synchronizing with older revisions
      7. 2.3.7. Listing files in your workspace
      8. 2.3.8. Detecting missing workspace files
      9. 2.3.9. Replacing missing files
      10. 2.3.10. Detecting files that didn’t come from the depot
    4. 2.4. Local Syntax, Wildcard Expansion, and Special Characters
    5. 2.5. Working with Local Files
      1. 2.5.1. Opening files for editing
      2. 2.5.2. Which files am I working on?
      3. 2.5.3. Who’s working on these files?
      4. 2.5.4. Which files did I change?
      5. 2.5.5. Adding new files to the depot
      6. 2.5.6. Adding an entire directory tree of files
      7. 2.5.7. Deleting depot files
      8. 2.5.8. Cloning depot files and directories
      9. 2.5.9. Modifying files as you clone them
      10. 2.5.10. Renaming files and directories
      11. 2.5.11. Replacing and swapping file content
      12. 2.5.12. Locking files
      13. 2.5.13. Designating file types
      14. 2.5.14. Changing the type of existing files
      15. 2.5.15. Opening files after the fact
      16. 2.5.16. Reverting files
    6. 2.6. Working with Pending Changelists and Submitting Files
      1. 2.6.1. Submitting a pending changelist
      2. 2.6.2. Preventing unchanged files from being submitted
      3. 2.6.3. Creating additional changelists
      4. 2.6.4. Do I have more than One pending changelist?
      5. 2.6.5. Moving files from one changelist to another
      6. 2.6.6. What’s in this changelist?
      7. 2.6.7. Submitting a numbered pending changelist
      8. 2.6.8. Getting rid of empty changelists
      9. 2.6.9. Submitting a Subset of opened files
      10. 2.6.10. When submit fails
      11. 2.6.11. Resolving files
      12. 2.6.12. Listing unresolved files
    7. 2.7. Removing and Restoring Files
      1. 2.7.1. Removing workspace files
      2. 2.7.2. Deleting depot files
      3. 2.7.3. Obliterating files
    8. 2.8. Useful Recipes
      1. 2.8.1. Reconciling offline changes
      2. 2.8.2. Backing out a recent change
  4. 3. Resolving and Merging Files
    1. 3.1. Resolving: When, What, and How
      1. 3.1.1. Are You in Sync?
      2. 3.1.2. Which files need resolving?
      3. 3.1.3. Resolving files automatically
      4. 3.1.4. “Yours,” “theirs,” and “base”
      5. 3.1.5. Resolving files by copying theirs into yours
      6. 3.1.6. Resolving files by ignoring theirs
      7. 3.1.7. Resolving files by merging theirs into yours
      8. 3.1.8. Resolving files interactively
      9. 3.1.9. Perforce doesn’t merge binary files
      10. 3.1.10. What’s been resolved, and how?
    2. 3.2. How Perforce Merges Text Files
      1. 3.2.1. Chunks and conflicts
      2. 3.2.2. A simple file merge
      3. 3.2.3. Merging moved lines
      4. 3.2.4. Comparing whitespace
    3. 3.3. Reconciling Structural Changes
      1. 3.3.1. Someone adds the files you were going to add
      2. 3.3.2. Someone deletes the files you were going to delete
      3. 3.3.3. Someone renames the files you were editing
      4. 3.3.4. Someone moves the files you were editing
      5. 3.3.5. Someone combines the files you were editing with other files
      6. 3.3.6. Someone deletes the files you were editing
      7. 3.3.7. Someone edits the files you were going to delete
      8. 3.3.8. Someone edits the files you planned to rename or move
      9. 3.3.9. Reconciling file type changes
    4. 3.4. Tips for Smoother Collaboration
      1. 3.4.1. Keep your workspace synchronized
      2. 3.4.2. Synchronize and resolve one changelist at a time
      3. 3.4.3. Be on the lookout for changes that can’t be resolved
      4. 3.4.4. Submit logical changelists
      5. 3.4.5. Check your merged files
    5. 3.5. The Arcana of Merging
      1. 3.5.1. Forced merging
      2. 3.5.2. Can you undo or redo a resolve?
      3. 3.5.3. Can you undo a merge?
      4. 3.5.4. What happens when you revert files?
      5. 3.5.5. Backing out changes, revisited
      6. 3.5.6. Configuring P4 to use P4Merge
      7. 3.5.7. Configuring an alternate merge tool
      8. 3.5.8. Merging nontext files
      9. 3.5.9. Setting P4MERGE
  5. 4. Branching and Integration
    1. 4.1. The Classic Case for A Branch
    2. 4.2. Creating Branches
      1. 4.2.1. Opening files for branching
      2. 4.2.2. Branching from a point in time
      3. 4.2.3. Am I branching the right files?
      4. 4.2.4. Oops, I branched the wrong files!
      5. 4.2.5. It’s not a branch until the files are submitted
      6. 4.2.6. Can you undo and redo a branch?
      7. 4.2.7. Creating really huge branches
      8. 4.2.8. Working in a New Branch
      9. 4.2.9. Browsing branch history
      10. 4.2.10. Comparing branches
    3. 4.3. Integrating Changes from Branch to Branch
      1. 4.3.1. Which Changes Need Integrating?
      2. 4.3.2. Integrating Changes incrementally
      3. 4.3.3. Integrations won’t be repeated
      4. 4.3.4. Which files need resolving ? (And why?)
      5. 4.3.5. “Yours”, “theirs”, and “base”, revisited
      6. 4.3.6. Merging the donor file into the target
      7. 4.3.7. Copying the donor file into the target
      8. 4.3.8. Ignoring the donor file’s changes
      9. 4.3.9. Editing files as you’re integrating them
      10. 4.3.10. Integrating by subdirectory
      11. 4.3.11. Cherry-picking changes to integrate
      12. 4.3.12. Integrating all changes at once
      13. 4.3.13. Which Changes Were Integrated?
      14. 4.3.14. Don’t break up changelists
    4. 4.4. Reconciling Structural Changes
      1. 4.4.1. Using branch views
      2. 4.4.2. Looking for a branch view
      3. 4.4.3. Branch views are reversible
      4. 4.4.4. Mapping one directory structure to another
      5. 4.4.5. Keeping added files from being propagated
      6. 4.4.6. Keeping target files from being deleted
      7. 4.4.7. Preventing warnings about deleted target files
    5. 4.5. The Arcana of Integration
      1. 4.5.1. Reconciling Split and Combined Files
      2. 4.5.2. Integration history can’t be undone
      3. 4.5.3. Forcing Perforce to Redo an Integration
      4. 4.5.4. The mechanics of integration
      5. 4.5.5. What interchanges really tells us
      6. 4.5.6. Decoding integration history
      7. 4.5.7. Why does editing matter?
      8. 4.5.8. The curious syntax of the integrate command
  6. 5. Labels and Jobs
    1. 5.1. Saving Important Configurations
      1. 5.1.1. Changelists and dates: the automatic snapshots
      2. 5.1.2. Comparing snapshots
    2. 5.2. Using Labels
      1. 5.2.1. Applying a label to files
      2. 5.2.2. Referring to labels
      3. 5.2.3. Which files did I label?
      4. 5.2.4. Locking a label
      5. 5.2.5. Do you really need a label?
      6. 5.2.6. Labeling the current workspace configuration
      7. 5.2.7. What’s the difference between tag and labelsync?
      8. 5.2.8. Finding and comparing labels
      9. 5.2.9. Reusable labels (rolling labels)
      10. 5.2.10. Archiving rolling labels with unique labels
      11. 5.2.11. Archiving rolling labels in files
      12. 5.2.12. Labels have views , too
      13. 5.2.13. Removing a label
      14. 5.2.14. Labels, snapshots, and workspaces
    3. 5.3. Using Jobs
      1. 5.3.1. What is a job?
      2. 5.3.2. Creating jobs
      3. 5.3.3. Searching for jobs
      4. 5.3.4. Linking jobs to changelists
      5. 5.3.5. Preselecting your own jobs
      6. 5.3.6. Linking jobs to changelists after the fact
      7. 5.3.7. Searching for job fixes
      8. 5.3.8. Deleting and restoring jobs
      9. 5.3.9. Jobs can’t be locked
    4. 5.4. Jobs as Changelist Markers
      1. 5.4.1. Marking changelist numbers
      2. 5.4.2. Looking up changelist numbers by job
  7. 6. Controlling and Automating Activity
    1. 6.1. Depot and File Access
      1. 6.1.1. Creating a new depot
      2. 6.1.2. Depot protections
      3. 6.1.3. Groups
    2. 6.2. Accessing Files in Other Domains
      1. 6.2.1. Switching domains
      2. 6.2.2. How remote depots work
      3. 6.2.3. Distributed software...
      4. 6.2.4. ...versus distributed software development
    3. 6.3. Saving and Restoring Specs
      1. 6.3.1. Setting up a spec depot
      2. 6.3.2. Restoring a spec
    4. 6.4. Change Notification and Change Monitoring
      1. 6.4.1. The Perforce change review daemon
      2. 6.4.2. Subscribing as a depot path reviewer
      3. 6.4.3. Review daemon commands
      4. 6.4.4. Using P4Web and browser bookmarks to monitor changes
      5. 6.4.5. Hyperlinks to Perforce files and objects
      6. 6.4.6. Undocumented P4Web URL tricks
    5. 6.5. Scripting Tips
      1. 6.5.1. The fstat command
      2. 6.5.2. Tagged output
      3. 6.5.3. Marshalled output
      4. 6.5.4. Dates and times
      5. 6.5.5. Specs and spec forms
      6. 6.5.6. Scripting language extensions
      7. 6.5.7. Don’t swamp your server
      8. 6.5.8. Triggers
    6. 6.6. Behind-the-Scenes Version Control
      1. 6.6.1. WebKeeper, a Perforce module for Apache
      2. 6.6.2. P4Web, Perforce’s own web server
      3. 6.6.3. How are WebKeeper and P4Web different?
      4. 6.6.4. Perforce via FTP
      5. 6.6.5. Windows applications and perforce plug-ins
      6. 6.6.6. Perforce as ODBC data source
  8. 7. How Software Evolves
    1. 7.1. The Story of Ace Engineering
    2. 7.2. The Mainline Model
      1. 7.2.1. From ideal world to real world
      2. 7.2.2. The flow of change
      3. 7.2.3. Branching from release codelines
      4. 7.2.4. Branching from development codelines
      5. 7.2.5. Soft, medium, and firm: the tofu scale
      6. 7.2.6. A codeline by any other name...
      7. 7.2.7. One-way codelines
      8. 7.2.8. Codelines that aren’t codelines
      9. 7.2.9. Musings on codeline diagrams
    3. 7.3. Ace Engineering Revisited
    4. 7.4. Containerizing
      1. 7.4.1. Modules
      2. 7.4.2. Codelines
      3. 7.4.3. Bodies of Code
  9. 8. Basic Codeline Management
    1. 8.1. Organizing Your Depot
      1. 8.1.1. Filespecs as containers
      2. 8.1.2. The depot hierarchy
      3. 8.1.3. The scope of a depot
      4. 8.1.4. Codeline grouping
      5. 8.1.5. Lineage versus location
      6. 8.1.6. Depot path naming conventions
      7. 8.1.7. Storing generated files
      8. 8.1.8. Codeline proliferation
      9. 8.1.9. How not to organize your depot
    2. 8.2. General Care and Feeding of Codelines
      1. 8.2.1. The codeline curator
      2. 8.2.2. Naming a codeline
      3. 8.2.3. Which modules go in a codeline?
      4. 8.2.4. The master workspace
      5. 8.2.5. The codeline’s branch view
      6. 8.2.6. Branching a codeline
      7. 8.2.7. Working in a codeline
      8. 8.2.8. Controlling access to a codeline
      9. 8.2.9. Retiring a codeline
    3. 8.3. Nightly Builds
      1. 8.3.1. The nightly build workspace
      2. 8.3.2. Synchronizing the nightly build
      3. 8.3.3. Opening generated files
      4. 8.3.4. Submitting generated files
      5. 8.3.5. Labeling nightly builds
      6. 8.3.6. Using the nightly build label
    4. 8.4. Is Bug X Fixed in Codeline Y?
      1. 8.4.1. Inside the perforce database
      2. 8.4.2. Commands that detect merged bug fixes
      3. 8.4.3. False positives
      4. 8.4.4. Making merge detection more accurate
  10. 9. Release Codelines
    1. 9.1. Creating a Release Codeline
      1. 9.1.1. When should we branch?
      2. 9.1.2. Who owns the release codeline?
      3. 9.1.3. Naming a release codeline
      4. 9.1.4. Which modules should we branch?
      5. 9.1.5. A branch view for the release codeline
      6. 9.1.6. The master workspace
      7. 9.1.7. Are we branching the right files?
      8. 9.1.8. A label view for the branch point
      9. 9.1.9. Labeling the branch point
      10. 9.1.10. Creating the release codeline—really!
      11. 9.1.11. Branching more files later
    2. 9.2. Working in a Release Codeline
      1. 9.2.1. The developer’s workspace
      2. 9.2.2. What to document in the change descriptions
      3. 9.2.3. Fixing a bug? Fix a job!
      4. 9.2.4. What if i can’t check in a change?
      5. 9.2.5. Keeping the branch view up to date
    3. 9.3. Integrating Changes into the Mainline
      1. 9.3.1. Which changes should be integrated?
      2. 9.3.2. When should changes be integrated?
      3. 9.3.3. Who does the integration?
      4. 9.3.4. A workspace for integrating into MAIN
      5. 9.3.5. Finding unintegrated changes
      6. 9.3.6. When it’s okay to integrate changes out of order
      7. 9.3.7. Integrating a change
      8. 9.3.8. How much has the mainline changed?
    4. 9.4. Making a Release
      1. 9.4.1. Building the release
      2. 9.4.2. Labeling the release
      3. 9.4.3. Making point releases
      4. 9.4.4. Generating release note information
    5. 9.5. Distributing Releases
      1. 9.5.1. From release codeline to distribution stream
      2. 9.5.2. From distribution stream to FTP site
      3. 9.5.3. Oops, we released the wrong build!
      4. 9.5.4. Using P4FTP as a sync daemon
    6. 9.6. Breaking the Rules
      1. 9.6.1. Backporting a bug fix
      2. 9.6.2. Pulling late-breaking development into a release
    7. 9.7. Retiring a Release Codeline
      1. 9.7.1. Who’s still working in a release codeline?
      2. 9.7.2. Are all changes integrated?
      3. 9.7.3. Setting protections to prevent changes
      4. 9.7.4. Setting protections to hide a retired codeline
      5. 9.7.5. Annotating a release codeline’s branch and label views
    8. 9.8. Task Branches and Patch Branches
      1. 9.8.1. Creating a task branch
      2. 9.8.2. Working on files in a task branch
      3. 9.8.3. Keeping a task branch and its workspace up to date
      4. 9.8.4. Reviewing and integrating task branch changes
      5. 9.8.5. Creating a patch branch
  11. 10. Development Codelines
    1. 10.1. Creating A Development Codeline
      1. 10.1.1. Why a Development Codeline?
      2. 10.1.2. What goes on in a development codeline?
      3. 10.1.3. Who owns the development codeline?
      4. 10.1.4. Naming the development codeline
      5. 10.1.5. Which modules should we branch?
      6. 10.1.6. Why branch static modules ?
      7. 10.1.7. A branch view for the development codeline
      8. 10.1.8. Creating a master workspace
      9. 10.1.9. Branching the development codeline
    2. 10.2. Working in a Development Codeline
      1. 10.2.1. The developer’s workspace
      2. 10.2.2. Workspace File Filters
      3. 10.2.3. Writing helpful changelist descriptions
    3. 10.3. Keeping a Development Codeline Up to Date
      1. 10.3.1. When should a development codeline be updated?
      2. 10.3.2. Which changes need integrating?
      3. 10.3.3. Adjusting the development codeline’s branch view
      4. 10.3.4. Integrating changes
    4. 10.4. Working with Third-Party Software
      1. 10.4.1. Importing third-Party software
      2. 10.4.2. Branching imported code to the development codeline
      3. 10.4.3. Updating the development codeline’s branch view
      4. 10.4.4. Importing a new distribution
      5. 10.4.5. Merging a new distribution with local changes
    5. 10.5. Delivering Completed Development Work
      1. 10.5.1. Merge down, copy up
      2. 10.5.2. When should development be delivered?
      3. 10.5.3. Identifying a Point of Completion
      4. 10.5.4. Which changes should be integrated into the parent?
      5. 10.5.5. Freezing the parent codeline
      6. 10.5.6. Which Workspace?
      7. 10.5.7. Preparing a change description
      8. 10.5.8. Normalizing the branch view
      9. 10.5.9. Integrating into the parent codeline
      10. 10.5.10. Integrating neglected files
      11. 10.5.11. Thawing the parent codeline
      12. 10.5.12. Retiring a development codeline
    6. 10.6. The Soft Codelines
      1. 10.6.1. Shelving Work in Progress
      2. 10.6.2. Private branches
      3. 10.6.3. Code reviews
      4. 10.6.4. Reparenting a private branch
      5. 10.6.5. Redeploying a private branch
  12. 11. Staging Streams and Web Content
    1. 11.1. Staging Web Content
      1. 11.1.1. Web Content at Ace Engineering
      2. 11.1.2. The Release Cycle
      3. 11.1.3. How Web Sites Are Updated
      4. 11.1.4. Pulling a release into testing
      5. 11.1.5. Publishing a tested release
      6. 11.1.6. Release timing is flexible
      7. 11.1.7. The web content audit trail
    2. 11.2. Visual Content Development
      1. 11.2.1. The visual content codeline
      2. 11.2.2. Working on visual content
      3. 11.2.3. What’s ready to be released?
      4. 11.2.4. Automating continuous integration
      5. 11.2.5. Enforcing the use of jobs
      6. 11.2.6. Preventing merging
    3. 11.3. Bug Fixes and Staging Streams
      1. 11.3.1. Non critical bugs
      2. 11.3.2. Show stoppers in WEBQA
      3. 11.3.3. Rolling back the published web site
      4. 11.3.4. Forcing integration after a roll-back
    4. 11.4. Major Web Development
  13. A. Setting Up a Perforce Test Environment
    1. A.1. Setup
      1. A.1.1. Installing Perforce on Windows
      2. A.1.2. Installing Perforce on Linux and other Unix systems
      3. A.1.3. Installing Perforce on Mac OS X
      4. A.1.4. Your test environment
    2. A.2. Connecting to Other Servers
      1. A.2.1. Which server am I connected to?
    3. A.3. Getting Help
  14. B. Perforce Terminology and P4 Commands
  15. C. Bibliography
  16. Glossary
  17. About the Author
  18. About the Author
  19. Colophon
  20. Copyright

Product information

  • Title: Practical Perforce
  • Author(s): Laura Wingerd
  • Release date: November 2005
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9780596518073