Mercurial · The Definitive Guide by O'Sullivan, Bryan -- Read -- Imperial Library of Trantor

Index

Mercurial: The Definitive Guide

Preface

Technical Storytelling Thank You for Supporting Mercurial Conventions Used in This Book Using Code Examples Safari® Books Online How to Contact Us This Book Is Free Acknowledgments

1. A Brief History of Revision Control

Why Revision Control? Why Mercurial?

Why Use Revision Control? The Many Names of Revision Control

This Book Is a Work in Progress About the Examples in This Book Trends in the Field A Few Advantages of Distributed Revision Control

Advantages for Open Source Projects

The forking non-problem

Advantages for Commercial Projects

Why Choose Mercurial? Mercurial Compared with Other Tools

Subversion Git CVS Commercial Tools Choosing a Revision Control Tool

Switching from Another Tool to Mercurial A Short History of Revision Control

2. A Tour of Mercurial: The Basics

Installing Mercurial on Your System

Windows Mac OS X Linux Solaris

Getting Started

Built-In Help

Working with a Repository

Making a Local Copy of a Repository What’s in a Repository?

A Tour Through History

Changesets, Revisions, and Talking to Other People Viewing Specific Revisions More Detailed Information

All About Command Options Making and Reviewing Changes Recording Changes in a New Changeset

Setting Up a Username

Creating a Mercurial configuration file Choosing a username

Writing a Commit Message Writing a Good Commit Message Aborting a Commit Admiring Our New Handiwork

Sharing Changes

Pulling Changes from Another Repository Updating the Working Directory Pushing Changes to Another Repository Default Locations Sharing Changes over a Network

Starting a New Project

3. A Tour of Mercurial: Merging Work

Merging Streams of Work

Head Changesets Performing the Merge Committing the Results of the Merge

Merging Conflicting Changes

Using a Graphical Merge Tool A Worked Example

Simplifying the Pull-Merge-Commit Sequence Renaming, Copying, and Merging

4. Behind the Scenes

Mercurial’s Historical Record

Tracking the History of a Single File Managing Tracked Files Recording Changeset Information Relationships Between Revisions

Safe, Efficient Storage

Efficient Storage Safe Operation Fast Retrieval Identification and Strong Integrity

Revision History, Branching, and Merging The Working Directory

What Happens When You Commit Creating a New Head Merging Changes Merging and Renames

Other Interesting Design Features

Clever Compression

Network recompression

Read/Write Ordering and Atomicity Concurrent Access

Safe dirstate access

Avoiding Seeks Other Contents of the Dirstate

5. Mercurial in Daily Use

Telling Mercurial Which Files to Track

Explicit Versus Implicit File Naming Mercurial Tracks Files, Not Directories

How to Stop Tracking a File

Removing a File Does Not Affect Its History Missing Files Useful Shorthand: Adding and Removing Files in One Step

Copying Files

The Results of Copying During a Merge Why Should Changes Follow Copies? How to Make Changes Not Follow a Copy Behavior of the hg copy Command

Renaming Files

Renaming Files and Merging Changes Divergent Renames and Merging Convergent Renames and Merging Other Name-Related Corner Cases

Recovering from Mistakes Dealing with Tricky Merges

File Resolution States Resolving a File Merge

More Useful Diffs Which Files to Manage, and Which to Avoid Backups and Mirroring

6. Collaborating with Other People

Mercurial’s Web Interface Collaboration Models

Factors to Keep in Mind Informal Anarchy A Single Central Repository A Hosted Central Repository Working with Multiple Branches Feature Branches The Release Train The Linux Kernel Model Pull-Only Versus Shared-Push Collaboration Where Collaboration Meets Branch Management

The Technical Side of Sharing Informal Sharing with hg serve

A Few Things to Keep in Mind

Using the Secure Shell Protocol

How to Read and Write ssh URLs Finding an ssh Client for Your System Generating a Key Pair Using an Authentication Agent Configuring the Server Side Properly Using Compression with ssh

