
bos@84: \chapter{A lightning tour of Mercurial}
bos@84: \label{chap:tour}
bos@84: 
bos@84: \section{Installing Mercurial on your system}
bos@84: \label{sec:tour:install}
bos@84: 
bos@85: Prebuilt binary packages of Mercurial are available for every popular
bos@85: operating system.  These make it easy to start using Mercurial on your
bos@85: computer immediately.
bos@85: 
bos@84: \subsection{Linux}
bos@84: 
bos@84: Because each Linux distribution has its own packaging tools, policies,
bos@84: and rate of development, it's difficult to give a comprehensive set of
bos@85: instructions on how to install Mercurial binaries.  The version of
bos@85: Mercurial that you will end up with can vary depending on how active
bos@85: the person is who maintains the package for your distribution.
bos@84: 
bos@84: To keep things simple, I will focus on installing Mercurial from the
bos@84: command line under the most popular Linux distributions.  Most of
bos@84: these distributions provide graphical package managers that will let
bos@84: you install Mercurial with a single click; the package name to look
bos@84: for is \texttt{mercurial}.
bos@84: 
bos@85: \begin{itemize}
bos@85: \item[Debian]
bos@85:   \begin{codesample4}
bos@85:     apt-get install mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[Fedora Core]
bos@85:   \begin{codesample4}
bos@85:     yum install mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[Gentoo]
bos@85:   \begin{codesample4}
bos@85:     emerge mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[OpenSUSE]
bos@85:   \begin{codesample4}
bos@85:     yum install mercurial
bos@85:   \end{codesample4}
bos@84: 
bos@85: \item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
bos@85:   should not use it.  If you know how, you can rebuild and install the
bos@85:   Debian package.  It's probably easier to build Mercurial from source
bos@85:   and simply run that; see section~\ref{sec:srcinstall:unixlike} for
bos@85:   details.
bos@85: \end{itemize}
bos@84: 
bos@84: \subsection{Mac OS X}
bos@84: 
bos@84: Lee Cantey publishes an installer of Mercurial for Mac OS~X at
bos@84: \url{http://mercurial.berkwood.com}.  This package works on both
bos@85: Intel-~and Power-based Macs.  Before you can use it, you must install
bos@85: a compatible version of Universal MacPython~\cite{web:macpython}.  This
bos@85: is easy to do; simply follow the instructions on Lee's site.
bos@84: 
bos@84: \subsection{Solaris}
bos@84: 
bos@84: XXX.
bos@84: 
bos@84: \subsection{Windows}
bos@84: 
bos@84: Lee Cantey publishes an installer of Mercurial for Windows at
bos@84: \url{http://mercurial.berkwood.com}.  This package has no external
bos@84: dependencies; it ``just works''.
bos@84: 
bos@84: \begin{note}
bos@84:   The Windows version of Mercurial does not automatically convert line
bos@84:   endings between Windows and Unix styles.  If you want to share work
bos@84:   with Unix users, you must do a little additional configuration
bos@84:   work. XXX Flesh this out.
bos@84: \end{note}
bos@84: 
bos@87: \section{Getting started}
bos@87: 
bos@87: To begin, we'll use the \hgcmd{version} command to find out whether
bos@87: Mercurial is actually installed properly.  The actual version
bos@87: information that it prints isn't so important; it's whether it prints
bos@87: anything at all that we care about.
bos@87: \interaction{tour.version}
bos@87: 
bos@87: \subsection{Built-in help}
bos@87: 
bos@87: Mercurial provides a built-in help system.  This invaluable for those
bos@87: times when you find yourself stuck trying to remember how to run a
bos@87: command.  If you are completely stuck, simply run \hgcmd{help}; it
bos@87: will print a brief list of commands, along with a description of what
bos@87: each does.  If you ask for help on a specific command (as below), it
bos@87: prints more detailed information.
bos@87: \interaction{tour.help}
bos@87: For a more impressive level of detail (which you won't usually need)
bos@87: run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
bos@87: for \hggopt{--verbose}, and tells Mercurial to print more information
bos@87: than it usually would.
bos@87: 
bos@87: \section{Working with a repository}
bos@87: 
bos@87: In Mercurial, everything happens inside a \emph{repository}.  The
bos@87: repository for a project contains all of the files that ``belong to''
bos@87: that project, along with a historical record of the project's files.
bos@87: 
bos@87: There's nothing particularly magical about a repository; it is simply
bos@87: a directory tree in your filesystem that Mercurial treats as special.
bos@87: You can rename delete a repository any time you like, using either the
bos@87: command line or your file browser.
bos@87: 
bos@87: \subsection{Making a copy of a repository}
bos@87: 
bos@87: \emph{Copying} a repository is just a little bit special.  While you
bos@87: could use a normal file copying command to make a copy of a
bos@87: repository, it's best to use a built-in command that Mercurial
bos@87: provides.  This command is called \hgcmd{clone}, because it creates an
bos@87: identical copy of an existing repository.
bos@87: \interaction{tour.clone}
bos@87: If our clone succeeded, we should now have a local directory called
bos@87: \dirname{hello}.  This directory will contain some files.
bos@87: \interaction{tour.ls}
bos@87: These files have the same contents and history in our repository as
bos@87: they do in the repository we cloned.
bos@87: 
bos@87: Every Mercurial repository is complete, self-contained, and
bos@87: independent.  It contains its own private copy of a project's files
bos@87: and history.  A cloned repository remembers the location of the
bos@87: repository it was cloned from, but it does not communicate with that
bos@87: repository, or any other, unless you tell it to.
bos@87: 
bos@87: What this means for now is that we're free to experiment with our
bos@87: repository, safe in the knowledge that it's a private ``sandbox'' that
bos@87: won't affect anyone else.
bos@85: 
bos@84: %%% Local Variables: 
bos@84: %%% mode: latex
bos@84: %%% TeX-master: "00book"
bos@84: %%% End: 




