Table Of ContentMercurial: The Definitive Guide
Mercurial: The Definitive Guide
Bryan O’Sullivan
Beijing • Cambridge • Farnham • Köln • Sebastopol • Taipei • Tokyo
Mercurial: The Definitive Guide
by Bryan O’Sullivan
Copyright © 2009 Bryan O’Sullivan. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions
are also available for most titles (http://my.safaribooksonline.com). For more information, contact our
corporate/institutional sales department: (800) 998-9938 or [email protected].
Editor: Mike Loukides Indexer: Seth Maislin
Production Editor: Adam Witwer Cover Designer: Karen Montgomery
Proofreader: Emily Quill Interior Designer: David Futato
Illustrator: Robert Romano
Printing History:
June 2009: First Edition.
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of
O’Reilly Media, Inc. The image of a House Martin and related trade dress are trademarks of O’Reilly
Media, Inc.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a
trademark claim, the designations have been printed in caps or initial caps.
This book is licensed under the Open Publication License.
While every precaution has been taken in the preparation of this book, the publisher and author assume
no responsibility for errors or omissions, or for damages resulting from the use of the information con-
tained herein.
ISBN: 978-0-596-80067-3
[M]
1244822988
Table of Contents
Preface ..................................................................... xv
1. A Brief History of Revision Control ......................................... 1
Why Revision Control? Why Mercurial? 1
Why Use Revision Control? 1
The Many Names of Revision Control 2
This Book Is a Work in Progress 3
About the Examples in This Book 3
Trends in the Field 3
A Few Advantages of Distributed Revision Control 4
Advantages for Open Source Projects 5
Advantages for Commercial Projects 6
Why Choose Mercurial? 6
Mercurial Compared with Other Tools 7
Subversion 7
Git 8
CVS 9
Commercial Tools 10
Choosing a Revision Control Tool 10
Switching from Another Tool to Mercurial 10
A Short History of Revision Control 11
2. A Tour of Mercurial: The Basics ........................................... 13
Installing Mercurial on Your System 13
Windows 13
Mac OS X 13
Linux 13
Solaris 14
Getting Started 14
Built-In Help 14
Working with a Repository 15
Making a Local Copy of a Repository 15
v
What’s in a Repository? 16
A Tour Through History 16
Changesets, Revisions, and Talking to Other People 17
Viewing Specific Revisions 18
More Detailed Information 19
All About Command Options 20
Making and Reviewing Changes 21
Recording Changes in a New Changeset 23
Setting Up a Username 23
Writing a Commit Message 24
Writing a Good Commit Message 25
Aborting a Commit 26
Admiring Our New Handiwork 26
Sharing Changes 26
Pulling Changes from Another Repository 26
Updating the Working Directory 28
Pushing Changes to Another Repository 29
Default Locations 30
Sharing Changes over a Network 30
Starting a New Project 31
3. A Tour of Mercurial: Merging Work ........................................ 33
Merging Streams of Work 33
Head Changesets 34
Performing the Merge 35
Committing the Results of the Merge 37
Merging Conflicting Changes 38
Using a Graphical Merge Tool 38
A Worked Example 40
Simplifying the Pull-Merge-Commit Sequence 42
Renaming, Copying, and Merging 43
4. Behind the Scenes ..................................................... 45
Mercurial’s Historical Record 45
Tracking the History of a Single File 45
Managing Tracked Files 46
Recording Changeset Information 46
Relationships Between Revisions 46
Safe, Efficient Storage 47
Efficient Storage 47
Safe Operation 47
Fast Retrieval 48
Identification and Strong Integrity 48
vi | Table of Contents
Revision History, Branching, and Merging 49
The Working Directory 50
What Happens When You Commit 50
Creating a New Head 53
Merging Changes 54
Merging and Renames 56
Other Interesting Design Features 56
Clever Compression 56
Read/Write Ordering and Atomicity 57
Concurrent Access 57
Avoiding Seeks 58
Other Contents of the Dirstate 58
5. Mercurial in Daily Use ................................................... 61
Telling Mercurial Which Files to Track 61
Explicit Versus Implicit File Naming 62
Mercurial Tracks Files, Not Directories 62
How to Stop Tracking a File 63
Removing a File Does Not Affect Its History 63
Missing Files 64
Useful Shorthand: Adding and Removing Files in One Step 64
Copying Files 65
The Results of Copying During a Merge 65
Why Should Changes Follow Copies? 66
How to Make Changes Not Follow a Copy 67
Behavior of the hg copy Command 67
Renaming Files 68
Renaming Files and Merging Changes 69
Divergent Renames and Merging 69
Convergent Renames and Merging 70
Other Name-Related Corner Cases 70
Recovering from Mistakes 71
Dealing with Tricky Merges 71
File Resolution States 73
Resolving a File Merge 73
More Useful Diffs 73
Which Files to Manage, and Which to Avoid 74
Backups and Mirroring 76
6. Collaborating with Other People ......................................... 77
Mercurial’s Web Interface 77
Collaboration Models 78
Factors to Keep in Mind 78
Table of Contents | vii
Informal Anarchy 79
A Single Central Repository 79
A Hosted Central Repository 80
Working with Multiple Branches 80
Feature Branches 82
The Release Train 83
The Linux Kernel Model 83
Pull-Only Versus Shared-Push Collaboration 84
Where Collaboration Meets Branch Management 85
The Technical Side of Sharing 85
Informal Sharing with hg serve 85
A Few Things to Keep in Mind 86
Using the Secure Shell Protocol 86
How to Read and Write ssh URLs 86
Finding an ssh Client for Your System 87
Generating a Key Pair 87
Using an Authentication Agent 88
Configuring the Server Side Properly 88
Using Compression with ssh 90
Serving Over HTTP Using CGI 91
Web Server Configuration Checklist 91
Basic CGI Configuration 92
Sharing Multiple Repositories with One CGI Script 94
Downloading Source Archives 96
Web Configuration Options 96
System-Wide Configuration 98
Making Mercurial More Trusting 99
7. Filenames and Pattern Matching ........................................ 101
Simple File Naming 101
Running Commands Without Any Filenames 101
Telling You What’s Going On 103
Using Patterns to Identify Files 103
Shell-Style Glob Patterns 104
Regular Expression Matching with Re Patterns 105
Filtering Files 105
Permanently Ignoring Unwanted Files and Directories 106
Case Sensitivity 107
Safe, Portable Repository Storage 107
Detecting Case Conflicts 107
Fixing a Case Conflict 108
viii | Table of Contents