Serving Over HTTP Using CGI

Web Server Configuration Checklist Basic CGI Configuration

What could possibly go wrong? Configuring lighttpd

Sharing Multiple Repositories with One CGI Script

Explicitly specifying which repositories to publish

Downloading Source Archives Web Configuration Options

Options specific to an individual repository Options specific to the hg serve command Choosing the right ~/.hgrc file to add web items to

System-Wide Configuration

Making Mercurial More Trusting

7. Filenames and Pattern Matching

Simple File Naming Running Commands Without Any Filenames Telling You What’s Going On Using Patterns to Identify Files

Shell-Style Glob Patterns

Watch out!

Regular Expression Matching with Re Patterns

Filtering Files Permanently Ignoring Unwanted Files and Directories Case Sensitivity

Safe, Portable Repository Storage Detecting Case Conflicts Fixing a Case Conflict

8. Managing Releases and Branchy Development

Giving a Persistent Name to a Revision

Handling Tag Conflicts During a Merge Tags and Cloning When Permanent Tags Are Too Much

The Flow of Changes: Big Picture Versus Little Picture Managing Big-Picture Branches in Repositories Don’t Repeat Yourself: Merging Across Branches Naming Branches Within One Repository Dealing with Multiple Named Branches in a Repository Branch Names and Merging Branch Naming Is Generally Useful

9. Finding and Fixing Mistakes

Erasing Local History

The Accidental Commit Rolling Back a Transaction The Erroneous Pull Rolling Back Is Useless Once You’ve Pushed You Can Only Roll Back Once

Reverting the Mistaken Change

File Management Errors

Dealing with Committed Changes

Backing Out a Changeset Backing Out the Tip Changeset Backing Out a Non-Tip Change

Always use the --merge option

Gaining More Control of the Backout Process Why hg backout Works As It Does

Changes That Should Never Have Been

Backing Out a Merge Protect Yourself from Escaped Changes What to Do About Sensitive Changes That Escape

Finding the Source of a Bug

Using the hg bisect Command Cleaning Up After Your Search

Tips for Finding Bugs Effectively

Give Consistent Input Automate As Much As Possible Check Your Results Beware Interference Between Bugs Bracket Your Search Lazily

10. Handling Repository Events with Hooks

An Overview of Hooks in Mercurial Hooks and Security

Hooks Are Run with Your Privileges Hooks Do Not Propagate Hooks Can Be Overridden Ensuring That Critical Hooks Are Run

A Short Tutorial on Using Hooks

Performing Multiple Actions Per Event Controlling Whether an Activity Can Proceed

Writing Your Own Hooks

Choosing How Your Hook Should Run Hook Parameters Hook Return Values and Activity Control Writing an External Hook Telling Mercurial to Use an In-Process Hook Writing an In-Process Hook

Some Hook Examples

Writing Meaningful Commit Messages Checking for Trailing Whitespace

Bundled Hooks

acl—Access Control for Parts of a Repository

Configuring the acl hook Testing and troubleshooting

bugzilla—Integration with Bugzilla

Configuring the bugzilla hook Mapping committer names to Bugzilla usernames Configuring the text that gets added to a bug Testing and troubleshooting

notify—Send Email Notifications

Configuring the notify hook Testing and troubleshooting

Information for Writers of Hooks

In-Process Hook Execution External Hook Execution Finding Out Where Changesets Come From

Sources of changesets Where changes are going—remote repository URLs

Hook Reference

changegroup—After Remote Changesets Added commit—After a New Changeset Is Created incoming—After One Remote Changeset Is Added outgoing—After Changesets Are Propagated prechangegroup—Before Starting to Add Remote Changesets precommit—Before Starting to Commit a Changeset preoutgoing—Before Starting to Propagate Changesets pretag—Before Tagging a Changeset pretxnchangegroup—Before Completing Addition of Remote Changesets pretxncommit—Before Completing Commit of New Changeset preupdate—Before Updating or Merging Working Directory tag—After Tagging a Changeset update—After Updating or Merging Working Directory

11. Customizing the Output of Mercurial

Using Precanned Output Styles

Setting a Default Style

Commands That Support Styles and Templates The Basics of Templating Common Template Keywords Escape Sequences Filtering Keywords to Change Their Results

Combining Filters

From Templates to Styles

The Simplest of Style Files Style File Syntax

Style Files by Example

Identifying Mistakes in Style Files Uniquely Identifying a Repository Listing Files on Multiple Lines Mimicking Subversion’s Output

12. Managing Changes with Mercurial Queues

The Patch Management Problem The Prehistory of Mercurial Queues

A Patchwork Quilt From Patchwork Quilt to Mercurial Queues

The Huge Advantage of MQ Understanding Patches Getting Started with Mercurial Queues

Creating a New Patch Refreshing a Patch Stacking and Tracking Patches Manipulating the Patch Stack Pushing and Popping Many Patches Safety Checks, and Overriding Them Working on Several Patches at Once

More About Patches

The Strip Count Strategies for Applying a Patch Some Quirks of Patch Representation Beware the Fuzz Handling Rejection

More on Patch Management

Deleting Unwanted Patches Converting to and from Permanent Revisions

Getting the Best Performance Out of MQ Updating Your Patches When the Underlying Code Changes Identifying Patches Useful Things to Know About Managing Patches in a Repository

MQ Support for Patch Repositories A Few Things to Watch Out For

Third-Party Tools for Working with Patches Good Ways to Work with Patches MQ Cookbook

Managing Trivial Patches Combining Entire Patches Merging Part of One Patch into Another

Differences Between Quilt and MQ

13. Advanced Uses of Mercurial Queues

The Problem of Many Targets

Tempting Approaches That Don’t Work Well

Conditionally Applying Patches with Guards Controlling the Guards on a Patch Selecting the Guards to Use MQ’s Rules for Applying Patches Trimming the Work Environment Dividing Up the Series File Maintaining the Patch Series

The Art of Writing Backport Patches

Useful Tips for Developing with MQ

Organizing Patches in Directories Viewing the History of a Patch

14. Adding Functionality with Extensions

Improve Performance with the inotify Extension Flexible Diff Support with the extdiff Extension

Defining Command Aliases

Cherry-Picking Changes with the transplant Extension Sending Changes via Email with the patchbomb Extension

Changing the Behavior of Patchbombs

A. Migrating to Mercurial

Importing History from Another System

Converting Multiple Branches Mapping Usernames Tidying Up the Tree Improving Subversion Conversion Performance

Migrating from Subversion

Philosophical Differences

Scope of commands Multi-user operation and safety Published versus local changes

Quick Reference

Useful Tips for Newcomers

B. Mercurial Queues Reference

MQ Command Reference

qapplied—Print Applied Patches qcommit—Commit Changes in the Queue Repository qdelete—Delete a Patch from the Series File qdiff—Print a Diff of the Topmost Applied Patch qfold—Move Applied Patches into Repository History qfold—Merge (fold) Several Patches into One qheader—Display the Header/Description of a Patch qimport—Import a Third-Party Patch into the Queue qinit—Prepare a Repository to Work with MQ qnew—Create a New Patch qnext—Print the Name of the Next Patch qpop—Pop Patches Off the Stack qprev—Print the Name of the Previous Patch qpush—Push Patches onto the Stack qrefresh—Update the Topmost Applied Patch qrename—Rename a Patch qseries—Print the Entire Patch Series qtop—Print the Name of the Current Patch qunapplied—Print Patches Not yet Applied hg strip—Remove a Revision and Descendants

MQ File Reference

The Series File The Status File

C. Installing Mercurial from Source

On a Unix-Like System On Windows

D. Open Publication License

Requirements on Both Unmodified and Modified Versions Copyright Scope of License Requirements on Modified Works Good-Practice Recommendations License Options

Index About the Author Colophon

← Prev
Back
Next →

← Prev
Back
Next →