1.1 --- a/en/intro.tex	Mon May 14 15:22:32 2007 -0700
     1.2 +++ b/en/intro.tex	Sat May 26 12:04:52 2007 -0700
     1.3 @@ -320,6 +320,157 @@
     1.4  
     1.5  \section{Why choose Mercurial?}
     1.6  
     1.7 +Mercurial has a unique set of properties that make it a particularly
     1.8 +good choice as a revision control system.
     1.9 +\begin{itemize}
    1.10 +\item It is easy to learn and use.
    1.11 +\item It is lightweight.
    1.12 +\item It scales excellently.
    1.13 +\item It is easy to customise.
    1.14 +\end{itemize}
    1.15 +
    1.16 +If you are at all familiar with revision control systems, you should
    1.17 +be able to get up and running with Mercurial in less than five
    1.18 +minutes.  Even if not, it will take no more than a few minutes
    1.19 +longer.  Mercurial's command and feature sets are generally uniform
    1.20 +and consistent, so you can keep track of a few general rules instead
    1.21 +of a host of exceptions.
    1.22 +
    1.23 +On a small project, you can start working with Mercurial in moments.
    1.24 +Creating new changes and branches; transferring changes around
    1.25 +(whether locally or over a network); and history and status operations
    1.26 +are all fast.  Mercurial attempts to stay nimble and largely out of
    1.27 +your way by combining low cognitive overhead with blazingly fast
    1.28 +operations.
    1.29 +
    1.30 +The usefulness of Mercurial is not limited to small projects: it is
    1.31 +used by projects with hundreds to thousands of contributors, each
    1.32 +containing tens of thousands of files and hundreds of megabytes of
    1.33 +source code.
    1.34 +
    1.35 +If the core functionality of Mercurial is not enough for you, it's
    1.36 +easy to build on.  Mercurial is well suited to scripting tasks, and
    1.37 +its clean internals and implementation in Python make it easy to add
    1.38 +features in the form of extensions.  There are a number of popular and
    1.39 +useful extensions already available, ranging from helping to identify
    1.40 +bugs to improving performance.
    1.41 +
    1.42 +\section{Mercurial compared with other tools}
    1.43 +
    1.44 +Before you read on, please understand that this section necessarily
    1.45 +reflects my own experiences, interests, and (dare I say it) biases.  I
    1.46 +have used every one of the revision control tools listed below, in
    1.47 +most cases for several years at a time.
    1.48 +
    1.49 +\subsection{Subversion}
    1.50 +
    1.51 +Subversion is a popular revision control tool, developed to replace
    1.52 +CVS.  It has a centralised client/server architecture.
    1.53 +
    1.54 +Subversion and Mercurial have similarly named commands for performing
    1.55 +the same operations, so it is easy for a person who is familiar with
    1.56 +one to learn to use the other.  Both tools are portable to all popular
    1.57 +operating systems.
    1.58 +
    1.59 +Mercurial has a substantial performance advantage over Subversion on
    1.60 +every revision control operation I have benchmarked.  I have measured
    1.61 +its advantage as ranging from a factor of two to a factor of six when
    1.62 +compared with Subversion~1.4.3's \emph{ra\_local} file store, which is
    1.63 +the fastest access method available).  In more realistic deployments
    1.64 +involving a network-based store, Subversion will be at a substantially
    1.65 +larger disadvantage.
    1.66 +
    1.67 +Additionally, Subversion incurs a substantial storage overhead to
    1.68 +avoid network transactions for a few common operations, such as
    1.69 +finding modified files (\texttt{status}) and displaying modifications
    1.70 +against the current revision (\texttt{diff}).  A Subversion working
    1.71 +copy is, as a result, often approximately the same size as, or larger
    1.72 +than, a Mercurial repository and working directory, even though the
    1.73 +Mercurial repository contains a complete history of the project.
    1.74 +
    1.75 +Subversion does not have a history-aware merge capability, forcing its
    1.76 +users to know exactly which revisions to merge between branches.  This
    1.77 +shortcoming is scheduled to be addressed in version 1.5.
    1.78 +
    1.79 +Subversion is currently more widely supported by
    1.80 +revision-control-aware third party tools than is Mercurial, although
    1.81 +this gap is closing.  Like Mercurial, Subversion has an excellent user
    1.82 +manual.
    1.83 +
    1.84 +Several tools exist to accurately and completely import revision
    1.85 +history from a Subversion repository into a Mercurial repository,
    1.86 +making the transition from the older tool relatively painless.
    1.87 +
    1.88 +\subsection{Git}
    1.89 +
    1.90 +Git is a distributed revision control tool that was developed for
    1.91 +managing the Linux kernel source tree.  Like Mercurial, its early
    1.92 +design was somewhat influenced by Monotone.
    1.93 +
    1.94 +Git has an overwhelming command set, with version~1.5.0 providing~139
    1.95 +individual commands.  It has a reputation for being difficult to
    1.96 +learn.  It does not have a user manual, only documentation for
    1.97 +individual commands.
    1.98 +
    1.99 +In terms of performance, git is extremely fast.  There are several
   1.100 +common cases in which it is faster than Mercurial, at least on Linux.
   1.101 +However, its performance on (and general support for) Windows is, at
   1.102 +the time of writing, far behind that of Mercurial.
   1.103 +
   1.104 +While a Mercurial repository needs no maintenance, a Git repository
   1.105 +requires frequent manual ``repacks'' of its metadata.  Without these,
   1.106 +performance degrades, while space usage grows rapidly.  A server that
   1.107 +contains many Git repositories that are not rigorously and frequently
   1.108 +repacked will become heavily disk-bound during backups, and there have
   1.109 +been instances of daily backups taking far longer than~24 hours as a
   1.110 +result.  A freshly packed Git repository is slightly smaller than a
   1.111 +Mercurial repository, but an unpacked repository is several orders of
   1.112 +magnitude larger.
   1.113 +
   1.114 +The core of Git is written in C.  Many Git commands are implemented as
   1.115 +shell or Perl scripts, and the quality of these scripts varies widely.
   1.116 +I have encountered a number of instances where scripts charged along
   1.117 +blindly in the presence of errors that should have been fatal.
   1.118 +
   1.119 +\subsection{CVS}
   1.120 +
   1.121 +CVS is probably the most widely used revision control tool in the
   1.122 +world.  Due to its age and internal untidiness, it has been
   1.123 +essentially unmaintained for many years.
   1.124 +
   1.125 +It has a centralised client/server architecture.  It does not group
   1.126 +related file changes into atomic commits, making it easy for people to
   1.127 +``break the build''.  It has a muddled and incoherent notion of tags
   1.128 +and branches that I will not attempt to even describe.  It does not
   1.129 +support renaming of files or directories well, making it easy to
   1.130 +corrupt a repository.  It has almost no internal consistency checking
   1.131 +capabilities, so it is usually not even possible to tell whether or
   1.132 +how a repository is corrupt.  I would not recommend CVS for any
   1.133 +project, existing or new.
   1.134 +
   1.135 +Mercurial can import CVS revision history.  However, there are a few
   1.136 +caveats that apply; these are true of every other revision control
   1.137 +tool's CVS importer, too.  Due to CVS's lack of atomic changes and
   1.138 +unversioned filesystem hierarchy, it is not possible to reconstruct
   1.139 +CVS history completely accurately; some guesswork is involved, and
   1.140 +renames will usually not show up.  Because a lot of advanced CVS
   1.141 +administration has to be done by hand and is hence error-prone, it's
   1.142 +common for CVS importers to run into multiple problems with corrupted
   1.143 +repositories (completely bogus revision timestamps and files that have
   1.144 +remained locked for over a decade are just two of the less interesting
   1.145 +problems I can recall from personal experience).
   1.146 +
   1.147 +\subsection{Commercial tools}
   1.148 +
   1.149 +Perforce has a centralised client/server architecture, with no
   1.150 +client-side caching of any data.  Unlike modern revision control
   1.151 +tools, Perforce requires that a user run a command to inform the
   1.152 +server about every file they intend to edit.
   1.153 +
   1.154 +The performance of Perforce is quite good for small teams, but it
   1.155 +falls off rapidly as the number of users grows beyond a few dozen.
   1.156 +Modestly large Perforce installations require the deployment of
   1.157 +proxies to cope with the load their users generate.
   1.158  
   1.159  %%% Local Variables: 
   1.160  %%% mode: latex