bos@95: \chapter{A tour of Mercurial: the basics} bos@95: \label{chap:tour-basic} 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@91: with it are said to live in the \emph{working directory}. An easy way bos@91: to 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@91: \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a bos@91: revision number or a long-form changeset identifier, and you can bos@91: provide as many revisions as you want. \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@91: \subsection{More detailed information} bos@91: bos@91: While the summary information printed by \hgcmd{log} is useful if you bos@91: already know what you're looking for, you may need to see a complete bos@91: description of the change, or a list of the files changed, if you're bos@91: trying to decide whether a changeset is the one you're looking for. bos@91: The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) bos@91: option gives you this extra detail. bos@91: \interaction{tour.log-v} bos@91: bos@91: If you want to see both the description and content of a change, add bos@91: the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays bos@91: the content of a change as a \emph{unified diff} (if you've never seen bos@91: a unified diff before, see section~\ref{sec:mq:patch} for an overview). bos@91: \interaction{tour.log-vp} bos@91: bos@91: \section{All about command options} bos@91: bos@91: Let's take a brief break from exploring Mercurial commands to discuss bos@91: a pattern in the way that they work; you may find this useful to keep bos@91: in mind as we continiue our tour. bos@91: bos@91: Mercurial has a consistent and straightforward approach to dealing bos@91: with the options that you can pass to commands. It follows the bos@91: conventions for options that are common to modern Linux and Unix bos@91: systems. bos@91: \begin{itemize} bos@91: \item Every option has a long name. For example, as we've already bos@91: seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. bos@91: \item Most options have short names, too. Instead of bos@91: \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that bos@91: some options don't have short names is that the options in question bos@91: are rarely used.) bos@91: \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), bos@91: while short options start with one (e.g.~\hgopt{log}{-r}). bos@91: \item Option naming and usage is consistent across commands. For bos@91: example, every command that lets you specify a changeset~ID or bos@91: revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} bos@91: arguments. bos@91: \end{itemize} bos@91: In the examples throughout this book, I use short options instead of bos@91: long. This just reflects my own preference, so don't read anything bos@91: significant into it. bos@91: bos@91: Most commands that print output of some kind will print more output bos@91: when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less bos@91: when passed \hggopt{-q} (or \hggopt{--quiet}). bos@91: bos@91: \section{Making and reviewing changes} bos@91: bos@91: Now that we have a grasp of viewing history in Mercurial, let's take a bos@91: look at making some changes and examining them. bos@91: bos@91: The first thing we'll do is isolate our experiment in a repository of bos@91: its own. We use the \hgcmd{clone} command, but we don't need to bos@91: clone a copy of the remote repository. Since we already have a copy bos@91: of it locally, we can just clone that instead. This is much faster bos@91: than cloning over the network, and cloning a local repository uses bos@91: less disk space in most cases, too. bos@91: \interaction{tour.reclone} bos@91: As an aside, it's often good practice to keep a ``pristine'' copy of a bos@91: remote repository around, which you can then make temporary clones of bos@91: to create sandboxes for each task you want to work on. This lets you bos@91: work on multiple tasks in parallel, each isolated from the others bos@91: until it's complete and you're ready to integrate it back. Because bos@91: local clones are so cheap, there's almost no overhead to cloning and bos@91: destroying repositories whenever you want. bos@91: bos@91: In our \dirname{my-hello} repository, we have a file bos@91: \filename{hello.c} that contains the classic ``hello, world'' program. bos@91: Let's use the ancient and venerable \command{sed} command to edit this bos@91: file so that it prints a second line of output. (I'm only using bos@91: \command{sed} to do this because it's easy to write a scripted example bos@91: this way. Since you're not under the same constraint, you probably bos@91: won't want to use \command{sed}; simply use your preferred text editor to bos@91: do the same thing.) bos@91: \interaction{tour.sed} bos@91: bos@91: Mercurial's \hgcmd{status} command will tell us what Mercurial knows bos@91: about the files in the repository. bos@91: \interaction{tour.status} bos@91: The \hgcmd{status} command prints no output for some files, but a line bos@91: starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell bos@91: it to, \hgcmd{status} will not print any output for files that have bos@91: not been modified. bos@91: bos@91: The ``\texttt{M}'' indicates that Mercurial has noticed that we bos@91: modified \filename{hello.c}. Notice that we didn't need to bos@91: \emph{inform} Mercurial that we were going to modify the file before bos@91: we started, or that we had modified the file after we were done; it bos@91: was able to figure this out itself. bos@91: bos@91: It's a little bit helpful to know that we've modified bos@91: \filename{hello.c}, but we might prefer to know exactly \emph{what} bos@91: changes we've made to it. To do this, we use the \hgcmd{diff} bos@91: command. bos@91: \interaction{tour.diff} bos@91: bos@91: \section{Recording changes in a new changeset} bos@91: bos@91: We can modify files, build and test our changes, and use bos@91: \hgcmd{status} and \hgcmd{diff} to review our changes, until we're bos@91: satisfied with what we've done and arrive at a natural stopping point bos@91: where we want to record our work in a new changeset. bos@91: bos@91: The \hgcmd{commit} command lets us create a new changeset; we'll bos@91: usually refer to this as ``making a commit'' or ``committing''. bos@91: bos@91: \subsection{Writing a commit message} bos@91: bos@91: When we commit a change, Mercurial drops us into a text editor, to bos@91: enter a message that will describe the modifications we've made in bos@91: this changeset. This is called the \emph{commit message}. It will be bos@91: a record for readers of what we did and why, and it will be printed by bos@91: \hgcmd{log} after we've finished committing. bos@91: \interaction{tour.commit} bos@91: bos@91: The editor that the \hgcmd{commit} command drops us into will contain bos@91: an empty line, followed by a number of lines starting with bos@91: ``\texttt{HG:}''. bos@91: \begin{codesample2} bos@91: \emph{empty line} bos@91: HG: changed hello.c bos@91: \end{codesample2} bos@91: Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses bos@91: them only to tell us which files it's recording changes to. Modifying bos@91: or deleting these lines has no effect. bos@91: bos@91: \subsection{Writing a good commit message} bos@91: bos@91: Since \hgcmd{log} only prints the first line of a commit message by bos@91: default, it's best to write a commit message whose first line stands bos@91: alone. Here's a real example of a commit message that \emph{doesn't} bos@91: follow this guideline, and hence has a summary that is not readable. bos@91: \begin{codesample2} bos@91: changeset: 73:584af0e231be bos@91: user: Censored Person bos@91: date: Tue Sep 26 21:37:07 2006 -0700 bos@91: summary: include buildmeister/commondefs. Add an exports and install bos@91: \end{codesample2} bos@91: bos@91: As far as the remainder of the contents of the commit message are bos@91: concerned, there are no hard-and-fast rules. Mercurial itself doesn't bos@91: interpret or care about the contents of the commit message, though bos@91: your project may have policies that dictate a certain kind of bos@91: formatting. bos@91: bos@91: My personal preference is for short, but informative, commit messages bos@91: that tell me something that I can't figure out with a quick glance at bos@91: the output of \hgcmdargs{log}{--patch}. bos@91: bos@91: \subsection{Aborting a commit} bos@91: bos@91: If you decide that you don't want to commit while in the middle of bos@91: editing a commit message, simply exit from your editor without saving bos@91: the file that it's editing. This will cause nothing to happen to bos@91: either the repository or the working directory. bos@91: bos@91: If we run the \hgcmd{commit} command without any arguments, it records bos@91: all of the changes we've made, as reported by \hgcmd{status} and bos@91: \hgcmd{diff}. bos@91: bos@91: \subsection{Admiring our new handywork} bos@91: bos@91: Once we've finished the commit, we can use the \hgcmd{tip} command to bos@91: display the changeset we just created. This command produces output bos@91: that is identical to \hgcmd{log}, but it only displays the newest bos@91: revision in the repository. bos@91: \interaction{tour.tip} bos@91: We refer to the newest revision in the repository as the tip revision, bos@91: or simply the tip. bos@91: bos@91: \section{Sharing changes} bos@91: bos@91: We mentioned earlier that repositories in Mercurial are bos@91: self-contained. This means that the changeset we just created exists bos@91: only in our \dirname{my-hello} repository. Let's look at a few ways bos@91: that we can propagate this change into other repositories. bos@91: bos@91: \subsection{Pulling changes from another repository} bos@91: \label{sec:tour:pull} bos@91: bos@91: To get started, let's clone our original \dirname{hello} repository, bos@91: which does not contain the change we just committed. We'll call our bos@91: temporary repository \dirname{hello-pull}. bos@91: \interaction{tour.clone-pull} bos@91: bos@91: We'll use the \hgcmd{pull} command to bring changes from bos@91: \dirname{my-hello} into \dirname{hello-pull}. However, blindly bos@91: pulling unknown changes into a repository is a somewhat scary bos@91: prospect. Mercurial provides the \hgcmd{incoming} command to tell us bos@91: what changes the \hgcmd{pull} command \emph{would} pull into the bos@91: repository, without actually pulling the changes in. bos@91: \interaction{tour.incoming} bos@91: (Of course, someone could cause more changesets to appear in the bos@91: repository that we ran \hgcmd{incoming} in, before we get a chance to bos@91: \hgcmd{pull} the changes, so that we could end up pulling changes that we bos@91: didn't expect.) bos@91: bos@91: Bringing changes into a repository is a simple matter of running the bos@91: \hgcmd{pull} command, and telling it which repository to pull from. bos@91: \interaction{tour.pull} bos@91: As you can see from the before-and-after output of \hgcmd{tip}, we bos@91: have successfully pulled changes into our repository. There remains bos@92: one step before we can see these changes in the working directory. bos@92: bos@92: \subsection{Updating the working directory} bos@92: bos@92: We have so far glossed over the relationship between a repository and bos@91: its working directory. The \hgcmd{pull} command that we ran in bos@91: section~\ref{sec:tour:pull} brought changes into the repository, but bos@91: if we check, there's no sign of those changes in the working bos@91: directory. This is because \hgcmd{pull} does not (by default) touch bos@91: the working directory. Instead, we use the \hgcmd{update} command to bos@91: do this. bos@91: \interaction{tour.update} bos@91: bos@91: It might seem a bit strange that \hgcmd{pull} doesn't update the bos@91: working directory automatically. There's actually a good reason for bos@91: this: you can use \hgcmd{update} to update the working directory to bos@91: the state it was in at \emph{any revision} in the history of the bos@91: repository. If you had the working directory updated to an old bos@91: revision---to hunt down the origin of a bug, say---and ran a bos@91: \hgcmd{pull} which automatically updated the working directory to a bos@91: new revision, you might not be terribly happy. bos@91: bos@91: However, since pull-then-update is such a common thing to do, bos@91: Mercurial lets you combine the two by passing the \hgopt{pull}{-u} bos@91: option to \hgcmd{pull}. bos@91: \begin{codesample2} bos@91: hg pull -u bos@91: \end{codesample2} bos@92: If you look back at the output of \hgcmd{pull} in bos@92: section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, bos@92: you can see that it printed a helpful reminder that we'd have to take bos@92: an explicit step to update the working directory: bos@92: \begin{codesample2} bos@92: (run 'hg update' to get a working copy) bos@92: \end{codesample2} bos@91: bos@91: To find out what revision the working directory is at, use the bos@91: \hgcmd{parents} command. bos@91: \interaction{tour.parents} bos@91: To update the working directory to a particular revision, give a bos@91: revision number or changeset~ID to the \hgcmd{update} command. bos@91: \interaction{tour.older} bos@91: If you omit an explicit revision, \hgcmd{update} will update to the bos@94: tip revision, as shown by the second call to \hgcmd{update} in the bos@94: example above. bos@91: bos@92: \subsection{Pushing changes to another repository} bos@92: bos@92: Mercurial lets us push changes to another repository, from the bos@92: repository we're currently visiting. As with the example of bos@92: \hgcmd{pull} above, we'll create a temporary repository to push our bos@92: changes into. bos@92: \interaction{tour.clone-push} bos@92: The \hgcmd{outgoing} command tells us what changes would be pushed bos@92: into another repository. bos@92: \interaction{tour.outgoing} bos@92: And the \hgcmd{push} command does the actual push. bos@92: \interaction{tour.push} bos@92: As with \hgcmd{pull}, the \hgcmd{push} command does not update the bos@92: working directory in the repository that it's pushing changes into. bos@92: (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} bos@92: option that updates the other repository's working directory.) bos@92: bos@92: What happens if we try to pull or push changes and the receiving bos@92: repository already has those changes? Nothing too exciting. bos@92: \interaction{tour.push.nothing} bos@92: bos@93: \subsection{Sharing changes over a network} bos@93: bos@93: The commands we have covered in the previous few sections are not bos@93: limited to working with local repositories. Each works in exactly the bos@93: same fashion over a network connection; simply pass in a URL instead bos@93: of a local path. bos@93: \interaction{tour.outgoing.net} bos@93: In this example, we can see what changes we could push to the remote bos@93: repository, but the repository is understandably not set up to let bos@93: anonymous users push to it. bos@93: \interaction{tour.push.net} bos@93: bos@84: %%% Local Variables: bos@84: %%% mode: latex bos@84: %%% TeX-master: "00book" bos@84: %%% End: