Mercurial > hgbook
diff en/ch02-tour-basic.xml @ 831:acf9dc5f088d
Add a skeletal preface.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu, 07 May 2009 21:07:35 -0700 |
| parents | en/ch01-tour-basic.xml@d2aacc06e562 |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/ch02-tour-basic.xml Thu May 07 21:07:35 2009 -0700 @@ -0,0 +1,1035 @@ +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> + +<chapter id="chap:tour-basic"> + <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?> + <title>A tour of Mercurial: the basics</title> + + <sect1 id="sec:tour:install"> + <title>Installing Mercurial on your system</title> + + <para id="x_1">Prebuilt binary packages of Mercurial are available for + every popular operating system. These make it easy to start + using Mercurial on your computer immediately.</para> + + <sect2> + <title>Windows</title> + + <para id="x_c">The best version of Mercurial for Windows is + TortoiseHg, which can be found at <ulink + url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. + This package has no external dependencies; it <quote>just + works</quote>. It provides both command line and graphical + user interfaces.</para> + + </sect2> + + <sect2> + <title>Mac OS X</title> + + <para id="x_a">Lee Cantey publishes an installer of Mercurial + for Mac OS X at <ulink + url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> + </sect2> + + <sect2> + <title>Linux</title> + + <para id="x_2">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.</para> + + <para id="x_3">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 + <literal>mercurial</literal>.</para> + + <itemizedlist> + <listitem><para id="x_4">Ubuntu and Debian:</para> + <programlisting>apt-get install mercurial</programlisting></listitem> + <listitem><para id="x_5">Fedora:</para> + <programlisting>yum install mercurial</programlisting></listitem> + <listitem><para id="x_715">OpenSUSE:</para> + <programlisting>zypper install mercurial</programlisting></listitem> + <listitem><para id="x_6">Gentoo:</para> + <programlisting>emerge mercurial</programlisting></listitem> + </itemizedlist> + + </sect2> + <sect2> + <title>Solaris</title> + + <para id="x_9">SunFreeWare, at <ulink + url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, + provides prebuilt packages of Mercurial.</para> + + </sect2> + + </sect1> + + <sect1> + <title>Getting started</title> + + <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg + version</command> command to find out whether Mercurial is + installed properly. The actual version information that it + prints isn't so important; we simply care whether the command + runs and prints anything at all.</para> + + &interaction.tour.version; + + <sect2> + <title>Built-in help</title> + + <para id="x_f">Mercurial provides a built-in help system. This is + invaluable for those times when you find yourself stuck + trying to remember how to run a command. If you are + completely stuck, simply run <command role="hg-cmd">hg + help</command>; 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.</para> + + &interaction.tour.help; + + <para id="x_10">For a more impressive level of detail (which you won't + usually need) run <command role="hg-cmd">hg help <option + role="hg-opt-global">-v</option></command>. The <option + role="hg-opt-global">-v</option> option is short for + <option role="hg-opt-global">--verbose</option>, and tells + Mercurial to print more information than it usually + would.</para> + + </sect2> + </sect1> + <sect1> + <title>Working with a repository</title> + + <para id="x_11">In Mercurial, everything happens inside a + <emphasis>repository</emphasis>. The repository for a project + contains all of the files that <quote>belong to</quote> that + project, along with a historical record of the project's + files.</para> + + <para id="x_12">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 or delete a repository any + time you like, using either the command line or your file + browser.</para> + + <sect2> + <title>Making a local copy of a repository</title> + + <para id="x_13"><emphasis>Copying</emphasis> 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 <command role="hg-cmd">hg clone</command>, because it + makes an identical copy of an existing repository.</para> + + &interaction.tour.clone; + + <para id="x_67c">One advantage of using <command role="hg-cmd">hg + clone</command> is that, as we can see above, it lets us clone + repositories over the network. Another is that it remembers + where we cloned from, which we'll find useful soon when we + want to fetch new changes from another repository.</para> + + <para id="x_14">If our clone succeeded, we should now have a local + directory called <filename class="directory">hello</filename>. + This directory will contain some files.</para> + + &interaction.tour.ls; + + <para id="x_15">These files have the same contents and history in our + repository as they do in the repository we cloned.</para> + + <para id="x_16">Every Mercurial repository is complete, + self-contained, and independent. It contains its own private + copy of a project's files and history. As we just mentioned, + a cloned repository remembers the location of the repository + it was cloned from, but Mercurial will not communicate with + that repository, or any other, unless you tell it to.</para> + + <para id="x_17">What this means for now is that we're free to experiment + with our repository, safe in the knowledge that it's a private + <quote>sandbox</quote> that won't affect anyone else.</para> + + </sect2> + <sect2> + <title>What's in a repository?</title> + + <para id="x_18">When we take a more detailed look inside a repository, we + can see that it contains a directory named <filename + class="directory">.hg</filename>. This is where Mercurial + keeps all of its metadata for the repository.</para> + + &interaction.tour.ls-a; + + <para id="x_19">The contents of the <filename + class="directory">.hg</filename> directory and its + subdirectories are private to Mercurial. Every other file and + directory in the repository is yours to do with as you + please.</para> + + <para id="x_1a">To introduce a little terminology, the <filename + class="directory">.hg</filename> directory is the + <quote>real</quote> repository, and all of the files and + directories that coexist with it are said to live in the + <emphasis>working directory</emphasis>. An easy way to + remember the distinction is that the + <emphasis>repository</emphasis> contains the + <emphasis>history</emphasis> of your project, while the + <emphasis>working directory</emphasis> contains a + <emphasis>snapshot</emphasis> of your project at a particular + point in history.</para> + + </sect2> + </sect1> + <sect1> + <title>A tour through history</title> + + <para id="x_1b">One of the first things we might want to do with a new, + unfamiliar repository is understand its history. The <command + role="hg-cmd">hg log</command> command gives us a view of + the history of changes in the repository.</para> + + &interaction.tour.log; + + <para id="x_1c">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 + <emphasis>changeset</emphasis>, because it can contain a record + of changes to several files.</para> + + <para id="x_1d">The fields in a record of output from <command + role="hg-cmd">hg log</command> are as follows.</para> + + <itemizedlist> + <listitem><para id="x_1e"><literal>changeset</literal>: This + field has the format of a number, followed by a colon, + followed by a hexadecimal (or <emphasis>hex</emphasis>) + string. These are <emphasis>identifiers</emphasis> for the + changeset. The hex string is a unique identifier: the same + hex string will always refer to the same changeset in every + copy of this repository. The + number is shorter and easier to type than the hex string, + but it isn't unique: the same number in two different clones + of a repository may identify different changesets.</para> + </listitem> + <listitem><para id="x_1f"><literal>user</literal>: 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.</para></listitem> + <listitem><para id="x_20"><literal>date</literal>: The date and time on + which the changeset was created, and the timezone in which + it was created. (The date and time are local to that + timezone; they display what time and date it was for the + person who created the changeset.)</para></listitem> + <listitem><para id="x_21"><literal>summary</literal>: The first line of + the text message that the creator of the changeset entered + to describe the changeset.</para></listitem> + <listitem> + <para id="x_67d">Some changesets, such as the first in the list above, + have a <literal>tag</literal> field. A tag is another way + to identify a changeset, by giving it an easy-to-remember + name. (The tag named <literal>tip</literal> is special: it + always refers to the newest change in a repository.)</para> + </listitem> + </itemizedlist> + + <para id="x_22">The default output printed by <command + role="hg-cmd">hg log</command> is purely a summary; it is + missing a lot of detail.</para> + + <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides + a graphical representation of the history of the <filename + class="directory">hello</filename> repository, to make it a + little easier to see which direction history is + <quote>flowing</quote> in. We'll be returning to this figure + several times in this chapter and the chapter that + follows.</para> + + <figure id="fig:tour-basic:history"> + <title>Graphical history of the <filename + class="directory">hello</filename> repository</title> + <mediaobject> + <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject> + <textobject><phrase>XXX add text</phrase></textobject> + </mediaobject> + </figure> + + <sect2> + <title>Changesets, revisions, and talking to other + people</title> + + <para id="x_25">As English is a notoriously sloppy language, and computer + science has a hallowed history of terminological confusion + (why use one term when four will do?), revision control has a + variety of words and phrases that mean the same thing. If you + are talking about Mercurial history with other people, you + will find that the word <quote>changeset</quote> is often + compressed to <quote>change</quote> or (when written) + <quote>cset</quote>, and sometimes a changeset is referred to + as a <quote>revision</quote> or a <quote>rev</quote>.</para> + + <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you + use to refer to the concept of <quote>a changeset</quote>, the + <emphasis>identifier</emphasis> that you use to refer to + <quote>a <emphasis>specific</emphasis> changeset</quote> is of + great importance. Recall that the <literal>changeset</literal> + field in the output from <command role="hg-cmd">hg + log</command> identifies a changeset using both a number and + a hexadecimal string.</para> + <itemizedlist> + <listitem><para id="x_27">The revision number is a handy + notation that is <emphasis>only valid in that + repository</emphasis>.</para></listitem> + <listitem><para id="x_28">The hexadecimal string is the + <emphasis>permanent, unchanging identifier</emphasis> that + will always identify that exact changeset in + <emphasis>every</emphasis> copy of the + repository.</para></listitem></itemizedlist> + + <para id="x_29">This distinction is important. If you send + someone an email talking about <quote>revision 33</quote>, + there's a high likelihood that their revision 33 will + <emphasis>not be the same</emphasis> 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 <literal>a,b,c</literal> + can easily appear in one repository as + <literal>0,1,2</literal>, while in another as + <literal>0,2,1</literal>.</para> + + <para id="x_2a">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.</para> + + </sect2> + <sect2> + <title>Viewing specific revisions</title> + + <para id="x_2b">To narrow the output of <command role="hg-cmd">hg + log</command> down to a single revision, use the <option + role="hg-opt-log">-r</option> (or <option + role="hg-opt-log">--rev</option>) option. You can use + either a revision number or a hexadecimal identifier, + and you can provide as many revisions as you want.</para> + + &interaction.tour.log-r; + + <para id="x_2c">If you want to see the history of several revisions + without having to list each one, you can use <emphasis>range + notation</emphasis>; this lets you express the idea <quote>I + want all revisions between <literal>abc</literal> and + <literal>def</literal>, inclusive</quote>.</para> + + &interaction.tour.log.range; + + <para id="x_2d">Mercurial also honours the order in which you specify + revisions, so <command role="hg-cmd">hg log -r 2:4</command> + prints 2, 3, and 4. while <command role="hg-cmd">hg log -r + 4:2</command> prints 4, 3, and 2.</para> + + </sect2> + <sect2> + <title>More detailed information</title> + + <para id="x_2e">While the summary information printed by <command + role="hg-cmd">hg log</command> is useful if you already know + what you're looking for, you may need to see a complete + description of the change, or a list of the files changed, if + you're trying to decide whether a changeset is the one you're + looking for. The <command role="hg-cmd">hg log</command> + command's <option role="hg-opt-global">-v</option> (or <option + role="hg-opt-global">--verbose</option>) option gives you + this extra detail.</para> + + &interaction.tour.log-v; + + <para id="x_2f">If you want to see both the description and + content of a change, add the <option + role="hg-opt-log">-p</option> (or <option + role="hg-opt-log">--patch</option>) option. This displays + the content of a change as a <emphasis>unified diff</emphasis> + (if you've never seen a unified diff before, see <xref + linkend="sec:mq:patch"/> for an overview).</para> + + &interaction.tour.log-vp; + + <para id="x_67e">The <option role="hg-opt-log">-p</option> option is + tremendously useful, so it's well worth remembering.</para> + + </sect2> + </sect1> + + <sect1> + <title>All about command options</title> + + <para id="x_30">Let's take a brief break from exploring Mercurial commands + to discuss a pattern in the way that they work; you may find + this useful to keep in mind as we continue our tour.</para> + + <para id="x_31">Mercurial has a consistent and straightforward approach to + dealing with the options that you can pass to commands. It + follows the conventions for options that are common to modern + Linux and Unix systems.</para> + + <itemizedlist> + <listitem> + <para id="x_32">Every option has a long name. For example, as + we've already seen, the <command role="hg-cmd">hg + log</command> command accepts a <option + role="hg-opt-log">--rev</option> option.</para> + </listitem> + <listitem> + <para id="x_33">Most options have short names, too. Instead + of <option role="hg-opt-log">--rev</option>, we can use + <option role="hg-opt-log">-r</option>. (The reason that + some options don't have short names is that the options in + question are rarely used.)</para> + </listitem> + <listitem> + <para id="x_34">Long options start with two dashes (e.g. + <option role="hg-opt-log">--rev</option>), while short + options start with one (e.g. <option + role="hg-opt-log">-r</option>).</para> + </listitem> + <listitem> + <para id="x_35">Option naming and usage is consistent across + commands. For example, every command that lets you specify + a changeset ID or revision number accepts both <option + role="hg-opt-log">-r</option> and <option + role="hg-opt-log">--rev</option> arguments.</para> + </listitem> + <listitem> + <para id="x_67f">If you are using short options, you can save typing by + running them together. For example, the command <command + role="hg-cmd">hg log -v -p -r 2</command> can be written + as <command role="hg-cmd">hg log -vpr2</command>.</para> + </listitem> + </itemizedlist> + + <para id="x_36">In the examples throughout this book, I usually + use short options instead of long. This simply reflects my own + preference, so don't read anything significant into it.</para> + + <para id="x_37">Most commands that print output of some kind will print more + output when passed a <option role="hg-opt-global">-v</option> + (or <option role="hg-opt-global">--verbose</option>) option, and + less when passed <option role="hg-opt-global">-q</option> (or + <option role="hg-opt-global">--quiet</option>).</para> + + <note> + <title>Option naming consistency</title> + + <para id="x_680">Almost always, Mercurial commands use consistent option + names to refer to the same concepts. For instance, if a + command deals with changesets, you'll always identify them + with <option role="hg-opt-log">--rev</option> or <option + role="hg-opt-log">-r</option>. This consistent use of + option names makes it easier to remember what options a + particular command takes.</para> + </note> + + </sect1> + <sect1> + <title>Making and reviewing changes</title> + + <para id="x_38">Now that we have a grasp of viewing history in Mercurial, + let's take a look at making some changes and examining + them.</para> + + <para id="x_39">The first thing we'll do is isolate our experiment in a + repository of its own. We use the <command role="hg-cmd">hg + clone</command> command, but we don't need to clone a copy of + the remote repository. Since we already have a copy of it + locally, we can just clone that instead. This is much faster + than cloning over the network, and cloning a local repository + uses less disk space in most cases, too<footnote> + <para id="x_681">The saving of space arises when source and destination + repositories are on the same filesystem, in which case + Mercurial will use hardlinks to do copy-on-write sharing of + its internal metadata. If that explanation meant nothing to + you, don't worry: everything happens transparently and + automatically, and you don't need to understand it.</para> + </footnote>.</para> + + &interaction.tour.reclone; + + <para id="x_3a">As an aside, it's often good practice to keep a + <quote>pristine</quote> copy of a remote repository around, + which you can then make temporary clones of to create sandboxes + for each task you want to work on. This lets you work on + multiple tasks in parallel, each isolated from the others until + it's complete and you're ready to integrate it back. Because + local clones are so cheap, there's almost no overhead to cloning + and destroying repositories whenever you want.</para> + + <para id="x_3b">In our <filename class="directory">my-hello</filename> + repository, we have a file <filename>hello.c</filename> that + contains the classic <quote>hello, world</quote> program.</para> + + &interaction.tour.cat1; + + <para id="x_682">Let's edit this file so that it prints a second line of + output.</para> + + &interaction.tour.cat2; + + <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> + command will tell us what Mercurial knows about the files in the + repository.</para> + + &interaction.tour.status; + + <para id="x_3d">The <command role="hg-cmd">hg status</command> command + prints no output for some files, but a line starting with + <quote><literal>M</literal></quote> for + <filename>hello.c</filename>. Unless you tell it to, <command + role="hg-cmd">hg status</command> will not print any output + for files that have not been modified.</para> + + <para id="x_3e">The <quote><literal>M</literal></quote> indicates that + Mercurial has noticed that we modified + <filename>hello.c</filename>. We didn't need to + <emphasis>inform</emphasis> Mercurial that we were going to + modify the file before we started, or that we had modified the + file after we were done; it was able to figure this out + itself.</para> + + <para id="x_3f">It's somewhat helpful to know that we've modified + <filename>hello.c</filename>, but we might prefer to know + exactly <emphasis>what</emphasis> changes we've made to it. To + do this, we use the <command role="hg-cmd">hg diff</command> + command.</para> + + &interaction.tour.diff; + + <tip> + <title>Understanding patches</title> + + <para id="x_683">Remember to take a look at <xref + linkend="sec:mq:patch"/> if you don't know how to read + output above.</para> + </tip> + </sect1> + <sect1> + <title>Recording changes in a new changeset</title> + + <para id="x_40">We can modify files, build and test our changes, and use + <command role="hg-cmd">hg status</command> and <command + role="hg-cmd">hg diff</command> to review our changes, until + we're satisfied with what we've done and arrive at a natural + stopping point where we want to record our work in a new + changeset.</para> + + <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets + us create a new changeset; we'll usually refer to this as + <quote>making a commit</quote> or + <quote>committing</quote>.</para> + + <sect2> + <title>Setting up a username</title> + + <para id="x_42">When you try to run <command role="hg-cmd">hg + commit</command> for the first time, it is not guaranteed to + succeed. Mercurial records your name and address with each + change that you commit, so that you and others will later be + able to tell who made each change. Mercurial tries to + automatically figure out a sensible username to commit the + change with. It will attempt each of the following methods, + in order:</para> + <orderedlist> + <listitem><para id="x_43">If you specify a <option + role="hg-opt-commit">-u</option> option to the <command + role="hg-cmd">hg commit</command> command on the command + line, followed by a username, this is always given the + highest precedence.</para></listitem> + <listitem><para id="x_44">If you have set the <envar>HGUSER</envar> + environment variable, this is checked + next.</para></listitem> + <listitem><para id="x_45">If you create a file in your home + directory called <filename + role="special">.hgrc</filename>, with a <envar + role="rc-item-ui">username</envar> entry, that will be + used next. To see what the contents of this file should + look like, refer to <xref + linkend="sec:tour-basic:username"/> + below.</para></listitem> + <listitem><para id="x_46">If you have set the <envar>EMAIL</envar> + environment variable, this will be used + next.</para></listitem> + <listitem><para id="x_47">Mercurial will query your system to find out + your local user name and host name, and construct a + username from these components. Since this often results + in a username that is not very useful, it will print a + warning if it has to do + this.</para></listitem> + </orderedlist> + <para id="x_48">If all of these mechanisms fail, Mercurial will + fail, printing an error message. In this case, it will not + let you commit until you set up a + username.</para> + <para id="x_49">You should think of the <envar>HGUSER</envar> environment + variable and the <option role="hg-opt-commit">-u</option> + option to the <command role="hg-cmd">hg commit</command> + command as ways to <emphasis>override</emphasis> Mercurial's + default selection of username. For normal use, the simplest + and most robust way to set a username for yourself is by + creating a <filename role="special">.hgrc</filename> file; see + below for details.</para> + <sect3 id="sec:tour-basic:username"> + <title>Creating a Mercurial configuration file</title> + + <para id="x_4a">To set a user name, use your favorite editor + to create a file called <filename + role="special">.hgrc</filename> in your home directory. + Mercurial will use this file to look up your personalised + configuration settings. The initial contents of your + <filename role="special">.hgrc</filename> should look like + this.</para> + + <tip> + <title><quote>Home directory</quote> on Windows</title> + + <para id="x_716">When we refer to your home directory, on an English + language installation of Windows this will usually be a + folder named after your user name in + <filename>C:\Documents and Settings</filename>. You can + find out the exact name of your home directory by opening + a command prompt window and running the following + command.</para> + + <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen> + </tip> + + <programlisting># This is a Mercurial configuration file. +[ui] +username = Firstname Lastname <email.address@example.net></programlisting> + + <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a + <emphasis>section</emphasis> of the config file, so you can + read the <quote><literal>username = ...</literal></quote> + line as meaning <quote>set the value of the + <literal>username</literal> item in the + <literal>ui</literal> section</quote>. A section continues + until a new section begins, or the end of the file. + Mercurial ignores empty lines and treats any text from + <quote><literal>#</literal></quote> to the end of a line as + a comment.</para> + </sect3> + + <sect3> + <title>Choosing a user name</title> + + <para id="x_4c">You can use any text you like as the value of + the <literal>username</literal> config item, since this + information is for reading by other people, but will not be + interpreted by Mercurial. The convention that most people + follow is to use their name and email address, as in the + example above.</para> + <note> + <para id="x_4d">Mercurial's built-in web server obfuscates + email addresses, to make it more difficult for the email + harvesting tools that spammers use. This reduces the + likelihood that you'll start receiving more junk email if + you publish a Mercurial repository on the + web.</para></note> + </sect3> + </sect2> + <sect2> + <title>Writing a commit message</title> + + <para id="x_4e">When we commit a change, Mercurial drops us into + a text editor, to enter a message that will describe the + modifications we've made in this changeset. This is called + the <emphasis>commit message</emphasis>. It will be a record + for readers of what we did and why, and it will be printed by + <command role="hg-cmd">hg log</command> after we've finished + committing.</para> + + &interaction.tour.commit; + + <para id="x_4f">The editor that the <command role="hg-cmd">hg + commit</command> command drops us into will contain an empty + line or two, followed by a number of lines starting with + <quote><literal>HG:</literal></quote>.</para> + + <programlisting> +This is where I type my commit comment. + +HG: Enter commit message. Lines beginning with 'HG:' are removed. +HG: -- +HG: user: Bryan O'Sullivan <bos@serpentine.com> +HG: branch 'default' +HG: changed hello.c</programlisting> + + <para id="x_50">Mercurial ignores the lines that start with + <quote><literal>HG:</literal></quote>; it uses them only to + tell us which files it's recording changes to. Modifying or + deleting these lines has no effect.</para> + </sect2> + <sect2> + <title>Writing a good commit message</title> + + <para id="x_51">Since <command role="hg-cmd">hg log</command> + only prints the first line of a commit message by default, + it's best to write a commit message whose first line stands + alone. Here's a real example of a commit message that + <emphasis>doesn't</emphasis> follow this guideline, and hence + has a summary that is not readable.</para> + + <programlisting> +changeset: 73:584af0e231be +user: Censored Person <censored.person@example.org> +date: Tue Sep 26 21:37:07 2006 -0700 +summary: include buildmeister/commondefs. Add exports.</programlisting> + + <para id="x_52">As far as the remainder of the contents of the + commit message are concerned, there are no hard-and-fast + rules. Mercurial itself doesn't interpret or care about the + contents of the commit message, though your project may have + policies that dictate a certain kind of formatting.</para> + <para id="x_53">My personal preference is for short, but + informative, commit messages that tell me something that I + can't figure out with a quick glance at the output of <command + role="hg-cmd">hg log --patch</command>.</para> + <para id="x_55">If we run the <command role="hg-cmd">hg + commit</command> command without any arguments, it records + all of the changes we've made, as reported by <command + role="hg-cmd">hg status</command> and <command + role="hg-cmd">hg diff</command>.</para> + + <note> + <title>A surprise for Subversion users</title> + + <para id="x_717">Like other Mercurial commands, if we don't supply + explicit names to commit to the <command role="hg-cmd">hg + commit</command>, it will operate across a repository's + entire working directory. Be wary of this if you're coming + from the Subversion or CVS world, since you might expect it + to operate only on the current directory that you happen to + be visiting and its subdirectories.</para> + </note> + </sect2> + + <sect2> + <title>Aborting a commit</title> + + <para id="x_54">If you decide that you don't want to commit + while in the middle of editing a commit message, simply exit + from your editor without saving the file that it's editing. + This will cause nothing to happen to either the repository or + the working directory.</para> + </sect2> + + <sect2> + <title>Admiring our new handiwork</title> + + <para id="x_56">Once we've finished the commit, we can use the + <command role="hg-cmd">hg tip</command> command to display the + changeset we just created. This command produces output that + is identical to <command role="hg-cmd">hg log</command>, but + it only displays the newest revision in the repository.</para> + + &interaction.tour.tip; + + <para id="x_57">We refer to the newest revision in the + repository as the <emphasis>tip revision</emphasis>, or simply + the <emphasis>tip</emphasis>.</para> + + <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command> + command accepts many of the same options as <command + role="hg-cmd">hg log</command>, so <option + role="hg-opt-global">-v</option> above indicates <quote>be + verbose</quote>, <option role="hg-opt-tip">-p</option> + specifies <quote>print a patch</quote>. The use of <option + role="hg-opt-tip">-p</option> to print patches is another + example of the consistent naming we mentioned earlier.</para> + </sect2> + </sect1> + + <sect1> + <title>Sharing changes</title> + + <para id="x_58">We mentioned earlier that repositories in + Mercurial are self-contained. This means that the changeset we + just created exists only in our <filename + class="directory">my-hello</filename> repository. Let's look + at a few ways that we can propagate this change into other + repositories.</para> + + <sect2 id="sec:tour:pull"> + <title>Pulling changes from another repository</title> + + <para id="x_59">To get started, let's clone our original + <filename class="directory">hello</filename> repository, which + does not contain the change we just committed. We'll call our + temporary repository <filename + class="directory">hello-pull</filename>.</para> + + &interaction.tour.clone-pull; + + <para id="x_5a">We'll use the <command role="hg-cmd">hg + pull</command> command to bring changes from <filename + class="directory">my-hello</filename> into <filename + class="directory">hello-pull</filename>. However, blindly + pulling unknown changes into a repository is a somewhat scary + prospect. Mercurial provides the <command role="hg-cmd">hg + incoming</command> command to tell us what changes the + <command role="hg-cmd">hg pull</command> command + <emphasis>would</emphasis> pull into the repository, without + actually pulling the changes in.</para> + + &interaction.tour.incoming; + + <para id="x_5c">Bringing changes into a repository is a simple + matter of running the <command role="hg-cmd">hg pull</command> + command, and optionally telling it which repository to pull from.</para> + + &interaction.tour.pull; + + <para id="x_5d">As you can see from the before-and-after output + of <command role="hg-cmd">hg tip</command>, we have + successfully pulled changes into our repository. However, + Mercurial separates pulling changes in from updating the + working directory. There remains one step before we will see + the changes that we just pulled appear in the working + directory.</para> + + <tip> + <title>Pulling specific changes</title> + + <para id="x_5b">It is possible that due to the delay between + running <command role="hg-cmd">hg incoming</command> and + <command role="hg-cmd">hg pull</command>, you may not see + all changesets that will be brought from the other + repository. Suppose you're pulling changes from a repository + on the network somewhere. While you are looking at the + <command role="hg-cmd">hg incoming</command> output, and + before you pull those changes, someone might have committed + something in the remote repository. This means that it's + possible to pull more changes than you saw when using + <command role="hg-cmd">hg incoming</command>.</para> + + <para id="x_718">If you only want to pull precisely the changes that were + listed by <command role="hg-cmd">hg incoming</command>, or + you have some other reason to pull a subset of changes, + simply identify the change that you want to pull by its + changeset ID, e.g. <command>hg pull + -r7e95bb</command>.</para> + </tip> + </sect2> + + <sect2> + <title>Updating the working directory</title> + + <para id="x_5e">We have so far glossed over the relationship + between a repository and its working directory. The <command + role="hg-cmd">hg pull</command> command that we ran in + <xref linkend="sec:tour:pull"/> brought changes into the + repository, but if we check, there's no sign of those changes + in the working directory. This is because <command + role="hg-cmd">hg pull</command> does not (by default) touch + the working directory. Instead, we use the <command + role="hg-cmd">hg update</command> command to do this.</para> + + &interaction.tour.update; + + <para id="x_5f">It might seem a bit strange that <command + role="hg-cmd">hg pull</command> doesn't update the working + directory automatically. There's actually a good reason for + this: you can use <command role="hg-cmd">hg update</command> + to update the working directory to the state it was in at + <emphasis>any revision</emphasis> in the history of the + repository. If you had the working directory updated to an + old revision&emdash;to hunt down the origin of a bug, + say&emdash;and ran a <command role="hg-cmd">hg pull</command> + which automatically updated the working directory to a new + revision, you might not be terribly happy.</para> + + <para id="x_60">Since pull-then-update is such a common sequence + of operations, Mercurial lets you combine the two by passing + the <option role="hg-opt-pull">-u</option> option to <command + role="hg-cmd">hg pull</command>.</para> + + <para id="x_61">If you look back at the output of <command + role="hg-cmd">hg pull</command> in <xref + linkend="sec:tour:pull"/> when we ran it without <option + role="hg-opt-pull">-u</option>, you can see that it printed + a helpful reminder that we'd have to take an explicit step to + update the working directory.</para> + + <para id="x_62">To find out what revision the working directory + is at, use the <command role="hg-cmd">hg parents</command> + command.</para> + + &interaction.tour.parents; + + <para id="x_63">If you look back at <xref + linkend="fig:tour-basic:history"/>, you'll see arrows + connecting each changeset. The node that the arrow leads + <emphasis>from</emphasis> in each case is a parent, and the + node that the arrow leads <emphasis>to</emphasis> is its + child. The working directory has a parent in just the same + way; this is the changeset that the working directory + currently contains.</para> + + <para id="x_64">To update the working directory to a particular + revision, give a revision number or changeset ID to the + <command role="hg-cmd">hg update</command> command.</para> + + &interaction.tour.older; + + <para id="x_65">If you omit an explicit revision, <command + role="hg-cmd">hg update</command> will update to the tip + revision, as shown by the second call to <command + role="hg-cmd">hg update</command> in the example + above.</para> + </sect2> + + <sect2> + <title>Pushing changes to another repository</title> + + <para id="x_66">Mercurial lets us push changes to another + repository, from the repository we're currently visiting. As + with the example of <command role="hg-cmd">hg pull</command> + above, we'll create a temporary repository to push our changes + into.</para> + + &interaction.tour.clone-push; + + <para id="x_67">The <command role="hg-cmd">hg outgoing</command> + command tells us what changes would be pushed into another + repository.</para> + + &interaction.tour.outgoing; + + <para id="x_68">And the <command role="hg-cmd">hg push</command> + command does the actual push.</para> + + &interaction.tour.push; + + <para id="x_69">As with <command role="hg-cmd">hg + pull</command>, the <command role="hg-cmd">hg push</command> + command does not update the working directory in the + repository that it's pushing changes into. Unlike <command + role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg + push</command> does not provide a <literal>-u</literal> + option that updates the other repository's working directory. + This asymmetry is deliberate: the repository we're pushing to + might be on a remote server and shared between several people. + If we were to update its working directory while someone was + working in it, their work would be disrupted.</para> + + <para id="x_6a">What happens if we try to pull or push changes + and the receiving repository already has those changes? + Nothing too exciting.</para> + + &interaction.tour.push.nothing; + </sect2> + + <sect2> + <title>Default locations</title> + + <para id="x_719">When we clone a repository, Mercurial records the location + of the repository we cloned in the + <filename>.hg/hgrc</filename> file of the new repository. If + we don't supply a location to <command>hg pull</command> from + or <command>hg push</command> to, those commands will use this + location as a default. The <command>hg incoming</command> + and <command>hg outgoing</command> commands do so too.</para> + + <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename> + file in a text editor, you will see contents like the + following.</para> + + <programlisting>[paths] +default = http://www.selenic.com/repo/hg</programlisting> + + <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the + default location for <command>hg push</command> and + <command>hg outgoing</command> be different from those for + <command>hg pull</command> and <command>hg incoming</command>. + We can do this by adding a <literal>default-push</literal> + entry to the <literal>[paths]</literal> section of the + <filename>.hg/hgrc</filename> file, as follows.</para> + + <programlisting>[paths] +default = http://www.selenic.com/repo/hg +default-push = http://hg.example.com/hg</programlisting> + </sect2> + + <sect2> + <title>Sharing changes over a network</title> + + <para id="x_6b">The commands we have covered in the previous few + sections are not limited to working with local repositories. + Each works in exactly the same fashion over a network + connection; simply pass in a URL instead of a local + path.</para> + + &interaction.tour.outgoing.net; + + <para id="x_6c">In this example, we can see what changes we + could push to the remote repository, but the repository is + understandably not set up to let anonymous users push to + it.</para> + + &interaction.tour.push.net; + </sect2> + </sect1> + + <sect1> + <title>Starting a new project</title> + + <para id="x_71c">It is just as easy to begin a new project as to work on one + that already exists. The <command>hg init</command> command + creates a new, empty Mercurial repository.</para> + + &interaction.ch01-new.init; + + <para id="x_71d">This simply creates a repository named + <filename>myproject</filename> in the current directory.</para> + + &interaction.ch01-new.ls; + + <para id="x_71e">We can tell that <filename>myproject</filename> is a + Mercurial repository, because it contains a + <filename>.hg</filename> directory.</para> + + &interaction.ch01-new.ls2; + + <para id="x_71f">If we want to add some pre-existing files to the repository, + we copy them into place, and tell Mercurial to start tracking + them using the <command>hg add</command> command.</para> + + &interaction.ch01-new.add; + + <para id="x_720">Once we are satisfied that our project looks right, we + commit our changes.</para> + + &interaction.ch01-new.commit; + + <para id="x_721">It takes just a few moments to start using Mercurial on a + new project, which is part of its appeal. Revision control is + now so easy to work with, we can use it on the smallest of + projects that we might not have considered with a more + complicated tool.</para> + </sect1> +</chapter> + +<!-- +local variables: +sgml-parent-document: ("00book.xml" "book" "chapter") +end: +-->