Mercurial: The Definitive Guide

Mercurial: The Definitive Guide

by Bryan O'Sullivan
Released June 2009
Publisher(s): O'Reilly Media, Inc.
ISBN: 9780596555474

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

O’Reilly members get unlimited access to live online training experiences, plus books, videos, and digital content from O’Reilly and nearly 200 trusted publishing partners.

Start your free trial

Book description

This instructive book takes you step by step through ways to track, merge, and manage both open source and commercial software projects with Mercurial, using Windows, Mac OS X, Linux, Solaris, and other systems. Mercurial is the easiest system to learn when it comes to distributed revision control. And it's a very flexible tool that's ideal whether you're a lone programmer working on a small project, or part of a huge team dealing with thousands of files.

Mercurial permits a countless variety of development and collaboration methods, and this book offers several concrete suggestions to get you started. This guide will help you:

  • Learn the basics of working with a repository, changesets, and revisions
  • Merge changes from separate repositories
  • Set up Mercurial to work with files on a daily basis, including which ones to track
  • Get examples and tools for setting up various workflow models
  • Manage a project that's making progress on multiple fronts at once
  • Find and fix mistakes by isolating problem sources
  • Use hooks to perform actions automatically in response to repository events
  • Customize the output of Mercurial


Mercurial: The Definitive Guide maintains a strong focus on simplicity to help you learn Mercurial quickly and thoroughly.

Publisher resources

View/Submit Errata

Table of contents

  1. Mercurial: The Definitive Guide
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. Preface
      1. Technical Storytelling
      2. Thank You for Supporting Mercurial
      3. Conventions Used in This Book
      4. Using Code Examples
      5. Safari® Books Online
      6. How to Contact Us
      7. This Book Is Free
      8. Acknowledgments
    3. 1. A Brief History of Revision Control
      1. Why Revision Control? Why Mercurial?
        1. Why Use Revision Control?
        2. The Many Names of Revision Control
      2. This Book Is a Work in Progress
      3. About the Examples in This Book
      4. Trends in the Field
      5. A Few Advantages of Distributed Revision Control
        1. Advantages for Open Source Projects
          1. The forking non-problem
        2. Advantages for Commercial Projects
      6. Why Choose Mercurial?
      7. Mercurial Compared with Other Tools
        1. Subversion
        2. Git
        3. CVS
        4. Commercial Tools
        5. Choosing a Revision Control Tool
      8. Switching from Another Tool to Mercurial
      9. A Short History of Revision Control
    4. 2. A Tour of Mercurial: The Basics
      1. Installing Mercurial on Your System
        1. Windows
        2. Mac OS X
        3. Linux
        4. Solaris
      2. Getting Started
        1. Built-In Help
      3. Working with a Repository
        1. Making a Local Copy of a Repository
        2. What’s in a Repository?
      4. A Tour Through History
        1. Changesets, Revisions, and Talking to Other People
        2. Viewing Specific Revisions
        3. More Detailed Information
      5. All About Command Options
      6. Making and Reviewing Changes
      7. Recording Changes in a New Changeset
        1. Setting Up a Username
          1. Creating a Mercurial configuration file
          2. Choosing a username
        2. Writing a Commit Message
        3. Writing a Good Commit Message
        4. Aborting a Commit
        5. Admiring Our New Handiwork
      8. Sharing Changes
        1. Pulling Changes from Another Repository
        2. Updating the Working Directory
        3. Pushing Changes to Another Repository
        4. Default Locations
        5. Sharing Changes over a Network
      9. Starting a New Project
    5. 3. A Tour of Mercurial: Merging Work
      1. Merging Streams of Work
        1. Head Changesets
        2. Performing the Merge
        3. Committing the Results of the Merge
      2. Merging Conflicting Changes
        1. Using a Graphical Merge Tool
        2. A Worked Example
      3. Simplifying the Pull-Merge-Commit Sequence
      4. Renaming, Copying, and Merging
    6. 4. Behind the Scenes
      1. Mercurial’s Historical Record
        1. Tracking the History of a Single File
        2. Managing Tracked Files
        3. Recording Changeset Information
        4. Relationships Between Revisions
      2. Safe, Efficient Storage
        1. Efficient Storage
        2. Safe Operation
        3. Fast Retrieval
        4. Identification and Strong Integrity
      3. Revision History, Branching, and Merging
      4. The Working Directory
        1. What Happens When You Commit
        2. Creating a New Head
        3. Merging Changes
        4. Merging and Renames
      5. Other Interesting Design Features
        1. Clever Compression
          1. Network recompression
        2. Read/Write Ordering and Atomicity
        3. Concurrent Access
          1. Safe dirstate access
        4. Avoiding Seeks
        5. Other Contents of the Dirstate
    7. 5. Mercurial in Daily Use
      1. Telling Mercurial Which Files to Track
        1. Explicit Versus Implicit File Naming
        2. Mercurial Tracks Files, Not Directories
      2. How to Stop Tracking a File
        1. Removing a File Does Not Affect Its History
        2. Missing Files
        3. Useful Shorthand: Adding and Removing Files in One Step
      3. Copying Files
        1. The Results of Copying During a Merge
        2. Why Should Changes Follow Copies?
        3. How to Make Changes Not Follow a Copy
        4. Behavior of the hg copy Command
      4. Renaming Files
        1. Renaming Files and Merging Changes
        2. Divergent Renames and Merging
        3. Convergent Renames and Merging
        4. Other Name-Related Corner Cases
      5. Recovering from Mistakes
      6. Dealing with Tricky Merges
        1. File Resolution States
        2. Resolving a File Merge
      7. More Useful Diffs
      8. Which Files to Manage, and Which to Avoid
      9. Backups and Mirroring
    8. 6. Collaborating with Other People
      1. Mercurial’s Web Interface
      2. Collaboration Models
        1. Factors to Keep in Mind
        2. Informal Anarchy
        3. A Single Central Repository
        4. A Hosted Central Repository
        5. Working with Multiple Branches
        6. Feature Branches
        7. The Release Train
        8. The Linux Kernel Model
        9. Pull-Only Versus Shared-Push Collaboration
        10. Where Collaboration Meets Branch Management
      3. The Technical Side of Sharing
      4. Informal Sharing with hg serve
        1. A Few Things to Keep in Mind
      5. Using the Secure Shell Protocol
        1. How to Read and Write ssh URLs
        2. Finding an ssh Client for Your System
        3. Generating a Key Pair
        4. Using an Authentication Agent
        5. Configuring the Server Side Properly
        6. Using Compression with ssh
      6. Serving Over HTTP Using CGI
        1. Web Server Configuration Checklist
        2. Basic CGI Configuration
          1. What could possibly go wrong?
          2. Configuring lighttpd
        3. Sharing Multiple Repositories with One CGI Script
          1. Explicitly specifying which repositories to publish
        4. Downloading Source Archives
        5. Web Configuration Options
          1. Options specific to an individual repository
          2. Options specific to the hg serve command
          3. Choosing the right ~/.hgrc file to add web items to
      7. System-Wide Configuration
        1. Making Mercurial More Trusting
    9. 7. Filenames and Pattern Matching
      1. Simple File Naming
      2. Running Commands Without Any Filenames
      3. Telling You What’s Going On
      4. Using Patterns to Identify Files
        1. Shell-Style Glob Patterns
          1. Watch out!
        2. Regular Expression Matching with Re Patterns
      5. Filtering Files
      6. Permanently Ignoring Unwanted Files and Directories
      7. Case Sensitivity
        1. Safe, Portable Repository Storage
        2. Detecting Case Conflicts
        3. Fixing a Case Conflict
    10. 8. Managing Releases and Branchy Development
      1. Giving a Persistent Name to a Revision
        1. Handling Tag Conflicts During a Merge
        2. Tags and Cloning
        3. When Permanent Tags Are Too Much
      2. The Flow of Changes: Big Picture Versus Little Picture
      3. Managing Big-Picture Branches in Repositories
      4. Don’t Repeat Yourself: Merging Across Branches
      5. Naming Branches Within One Repository
      6. Dealing with Multiple Named Branches in a Repository
      7. Branch Names and Merging
      8. Branch Naming Is Generally Useful
    11. 9. Finding and Fixing Mistakes
      1. Erasing Local History
        1. The Accidental Commit
        2. Rolling Back a Transaction
        3. The Erroneous Pull
        4. Rolling Back Is Useless Once You’ve Pushed
        5. You Can Only Roll Back Once
      2. Reverting the Mistaken Change
        1. File Management Errors
      3. Dealing with Committed Changes
        1. Backing Out a Changeset
        2. Backing Out the Tip Changeset
        3. Backing Out a Non-Tip Change
          1. Always use the --merge option
        4. Gaining More Control of the Backout Process
        5. Why hg backout Works As It Does
      4. Changes That Should Never Have Been
        1. Backing Out a Merge
        2. Protect Yourself from Escaped Changes
        3. What to Do About Sensitive Changes That Escape
      5. Finding the Source of a Bug
        1. Using the hg bisect Command
        2. Cleaning Up After Your Search
      6. Tips for Finding Bugs Effectively
        1. Give Consistent Input
        2. Automate As Much As Possible
        3. Check Your Results
        4. Beware Interference Between Bugs
        5. Bracket Your Search Lazily
    12. 10. Handling Repository Events with Hooks
      1. An Overview of Hooks in Mercurial
      2. Hooks and Security
        1. Hooks Are Run with Your Privileges
        2. Hooks Do Not Propagate
        3. Hooks Can Be Overridden
        4. Ensuring That Critical Hooks Are Run
      3. A Short Tutorial on Using Hooks
        1. Performing Multiple Actions Per Event
        2. Controlling Whether an Activity Can Proceed
      4. Writing Your Own Hooks
        1. Choosing How Your Hook Should Run
        2. Hook Parameters
        3. Hook Return Values and Activity Control
        4. Writing an External Hook
        5. Telling Mercurial to Use an In-Process Hook
        6. Writing an In-Process Hook
      5. Some Hook Examples
        1. Writing Meaningful Commit Messages
        2. Checking for Trailing Whitespace
      6. Bundled Hooks
        1. acl—Access Control for Parts of a Repository
          1. Configuring the acl hook
          2. Testing and troubleshooting
        2. bugzilla—Integration with Bugzilla
          1. Configuring the bugzilla hook
          2. Mapping committer names to Bugzilla usernames
          3. Configuring the text that gets added to a bug
          4. Testing and troubleshooting
        3. notify—Send Email Notifications
          1. Configuring the notify hook
          2. Testing and troubleshooting
      7. Information for Writers of Hooks
        1. In-Process Hook Execution
        2. External Hook Execution
        3. Finding Out Where Changesets Come From
          1. Sources of changesets
          2. Where changes are going—remote repository URLs
      8. Hook Reference
        1. changegroup—After Remote Changesets Added
        2. commit—After a New Changeset Is Created
        3. incoming—After One Remote Changeset Is Added
        4. outgoing—After Changesets Are Propagated
        5. prechangegroup—Before Starting to Add Remote Changesets
        6. precommit—Before Starting to Commit a Changeset
        7. preoutgoing—Before Starting to Propagate Changesets
        8. pretag—Before Tagging a Changeset
        9. pretxnchangegroup—Before Completing Addition of Remote Changesets
        10. pretxncommit—Before Completing Commit of New Changeset
        11. preupdate—Before Updating or Merging Working Directory
        12. tag—After Tagging a Changeset
        13. update—After Updating or Merging Working Directory
    13. 11. Customizing the Output of Mercurial
      1. Using Precanned Output Styles
        1. Setting a Default Style
      2. Commands That Support Styles and Templates
      3. The Basics of Templating
      4. Common Template Keywords
      5. Escape Sequences
      6. Filtering Keywords to Change Their Results
        1. Combining Filters
      7. From Templates to Styles
        1. The Simplest of Style Files
        2. Style File Syntax
      8. Style Files by Example
        1. Identifying Mistakes in Style Files
        2. Uniquely Identifying a Repository
        3. Listing Files on Multiple Lines
        4. Mimicking Subversion’s Output
    14. 12. Managing Changes with Mercurial Queues
      1. The Patch Management Problem
      2. The Prehistory of Mercurial Queues
        1. A Patchwork Quilt
        2. From Patchwork Quilt to Mercurial Queues
      3. The Huge Advantage of MQ
      4. Understanding Patches
      5. Getting Started with Mercurial Queues
        1. Creating a New Patch
        2. Refreshing a Patch
        3. Stacking and Tracking Patches
        4. Manipulating the Patch Stack
        5. Pushing and Popping Many Patches
        6. Safety Checks, and Overriding Them
        7. Working on Several Patches at Once
      6. More About Patches
        1. The Strip Count
        2. Strategies for Applying a Patch
        3. Some Quirks of Patch Representation
        4. Beware the Fuzz
        5. Handling Rejection
      7. More on Patch Management
        1. Deleting Unwanted Patches
        2. Converting to and from Permanent Revisions
      8. Getting the Best Performance Out of MQ
      9. Updating Your Patches When the Underlying Code Changes
      10. Identifying Patches
      11. Useful Things to Know About
      12. Managing Patches in a Repository
        1. MQ Support for Patch Repositories
        2. A Few Things to Watch Out For
      13. Third-Party Tools for Working with Patches
      14. Good Ways to Work with Patches
      15. MQ Cookbook
        1. Managing Trivial Patches
        2. Combining Entire Patches
        3. Merging Part of One Patch into Another
      16. Differences Between Quilt and MQ
    15. 13. Advanced Uses of Mercurial Queues
      1. The Problem of Many Targets
        1. Tempting Approaches That Don’t Work Well
      2. Conditionally Applying Patches with Guards
      3. Controlling the Guards on a Patch
      4. Selecting the Guards to Use
      5. MQ’s Rules for Applying Patches
      6. Trimming the Work Environment
      7. Dividing Up the Series File
      8. Maintaining the Patch Series
        1. The Art of Writing Backport Patches
      9. Useful Tips for Developing with MQ
        1. Organizing Patches in Directories
        2. Viewing the History of a Patch
    16. 14. Adding Functionality with Extensions
      1. Improve Performance with the inotify Extension
      2. Flexible Diff Support with the extdiff Extension
        1. Defining Command Aliases
      3. Cherry-Picking Changes with the transplant Extension
      4. Sending Changes via Email with the patchbomb Extension
        1. Changing the Behavior of Patchbombs
    17. A. Migrating to Mercurial
      1. Importing History from Another System
        1. Converting Multiple Branches
        2. Mapping Usernames
        3. Tidying Up the Tree
        4. Improving Subversion Conversion Performance
      2. Migrating from Subversion
        1. Philosophical Differences
          1. Scope of commands
          2. Multi-user operation and safety
          3. Published versus local changes
        2. Quick Reference
      3. Useful Tips for Newcomers
    18. B. Mercurial Queues Reference
      1. MQ Command Reference
        1. qapplied—Print Applied Patches
        2. qcommit—Commit Changes in the Queue Repository
        3. qdelete—Delete a Patch from the Series File
        4. qdiff—Print a Diff of the Topmost Applied Patch
        5. qfold—Move Applied Patches into Repository History
        6. qfold—Merge (fold) Several Patches into One
        7. qheader—Display the Header/Description of a Patch
        8. qimport—Import a Third-Party Patch into the Queue
        9. qinit—Prepare a Repository to Work with MQ
        10. qnew—Create a New Patch
        11. qnext—Print the Name of the Next Patch
        12. qpop—Pop Patches Off the Stack
        13. qprev—Print the Name of the Previous Patch
        14. qpush—Push Patches onto the Stack
        15. qrefresh—Update the Topmost Applied Patch
        16. qrename—Rename a Patch
        17. qseries—Print the Entire Patch Series
        18. qtop—Print the Name of the Current Patch
        19. qunapplied—Print Patches Not yet Applied
        20. hg strip—Remove a Revision and Descendants
      2. MQ File Reference
        1. The Series File
        2. The Status File
    19. C. Installing Mercurial from Source
      1. On a Unix-Like System
      2. On Windows
    20. D. Open Publication License
      1. Requirements on Both Unmodified and Modified Versions
      2. Copyright
      3. Scope of License
      4. Requirements on Modified Works
      5. Good-Practice Recommendations
      6. License Options
    21. Index
    22. About the Author
    23. Colophon
    24. SPECIAL OFFER: Upgrade this ebook with O’Reilly

Product information

  • Title: Mercurial: The Definitive Guide
  • Author(s): Bryan O'Sullivan
  • Release date: June 2009
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9780596555474