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: