Mercurial > hgbook
view en/tour.tex @ 88:d351032c189c
Progress with log coverage.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu, 12 Oct 2006 10:33:03 -0700 |
parents | 0995016342f8 |
children | 7524d52d9577 |
line wrap: on
line source
\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: