Distributed revision control with Mercurial

Bryan O’Sullivan

Copyright © 2006, 2007 Bryan O’Sullivan.
This material may be distributed only subject to the terms and conditions set forth in version 1.0 of the Open Publication License. Please refer to Appendix D for the license text.
This book was prepared from rev 028543f67bea, dated 2008-08-20 15:27 -0700, using rev a58a611c320f of Mercurial.
List of Figures
 0.1 This book is a work in progress
 0.2 About the examples in this book
 0.3 Colophon—this book is Free
1 Introduction
 1.1 About revision control
 1.2 A short history of revision control
 1.3 Trends in revision control
 1.4 A few of the advantages of distributed revision control
 1.5 Why choose Mercurial?
 1.6 Mercurial compared with other tools
 1.7 Switching from another tool to Mercurial
2 A tour of Mercurial: the basics
 2.1 Installing Mercurial on your system
 2.2 Getting started
 2.3 Working with a repository
 2.4 A tour through history
 2.5 All about command options
 2.6 Making and reviewing changes
 2.7 Recording changes in a new changeset
 2.8 Sharing changes
3 A tour of Mercurial: merging work
 3.1 Merging streams of work
 3.2 Merging conflicting changes
 3.3 Simplifying the pull-merge-commit sequence
4 Behind the scenes
 4.1 Mercurial’s historical record
 4.2 Safe, efficient storage
 4.3 Revision history, branching, and merging
 4.4 The working directory
 4.5 Other interesting design features
5 Mercurial in daily use
 5.1 Telling Mercurial which files to track
 5.2 How to stop tracking a file
 5.3 Copying files
 5.4 Renaming files
 5.5 Recovering from mistakes
6 Collaborating with other people
 6.1 Mercurial’s web interface
 6.2 Collaboration models
 6.3 The technical side of sharing
 6.4 Informal sharing with “hg serve
 6.5 Using the Secure Shell (ssh) protocol
 6.6 Serving over HTTP using CGI
7 File names and pattern matching
 7.1 Simple file naming
 7.2 Running commands without any file names
 7.3 Telling you what’s going on
 7.4 Using patterns to identify files
 7.5 Filtering files
 7.6 Ignoring unwanted files and directories
 7.7 Case sensitivity
8 Managing releases and branchy development
 8.1 Giving a persistent name to a revision
 8.2 The flow of changes—big picture vs. little
 8.3 Managing big-picture branches in repositories
 8.4 Don’t repeat yourself: merging across branches
 8.5 Naming branches within one repository
 8.6 Dealing with multiple named branches in a repository
 8.7 Branch names and merging
 8.8 Branch naming is generally useful
9 Finding and fixing your mistakes
 9.1 Erasing local history
 9.2 Reverting the mistaken change
 9.3 Dealing with committed changes
 9.4 Changes that should never have been
 9.5 Finding the source of a bug
 9.6 Tips for finding bugs effectively
10 Handling repository events with hooks
 10.1 An overview of hooks in Mercurial
 10.2 Hooks and security
 10.3 Care with pretxn hooks in a shared-access repository
 10.4 A short tutorial on using hooks
 10.5 Writing your own hooks
 10.6 Some hook examples
 10.7 Bundled hooks
 10.8 Information for writers of hooks
 10.9 Hook reference
11 Customising the output of Mercurial
 .1Using precanned output styles
 .2Commands that support styles and templates
 .3The basics of templating
 .4Common template keywords
 .5Escape sequences
 .6Filtering keywords to change their results
 .7From templates to styles
 .8Style files by example
12 Managing change with Mercurial Queues
 12.1 The patch management problem
 12.2 The prehistory of Mercurial Queues
 12.3 The huge advantage of MQ
 12.4 Understanding patches
 12.5 Getting started with Mercurial Queues
 12.6 More about patches
 12.7 Getting the best performance out of MQ
 12.8 Updating your patches when the underlying code changes
 12.9 Identifying patches
 12.10 Useful things to know about
 12.11 Managing patches in a repository
 12.12 Third party tools for working with patches
 12.13 Good ways to work with patches
 12.14 MQ cookbook
 12.15 Differences between quilt and MQ
13 Advanced uses of Mercurial Queues
 13.1 The problem of many targets
 13.2 Conditionally applying patches with guards
 13.3 Controlling the guards on a patch
 13.4 Selecting the guards to use
 13.5 MQ’s rules for applying patches
 13.6 Trimming the work environment
 13.7 Dividing up the series file
 13.8 Maintaining the patch series
 13.9 Useful tips for developing with MQ
14 Adding functionality with extensions
 14.1 Improve performance with the inotify extension
 14.2 Flexible diff support with the extdiff extension
 14.3 Cherrypicking changes with the transplant extension
 14.4 Send changes via email with the patchbomb extension
A Command reference
 A.1 hg add”—add files at the next commit
 A.2 hg diff”—print changes in history or working directory
 A.3 hg version”—print version and copyright information
B Mercurial Queues reference
 B.1 MQ command reference
 B.2 MQ file reference
C Installing Mercurial from source
 C.1 On a Unix-like system
 C.2 On Windows
D Open Publication License
 D.1 Requirements on both unmodified and modified versions
 D.2 Copyright
 D.3 Scope of license
 D.4 Requirements on modified works
 D.5 Good-practice recommendations
 D.6 License options