annotate en/tour.tex @ 88:d351032c189c

Progress with log coverage.

\chapter{A lightning tour of Mercurial}
\label{chap:tour}

\section{Installing Mercurial on your system}
\label{sec:tour:install}

Prebuilt binary packages of Mercurial are available for every popular
operating system.  These make it easy to start using Mercurial on your
computer immediately.

\subsection{Linux}

Because each Linux distribution has its own packaging tools, policies,
and rate of development, it's difficult to give a comprehensive set of
instructions on how to install Mercurial binaries.  The version of
Mercurial that you will end up with can vary depending on how active
the person is who maintains the package for your distribution.

To keep things simple, I will focus on installing Mercurial from the
command line under the most popular Linux distributions.  Most of
these distributions provide graphical package managers that will let
you install Mercurial with a single click; the package name to look
for is \texttt{mercurial}.

\begin{itemize}
\item[Debian]
  \begin{codesample4}
    apt-get install mercurial
  \end{codesample4}

\item[Fedora Core]
  \begin{codesample4}
    yum install mercurial
  \end{codesample4}

\item[Gentoo]
  \begin{codesample4}
    emerge mercurial
  \end{codesample4}

\item[OpenSUSE]
  \begin{codesample4}
    yum install mercurial
  \end{codesample4}

\item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
  should not use it.  If you know how, you can rebuild and install the
  Debian package.  It's probably easier to build Mercurial from source
  and simply run that; see section~\ref{sec:srcinstall:unixlike} for
  details.
\end{itemize}

\subsection{Mac OS X}

Lee Cantey publishes an installer of Mercurial for Mac OS~X at
\url{http://mercurial.berkwood.com}.  This package works on both
Intel-~and Power-based Macs.  Before you can use it, you must install
a compatible version of Universal MacPython~\cite{web:macpython}.  This
is easy to do; simply follow the instructions on Lee's site.

\subsection{Solaris}

XXX.

\subsection{Windows}

Lee Cantey publishes an installer of Mercurial for Windows at
\url{http://mercurial.berkwood.com}.  This package has no external
dependencies; it ``just works''.

\begin{note}
  The Windows version of Mercurial does not automatically convert line
  endings between Windows and Unix styles.  If you want to share work
  with Unix users, you must do a little additional configuration
  work. XXX Flesh this out.
\end{note}

\section{Getting started}

To begin, we'll use the \hgcmd{version} command to find out whether
Mercurial is actually installed properly.  The actual version
information that it prints isn't so important; it's whether it prints
anything at all that we care about.
\interaction{tour.version}

\subsection{Built-in help}

Mercurial provides a built-in help system.  This invaluable for those
times when you find yourself stuck trying to remember how to run a
command.  If you are completely stuck, simply run \hgcmd{help}; it
will print a brief list of commands, along with a description of what
each does.  If you ask for help on a specific command (as below), it
prints more detailed information.
\interaction{tour.help}
For a more impressive level of detail (which you won't usually need)
run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
for \hggopt{--verbose}, and tells Mercurial to print more information
than it usually would.

\section{Working with a repository}

In Mercurial, everything happens inside a \emph{repository}.  The
repository for a project contains all of the files that ``belong to''
that project, along with a historical record of the project's files.

There's nothing particularly magical about a repository; it is simply
a directory tree in your filesystem that Mercurial treats as special.
You can rename delete a repository any time you like, using either the
command line or your file browser.

\subsection{Making a local copy of a repository}

\emph{Copying} a repository is just a little bit special.  While you
could use a normal file copying command to make a copy of a
repository, it's best to use a built-in command that Mercurial
provides.  This command is called \hgcmd{clone}, because it creates an
identical copy of an existing repository.
\interaction{tour.clone}
If our clone succeeded, we should now have a local directory called
\dirname{hello}.  This directory will contain some files.
\interaction{tour.ls}
These files have the same contents and history in our repository as
they do in the repository we cloned.

Every Mercurial repository is complete, self-contained, and
independent.  It contains its own private copy of a project's files
and history.  A cloned repository remembers the location of the
repository it was cloned from, but it does not communicate with that
repository, or any other, unless you tell it to.

What this means for now is that we're free to experiment with our
repository, safe in the knowledge that it's a private ``sandbox'' that
won't affect anyone else.

\subsection{What's in a repository?}

When we take a more detailed look inside a repository, we can see that
it contains a directory named \dirname{.hg}.  This is where Mercurial
keeps all of its metadata for the repository.
\interaction{tour.ls-a}

The contents of the \dirname{.hg} directory and its subdirectories are
private to Mercurial.  Every other file and directory in the
repository is yours to do with as you please.

To introduce a little terminology, the \dirname{.hg} directory is the
``real'' repository, and all of the files and directories that coexist
with it are said to live in the ``working directory''.  An easy way to
remember the distinction is that the \emph{repository} contains the
\emph{history} of your project, while the \emph{working directory}
contains a \emph{snapshot} of your project at a particular point in
history.

\section{A tour through history}

One of the first things we might want to do with a new, unfamiliar
repository is understand its history.  The \hgcmd{log} command gives
us a view of history.
\interaction{tour.log}
By default, this command prints a brief paragraph of output for each
change to the project that was recorded.  In Mercurial terminology, we
call each of these recorded events a \emph{changeset}, because it can
contain a record of changes to several files.

The fields in a record of output from \hgcmd{log} are as follows.
\begin{itemize}
\item[\texttt{changeset}] This field has the format of a number,
  followed by a colon, followed by a hexadecimal string.  These are
  \emph{identifiers} for the changeset.  There are two identifiers
  because the number is shorter and easier to type than the hex
  string.
\item[\texttt{user}] The identity of the person who created the
  changeset.  This is a free-form field, but it most often contains a
  person's name and email address.
\item[\texttt{date}] The date and time on which the changeset was
  created, and the timezone in which it was created.  (Thef date and
  time are local to that timezone; they display what time and date it
  was for the person who created the changeset.)
\item[\texttt{summary}] The first line of the text message that the
  creator of the changeset entered to describe the changeset.
\end{itemize}
The default output printed by \hgcmd{log} is purely a summary; it is
missing a lot of detail.

\subsection{Changesets, revisions, and identification}

English being a notoriously sloppy language, we have a variety of
terms that have the same meaning.  If you are talking about Mercurial
history with other people, you will find that the word ``changeset''
is often compressed to ``change'' or ``cset'', and sometimes a
changeset is referred to as a ``revision'' or a ``rev''.

While it doesn't matter what \emph{word} you use to refer to the
concept of ``a~changeset'', the \emph{identifier} that you use to
refer to ``a~\emph{specific} changeset'' is of great importance.
Recall that the \texttt{changeset} field in the output from
\hgcmd{log} identifies a changeset using both a number and a
hexadecimal string.  The number is \emph{only valid in that
  repository}, while the hex string is the \emph{permanent, unchanging
  identifier} that will always identify that changeset in every copy
of the repository.

This distinction is important.  If you send someone an email talking
about ``revision~33'', there's a high likelihood that their
revision~33 will \emph{not be the same} as yours.  The reason for this
is that a revision number depends on the order in which changes
arrived in a repository, and there is no guarantee that the same
changes will happen in the same order in different repositories.
Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
while in another as $1,0,2$.

Mercurial uses revision numbers purely as a convenient shorthand.  If
you need to discuss a changeset with someone, or make a record of a
changeset for some other reason (for example, in a bug report), use
the hexadecimal identifier.

\subsection{Viewing specific revisions}

To narrow the output of \hgcmd{log} down to a single revision, use the
\hgopt{log}{-r} option.  You can use either a revision number or a
long-form changeset identifier, and you can provide as many revisions
as you want.
\interaction{tour.log-r}

If you want to see the history of several revisions without having to
list each one, you can use \emph{range notation}; this lets you
express the idea ``I want all revisions between $a$ and $b$,
inclusive''.
\interaction{tour.log.range}
Mercurial also honours the order in which you specify revisions, so
\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
prints $4,3,2$.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: