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@88: \subsection{Making a local 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@88: \subsection{What's in a repository?} bos@88: bos@88: When we take a more detailed look inside a repository, we can see that bos@88: it contains a directory named \dirname{.hg}. This is where Mercurial bos@88: keeps all of its metadata for the repository. bos@88: \interaction{tour.ls-a} bos@88: bos@88: The contents of the \dirname{.hg} directory and its subdirectories are bos@88: private to Mercurial. Every other file and directory in the bos@88: repository is yours to do with as you please. bos@88: bos@88: To introduce a little terminology, the \dirname{.hg} directory is the bos@88: ``real'' repository, and all of the files and directories that coexist bos@88: with it are said to live in the ``working directory''. An easy way to bos@88: remember the distinction is that the \emph{repository} contains the bos@88: \emph{history} of your project, while the \emph{working directory} bos@88: contains a \emph{snapshot} of your project at a particular point in bos@88: history. bos@88: bos@88: \section{A tour through history} bos@88: bos@88: One of the first things we might want to do with a new, unfamiliar bos@88: repository is understand its history. The \hgcmd{log} command gives bos@88: us a view of history. bos@88: \interaction{tour.log} bos@88: By default, this command prints a brief paragraph of output for each bos@88: change to the project that was recorded. In Mercurial terminology, we bos@88: call each of these recorded events a \emph{changeset}, because it can bos@88: contain a record of changes to several files. bos@88: bos@88: The fields in a record of output from \hgcmd{log} are as follows. bos@88: \begin{itemize} bos@88: \item[\texttt{changeset}] This field has the format of a number, bos@88: followed by a colon, followed by a hexadecimal string. These are bos@88: \emph{identifiers} for the changeset. There are two identifiers bos@88: because the number is shorter and easier to type than the hex bos@88: string. bos@88: \item[\texttt{user}] The identity of the person who created the bos@88: changeset. This is a free-form field, but it most often contains a bos@88: person's name and email address. bos@88: \item[\texttt{date}] The date and time on which the changeset was bos@88: created, and the timezone in which it was created. (Thef date and bos@88: time are local to that timezone; they display what time and date it bos@88: was for the person who created the changeset.) bos@88: \item[\texttt{summary}] The first line of the text message that the bos@88: creator of the changeset entered to describe the changeset. bos@88: \end{itemize} bos@88: The default output printed by \hgcmd{log} is purely a summary; it is bos@88: missing a lot of detail. bos@88: bos@88: \subsection{Changesets, revisions, and identification} bos@88: bos@88: English being a notoriously sloppy language, we have a variety of bos@88: terms that have the same meaning. If you are talking about Mercurial bos@88: history with other people, you will find that the word ``changeset'' bos@88: is often compressed to ``change'' or ``cset'', and sometimes a bos@88: changeset is referred to as a ``revision'' or a ``rev''. bos@88: bos@88: While it doesn't matter what \emph{word} you use to refer to the bos@88: concept of ``a~changeset'', the \emph{identifier} that you use to bos@88: refer to ``a~\emph{specific} changeset'' is of great importance. bos@88: Recall that the \texttt{changeset} field in the output from bos@88: \hgcmd{log} identifies a changeset using both a number and a bos@88: hexadecimal string. The number is \emph{only valid in that bos@88: repository}, while the hex string is the \emph{permanent, unchanging bos@88: identifier} that will always identify that changeset in every copy bos@88: of the repository. bos@88: bos@88: This distinction is important. If you send someone an email talking bos@88: about ``revision~33'', there's a high likelihood that their bos@88: revision~33 will \emph{not be the same} as yours. The reason for this bos@88: is that a revision number depends on the order in which changes bos@88: arrived in a repository, and there is no guarantee that the same bos@88: changes will happen in the same order in different repositories. bos@88: Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, bos@88: while in another as $1,0,2$. bos@88: bos@88: Mercurial uses revision numbers purely as a convenient shorthand. If bos@88: you need to discuss a changeset with someone, or make a record of a bos@88: changeset for some other reason (for example, in a bug report), use bos@88: the hexadecimal identifier. bos@88: bos@88: \subsection{Viewing specific revisions} bos@88: bos@88: To narrow the output of \hgcmd{log} down to a single revision, use the bos@88: \hgopt{log}{-r} option. You can use either a revision number or a bos@88: long-form changeset identifier, and you can provide as many revisions bos@88: as you want. bos@88: \interaction{tour.log-r} bos@88: bos@88: If you want to see the history of several revisions without having to bos@88: list each one, you can use \emph{range notation}; this lets you bos@88: express the idea ``I want all revisions between $a$ and $b$, bos@88: inclusive''. bos@88: \interaction{tour.log.range} bos@88: Mercurial also honours the order in which you specify revisions, so bos@88: \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} bos@88: prints $4,3,2$. bos@88: bos@84: %%% Local Variables: bos@84: %%% mode: latex bos@84: %%% TeX-master: "00book" bos@84: %%% End: